LWS Protocol

respec docs
CG report - 2024-05-12
Editor's draft - 2025-04-12
CG-to-ED delta:
- + Previous editors: Added formal past editors section recognizing Justin Bingham, Dmitri Zagidulin, Sarven Capadisli, Tim Berners-Lee and Ruben Verborgh
- + HTTP Server MUST generate a Last-Modified header field in response to GET and HEAD requests.
- ~~- The PATCH ?insertions formulae MUST NOT contain blank nodes.~~
- + IANA Reg Security Considerations: Servers are strongly encouraged to implement additional security measures…
- + IANA Reg Privacy Considerations: Servers are encouraged to respond with the 451 status code…

Reference UCS Glossary for now to keep them in sync.
Include REST examples but keep spec abstract to:
- provide intuitive names for states, operations, and responses
- factor states, operations and responses so e.g. update resource responses are the same from HTTP PATCH or from HTTP PUT
- enable alternate bindings.
I like to have a marker (e.g. left-border) to highlight informative regions, but it's pretty ugly.

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 , 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 terms "authorization server" and "client" are defined by the OAuth 2.0 Authorization Framework [ RFC6749 ].

The terms "end-user" and "issuer" are defined by OpenID Connect Core 1.0 [ OPENID-CONNECT-CORE ].

This specificaiton defines the following terms:

end-user credential — a security token that asserts claims about an end-user. This token is secured with a cryptographic proof.
authentication suite — a defined validation mechanism for a concrete serialization of an end-user credential.

This specification defines operations on served resources , the resulting change of state, and a response indended to give the requesting agent requested infomation or inform them of the outcome of the operation . An operation is any of the following actions that can be performed on a served resource :

create resource -
read resource -
update resource -
delete resource -

The folowing section will describe the semantics and responses of these operations but the following core responses apply to any operation:

success - the operation is believe to have completed. This may be accompanied by a resource representation conveying the contents of a served resource . A success response is not defined for the create resource operation. See instead created .
not permitted
unknown requester
unknown error - reserved for error conditions that arrise that are not anticipated by the specification

This section defines a mechanism for identifying agents and end users that interact with a linked web storage server. This specification does not mandate a particular format for end-user credentials, though it does describe how existing identity systems can be used in conjunction with the linked web storage authorization framework.

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.

Linked Web Storage describes a mechanism for persisting and managing protected data on the Web. Authorization is the mechanism by which agents request and present access tokens in order to access this protected data.

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.

All protected resources managed by a storage server require a valid access token, generated by a trusted authorization server. A client can discover the location of a trusted authorization server by making an unauthorized HTTP request to a protected resource.

A storage server generating a 401 (Unauthorized) response MUST send a WWW-Authenticate header field containing at least one conforming challenge. A conforming challenge will include the parameters described below:

as_uri REQUIRED — The value of this parameter is an absolute URI identifying the authorization server where a client can retrieve an access token. The value of this parameter will be the same as the iss claim of a valid access token.
realm REQUIRED — The value of this parameter is an absolute URI indicating the scope of protection. This value will be included in the audience ( aud ) claim of an access token. A client MUST verify that the URI of the originating request is logically contained within the realm presented in this response.

Other headers and parameters MAY be included.

An example 401 response is included below.

Example 1

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

error=

"invalid_token"

An authorization server MUST provide a metadata resource to allow clients to discover endpoint locations and capabilities as described in [ RFC8414 ]. This metadata resource MUST be available at a URL with the path /.well-known/lws-configuration.

An authorization server SHOULD advertise the subject tokens that it supports by including a subject_token_types_supported entry in the server metadata document. This entry is a JSON array containing a list of valid subject_token_type values that can be supplied at the authorization server's token endpoint.

An example authorization server metadata resource is included below.

Example 2

{
    "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"]

}

An LWS authorization server is a conforming OAuth 2.0 authorization server, capable of issuing access tokens to a client for use with a storage server. In order to issue an access token, a client must first present a valid subject token, such as an end-user credential, to the authorization server via OAuth 2.0 Token Exchange [ RFC8693 ].

The authorization server's token endpoint MUST support the urn:ietf:params:oauth:grant-type:token-exchange grant type, as described in OAuth 2.0 Token Exchange [ RFC8693 ].

When performing the token exchange grant type, the following additional requirements apply:

The resource parameter is REQUIRED . The value of this parameter MUST be an absolute URI and will be used to populate the aud (audience) claim in the resulting access token. The supplied value will be the same as the realm parameter response in a WWW-Authenticate challenge. The authorization server MUST reject any request in which the resource parameter identifies an unknown or untrusted storage.
The subject_token parameter is REQUIRED . The value of this parameter MUST include a valid subject token, such as an end-user credential.
Before returning an access token to the client, the authorization server MUST successfully validate all presented tokens.

