Add scope diagrams section with C4 Level 1 and Level 2 diagrams by jeremycaine · Pull Request #159 · w3c/lws-protocol

jeremycaine · 2026-05-15T17:20:09Z

Editorial - Clarify systems diagram (at least scope/system context; platform independent model)

laurensdeb · 2026-06-01T12:12:25Z

+  System(client, "Client application", "Requests and manages resources")
+  System(lws, "LWS server", "Manages resource hierarchy and access")
+  System_Ext(idp, "Identity provider", "Issues signed credentials")
+  System_Ext(ext, "External resources", "Web resources under management")


What do you mean by "external resources"? Are these the same as the "LWS resources" we defined in the terminology? If so, it might be best to re-use that term.

Suggested change

System_Ext(ext, "External resources", "Web resources under management")

System_Ext(ext, "LWS resources", "Web resources under management")

elf-pavlik · 2026-06-09T15:20:08Z

@jeremycaine In various projects I've been using https://likec4.dev/

There's even some work on embedding it in specs

Exploration: LikeC4 Diagramm solid/solid-oidc#251

relaxing as JSON-LD is not only media type Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

elaborate on private, public and restricted Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

point that an LWS account not required; plus CIDs Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

elf-pavlik · 2026-06-23T19:02:25Z

@jeremycaine you can see two different LikeC4 diagrams I've done for LWS in

Create Threat Model Note #177

Would you like to coordinate our diagramming efforts?

Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

acoburn

The LWS protocol intentionally does not have a notion of "external resources". I would remove references to external resources.

acoburn · 2026-06-29T17:37:26Z

+  Person(user, "User", "Person accessing resources")
+  System(client, "Client application", "Requests and manages resources")
+  System_Ext(idp, "Identity provider", "Issues signed credentials")
+  System_Ext(ext, "External resources", "Web resources under management")


Suggested change

System_Ext(ext, "External resources", "Web resources under management")

System_Ext(ext, "LWS resources", "Web resources under management")

acoburn · 2026-06-29T17:39:32Z

+    Container(authn, "Authentication", "Validates credential against identity provider")
+    Container(authz, "Authorization", "Enforces resource manager access decisions")
+    Container(rm, "Resource Management", "Manages containers, containment and linksets")
+    Container(era, "External Resource Access", "Mediates access to external web resources")


I would remove this line. The LWS protocol does not define any behavior to interact with "external resources"

acoburn · 2026-06-29T17:41:32Z

