diff --git a/lws10-core/diagrams/README.md b/lws10-core/diagrams/README.md new file mode 100644 index 0000000..959df4b --- /dev/null +++ b/lws10-core/diagrams/README.md @@ -0,0 +1,62 @@ +# Diagrams + +The figures in this folder are generated from `../lws10-core.c4`, a +[LikeC4](https://likec4.dev) model of the specification's architecture. Do not +edit the `.svg` files directly — edit the `.c4` source and regenerate. + +None of the tooling below should be installed inside this repository. Everything +is run from a separate folder on your own machine; only the resulting `.svg` +files ever get committed here. + +## Prerequisites + +- [Node.js](https://nodejs.org) (for `npx`/`npm`) +- [Graphviz](https://graphviz.org) — provides the `dot` command + ```bash + brew install graphviz # macOS + apt-get install graphviz # Debian/Ubuntu + ``` + +No headless browser is required for this workflow — `dot` output goes straight +to real vector SVG. + +## 1. Install LikeC4 (outside this repo) + +Set up a scratch folder somewhere outside the repo, e.g. under your home +directory, and install LikeC4 there: + +```bash +mkdir -p ~/tools/likec4-tooling && cd ~/tools/likec4-tooling +npm init -y +npm install likec4 +``` + +You only need to do this once. Run every command below from inside +`~/tools/likec4-tooling`. + +## 2. Generate `.dot` files from the model +Your `lws-protocol` repo is at `/path/to/` +``` +export DOTPATH=/path/to/lws-protocol +``` + +And we need to delete the index.dot because we don't need it. +```bash +npx likec4 gen dot $DOTPATH/lws10-core/diagrams +rm $DOTPATH/lws10-core/diagrams/index.dot +``` + +This reads `lws10-core.c4` and writes one `.dot` file per view into `diagrams/`, +named after the view id (e.g. `fig-container-diagram.dot`). These files carry the +model's actual layout parameters and theme color. + +## 3. Render `.dot` → `.svg` + +```bash +cd $DOTPATH +for f in *.dot; do + dot -Tsvg "$f" -o "./$(basename "${f%.dot}").svg" +done +``` + +This writes the SVGs directly into this `diagrams/` folder. diff --git a/lws10-core/diagrams/fig-container-diagram.dot b/lws10-core/diagrams/fig-container-diagram.dot new file mode 100644 index 0000000..e57be85 --- /dev/null +++ b/lws10-core/diagrams/fig-container-diagram.dot @@ -0,0 +1,143 @@ +digraph { + graph [TBbalance=min, + bgcolor=transparent, + compound=true, + fontname=Arial, + fontsize=20, + labeljust=l, + labelloc=t, + layout=dot, + likec4_viewId="fig-container-diagram", + nodesep=1.528, + outputorder=nodesfirst, + pad=0.209, + rankdir=TB, + ranksep=1.667, + splines=spline + ]; + node [color="#2563eb", + fillcolor="#3b82f6", + fontcolor="#eff6ff", + fontname=Arial, + penwidth=0, + shape=rect, + style=filled + ]; + edge [arrowsize=0.75, + color="#8D8D8D", + fontcolor="#C9C9C9", + fontname=Arial, + fontsize=14, + penwidth=2, + style="" + ]; + subgraph "cluster_lws-server" { + graph [color="#0d374e", + fillcolor="#0f4460", + label=<LWS SERVER>, + likec4_depth=2, + likec4_id="lws-server", + likec4_level=0, + margin=40, + style=filled + ]; + subgraph "cluster_resource-server" { + graph [color="#0b3c57", + fillcolor="#0d4b6c", + label=<RESOURCE SERVER>, + likec4_depth=1, + likec4_id="lws-server.resource-server", + likec4_level=1, + margin=32, + style=filled + ]; + storage [color="#0369a1", + fillcolor="#0284c7", + fontcolor="#f0f9ff", + height=2.5, + label=<
Storage
A set of hierarchically organized HTTP
resources managed per LWS conventions
>, + likec4_id="lws-server.resource-server.storage", + likec4_level=2, + margin="0.223,0.223", + width=4.445]; + } + "authorization-server" [color="#0369a1", + fillcolor="#0284c7", + fontcolor="#f0f9ff", + height=2.5, + label=<
Authorization Server
An OAuth 2.0 authorization server that issues
access tokens. MAY be an external system
>, + likec4_id="lws-server.authorization-server", + likec4_level=1, + margin="0.223,0.223", + width=4.445]; + } + "lws-client" [color="#0369a1", + fillcolor="#0284c7", + fontcolor="#f0f9ff", + height=2.5, + label=<
LWS Client
An HTTP client that complies with the LWS
Protocol
>, + likec4_id="lws-client", + likec4_level=0, + margin="0.223,0.223", + width=4.445]; + "lws-client" -> "authorization-server" [arrowhead=normal, + label=<
requests access token
>, + likec4_id="9zky4r", + style=solid]; + "identity-provider" [color="#0369a1", + fillcolor="#0284c7", + fontcolor="#f0f9ff", + height=2.5, + label=<
Identity Provider
Confirms user identity and issues signed
credentials. MAY be an external system
>, + likec4_id="identity-provider", + likec4_level=0, + margin="0.223,0.223", + width=4.445]; + "lws-client" -> "identity-provider" [arrowhead=normal, + label=<
authenticates
>, + likec4_id=ydrjak, + style=solid, + weight=2]; + "lws-client" -> storage [arrowhead=normal, + lhead="cluster_resource-server", + likec4_id="1mtvne", + minlen=1, + style=solid, + xlabel=<
sends request
>]; + "controlled-identifier" [color="#0369a1", + fillcolor="#0284c7", + fontcolor="#f0f9ff", + height=2.5, + label=<
Controlled Identifier
An identifier that is controlled by an agent
and used to identify the agent to the LWS
system
>, + likec4_id="controlled-identifier", + likec4_level=0, + margin="0.223,0.223", + width=4.445]; + "authorization-server" -> "controlled-identifier" [arrowhead=normal, + label=<
verifies identity provider
>, + likec4_id="19toz03", + style=solid]; + "authorization-server" -> "identity-provider" [arrowhead=normal, + label=<
validates credentials
>, + likec4_id=lkcm0d, + style=solid]; + agent [color="#525252", + fillcolor="#737373", + fontcolor="#fafafa", + height=2.5, + label=<
Agent
An agent of the LWS system
>, + likec4_id=agent, + likec4_level=0, + margin="0.223,0.223", + width=4.445]; + "controlled-identifier" -> agent [arrowhead=normal, + label=<
identifies
>, + likec4_id="123ygk7", + style=solid, + weight=2]; + agent -> "lws-client" [arrowhead=normal, + label=<
agent requests
>, + likec4_id=u6f8pb, + style=solid, + weight=2]; +} diff --git a/lws10-core/diagrams/fig-container-diagram.svg b/lws10-core/diagrams/fig-container-diagram.svg new file mode 100644 index 0000000..1796dbe --- /dev/null +++ b/lws10-core/diagrams/fig-container-diagram.svg @@ -0,0 +1,125 @@ + + + + + + + +cluster_lws-server + +LWS SERVER + + +cluster_resource-server + +RESOURCE SERVER + + + +storage + +Storage +A set of hierarchically organized HTTP +resources managed per LWS conventions + + + +authorization-server + +Authorization Server +An OAuth 2.0 authorization server that issues +access tokens. MAY be an external system + + + +lws-client + +LWS Client +An HTTP client that complies with the LWS +Protocol + + + +identity-provider + +Identity Provider +Confirms user identity and issues signed +credentials. MAY be an external system + + + +controlled-identifier + +Controlled Identifier +An identifier that is controlled by an agent +and used to identify the agent to the LWS +system + + + +agent + +Agent +An agent of the LWS system + + + +authorization-server->identity-provider + + + +validates credentials + + + +authorization-server->controlled-identifier + + + +verifies identity provider + + + +lws-client->storage + + + +sends request + + + +lws-client->authorization-server + + + +requests access token + + + +lws-client->identity-provider + + + +authenticates + + + +controlled-identifier->agent + + + +identifies + + + +agent->lws-client + + + +agent requests + + + diff --git a/lws10-core/diagrams/lws10-core.c4 b/lws10-core/diagrams/lws10-core.c4 new file mode 100644 index 0000000..5288ea4 --- /dev/null +++ b/lws10-core/diagrams/lws10-core.c4 @@ -0,0 +1,71 @@ +specification { + + element actor { + style { + shape person + opacity 50% + color gray + } + } + element component { + style { + border solid + color secondary + } + } + + relationship manages { + color gray + line solid + } +} + +model { + agent = actor 'Agent' { + description 'An agent of the LWS system' + } + + component lws-client 'LWS Client' { + description 'An HTTP client that complies with the LWS Protocol' + } + component controlled-identifier 'Controlled Identifier' { + description 'An identifier that is controlled by an agent and used to identify the agent to the LWS system' + } + component identity-provider 'Identity Provider' { + description 'Confirms user identity and issues signed credentials. MAY be an external system' + } + component lws-server 'LWS Server' { + description 'An HTTP server that complies with the LWS Protocol' + + component authorization-server "Authorization Server" { + description 'An OAuth 2.0 authorization server that issues access tokens. MAY be an external system' + } + component resource-server 'Resource Server' { + description 'Manages data resources, containers, containment and linksets' + component storage 'Storage' { + description 'A set of hierarchically organized HTTP resources managed per LWS conventions' + style { + multiple true + } + } + } + } + + // To use your custom rules, swap '->' for your defined triggers: + agent .manages lws-client 'agent requests' + controlled-identifier .manages agent 'identifies' + lws-client .manages lws-server 'HTTP requests' + lws-client .manages identity-provider 'authenticates' + lws-client .manages authorization-server 'requests access token' + lws-client .manages resource-server 'sends request' + authorization-server .manages controlled-identifier 'verifies identity provider' + authorization-server .manages identity-provider 'validates credentials' +} + +views { + view fig-container-diagram of lws-server { + title 'Container Diagram' + autoLayout TopBottom + include *, identity-provider, agent, storage + } +} diff --git a/lws10-core/index.html b/lws10-core/index.html index 3da7ccd..12aa945 100644 --- a/lws10-core/index.html +++ b/lws10-core/index.html @@ -115,7 +115,29 @@

Document Conventions

Introduction

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

+

+ By standardising how an LWS server manages and provides access to a hierarchy of linked resources, the protocol enables users to use different LWS 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. Resources, their containment, and their metadata are managed by the server as a set of JSON-LD documents (and other representations). 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 user's identity is confirmed through an identity provider that can be external to the Linked Web Storage server. This separation means the server does not manage credentials directly; rather, it receives and validates a signed authentication credential as a token issued by a trusted identity provider. A user can therefore present their existing identity to any compliant server, without needing a new or existing separate account on that server. User authentication is defined in companion specifications for OpenID Connect, SAML 2.0, and self-signed controlled identifiers (CIDs). +

+

+ Authorization determines whether a requesting user 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:

+ +

+ Different compliant servers each maintain their own hierarchy of linked resources. A user can navigate across servers using the same identity, with access to each server's resources determined by the permissions granted by that servers resource managers. +

+

Resource Access

@@ -155,11 +177,25 @@

Security and Privacy

- A LWS 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 of this document MUST be respected. + An LWS 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 of this document MUST be respected.

-
+
+

Scope Diagrams

+

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

+
+ Figure: System Context shows the LWS System and its major components +
System Context shows the LWS System and its major components.
+
+ +
+ +

Terminology

@@ -207,7 +243,7 @@

Terminology

- This specification defines operations on served resources, the resulting change of state, and a response intended to give the requesting agent requested infomation or inform them of the outcome of the operation. + This specification defines operations on served resources, the resulting change of state, and a response intended to give the requesting agent requested information 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:

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