Non-normative example of a token request (the subject_token parameter has been truncated).

Example 3

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

If the token request is valid and the client is authorized to make the request, the authorization server response MUST conform to Section 5.1 from the OAuth 2.0 Authorization Framework [ RFC6749 ]. The resulting access token MUST conform to the JSON Web Token Profile for OAuth 2.0 Access Tokens [ RFC9068 ].

In addition, the access token must meet the following requirements:

sub (subject) — REQUIRED . This claim MUST be an absolute URI identifying the agent performing the operation
iss (issuer) — REQUIRED . This claim MUST be the absolute URI of the authorization server
client_id (client id) — REQUIRED . This claim MUST be an absolute URI identifying the client.
aud (audience) — REQUIRED . This claim MUST include the absolute URI supplied by the client in the resource parameter. This value will be used to restrict the entities for which the access token is valid. This will be the same value as provided by a storage server in the realm parameter of a WWW-Authenticate challenge.
exp (expiration) — REQUIRED . Authorization servers SHOULD issue tokens with short lifetimes ( RECOMMENDED : 300 seconds or less) to limit exposure from token theft.
iat (issued at) — REQUIRED .
jti (JWT ID) — REQUIRED .

A non-normative example of a successful token response is included below.

Example 4

HTTP/1.1 200 OK
Content-Type: application/json
{
    "access_token":"eyJ0eXAiOiJhcytqd3QiLCJhbGciOiJFUzI1NiIs...DeWt4QuZXso",
    "token_type":"Bearer",
    "expires_in":3600

}

All invalid or unauthorized requests MUST result in an error response as described in Section 5.2 in the OAuth 2.0 Authorization Framework [ RFC6749 ].

Example 5

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error":"invalid_request"

}

This section is non-normative.

An example access token issued by an authorization server is included below.

Example 6