+  Boundary(lws, "LWS server") {
+    Container(authn, "Authentication", "Validates credential against identity provider")
+    Container(authz, "Authorization", "Enforces resource manager access decisions")
+    Container(rm, "Resource Management", "Manages containers, containment and linksets")


I would rephrase the description to be "Manages containers, metadata and data resources" (linksets are a particular type of metadata resource that don't need explicit mention)

acoburn · 2026-06-29T17:42:32Z

+  Rel(rm, era, "resolves resource")
+  Rel(era, ext, "accesses")
+```
+Issue: The internal organisation of container, containment, and linkset management within the LWS server is not yet defined in the protocol. This diagram reflects current terminology and is subject to revision.


The internal organization is intentionally not defined by the protocol -- that is an implementation detail. I would remove this line.

acoburn · 2026-06-29T17:43:43Z

+        </p>
+        <figure id="fig-1-system-context">
+          <img src="diagrams/fig-1-system-context.svg" 
+              alt="LWS Protocol system context diagram showing the user, client application, LWS server, identity provider, and external resources"/>


I would remove "external resources" from this description

acoburn · 2026-06-29T17:44:37Z

+        </p>
+        <figure id="fig-2-container-diagram">
+          <img src="diagrams/fig-2-container-diagram.svg"
+              alt="LWS Protocol container diagram showing authentication, authorization, resource management, and external resource access within the LWS server boundary"/>


Suggested change

alt="LWS Protocol container diagram showing authentication, authorization, resource management, and external resource access within the LWS server boundary"/>

alt="LWS Protocol container diagram showing authentication, authorization, and resource management within the LWS server boundary"/>

elf-pavlik · 2026-06-30T01:37:57Z

Following up in discussion I had with @jeremycaine after the WG call.

https://w3c.github.io/lws-protocol/lws10-core/#conformance

LWS core defines two classes of products

LWS Server
LWS Client

You can find various normative statements with Clients MUST, Clients MAY etc.

Given notifications, access requests / grants, indexes / search, more distinct classes of products may need to be defined. This would be out of scope for this PR but something to keep track of in next iterations.

I will be adjusting LikeC4 model for #177 to reference those classes of products. I also created

Clarify relation to classes of products / conformance classes in the spec(s) threat-modeling-guide#32

…rotocol into scope-diagrams

…/lws-protocol into introduction-section

elf-pavlik · 2026-07-10T15:26:09Z

@jeremycaine I think your new diagrams look great!

When I compare them to to

The main difference seems to be that you illustrate the special case where End-user == Resource Owner, so Alice is accessing her own data. While in my diagrams I'm illustrating the general case where End-user != Resource Owner, so for example Alice is accessing Bob's data (on bob.example), and Charlie's data (on charlie.example), and ACME data (on acme.example).

Most of the complexity comes with the general scenario, the special case of user accessing their own data could be achieved in much simpler ways.

elf-pavlik · 2026-07-10T22:42:58Z

+    lws-client -> identity-provider 'authenticates'
+    lws-client -> resource-manager 'sends request'
+    resource-manager -> authentication 'authenticates request'
+    authentication -> identity-provider 'validates credentials'


My comment is mostly about this interaction. In general case this happesn between Authorization Server of the Resource Owner and the IdP of the End-user. Showing it as 'internal' to the LWS Server can bring confusion instead of clarifying it.

You can see Step 10 and after on https://elf-pavlik.github.io/lws-auth/view/oidc/?dynamic=sequence
And F5 & F6 on https://github.com/hackers4peace/likec4-example-customization/blob/4542f2b7edc20549bbf2f856483dccc94a7bdb0f/likec4/lws.c4#L54-L55

@elf-pavlik questions and we need a plan to ack your points

I assume your lws-auth view is some initial thought on how this flow might work. Ok we can integrate, but:

we need to agree the named component list for the PR view fig3-lws-server-components.

I have Resource Manager, Authorization, Authentication, Identity Provider.

You have Resource Authorization Server and Resource Server; plus User Authorization Server / IdP.

shouldn't IdP identity provide be for only authentication and not authorization?

Identity Provider (in my diagram) is internal to LWS server, but as we have stated in Introduction it could be either internal to scope of LWS Server or outside. The challenge is how to show that optionality. Perhaps that means we need to show IdP (internal) and IdP (external).

An LWS Client can authenticate with IdP (internal or external).

elf-pavlik · 2026-07-13T13:41:00Z

https://www.w3.org/2024/09/linked-web-storage-wg-charter.html#scope

This protocol will ensure interoperability between compliant user applications, and compliant storage and identity servers, thus giving users the freedom to select the applications and services that suit their needs.

The main challenge and resulting complexity comes from that loose coupling and interaction happening across independent security domains. I find it very important that this is reflected on the diagrams.

While implementations/deployments can adopt more monolith/collocated approaches. The protocol itself enables interop between autonomous systems and IMO we should be emphasising it's user centric design.

…rotocol into scope-diagrams

jeremycaine · 2026-07-23T16:02:59Z

In the working session today - 23 Jul 2026 - we reduced the the model and therefore the diagrams to a simpler set. This enables the PR to merge and we move on to other discussions, which will then update the diagrams in future PRs.

Points of the meeting

storage server terminology should become resource server (@jeswr )
with a base model in place, @elf-pavlik can build his threat model detail on this one
recognise that resource manager can manage multiple resources, but the relationships and hierarchy of resource (data resource, auxilliary etc is still being discussed) - therefore remove from model and diagrams for now

elf-pavlik

I'm happy to merge it without my suggestions and follow up with a PR myself proposing them right away. Not sure if github can do stacked PRs from multiple contributors 🤔 - in a way that both show up in this repo as PRs - this may require working on branches here rather than forks. (tools like Git Butler, Graphite etc. make stacking pretty easy)

Currently I would only keep fig-container-diagram.png, possibly fig-resource-server.png which will be just two nested boxes (inner style.multiple). fig-srorage.png could be separate PR from @jeremycaine

elf-pavlik · 2026-07-23T21:30:19Z

@jeremycaine I have a example with a single diagram that could replace the three in this PR (except storage which is for next PR)

preview: https://playground.likec4.dev/share/h0nM-I-NM9/view/fig-container-diagram/
source: fork button

Co-authored-by: elf Pavlik <elf-pavlik@hackers4peace.net>

bring Storage as a component inside scope of Resource Manager Co-authored-by: elf Pavlik <elf-pavlik@hackers4peace.net>

jeremycaine · 2026-07-27T10:01:45Z

@jeremycaine I have a example with a single diagram that could replace the three in this PR (except storage which is for next PR)

preview: https://playground.likec4.dev/share/h0nM-I-NM9/view/fig-container-diagram/

source: fork button

done - and then that actually removes the need for the resource manager diagram. everything for now in this PR can be shown in one diagram.

elf-pavlik · 2026-07-27T13:39:21Z

@jeremycaine I think you still may need to

re-export fig-container-diagram.png
delete index.png
remove commented out lines in .c4 and reindent it

TallTed · 2026-07-27T13:39:52Z

Looking at fig-system-context.png — Is there a justification for the shading of the shape detail texts? I think all text should be white, just like the primary titles, for FAR better contrast and visibility for all viewers, not only those with optical challenges.

I noted this looking at the single image linked above, but I think it equally valid for other images with shaded text. Generally speaking, such text should be simply black or white, regardless of the color behind it, choosing between these based on the stronger contrast value.

I'm also wondering why the arrows are all the same dotted line. Usually, dotted lines are used to show a different sort of connection than solid lines ... but there are no solid lines here, so I don't know why these lines aren't solid.

TallTed · 2026-07-27T13:45:42Z

Looking at fig-resource-server.png — Why is there a shadow-box behind the Storage block, but not the LWS Client nor the Resource Server? Given the title of this image, if one of these is to be highlighted, I would expect the Resource Server, not the Storage... Please explain/justify?

I'm also wondering why the arrows are all the same dotted line. Usually, dotted lines are used to show a different sort of connection than solid lines ... but there are no solid lines here, so I don't know why these lines aren't solid.

elf-pavlik · 2026-07-27T13:50:04Z

@TallTed storage has applied multiple style https://likec4.dev/dsl/styling/#multiple
Once the PR is merged would you like to take the .c4 file and work on fine tuning the styles to follow your suggestions. You could even paste it in LikeC4 playground and just work on it there.

TallTed · 2026-07-27T14:02:06Z

Looking at fig-storage.png —

The various line styles (including the outline of the large shaded block) don't seem to communicate anything that is not communicated by some other means. Are they meant to? If yes, (maybe that's in the nearby text) the image could benefit by some legend. If not, perhaps they should all be made solid/simple.
It seems that "bound to primary resource" is meant to apply to one of the nearby lines, but it's not clear which. This should be moved, perhaps simply atop the relevant line.
The shaded text again should be solid black or white.
It's confusing that the line from Auxiliary Resource to Metadata Resource goes outside the big shaded box. If it doesn't need to, I would adjust whatever placements bring it inside, just like all the other nearby lines.
The arrowed lines are obviously directional. What about the non-arrowed lines? These connections are confusing.

TallTed · 2026-07-27T14:05:46Z

[@elf-pavlik] @TallTed storage has applied multiple style https://likec4.dev/dsl/styling/#multiple
Once the PR is merged would you like to take the .c4 file and work on fine tuning the styles to follow your suggestions. You could even paste it in LikeC4 playground and just work on it there.

I can try. I've never used c4. (I have many years experience with layout and graphic tools for press-printing like Freehand, Quark XPress, and friends. These have mostly been superior to the various "direct to web" tools ... but who knows?)

w3cbot · 2026-07-27T14:59:34Z

This was discussed during the #lws meeting on 27 July 2026.

View the transcript

Vote: LWS Diagrams PR#159

jeremycaine: there were some issues with git push, not all images are correct
… TallTed has some comments on styles

TallTed: sorry I couldn't get to it sooner
… there are bunch of comments on the style
… is there an intent to change pngs to svg?
… partly because that we will need to figure out textual description to satisfy accessibility

jeremycaine: I didn't add any of that just used default rendering
… do we want to merge it and fix styles later

<Zakim> acoburn, you wanted to talk about merge mechanics

<ericP> elf-pavlik: suggest merging. we need to model to base other PRs. we can address alt text etc later.

<ericP> ... re SVG, I don't think there's an easy way to get SVGs;

<ericP> jeremycaine: is there a simple list for accessibility?

jeremycaine: are there accessiblity guidelines?

TallTed: there aren't great guides, we should have some textual descriptions
… they are usually manually constructed
… starting from SVG is easier

<ericP> TallTed: they rules are complex. generally manually produced from SVG to allow for cut and paste

TallTed: this way one doesn't have to retype

jeremycaine: I think we can merge and come back, not to block threat model

TallTed: I would like to open issues sooner than later

jeremycaine: i can merge it today tomorrow

<ericP> elf-pavlik: we should ask "is this an improvement"?

<ericP> ... we can convert PR comments to issues.

<TallTed> (How did we arrive at creating these in c4? I know other tools are being used in other WGs, often to produce far more complex graphics. This might be worth some exploration.)

<ericP> ... i would like to merge this C4 file

<ericP> PROPOSAL: Adopt diagrams included in w3c/lws-protocol#159

<gb> PR 159 Add scope diagrams section with C4 Level 1 and Level 2 diagrams (by jeremycaine)

<elf-pavlik> +1

<gibsonf1> +1

<jeremycaine> +1

<ericP> +1

<TallTed> +1

<acoburn> +1

<pchampin> +1

<AZ> +1

RESOLUTION: Adopt diagrams included in w3c/lws-protocol#159

<ryey> +1

jeremycaine · 2026-07-27T16:37:10Z

The .c4 model is in lws10-core/diagrams.
See README.md for instructions on generating .dot files and converting to .svg.
Index.html refers to SVGs.

elf-pavlik · 2026-07-27T23:49:32Z

I think generated SVG is less readable but as I said during the meeting I would mostly like to get that .c4 file merged.
Everyone still has a chance to fine tune image rendering and we could even use both where svg would be the accessible falback for png or embedd .c4 content for a11y via some other conversion, the sky is the limit.

acoburn

This PR was discussed and approved during the 2026-07-27 WG meeting

jeremycaine added 2 commits May 15, 2026 17:51

Add introduction section

954085c

Add scope diagrams section with C4 Level 1 and Level 2 diagrams

31b52dd

laurensdeb reviewed Jun 1, 2026

View reviewed changes

TallTed reviewed Jun 4, 2026

View reviewed changes

Comment thread lws10-core/diagrams/fig-2-container-diagram.md Outdated

TallTed reviewed Jun 4, 2026

View reviewed changes

Comment thread lws10-core/index.html Outdated

jeremycaine and others added 5 commits June 11, 2026 17:10

Update lws10-core/index.html

0a39c38

relaxing as JSON-LD is not only media type Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

Update lws10-core/index.html

cf9be25

elaborate on private, public and restricted Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

Update lws10-core/index.html

4ada3f2

Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

Update lws10-core/index.html

8f7c768

point that an LWS account not required; plus CIDs Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

Update lws10-core/index.html

25cdda7

Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

jeremycaine and others added 3 commits June 27, 2026 12:16

Update lws10-core/index.html

1e1ea84

Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

Update lws10-core/index.html

685d6fb

Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

Update lws10-core/diagrams/fig-2-container-diagram.md

aba265c

Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

acoburn reviewed Jun 29, 2026

View reviewed changes

jeremycaine added 7 commits June 30, 2026 09:39

Restore missing content in lws10-core/index.html

99e8716

Merge branch 'scope-diagrams' of https://github.com/jeremycaine/lws-p…

abca902

…rotocol into scope-diagrams

Restore missing content

810e52e

Merge branch 'introduction-section' of https://github.com/jeremycaine…

3187ac4

…/lws-protocol into introduction-section

edits in response to comments

29ece08

corrected identtity server scope

624685f

reworked diagrams using LikeC4 and markdown descriptions of each

66c4303

jeremycaine added 2 commits July 10, 2026 16:40

updated core index.html to show diagrams

457cfc8

updated core index.html with table text of diagram elements

7fe9a79

elf-pavlik reviewed Jul 10, 2026

View reviewed changes

Merge branch 'main' into introduction-section

ccafd9d

Merge branch 'scope-diagrams' of https://github.com/jeremycaine/lws-p…

04fa8e8

…rotocol into scope-diagrams

elf-pavlik reviewed Jul 23, 2026

View reviewed changes

Comment thread lws10-core/diagrams/lws10-core.c4 Outdated

elf-pavlik reviewed Jul 23, 2026

View reviewed changes

Comment thread lws10-core/index.html Outdated

elf-pavlik reviewed Jul 23, 2026

View reviewed changes

Comment thread lws10-core/diagrams/lws10-core.c4 Outdated

elf-pavlik reviewed Jul 23, 2026

View reviewed changes

Comment thread lws10-core/diagrams/lws10-core.c4 Outdated

elf-pavlik approved these changes Jul 23, 2026

View reviewed changes

elf-pavlik mentioned this pull request Jul 23, 2026

WIP: Add LWS threat model document #202

Open

jeremycaine and others added 5 commits July 27, 2026 08:37

Update lws10-core/diagrams/lws10-core.c4

73775ee

Co-authored-by: elf Pavlik <elf-pavlik@hackers4peace.net>

Update lws10-core/index.html

4df6eb0

Co-authored-by: elf Pavlik <elf-pavlik@hackers4peace.net>

Update lws10-core/diagrams/lws10-core.c4

ce51913

Co-authored-by: elf Pavlik <elf-pavlik@hackers4peace.net>

Update lws10-core/diagrams/lws10-core.c4

f8a88a6

bring Storage as a component inside scope of Resource Manager Co-authored-by: elf Pavlik <elf-pavlik@hackers4peace.net>

Merge branch 'main' into scope-diagrams

88b9eb2

diagram discussion iteration result in one diagram

e917c16

jeremycaine and others added 2 commits July 27, 2026 16:25

Merge branch 'main' into scope-diagrams

d095282

new svg diagrams

c535c31

acoburn approved these changes Jul 28, 2026

View reviewed changes

Merge branch 'main' into scope-diagrams

683b542

acoburn merged commit 5869f48 into w3c:main Jul 28, 2026
2 checks passed

	System_Ext(ext, "External resources", "Web resources under management")
	System_Ext(ext, "LWS resources", "Web resources under management")

	alt="LWS Protocol container diagram showing authentication, authorization, resource management, and external resource access within the LWS server boundary"/>
	alt="LWS Protocol container diagram showing authentication, authorization, and resource management within the LWS server boundary"/>

Uh oh!

Conversation

jeremycaine commented May 15, 2026 • edited by pr-preview Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

elf-pavlik commented Jun 9, 2026

Uh oh!

elf-pavlik commented Jun 23, 2026

Uh oh!

acoburn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elf-pavlik commented Jun 30, 2026

Uh oh!

elf-pavlik commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

elf-pavlik Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jeremycaine Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elf-pavlik commented Jul 13, 2026

Uh oh!

jeremycaine commented Jul 23, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

elf-pavlik left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elf-pavlik commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jeremycaine commented Jul 27, 2026

Uh oh!

elf-pavlik commented Jul 27, 2026

Uh oh!

TallTed commented Jul 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

TallTed commented Jul 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

elf-pavlik commented Jul 27, 2026

Uh oh!

TallTed commented Jul 27, 2026

Uh oh!

TallTed commented Jul 27, 2026

Uh oh!

w3cbot commented Jul 27, 2026

Vote: LWS Diagrams PR#159

Uh oh!

jeremycaine commented Jul 27, 2026

Uh oh!

elf-pavlik commented Jul 27, 2026

jeremycaine commented May 15, 2026 •

edited by pr-preview Bot

Loading

elf-pavlik commented Jul 10, 2026 •

edited

Loading

elf-pavlik Jul 10, 2026 •

edited

Loading

jeremycaine Jul 20, 2026 •

edited

Loading

elf-pavlik left a comment •

edited

Loading

elf-pavlik commented Jul 23, 2026 •

edited

Loading

TallTed commented Jul 27, 2026 •

edited

Loading

TallTed commented Jul 27, 2026 •

edited

Loading