[@@ from charter]

The Linked Web Storage Protocol specification aims to provide applications with secure and permissioned access to externally stored data in an interoperable way.

The Linked Web Storage Protocol does/does not include protocol details for integration with identity layers and mechanisms; access management and data integrity; notifications about resource changes; and authorization mechanisms.

This is an unofficial proposal.

Introduction

This specification defines the Linked Web Storage (LWS) Protocol, which enables client applications to access and manage web resources, based on the identity and permissions of an agent.

By standardizing how a resource server manages and provides access to a hierarchy of linked resources, the protocol enables users to use different client applications to interact with the same stored data. These linked resources are defined through containers and containment relationships that describe where things are located, and metadata that describes how the resources relate to each other.

The protocol defines standard operations on these resources to create, read, update, and delete. Each resource is identified by a URI. A client navigates the resource hierarchy from a root container, discovering contained resources and their relations through links provided in server responses.

A agent's identity is confirmed through an identity provider that can be external to the Linked Web Storage server. This loose coupling means the server does not necessarily manage credentials directly; rather, it can receive and validate a signed authentication credential as a token issued by a trusted identity provider. A user can therefore present an existing identity to a compliant server, without always needing a new or existing account just for that server. LWS makes use of user authentication as defined in specifications for OpenID Connect, SAML 2.0, and self-signed controlled identifiers (CIDs), for example.

Authorization determines whether a requesting agent has permission to access a resource or perform an operation on it. A compliant LWS server designates a resource manager for each resource that determines whether a resource is private (i.e., available only to its owner), restricted (i.e., available to a defined set of users), or public (i.e., available to any user). The server enforces the access decisions of the resource manager when handling each client request.

This specification is intended to be used by:

• Developers building client applications that access LWS resources
• Developers building compliant servers that mediate access to LWS resources

Different LWS server instances each maintain their own hierarchy of linked resources. An agent might use the same identification to navigate across servers, with access to each server's resources determined by the permissions granted by that server's resource managers. It is not guaranteed that every LWS server instance will support every possible agent identifier; any given LWS server instance might require that an agent identify itself via a particular identity provider, to gain access to resources managed by that server instance.

Scope Diagrams

The following diagrams are platform-independent models to guide implementation.

Terminology

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 specification defines the following terms:

• agent — a person, social entity, or software identified by a URI.
• authentication credential — a security token that asserts claims about an agent or end-user. This token is secured with a cryptographic proof. Examples of authentication credentials include assertions of identity such as OpenID Connect ID Tokens and SAML-based assertions as well as assertions of capability such as ZCAPs.
• authentication suite — a defined validation mechanism for a concrete serialization of an authentication credential.
• auxiliary resource — an LWS resource that plays a particular role with respect to a LWS resource, called its primary resource, and whose lifetime is bound to the primary resource. This specification defines linkset resource and metadata resource as types of auxiliary resources, but LWS Servers are free to manage additional kinds of auxiliary resources (e.g. access control resources, notification inboxes). Auxiliary resources are discovered using web links [[RFC8288]] of a specific type (see Section ). Some auxiliary resources may, in some implementations, be identical to their primary resource.
• LWS resource — an HTTP resource as defined in [[[RFC9110]]] which supports the read operations defined by the Linked Web Storage Protocol. Following [[[RFC9110]]], this specification "does not limit the nature of a [LWS] resource; it merely defines an interface that might be used to interact with [LWS] resources." [[RFC9110]]
• container — an LWS resource that is able to enumerate a collection of LWS resources, conforming to the conventions described in Section 8. Containers. The ability to create new resources in a container or to delete an existing container follows the requirements outlined in Section 9. Operations.
• data resource — a data-bearing LWS resource such as a document, image, or structured information whose support for update and delete operations follows the requirements outlined in Section 9. Operations.
• containment — the relationship between a container and the LWS resources whose lifecycle the container manages.
• linkset resource — a type of auxiliary resource whose representation conforms to [[[RFC9264]]]. Update operations for linkset resources follow the requirements outlined in Section 9. Operations.
• metadata resource — an auxiliary resource, managed by a storage, that describes an LWS resource and conforms to the conventions described in TBD. The lifecycle of a metadata resource is bound to the LWS resource it describes.
• resource — a resource is, as described by [[WebArch]] and [[RFC3986]], “whatever might be identified by a URI”. Resources whose essential characteristics can be conveyed in a message (such as web pages, images, structured data objects...) are called information resources [[WebArch]].
• storage — a set of hierarchically organized HTTP resources whose lifecycle is managed by the conventions described by the Linked Web Storage Protocol. A storage is described by a storage description resource which references a collection of services that provide affordances over those resources.
• storage controller — an agent that controls all resources in a storage.
• storage description — an LWS resource, conforming to the requirements of a W3C Controlled Identifier document [[!CID-1.0]], that describes a storage along with its services and capabilities.
• storage root — a container at the root of a containment hierarchy of a storage. The storage root is the only LWS resource that does not have a parent in the LWS containment hierarchy nor a primary resource.
• notification — a message describing an event that has occurred on a resource.
• subscription — a registration expressing interest in receiving notifications for a given resource or set of resources.
• subscriber — the agent that creates a subscription and receives the resulting notifications.
• notification suite — a defined delivery mechanism for a concrete channel through which notifications are sent to a subscriber.

Authentication

Authorization

Discovery

Logical Resource Organization

Containers

Operations

Notifications

Access Requests and Grants

LWS Media Type

JSON-LD Context

Resource Identification

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

Portability Considerations

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