- A storage description resource provides information a client can use + A storage description resource provides information a client can use when interacting with a storage, including descriptions of capabilities and service endpoints.
diff --git a/lws10-core/Privacy-Considerations.html b/lws10-core/Privacy-Considerations.html index 3103423..b131890 100644 --- a/lws10-core/Privacy-Considerations.html +++ b/lws10-core/Privacy-Considerations.html @@ -20,3 +20,24 @@ to correlate requests. When using pseudonymous identifiers, the authorization server will need to be careful not to issue the same identifier more than once. +assignee value in the request is associated with the
+ authenticated identity of the requesting agent.
+ + Access Requests and Grants provide a mechanism for an agent to request access to + resources and for a resource manager to grant access with defined constraints. + The endpoints for requesting and granting access act as a type of specialized inbox. +
+ ++ An agent does not present an access grant to a server as an authorization token. + Rather, the access grant serves as a record of what was authorized, to whom, + and under what constraints. When an access grant is created or revoked (deleted), it + is the responsibility of the server to adjust any underlying access policy to account for the + change. The interaction between an access grant endpoint and a particular policy + enforcement layer is out of scope for this specification. +
+ ++ The access profile defined in this section is based on concepts from the + Open Digital Rights Language (ODRL), including + actions, constraints, and assignees. Other profiles could use a different conceptual framework. +
+ ++ This section defines the following terms: +
+ +conformsTo property of a service object in its
+ Storage Description resource.
+
+ A storage MAY advertise support for access requests and access grants
+ in its storage description resource. When such support is advertised, a service
+ object describing an endpoint for access requests MUST have a
+ type equal to the string AccessRequestService, and a
+ service object describing an endpoint for access grants MUST have a
+ type equal to the string AccessGrantService. A service
+ object SHOULD include a conformsTo property whose value is a collection
+ of one or more URIs identifying the access profiles supported at that
+ endpoint. Additional properties MAY be included:
+
+{
+ "@context": [
+ "https://www.w3.org/ns/lws/v1"
+ ],
+ "id": "https://storage.example/",
+ "type": "Storage",
+ "service": [
+ {
+ "type": "AccessRequestService",
+ "serviceEndpoint": "https://access.example/request/",
+ "conformsTo": ["https://www.w3.org/ns/lws#AccessProfile"]
+ },
+ {
+ "type": "AccessGrantService",
+ "serviceEndpoint": "https://access.example/grant/",
+ "conformsTo": ["https://www.w3.org/ns/lws#AccessProfile"]
+ }
+ ]
+}
+
+
+ An access request or access grant is a data object that expresses properties
+ for identity and routing, as well as an access object that describes the
+ requested or permitted operations. A profile that describes access requests using
+ ODRL concepts is described in .
+
+ The following example illustrates an access request. The example is shown + using the JSON-LD serialization defined in . +
+ +
+{
+ "@context": [
+ "https://www.w3.org/ns/lws/v1"
+ ],
+ "type": ["AccessRequest"],
+ "inbox": "https://id.example/agent/inbox/",
+ "storage": "https://storage.example/",
+ "access": [{
+ "type": ["AccessPolicy"],
+ "action": ["read", "create"],
+ "assignee": "https://id.example/agent",
+ "target": {
+ "type": "StorageResource",
+ "value": ["https://storage.example/projects/"]
+ },
+ "constraint": [
+ {
+ "leftOperand": "purpose",
+ "operator": "eq",
+ "rightOperand": "https://purpose.example/collaboration"
+ },
+ {
+ "leftOperand": "dateTime",
+ "operator": "lteq",
+ "rightOperand": "2026-06-09T10:00:00Z"
+ }
+ ]
+ }]
+}
+
+
+ + The following example illustrates an access grant. The example is shown + using the JSON-LD serialization defined in . +
+ +
+{
+ "@context": [
+ "https://www.w3.org/ns/lws/v1"
+ ],
+ "type": ["AccessGrant"],
+ "storage": "https://storage.example/",
+ "access": [{
+ "type": ["AccessPolicy"],
+ "action": ["read"],
+ "assignee": "https://id.example/agent",
+ "target": {
+ "type": "StorageResource",
+ "value": ["https://storage.example/projects/"]
+ },
+ "constraint": [
+ {
+ "leftOperand": "purpose",
+ "operator": "eq",
+ "rightOperand": "https://purpose.example/collaboration"
+ },
+ {
+ "leftOperand": "dateTime",
+ "operator": "lteq",
+ "rightOperand": "2026-06-09T10:00:00Z"
+ }
+ ]
+ }]
+}
+
+
+ + Other properties MAY be present on access requests and access grants. +
+ +
+ The type property expresses the type of the document.
+
+ The value of the type property MUST be one or more
+ terms and
+ absolute URL strings. For an
+ access request, the value MUST include the term AccessRequest.
+ For an access grant, the value MUST include the term
+ AccessGrant. Additional type values MAY be included.
+
+ This property is REQUIRED. +
+ ++ This document defines the following type values for access requests and + access grants: +
+ +AccessRequest — a request by an agent for access to resources.
+ AccessGrant — an authorization by a storage controller granting
+ access to resources.
+
+{
+ "type": ["AccessGrant"]
+}
+
+
+ The storage property identifies the LWS storage to which the
+ access request or access grant is scoped.
+
+ The value of the storage property MUST be a URI.
+
+ This property is REQUIRED. +
+ +
+{
+ "storage": "https://storage.example/"
+}
+
+
+ The inbox property specifies a URI for receiving notifications related to
+ the access request or access grant
+ (see ).
+
+ The value of the inbox property MUST be a URI.
+
+ This property is OPTIONAL. +
+ +
+{
+ "inbox": "https://id.example/agent/inbox/"
+}
+
+
+ The access property describes the characteristics of one or more
+ access profiles, based on the profiles supported by a server. A
+ profile based on the
+ ODRL Information Model is described
+ in .
+
+ The value of the access property MUST be a collection of one or more
+ objects.
+
+ This property is REQUIRED. +
+
+ This specification defines an Access Profile based on the
+ [[!ODRL-MODEL|ODRL Information Model]] and [[!ODRL-VOCAB|ODRL Vocabulary]], identified
+ with the URL:
+ https://www.w3.org/ns/lws#AccessProfile.
+
+ The type property expresses the type of access policy.
+
+ The value of the type property MUST be one or more
+ terms and
+ absolute URL strings, and MUST include
+ the term AccessPolicy. Additional type values MAY be included.
+
+ The property is REQUIRED. +
+ +
+{
+ "access": [{
+ "type": ["AccessPolicy"]
+ }]
+}
+
+
+ The action property describes the operations that the agent wishes to
+ perform (in the case of a request) or is authorized to perform (in the case of a grant).
+
+ The value of the action property MUST be a collection of one or more
+ strings. Each value MUST correspond to an operation recognized by the server. The
+ following values MUST be supported: read, modify,
+ create, and delete. The read,
+ modify, and delete values are defined by the
+ [[!ODRL-VOCAB|ODRL Vocabulary]]. The create value is defined by this
+ specification.
+
+ These action values correspond to LWS operations as follows: +
+ +read — retrieve a resource or its metadata (HTTP GET, HEAD)modify — modify an existing resource (HTTP PUT, PATCH)create — create a new resource within a container (HTTP POST)
+ delete — remove an existing resource (HTTP DELETE)+ This property is REQUIRED. +
+ +
+{
+ "access": [{
+ "action": ["read", "create"]
+ }]
+}
+
+
+ The assignee property identifies the party that is requesting access (in
+ the case of a request) or that is being granted access (in the case of a grant).
+
+ The value of the assignee property MUST be a URI. Public access MAY be
+ assigned using the Agent class from the [[!FOAF|FOAF vocabulary]], identified by the URI
+ http://xmlns.com/foaf/0.1/Agent.
+
+ This property is REQUIRED. +
+ +
+{
+ "access": [{
+ "assignee": "https://id.example/agent"
+ }]
+}
+
+
+ The target property identifies the resources to which the
+ access request or access grant applies.
+
+ The target property MUST be an object containing the
+ following properties:
+
type — a term or
+ absolute URL string identifying the
+ type of target matcher.
+ value — a collection of one or more strings used to identify
+ the target resources.
+
+ This specification defines the following type values for use
+ with target objects:
+
https://www.w3.org/ns/lws#DataResource — matches
+ resources of type lws:DataResource.
+ https://www.w3.org/ns/lws#Container — matches
+ resources of type lws:Container.
+ https://www.w3.org/ns/lws#StorageResource — matches
+ any resource managed by a storage.
+ + A server MAY support additional type values. +
+ ++ This property is OPTIONAL. +
+ +
+{
+ "access": [{
+ "target": {
+ "type": "StorageResource",
+ "value": [
+ "https://storage.example/data/2025",
+ "https://storage.example/data/2026"
+ ]
+ }
+ }]
+}
+
+
+ The constraint property defines conditions that limit or qualify the
+ access being requested or granted. This property uses the ODRL
+ Constraint model.
+
+ The value of the constraint property, if present, MUST be a collection
+ of constraint objects. Each constraint object MUST include the following properties:
+
leftOperand — a string identifying the operand being constrained.
+ operator — a string identifying the comparison operator.
+ rightOperand — the value to compare against. The type depends on
+ the leftOperand.
+ + When multiple constraint objects are present, all of them MUST be satisfied. +
+ +
+ A server advertising support for this profile MUST support the following
+ leftOperand values:
+
client — representing the client identifier for an HTTP request
+ mediaType — representing the media type of the target HTTP
+ resource
+ type — representing the type URL expressed in a resource's link
+ headers
+ purpose — representing the intended use of the access being
+ requested or granted
+ dateTime — representing the current date time
+ + This property is OPTIONAL. +
+ ++ The following examples illustrate the use of these constraints: +
+ +
+ The following example uses a leftOperand value of
+ purpose to describe the intended
+ use of the access being requested or granted. When the eq operator
+ is used, the rightOperand value is a URI identifying a purpose.
+ When the isAnyOf operator is used, the rightOperand
+ value is an array of purpose URIs, and the constraint is satisfied if the
+ stated purpose matches any of the listed values:
+
+{
+ "access": [{
+ "constraint": [
+ {
+ "leftOperand": "purpose",
+ "operator": "isAnyOf",
+ "rightOperand": [
+ "https://purpose.example/collaboration",
+ "https://purpose.example/research"
+ ]
+ }
+ ]
+ }]
+}
+
+
+ The following example uses a leftOperand value of
+ client to restrict access
+ to a specific client application. When the eq operator is used, the
+ rightOperand value is a URI identifying the client:
+
+{
+ "access": [{
+ "constraint": [
+ {
+ "leftOperand": "client",
+ "operator": "eq",
+ "rightOperand": "https://app.example/client-id"
+ }
+ ]
+ }]
+}
+
+
+ The following example uses a leftOperand value of
+ mediaType to restrict
+ access to resources with specific media types. When the eq operator
+ is used, the rightOperand value is a string identifying an
+ IANA media type. When
+ the isAnyOf operator is used, the rightOperand value
+ is an array of media type strings, and access is permitted if the resource's
+ media type matches any of the listed values:
+
+{
+ "access": [{
+ "constraint": [
+ {
+ "leftOperand": "mediaType",
+ "operator": "isAnyOf",
+ "rightOperand": ["image/jpeg", "image/png"]
+ }
+ ]
+ }]
+}
+
+ + All LWS resources will include link headers indicating type values: +
+ ++Link: <https://www.w3.org/ns/lws#DataResource>; rel="type" +Link: <https://type.example/Playlist>; rel="type" ++ +
+ The following example uses a leftOperand value of
+ type to restrict access based on the resource types advertised
+ in HTTP Link headers.
+ When the eq operator is used, the rightOperand value
+ is a URI identifying a resource type. When the isAnyOf operator is
+ used, the rightOperand value is an array of type URIs, and access
+ is permitted if the resource's type matches any of the listed values:
+
+{
+ "access": [{
+ "constraint": [
+ {
+ "leftOperand": "type",
+ "operator": "isAnyOf",
+ "rightOperand": [
+ "https://type.example/Playlist",
+ "https://type.example/Song"
+ ]
+ }
+ ]
+ }]
+}
+
+
+ The following example uses a leftOperand value of
+ dateTime to limit access
+ to a specific time window. The gteq operator defines the start of the
+ window and the lteq operator defines the end. The
+ rightOperand value for temporal constraints is an
+ [[!XMLSCHEMA11-2|XML Schema]] dateTime string:
+
+{
+ "access": [{
+ "constraint": [
+ {
+ "leftOperand": "dateTime",
+ "operator": "gteq",
+ "rightOperand": "2026-03-09T12:00:00Z"
+ },
+ {
+ "leftOperand": "dateTime",
+ "operator": "lteq",
+ "rightOperand": "2026-06-09T10:00:00Z"
+ }
+ ]
+ }]
+}
+
+ + When multiple constraint objects are present, all of them MUST be satisfied for + access to be permitted. The following example restricts access to a specific client + application before a specific date: +
+ +
+{
+ "access": [{
+ "action": ["read"],
+ "assignee": "https://id.example/agent",
+ "target": {
+ "type": "StorageResource",
+ "value": ["https://storage.example/projects/"]
+ },
+ "constraint": [
+ {
+ "leftOperand": "dateTime",
+ "operator": "lteq",
+ "rightOperand": "2026-06-09T10:00:00Z"
+ },
+ {
+ "leftOperand": "client",
+ "operator": "eq",
+ "rightOperand": "https://app.example/client-id"
+ }
+ ]
+ }]
+}
+
+ + The data model defined in this section is independent of any particular + serialization. +
+ +
+ This specification defines a JSON-LD serialization for access requests and
+ access grants. Documents using this serialization MUST include an
+ @context property whose value is an ordered set that includes
+ https://www.w3.org/ns/lws/v1. Additional context entries MAY be
+ included to define extension terms.
+
+ The media type associated with this serialization is application/lws+json.
+
+{
+ "@context": [
+ "https://www.w3.org/ns/lws/v1"
+ ]
+}
+
+ + The access request and access grant endpoints are LWS containers and MUST + conform to the rules defined in this specification. +
+ ++ These endpoints minimally require support for GET and POST operations. The DELETE operation + is RECOMMENDED. Other operations MAY be supported. +
+ ++ These endpoints MUST support the JSON-LD serialization defined in + for both request and response payloads. Servers + MAY support additional serializations. +
+ +
+ An agent creates an access request by submitting a POST request to the
+ access request endpoint. A storage controller creates an access grant by
+ submitting a POST request to the access grant endpoint.
+
+ A successful POST operation MUST respond with a Location header set to
+ the URL of the new resource.
+
POST / — Create an access request.GET / — Retrieve a list of access requests.GET /:id — Retrieve a specific access request.DELETE /:id — Cancel an access request.POST / — Create an access grant.GET / — Retrieve a list of access grants.GET /:id — Retrieve a specific access grant.DELETE /:id — Revoke an access grant.+ This section needs to align with the yet-to-be-defined notification section of LWS. +
+ +
+ Notifications provide a mechanism for informing agents and storage controllers about changes to
+ access requests and access grants. When an inbox property is
+ present on an access request or access grant, the server SHOULD deliver
+ notifications to that endpoint, informing an
+ assignee of the event.
+
+ The serialization of notifications MUST conform to the requirements of the LWS + notification data model. +
+ +
+ Notifications delivered to an inbox endpoint MUST conform to the
+ requirements defined in the LWS protocol for notification delivery.
+
+ The notification mechanism described in this section is comparable to the
+ [[LDN|Linked Data Notifications]] pattern, in which notifications are discovered
+ via an inbox property and delivered by sending a POST
+ request to that inbox.
+
+ A server SHOULD send notifications in response to the following events: +
+ +inbox specified in
+ the associated access request.
+ + A server MAY send notifications in response to other events. +
+