LWS Protocol

The LWS Protocol defines standard interactions by which a some party can make some resources available to some agents.

• served resource - (available resource? published resource?) (not defined in UCS) A network-accessible entity exposed by a service for interaction, retrieval, or manipulation using the protocol defined in this document.
• requesting agent - (entity in UCS) An entity (e.g., client, user, or process) that initiates a request to interact with a servable resource.

A resource manager may keep a served resource private, may make it publicly available to anyone, or may limited its visibility to a constrained set of requesting agents.

• authentication - the process of verifying the identity of an agent executing a request.
• authorization - the process of determining whether an agent has permission to access a specific resource or perform one of a set of operations.
• resource manager - (controller in UCS) An agent that has permission to control access to a served resource.

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

A LWS REST Server is an HTTP server [rfc9112] that complies with all of the relevant "MUST" statements in this specification. Specifically, the relevant normative "MUST" statements in Sections 999 REST Binding of this document MUST be respected.

A LWS REST Client is an HTTP client [rfc9112] that complies with all of the relevant "MUST" statements in this specification. Specifically, the relevant normative "MUST" statements in Sections 999 REST Binding of this document MUST be respected.

The data model described in this section outlines the requirements for any concrete serialization of an end-user credential.

An end-user credential MUST include tamper evident claims about a subject, including:

• subject REQUIRED — an identifier for an end user. This MUST be an absolute URI.
• issuer REQUIRED — an identifier for the entity that issued the end-user credential. This MUST be an absolute URI.
• client REQUIRED — an identifier for a client application. This SHOULD be an absolute URI.
• audience restriction RECOMMENDED — a list of values that SHOULD include an authorization server identifier.

Validation of an end-user credential requires a trust relationship between the verifier and issuer of the credential. This trust relationship MAY be established through an out-of-band mechanism. Any additional mechanisms for establishing trust between a verifier and an issuer are outlined in specific authentication suites.

An end-user credential MUST be signed. It is RECOMMENDED that the signature uses asymmetric cryptography.

Each authentication suite MUST be associated with a token type URI. An authentication suite SHOULD use a URI defined in the IANA "OAuth URI" registry.

The roles in LWS authorization are the same as those defined by OAuth 2.0 Section 1.1 [RFC6749]: resource owner, resource server, client (called in this specification authorization client to avoid ambiguity), and authorization server. A storage server is a type of resource server that also conforms to the LWS storage specification.

This specification describes the interaction between a client and an authorization server as well as the interaction between a client and a conforming storage server.

The interaction between the authorization server and the storage server is out of scope of this specification. The authorization server may be the same server as the storage server or it may be a separate entity.

HTTP/2 401 Unauthorized
Link: ; rel="storageDescription"
WWW-Authenticate: Bearer as_uri="https://authorization.example",
                realm="https://storage.example/storage_1",
                error="invalid_token"
    

{
    "issuer": "https://authorization.example",
    "grant_types_supported": [
        "urn:ietf:params:oauth:grant-type:token-exchange"],
    "token_endpoint": "https://authorization.example/token",
    "jwks_uri": "https://authorization.example/jwks",
    "claims_supported": [
        "sub",
        "iss",
        "client_id",
        "aud"],
    "response_types_supported": [
        "token"],
    "subject_token_types_supported": [
        "urn:ietf:params:oauth:token-type:jwt",
        "urn:ietf:params:oauth:token-type:id-token"]
}

POST /token HTTP/1.1
Host: authorization.example
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&resource=https%3A%2F%2Fstorage.example%2Fstorage_1
&subject_token=eyJ0eXAiOiJhcytqd3QiLCJhbGciO...fiK51VwhsxJ-siBMR-YFiA
&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aid_token

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token":"eyJ0eXAiOiJhcytqd3QiLCJhbGciOiJFUzI1NiIs...DeWt4QuZXso",
    "token_type":"Bearer",
    "expires_in":3600
}

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error":"invalid_request"
}

