Add editors draft for LWS Access Requests and Access Grants

[acoburn]

Resolves #105

This adds a new specification document, defining a mechanism for agents to request access to LWS resources and for storage managers to grant access to those resources within defined constraints.

The defined features cover discovery, data model, protocol and policy profiles. The section related to notifications is intended as a stub and will need to be refined once #103 is proposed.

This proposal includes a specific policy profile based on the ODRL information model, though implementations are free to use different profiles, as appropriate.

/cc @KamiQuasi

---

Preview | Diff

[elf-pavlik]

I also see a need to have discovery on agent level, for example in CID. In many cases only resource controller identifier will be known but not any of their storages. This mechanism can still work independent of any storage and generic access requests can result in multiple access grants each in realm of different storage. At least SAI has such feature and I implemented it.

[laurensdeb]

I think it might be best to leave an AccessRequestService and an AccessGrantService as being scoped to a particular storage.

However I do see it possible for a service in an agent's CID to exist that orchestrates across AccessRequestServices and AccessGrantServices of all storages they control. I think that could be something built on top of LWS.

[elf-pavlik]

I'm fine with leaving things to be build on to of LWS, then it's just a matter of LWS being careful of not being overly restrictive and be very explicit about any assumptions that are being made. I don't think anything in current draft prevents using same user-centric requests and grants services across different storages.

[bjdmeest]

Agree with @elf-pavlik , so I would prefer not to put the restriction "to leave an AccessRequestService and an AccessGrantService as being scoped to a particular storage."

[bjdmeest]

Agree with @elf-pavlik , so I would prefer not to put the restriction "to leave an AccessRequestService and an AccessGrantService as being scoped to a particular storage."

[elf-pavlik]

I do like the overall direction, besides few inline comments.

storage manager is used across the document but I don't see clear definition. Based on my experience with SAI I would like that user-centric manager is supported which can manage multiple storages in control of given user.

In my implementation it is the same party as User Authorization Server on
https://elf-pavlik.github.io/lws-auth/view/oidc/?dynamic=sequence

And it can manage any number of storages.

EDIT: I see @uvdsl's https://github.com/uvdsl/solid-authorization-app also as a relevant prior art.

[renyuneyun]

storage manager is used across the document but I don't see clear definition.

I second @elf-pavlik's point on the need of clear definition of "storage manager". It's a new term here, and is different from related terms used previously, e.g. #27.

In my implementation it is the same party as User Authorization Server on

Is it for SAI, or for an improved OIDC flow in general?
And I'm slightly confused as I feel the storage manager should be the Resource Authorization Server? -- The storage manager is for the person/user who "owns" the resource, not the current active person/user which makes the request.

In addition, I feel there is also a nuanced distinction:

• Storage Authorization Server is the server, which serves multiples functionalities (esp. determining whether an agent already has access or not)
• Storage Manager is a "manager" (something that is more active), which, in the context of this PR, is the software that determines and manages whether an Access Request should be granted or not, and writes out the Access Grant.

In this definition, the Storage Manager does not have to be a part of the LWS service, while still allowing it to be part of the Storage Authorization Server; the user / Resource Owner can specify a custom "manager"/"service" for that if needed, such as SAI manager (?) or a policy engine that manages the (issuing and revoking of) access grants (semi-)automatically.

[elf-pavlik]

And I'm slightly confused as I feel the storage manager should be the Resource Authorization Server? -- The storage manager is for the person/user who "owns" the resource, not the current active person/user which makes the request.

I thinks Storage Manager and User Authorization Server are probably best defined as separate classes of products, LWS might even leave UAS up to other specs like some IETF drafts. Implementations may still implemented those classes of products in the same service as seein in this video I made for one of the TPACs https://youtu.be/SomSYn0h22Q
My sequence diagram only includes what's needed for that specific flow. It doesn't include storages owned/controlled by the End User (Aliece on the left) and also omits UAS of each of the resource owners (eg. Bob on the right). Something I see important and also applicable to Storage Manager.

• User AS - user associated
• Resource AS - storage associated

Its mostly my implementation feedback / prior-art I'm most famiiar with.

[laurensdeb]

Not blocking for this PR, but potentially also relevant for #82.

[laurensdeb]

Not blocking for this PR, but potentially also relevant for #82.

[acoburn]

I would very much expect that some form of paging would be involved here. I was trying not to restate what is already in the core specification, relying primarily on:

The access request and access grant endpoints are LWS containers and MUST conform to the rules defined in the LWS Protocol.

[laurensdeb]

One thing I do think is lacking here is a more explicit definition of the structure for the endpoints resolving a list of requests/grants. I would expect something similar to container representations perhaps.

[acoburn]

I was expecting that the response to a GET / request would be very much like a container representation. The only differences would be that the resources would have a "type": "AccessRequest" or "type": "AccessGrant" field. It is an open question as to whether these are also lws:DataResource entities.