{
  "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

Once a client is in possession of an access token, it will present this token to a storage server. The storage server is responsible for verifying this token before performing any operation.

A client MUST present an access token to a storage server using the Authorization header with an authentication scheme as defined in [ RFC6750 ].

Example 7



Authorization

:

Bearer
eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...

A storage server MUST validate an access token by performing the following checks, rejecting the request upon any failure:

JWT Signature Validation: Verify the JWT signature using the authorization server's public key retrieved from the jwks_uri specified in the authorization server metadata. Storage servers SHOULD cache these keys and MUST support key rotation.
Issuer Validation: Verify the iss claim matches the expected authorization server identifier.
Audience Validation: Verify the aud claim contains exactly one value and this value is an absolute URI identifying the storage server which logically contains the target resource.
Temporal Validation, subject to an allowable clock skew between systems.
- Verify the current time is before the exp (expiration) claim.
- Verify the current time is not before the nbf (not before) claim, if present.
- Verify that the iat (issued at) claim is not in the future.

If validation fails, the storage server MUST return 401 Unauthorized with a WWW-Authenticate header containing an appropriate error parameter (e.g., invalid_token, invalid_request, or insufficient_scope).

If the token is otherwise valid but an authorization policy does not allow the requested operation, the storage server MUST reject the request.

Define how requesting agents discover served resources and their capabilities.

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 the data model for logical resource organization within LWS, including how containers are structured, hierarchical relationships between resources, container semantics, containment rules, and the mechanisms for organizing and navigating collections of related resources. This should cover container creation, membership management, and the relationship between containers and the resources they contain.

This strawman mapping of the operations and responses defined above allows LWS REST Servers and LWS REST Clients to communicate over HTTP using REST conventions.

The following table maps LWS response to an HTTP status code and payload:

LWS response	HTTP status code	HTTP payload
success	200	resource representation
not permitted	...
unknown requester	...
unknown error	...
created	201

Define how resources are identified and addressed within the LWS Protocol, including URI schemes, resource naming conventions, and resolution mechanisms. This section may be moved within another section; e.g. Resource Access

this left intentionally blank

The features described in this section are being drafted to ground discussions and may be removed if there is:

Lack of consensus to include them, or
Lack of implementation of those features

this left intentionally blank

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

Describe considerations for ensuring LWS implementations can work across different platforms, environments, and storage backends while maintaining interoperability - and provide affordances to enable change in storage providers

this left intentionally blank

Formal security considerations section covering threat models, security requirements, and implementation guidance for secure LWS deployments.

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.

An Authorization Server implementation MUST support TLS. When using TLS, the client MUST perform a TLS/SSL server certificate check, per RFC 6125 [ RFC6125 ]. Implementation security considerations can be found in "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)" [ BCP195 ].

Bearer tokens are vulnerable to theft and replay. Required mitigations include:

Short Lifetimes: Tokens SHOULD have lifetimes of 300 seconds (5 minutes) or less
Audience Binding: Tokens MUST be bound to a specific storage server via the aud claim
Secure Storage: Clients MUST store tokens securely in memory when possible, never in localStorage, URLs, or logs

End-user credentials with unrestricted audiences MUST NOT be provided to untrusted authorization servers.

If an end-user credential issuer is unable to restrict the audience of a token, clients SHOULD use a mechanism such as OAuth 2.0 Token Exchange [ RFC8693 ] to create audience-restricted credentials before interacting with authorization servers.

Privacy implications of the LWS Protocol, including data minimization, user consent, and privacy-preserving implementation patterns.

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.

This specification adds the following value to the "Well-Known URIs" registry [ IANA.well-known ] established by RFC 5785 [ RFC5785 ].

URI suffix: lws-configuration
Change controller: W3C
Specification document: Section 5 of LWS-Auth
Related information: (none)

This specification adds the following value to the "OAuth Authorization Server Metadata" registry [ IANA.OAuth.Parameters ] established by [ RFC8414 ].

Metadata Name: token_subject_types_supported
Metadata Description: JSON array containing a list of the OAuth 2.0 "token_subject_type" values that this authorization server supports
Change Controller: W3C
Specification Document(s): Section 5 of LWS-Auth

[BCP195]: Reference not found.
[OPENID-CONNECT-CORE]: OpenID Connect Core 1.0 incorporating errata set 2 . N. Sakimura; J. Bradley; M. Jones; B. de Medeiros; C. Mortimore. OpenID Foundation. 15 December 2023. Final. URL: https://openid.net/specs/openid-connect-core-1_0.html
[RFC2119]: Key words for use in RFCs to Indicate Requirement Levels . S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC6125]: Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS) . P. Saint-Andre; J. Hodges. IETF. March 2011. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6125
[RFC6749]: The OAuth 2.0 Authorization Framework . D. Hardt, Ed. IETF. October 2012. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6749
[RFC6750]: The OAuth 2.0 Authorization Framework: Bearer Token Usage . M. Jones; D. Hardt. IETF. October 2012. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6750
[RFC8174]: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words . B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[RFC8414]: OAuth 2.0 Authorization Server Metadata . M. Jones; N. Sakimura; J. Bradley. IETF. June 2018. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc8414
[RFC8693]: OAuth 2.0 Token Exchange . M. Jones; A. Nadalin; B. Campbell, Ed.; J. Bradley; C. Mortimore. IETF. January 2020. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc8693
[RFC9068]: JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens . V. Bertocci. IETF. October 2021. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc9068
[rfc9112]: HTTP/1.1 . R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed. IETF. June 2022. Internet Standard. URL: https://httpwg.org/specs/rfc9112.html
[RFC9700]: Best Current Practice for OAuth 2.0 Security . T. Lodderstedt; J. Bradley; A. Labunets; D. Fett. IETF. January 2025. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc9700

[IANA.OAuth.Parameters]: Reference not found.
[IANA.well-known]: Reference not found.
[RFC5785]: Defining Well-Known Uniform Resource Identifiers (URIs) . M. Nottingham; E. Hammer-Lahav. IETF. April 2010. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc5785

LWS Protocol

Abstract

Status of This Document

For Editors

Resources

Tactics

1. Document Conventions

2. Introduction

2.1 Resource Access

2.2 Security and Privacy

2.3 Conformance

3. Terminology

4. Authentication

4.1 End-User Credential Data Model

4.2 End-User Credential Validation

4.3 End-User Credential Type Identifiers

5. Authorization

5.1 Roles

5.2 Protocol Flow

5.2.1 Authorization Server Discovery

5.2.2 Authorization Server Metadata

5.2.3 Token Exchange

5.2.3.1 Request

5.2.3.2 Response

5.2.3.3 Example access token

5.2.4 Token Validation by a Storage Server

5.2.4.1 Presentation

5.2.4.2 Validation

6. Discovery

7. Operations

7.1 create resource

7.2 read resource

7.3 update resource

7.4 delete resource

8. Logical Resource Organization

9. REST Binding

10. Resource Identification

11. Unstable Features

11.1 Profile Negotiation on Resources

11.2 Notifications

11.3 Inbox

12. Portability Considerations

13. Security Considerations

13.1 Authentication Security

13.2 Authorization Security

13.2.1 Transport Security

13.2.2 Token Security

13.2.3 End-User Credential Protection

14. Privacy Considerations

14.1 Authentication Privacy

14.2 Authorization Privacy

15. IANA Considerations

15.1 well-known URI Registry

15.2 OAuth Authorization Server Metadata Registry

A. References

A.1 Normative references

A.2 Informative references