{
  "kid": "ec51c6b2",
  "kty": "EC",
  "alg": "ES256",
  "crv": "P-256",
  "typ": "at+jwt"
}
.
{
  "sub": "https://id.example/agent",
  "iss": "https://authorization.example",
  "client_id": "https://app.example/id",
  "aud": "https://storage.example",
  "exp": 1735686300,
  "iat": 1735686000,
  "jti": "550e8400-e29b-41d4-a716-446655440000"
}
.
signature

Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...

A storage description resource provides information a client can use when when interacting with a storage, including descriptions of capabilities and service endpoints.

{
  "@context": "https://www.w3.org/ns/lws/v1",
  "id": "https://storage.example/root/",
  "type": "Storage",
  "service": [{
    "type": "StorageDescription",
    "serviceEndpoint": "https://storage.example/root/description"
  }]
}

{
  "@context": "https://w3.org/ns/lws/v1.jsonld",
  "id": "https://storage.example/root/",
  "type": "Storage",
  "capability": [{
    "type": "https://feature.example/PatchSupport",
    "mediaType": {
      "text/turtle": ["application/sparql-update"],
      "application/n-triples": ["application/sparql-update"],
      "application/linkset+json": ["application/merge-patch+json", "application/json-patch+json"]
    }
  }, {
    "type": "https://feature.example/ResumableUploads"
  }, {
    "type": "https://feature.example/ContentNegotiation",
    "source": "application/ld+json",
    "target": ["text/turtle", "application/n-triples"]
  }, {
    "type": "https://feature.example/ContentNegotiation",
    "source": "image/jpeg",
    "target": ["image/png"]
  ],
  "service": [{
    "type": "NotificationService",
    "serviceEndpoint": "https://storage.example/notification/api"
  }, {
    "type": "TypeIndexService",
    "serviceEndpoint": "https://storage.example/types/api"
  }, {
    "type": "DataSharingService",
    "serviceEndpoint": "https://storage.example/sharing/api"
  }]
}

Create resource

In addition to the core responses, a create operation may produce any of:

• created - .
• more? worthy of a list?

The read resource operation requests a resource representation. Draw from Solid Protocol - Reading Resources.

The update resource modifies the contents of a served resource. Draw from Solid Protocol - Reading Resources.

Delete resource

Define mechanisms for content negotiation based on profiles, allowing clients to request specific representations or views of resources (e.g., JSON-LD contexts, different RDF serializations, or application-specific profiles).

this left intentionally blank

Define notification mechanisms that allow clients to be informed of changes to resources, including subscription models, event formats, and delivery mechanisms.

this left intentionally blank

Define inbox resources with specific semantics within LWS, including message posting, retrieval, and management capabilities for asynchronous communication patterns.

this left intentionally blank

All communications related to requesting, retrieving and presenting end-user credentials between clients and servers must use TLS-protected connections.

End-user credentials are vulnerable to theft and replay. Tokens should have a reasonably short lifetime, such as 3600 seconds (1 hour).

Clients that persist end-user credentials must take great care to store these tokens securely. Tokens should never be stored unencrypted in a browser's localStorage, in URLs or in logs.

The recommendations described in Best Current Practice for OAuth 2.0 Security [RFC9700] apply to this specification.

End-user credentials carry information about users. While digital signatures can protect end-user credentials against tampering, it is possible for clients or other third parties to read the values inside an unencrypted credential.

As a result, issuers should create end-user credentials that contain only the information necessary for authentication. Avoid including sensitive attributes unless required.

Implementations should not log the full contents of an end-user credential. If logging is necessary, tokens should be truncated or hashed.

Minimal Disclosure: Authorization servers should issue tokens containing only information necessary for authorization. Avoid including sensitive subject attributes unless required.

Logging: Implementations should not log full token contents. If logging is necessary, tokens should be truncated or hashed.

When using pseudonymous identifiers in JWTs, client applications should request a batch issuance of JWTs and each JWT should be used only one time against the storage server. This makes it harder for a storage server to use pseudonymous identifiers to correlate requests. This does not prevent the storage server from using other information such as similarities in JWT content or originating IP address to correlate requests. When using pseudonymous identifiers, the authorization server should not issue the same pseudonymous identifier more than once.