[renyuneyun]

I think there is an important question here: how would permissions play with these containers?

In particular, after sending an access request, would the client&agent automatically have permissions to READ and DELETE the corresponding access request resources it has created?
If not, does that mean a client cannot revoke it's own access requests (due to the limit of the basic permission model; see also w3c/lws-ucs#144 for the issue about permissions for "creators of a resource")?

Without resolving that properly, operations (esp. DELETE) of access requests cannot be properly supported.

[acoburn]

I think ideally, an agent that creates an access request will be able to read and delete that request. I also think the spec needs to be careful when recommending specific access controls on these resources, since there may be other considerations.

[uvdsl]

I second @renyuneyun's concern here, this section might require careful wording.

[renyuneyun]

See above for comment on R746 aout DELETE and other operations.

[renyuneyun]

Is spam not a consideration at all? (see also w3c/lws-ucs#179)
I see it's highly likely spams can come to access requests.

[acoburn]

Spam should absolutely be a consideration. This has been added in 22f383d

[renyuneyun]

Does this imply all access grants should be retained by the storage indefinitely? That does not seem necessary nor practical.
What is the reason for allowing querying this?

[acoburn]

This definitely shouldn't imply that every access grant is retained indefinitely. Furthermore, data retention rules will likely vary significantly by deployment, so we likely shouldn't require anything too specific regarding retention. A deployment may want to clean up any expired access grant, for instance.

In terms of the specific rational for the GET / method, a storage controller may want to list through the active grants in order to revoke one of them.

[renyuneyun]

Right. So to seek further clarification: does Access Grant interplay with permissions? I mean, it should trigger a change of permissions (if needed), but is it the source of truth, or are they just expected to happen in that order? That matters if the user later decides to change the permission, regarding whether the Access Grant should be deleted automatically.

[acoburn]

storage manager is used across the document but I don't see clear definition.

I second @elf-pavlik's point on the need of clear definition of "storage manager". It's a new term here, and is different from related terms used previously, e.g. #27.

I very much agree. I also think that term should go into the core specification. If we find that its only use is in this document, then we can define it here.

[uvdsl]

Not fully done with my review, so here is Part 1.

[uvdsl]

What is a storage manager? This term is not defined here. (seeAlso github.com//issues/27)

[acoburn]

We definitely need to clarify terminology across all LWS documents. I would expect that we will have a term in the core specification that describes this role, and then we will use that term consistently here. The reason it's not defined in this document is because it is expected to exist in the core document.

I will add an in-line issue reference to #27 to make sure we clarify terms.

[uvdsl]

Does this mean that an LWS Server must be able to filter container items based on who accesses the container?

[acoburn]

This is a bit of a balancing act. This endpoint acts a bit like an LDN inbox and a bit like an LWS container. We were trying to build on some of these existing foundations, but there are (as you have pointed out) some notable differences w.r.t. filtering items. There was also an attempt here to align with how ActivityPub defines inboxes and outboxes, which uses this phrasing:

The outbox stream contains activities the user has published, subject to the ability of the requestor to retrieve the activity (that is, the contents of the outbox are filtered by the permissions of the person reading it).

I would welcome suggestions for how to indicate a behavior that (a) is widely implementable and (b) provides security guidance in line with good practice

[uvdsl]

Hm, tricky indeed if you do not assume a client to persist received access grants (which I thought would be a good idea to do as a client, e.g. via client LDN inbox or a webhook for grants to be posted to). I do see the use case where that is not the case and you might want to offer such an access grant retrieval endpoint. But I also see the other use cases where such an access grant retrieval endpoint is not strictly required because the client had been notified and had retrieved their access grant. (So maybe supporting such an endpoint for clients other than the ones managing the access should be a SHOULD?) This could be worth a discussion in the broader group.

Personally, I would prefer to keep the server-side logic invoked on each request to a minimum. Therefore, I usually favor "dumb" containers where I just store the grants in: user-centric in the recipient's storage and then a copy of that in the storage of the access granting agent.

In general, I think it might be valuable to clarify in which capacity the functionality of these endpoints exceeds or differs from regular LWS containers - just to avoid false assumptions about LWS containers in general.

[elf-pavlik]

In SAI grantee/assignee (social agent or app) has an agent registration from where it has references to all grants issued to it, including delegated ones. All grants, including delegated ones, are hosted in a registry / specialized pod of data owner. But all references are available and discoverable through agent registrations. In other words there is no reliance on filtering grant registry (container with all the grants) since grantee/asignee always has direct links to specific grants that they have access to.
This also covers

• add Type Index Section #115 (comment)

[renyuneyun]

So maybe supporting such an endpoint for clients other than the ones managing the access should be a SHOULD?

I have a similar feeling, though I'm not sure if this has any unexpected side effects.

Following the given definition and the text, I have been understanding the Access Grant as a piece of information that indicates access has been granted to a certain degree. It does not necessarily mean it is up-to-date or still valid -- 1) the user may have revoked or modified "it" (regardless of the definition) through (the process of creating) a new Access Grant; 2) the user may have changed the underlying permission settings (e.g. access control policies). In the meantime, it also does not necessarily mean the Access Grant matches all "permissions" that the Client has requested in the Access Request.

