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.

…/lws-protocol into scope-diagrams

elf-pavlik · 2026-07-14T21:39:36Z

+    description 'An agent of the LWS system'
+  }
+
+  lws = system 'LWS System' {


I would suggest removing LWS System, similar to The Web it is a heterogenous envoronment where interactions between autonomous parties follow specific protocol(s). Tyring to draw a box around it seems to me rather confusing.

@elf-pavlik
My point in the f2f April meeting and here - is that good architecture practice shows the system context boundary: anything inside will describe the specification to implement, anything outside are things with an known interaction model. I am not precious about the name, but I favour a clear defined boundary.

Alts. to LWS System -> LWS, LWS Scope Boundary, LWS Scope etc

TallTed · 2026-07-17T18:09:46Z

+
+| Box | Description |
+|---|---|
+| Agent | An agent of the LWS system |


Since LWS System = LWS Client + LWS Server, then I thought it simpler to say 'An agent of the LWS system'

TallTed · 2026-07-17T18:10:33Z

+| Box | Description |
+|---|---|
+| Agent | An agent of the LWS system |
+| LWS System | A system that implements the LWS Protocol |


Let's nail this point first then flow through changes

jeremycaine · 2026-07-20T13:02:31Z

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.

Please advise how we might reflect going across independent security domain in these, or additional, diagrams. @elf-pavlik

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

gibsonf1 · 2026-07-20T13:37:54Z

It's very confusing to call the manager of the LWS system the "Resource Manager" when that manager is manging far more than just resources but authentication, authorization etc. It would make far more sense to call this the "LWS Manager" and be less confusing by far, as that is exactly what this is, the LWS manager, (not generic resources)

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

jeremycaine added 2 commits July 14, 2026 19:08

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

c6295b9

…/lws-protocol into scope-diagrams

updated diagrams for agent

da07c8f

acoburn mentioned this pull request Jul 14, 2026

update terminology for Agent to align with system components #198

Closed

elf-pavlik reviewed Jul 14, 2026

View reviewed changes

elf-pavlik mentioned this pull request Jul 16, 2026

update terminology for Agent to align with system componentsadded clarity to agent definition #201

Closed

TallTed reviewed Jul 17, 2026

View reviewed changes

Comment thread lws10-core/diagrams/figures.md Outdated

TallTed reviewed Jul 17, 2026

View reviewed changes

Comment thread lws10-core/diagrams/figures.md Outdated

TallTed reviewed Jul 17, 2026

View reviewed changes

jeremycaine and others added 2 commits July 20, 2026 14:02

Update lws10-core/diagrams/figures.md

419ceeb

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

Update lws10-core/diagrams/figures.md

a99f7df

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

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

	\| Agent \| An agent of the LWS system \|
	\| Agent \| An agent that interacts with LWS servers and/or client tools \|

	\| LWS System \| A system that implements the LWS Protocol \|
	\| LWS Deployment \| A deployment of LWS servers and/or client tools \|

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

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

Uh oh!

Uh oh!

gibsonf1 commented Jul 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

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

jeremycaine commented Jul 20, 2026 •

edited

Loading