Therefore, I have a very mixed feeling of these endpoints, or alternative methods mentioned above (e.g. SAI's approach). I acknowledge and agree with the needs for the LWS Server to maintain an endpoint/location for a client to discover an/some Access Grant(s) it should receive, in case the client was not properly notified (e.g. because of offline). Fundamentally, the Access Grant needs to be received by the client to determine its further actions, otherwise this mechanism is unnecessary from the first instance -- even if (conceptually) the Access Grant only contains one sentence: "do as what you have requested". (In fact, we can have a discussion on whether this is needed in the first instance...)
Some questions arise:

1. Should the client (and user combination) always be able to obtain the latest known Access Grant?

   1. If yes, will there be an expiration time for retrieving any access grants? Otherwise, this container will only be larger when the user is interacting with more clients.

   2. What if the Access Grant no longer reflects the current status (e.g. user has manually made changes elsewhere to the permissions)?

2. Should the client (and user combination) be ever able to retrieve previously issued Access Grants (which, in principle, should be superseded by the new ones, I believe?)?

   1. If yes, previous two subquestions come again.

3. Should the client be able to see the existence (and URLs) of Access Grants for other clients or other users?

   1. This might not be critical, but worth answering. I feel this is undesired but acceptable if needed -- in the end, it only sees the (random) URLs, not the contents.

4. Should the client be able to know in its Access Grants about the granting of permission to other clients or users, if that's simultaneously granted?

   1. The previous discussion has mentioned this. I believe the answer is "no"? If so, what should the LWS Server (or Access Grant Service, or Storage Manager) do for any requests that contain such cases? (I'm aware this can be left as implementation details; I'm asking because we need to be cautious to rule out performance / resource bottlenecks if that's a big one.)
      1. Should they automatically split the Access Grants into multiple copies, each for one pair of Client + User, and store that to the container / endpoint here (and manage the permissions appropriately)?
      2. Or, should they have some internal mechanism that automatically filters the content based on the Client + User combination upon request?

In SAI grantee/assignee (social agent or app) has an agent registration from where it has references to all grants issued to it, including delegated ones.

To check some aspects:

1. Does SAI always only stored the latest access grants? (And in SAI's model, the grants are exactly the source of truth of permissions, right?)
2. When an App (used by Alice) requests access to resources in Bob's Pod, where should the grants be stored? Is it with Alice or Bob, or somewhere else related to SAI (service?)?
   1. Based on the description above, I feel the answer is at Bob's Pod (a dedicated/designated Pod, but still Bob's)? If so, how are the access granting action and the location of the access grant (document) transmitted to App or Alice?
      1. I suspect it's Bob's SAI agent/engine (not sure the exact name) who writes the notification and/or URL to Alice's Pod? Is that the Inbox of Alice's Pod, and what's the permission setting (or anything equivalent) to that location in Alice's Pod?

[elf-pavlik]

While the SAI spec leaves it bit underspecified, in https://sai.js.org I implemented custom policy engine for CSS and grants are indeed the source of truth. So data pods (aka. data registries) don't use WAC or ACP at all. I also have separate CSS instance for registry set pods which currently uses ACP but in a future it could also use more advanced version of grants.
I would also note that SAI defines all grants as immutable, so to change it a new one is created that supersedes the old one.
Any app used by Alice always requests access from Alice's AuthZ Agent / User AuthZ Server / Storage Manager. Then if Alice authorizes access to data owned by someone else, in a process Alice's Storage Manager would request grant for that app/client as Alice from Bob's storage manager. So the resulting grant will be for Alice + the app combination and will be stored in Bob's grant registry. App's agent registry hosted by Alice will have a links to all those grants across Alice's social network. This can be chained and resource's owner Storage Manager will verify the whole delegation chain before issuing a grant.
The location of the grant(s) is first included in response from Bob's SM to Alice's SM and then it will include it in Agent Registry it manages for the application.
I'll try to add it to my Motion Canvas slides I'm preparing for SoSy26 this weekend and drop a link here.

[elf-pavlik]

For now I added another view to my likeC4 sequence diagram
https://elf-pavlik.github.io/lws-auth/view/grants/?dynamic=sequence

It shows user-centric storage(s) manager which creates grants for data on any number of storages owned by the user and requests grants from storage(s) managers of other peers in a social graph for data owned by them (delegation). Step 5 has a note with link to a video with a screen catpture that shows user interaction with the authorization screen as currently implemented in https://sai.js.org

The sequence is simplified since some data in the video is also fetched directly from storages, for example if selecting specific resource(s).

[renyuneyun]

What if an agent controls multiple storages? This property would prevent the possibility that a request/grant spans multiple storages

Are you referring to that the user should have a holistic view of all accesses that the client would have (to all potential storages), to make their decision? What about other users' storages then (e.g. is that not a part of the holistic view)? And how can the client determine which storages are the current user's?

[renyuneyun]

ODRL is everything but simple

I actually kind of agree with this, from the perspective of policy reasoners / processing engines whose role is to compare two policies (esp. to determine whether two policies are compliant/compatible with each other or not). But ODRL model is not complex, to be fair.

arguments against coining this "LWS Access Policy Profile"

I may have an argument -- the sections underneath coined some open structures from ODRL (esp. the operands in this discussion thread), whose openness suggests this is not "LWS ... Profile", but a "LWS-flavored ODRL subset+modification", because it's not restrictive enough. Though, as being discussed there, if they are scoped / restricted, this argument doesn't hold.

Another argument may be related to the next PR (#109). If that indicates what this "xxx Profile" aims to evolve to, I would say the name is not accurate any more. The current form keeps a sensible distance to ODRL, because of the different roles they serve; that one has crossed the line too much.

[renyuneyun]

Does this then change the operational semantics of ODRL?

I don't think it deviates.

My intuition is very much related to the interplay of different fields as the object of access. My intuition is that this may result in a limitation in either expressivity or usefulness. (Will try to think of a real example. But happy to be defeated.)

[renyuneyun]

Right. So to seek further clarification: does Access Grant interplay with permissions? I mean, it should trigger a change of permissions (if needed), but is it the source of truth, or are they just expected to happen in that order? That matters if the user later decides to change the permission, regarding whether the Access Grant should be deleted automatically.

[renyuneyun]

Would rate limit be based on external information only, or (LWS) internal information as well? E.g., can Client ID or User's ID be used to determine rate limit? If so, does that necessitates appropriate capability of LWS service to interplay with the spam protector?

[ebremer]

NOTE: add text to spec to indicate explicitly that all arrays are unordered

[renyuneyun]

(From LWS meeting today)
People have confusion on the intention of the type field, partially also related to the explanation of these terms. Maybe we rename them to align with their implications, rather than splitting the types of targets.
E.g. they can be:

• Resource: This specific resource (content of a Resource, or representation of a Container);
• AllSubResources: This specific resource as well as all potential sub-resources if being a container

[uvdsl]

As inspiration, noting that SAI has scopeOfAuthorization with values interop:All, interop:AllFromAgent, interop:AllFromRegistry, interop:SelectedFromRegistry, interop:Inherited.

[pchampin]

I think an explicit link from an access grant to the access request it responds to, would be useful (in the light of the scenarios we just discussed at the F2F, where there is not always a 1-to-1 relationship, or where the access requests asks for a type (e.g. "photos") and the grant responds with a location.

[termontwouter]

Action point from London meeting: move Access(Request|Grant)Request API into profile.

[uvdsl]

@termontwouter, re #106 (comment), could you clarify again how the API is working/designed that your implementation uses? I did not quite catch that...

[termontwouter]

@uvdsl, we do not require a separate API to manage policies/requests/grants, but treat the OAuth (UMA/A4DS) token request as such. A successful request results in an access token and a receipt bound to a grant (and if necessary a change in policies). Having a single LWS-like API as a requirement would prevent such approaches, so instead the API should be defined by the access request/grant service profile itself.

[acoburn]

Several updates are included since the in-person discussion

• The term "storage controller" is used instead of "storage manager"
• The hasPurpose property is moved to an ODRL constraint
• The document has been integrated into the main LWS specification document

[gibsonf1]

Unable to preview this - see 404 not found.

[w3cbot]

This was discussed during the #lws meeting on 01 June 2026.

View the transcript

Access Requests vote #106

<pchampin> w3c/lws-protocol#106

<TallTed> +0 (regretfully, not up to speed following my holiday)

<TallTed> I request that going forward, links to issues/PRs (especially but not only those up for vote/decision) be included in the calendar agenda

<acoburn> PROPOSED: to merge the access request feature as defined in PR #106

<gb> Pull Request 106 Add editors draft for LWS Access Requests and Access Grants (by acoburn)

<pchampin> +1

<elf-pavlik> +1

<gibsonf1> +1

<termontwouter> +1

<ericP> +1

<eBremer> +1

<acoburn> +1

<jeswr> +1

<ryey> +1

<laurens> +1

<TallTed> +0 (as above)

RESOLUTION: to merge the access request feature as defined in PR #106

acoburn: I will merge it over next day or so

---