Agent-Specific Discovery #291

woutermont · 2022-12-06T17:46:46Z

No description provided.

proposals/specification/agent-specific-discovery/index.bs

woutermont · 2022-12-14T12:48:02Z

@tomhgmns

Signed-off-by: Wouter Termont <woutermont@gmail.com>

justinwb · 2022-12-19T13:14:57Z

@woutermont do you plan to adjust the relevant places in the interop spec as part of this proposal?

woutermont · 2022-12-19T13:56:17Z

@justinwb yes, working on it now; will hopefully finish tomorrow!

Signed-off-by: Wouter Termont <woutermont@gmail.com>

woutermont · 2022-12-28T17:05:09Z

Okay, so I've updated the proposal, taking more terminology from the main document, and then subtituted references to the proposal for some portions of the relevant sections in the main document. I tried to be conservative, so there is still quite a lot of text repeating what is already stated in the proposal.

In trying to align the two as good as possible, I wondered why we want to distinguish Social Agents from Applications at this level. Does the Authorization Agent need to know what type it is, given that they really contain the same info. Especially the double Registry->Registration predicate (hasApplicationRegistration/hasSocialAgentRegistration) is hard to incorporate. I feel that it only adds redundant data, since we get the same info from the resource it points to: the following paths hold the same information.

:registry interop:hasApplicationRegistration :registration .
:registry interop:hasRegistration / rdf:type interop:ApplicationRegistration .
:registry interop:hasRegistration / inter:registeredAgent / rdf:type interop:Application .

On another note: the resource hierachy included at the end of the section on Agent Registrations seems to give the wrong hint that it always has to be a filesystem-like structure. I think just including Turtle examples, or graphs like the ones in the Primer, are clearer.

Signed-off-by: Wouter Termont <woutermont@gmail.com>

elf-pavlik

I'm not sure about specifying registering agents (§5), if we want to do it it might be served better as a follow up step.

proposals/specification/agent-management/terms.bs

proposals/specification/agent-management/amd-response.bs

elf-pavlik · 2023-01-09T12:49:31Z

proposals/specification/agent-management/amd-response.bs

+omitted, in which case the [=Identity Document=] [SHOULD] contain an [=RDF
+Triple=] linking the [=Entity's=] [=Identifier=] to the URL of its [=Agent
+Manager=] with the predicate `interop:hasAgentManager`. The predicate [MAY] also
+be substituted by `rdfs:seeAlso` or `pim:preferencesFile`.


What is the reason for MAY on very generic rdfs:seeAlso? It could lead to a wikipedia page or anything that creator of the description finds relevant in any way.

Was for compatibility with legacy clients / discovery paths.

ACTION (@woutermont):

snippets of what legacy vs modern clients would have to implement

look into different profiles

put question of compatibility on next weeks agenda

ACTION: remove rdfs:seeAlso

Agree with the removal. Feels like very quickly an innocuous piece of code code be misconstrued as the trusted agent manager.

proposals/specification/agent-management/amd-result.bs

elf-pavlik · 2023-01-09T13:10:07Z

proposals/specification/agent-management/ard-request.bs

+[=Agent Manager's=] URL in which the value of the [:Authorization:] header is
+set to a [[DPOP]]-bound [[OIDC]] [=Identity Token=] containing an [=Identifier=]
+of the [=Agent=] as value of the `azp` [=Claim=] or as *sole* value of the
+`aud` [=Claim=].


If we want to be that specific we should probably reference Solid OIDC.
The ID Token is only pushed as a claim and access token should be used in Authorization header.

You're right! This should be an Access Token with the client_id set to the URI of the Agent.

Solid OIDC doesn't put any more specific requirement on the format of Access Tokens, they are left up to RS & AS.
I think we should use some abstract language and have non-normative reference to Solid-OIDC as a concrete example.

@csarven we think this should be discussed on Wednesday

ACTION: remove token details, talk about "authorized request" and refer to (yet to be created) solid ecosystem options

proposals/specification/agent-management/ard-response.bs

elf-pavlik · 2023-01-09T13:16:49Z

proposals/specification/agent-management/ard-response.bs

+
+#### Error Responses #### {#sec-ard-response-error}
+
+- If no [:Authorization:] header is present, the [=Agent Manager=] [MUST] respond with status code [S401], including a [:WWW-Authenticate:] header with the [:DPoP:] scheme. This response [MUST NOT] include an [:error:] parameter.


This prevents Agent Manager using it as it's Identity Document which would include some public information.

Not sure I understand. What would the Agent Manager use as who's Identity Document?

In sai-impl-service the AuthorizationAgent needs to get data from the solid storage. It has privileged access set to the end user (agent) and the authrization agent (client). In that case the Authorization Agent acts as Solid OIDC client and serves its identity document from the same IRI.

Okay, but what is preventing that?

ACTION: restore possibility of 200 response for public agents

woutermont · 2023-01-10T10:24:40Z

Ass requested by @elf-pavlik in yesterday's meeting, here's a quickly drafted snippet of how a client would discover its registration, with support for the "legacy" use of pim:preferencesFile, reading links out of the body rather than the headers, and supporting all reponse codes (303, 204 and 200). I've commented out (with //) those parts that would be superfluous when we would not provide this additional support (only read a single relation, only out of headers, and with only 204 responses) ... it's not much difference i.m.o.

The only thing I left out is the rdfs:seeOther link, because I must agree with @elf-pavlik that this would put too much burden on the client. So we only check for one or two predicates/links of which we specify that they should be unique.

/* RDF Parser */
// import { Parser } from 'n3';
// const parser = new Parser();

/* Shorthands */
const hasAM = 'http://www.w3.org/ns/solid/interop#hasAgentManager';
const regAgent = 'http://www.w3.org/ns/solid/interop#registeredAgent';
// const prefFile = 'https://www.w3.org/ns/pim/space#preferencesFile';

/* Helper functions */
// const const rdfLinks = (rdf) => Object.fromEntries(parser.parse(rdf)
//   .map((quad) => [quad.predicate.value, { target: quad.object.value, context: quad.subject.value }]))
const headerLinks = (response) => Object.fromEntries(
  response.headers?.get('link')?.split(',')?.map((link) => link.trim().split('; ')).map((params) => [
    params.find((param) => param.startsWith('rel=')).replaceAll(/(^rel="|"$)/g,''), ({
      target: params[0].replaceAll(/(^<|>$)/g,''),
      context: params.find((param) => param.startsWith('anchor='))?.replaceAll(/(^anchor="|"$)/g,'') ?? response.url
    })
  ])
)

const getRegistration = async (webid) {

  /* Get links from profile header and body */
  const profile = await fetch(webid);
  const hlinks = headerLinks(profile)
  let am = hlinks[hasAM];
  // let pf = hlinks[prefFile];
  // if (!am && !pf) {
  //   const rlinks = rdfLinks(await profile.text());
  //   am = rlinks[hasAM];
  //   pf = rlinks[prefFile];
  // }

  /* Abort if no indication of agent manager  */
  if (!am && !pf) return undefined; 

  /* Request agent registration */
  const token = getToken(profile);
  const target = am?.target ?? pm?.target
  const dpop = getDPoP('GET', target);
  const registration = await fetch(target, {
    redirect: manual,
    headers: {
      Authorization: `DPoP ${token}`,
      DPoP: dpop,
    },
  });

  /* Optimal case, we're done */
  // if (registration.status === 200) return parser.parse(await registration.text());

  /* Otherwise, follow registration link, then we're done */
  if (registration.status === 204 || registration.status === 303) { 
    const reg = headerLinks(registration)[regAgent].context;
    // const loc = registration.headers.get('location');
    const dpop = getDPoP('GET', reg ?? loc);
    const registration = await fetch(reg ?? loc, {
      headers: {
        Authorization: `DPoP ${token}`,
        DPoP: dpop,
      },
    });
    return parser.parse(await registration.text());
  }

  /* All other cases indicate some auth error
   * which SAI-aware clients could have foreseen. */
  throw new Error('Auth error');

}

PS: I wrote this code directly into this comment, so please treat it as pseudocode; no idea if it would work without some finetuning.

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

TallTed

Thinigs I fixed --

i.e. and e.g. should be avoided per i18n
Various language and punctuation errors

Things I haven't fixed --

example URIs should use IANA reserved Special Use Domains, not (for instance) URIs in my.id which is currently reserved by Indonesia, the controller of the id TLD

TallTed · 2023-02-13T13:38:27Z

proposals/specification/agent-management/agent-registering.bs

+This document does not specify the requirements an [=Agent=] has to comply with
+to get an [=Agent Registration=] in the [=Agent Registry=] of an [=Entity=], nor
+does it supply an exhaustive list of methods by which this **registration** is
+achieved (e.g. automatically via an API, interactively via a user interface).


Suggested change

achieved (e.g. automatically via an API, interactively via a user interface).

achieved (such as automatically via an API, or interactively via a user interface).

TallTed · 2023-02-13T13:39:49Z

proposals/specification/agent-management/agent-registering.bs

+[=Agent Manager=] as [=Link Context=] and the registration endpoint as [=Link
+Target=]. The [=Relation Type=] of the [:Link:] header [MUST] hold the semantics
+that indicate how to perform an [=Agent Registration Request=] at the [=Link
+Target=], e.g. as specified in an extension to this document.


Suggested change

Target=], e.g. as specified in an extension to this document.

Target=], such as those specified in an extension to this document.

TallTed · 2023-02-13T13:46:31Z

proposals/specification/agent-management/amd-request.bs

+
+[=Agents=] wishing to discover the [=Agent Manager=] for a given [=Entity=]
+[SHOULD] dereference an [=HTTP-Dereferenceable Identifier=] of that [=Entity=],
+e.g. `https://my.id/doc#me`.


Suggested change

e.g. `https://my.id/doc#me`.

for instance, `https://my.id/doc#me`.

TallTed · 2023-02-13T13:46:49Z

proposals/specification/agent-management/amd-response.bs

+
+### Discovery Response ### {#sec-amd-response}
+
+Upon reception of a request to the [=Identity Document=], its host [SHOULD]


Suggested change

Upon reception of a request to the [=Identity Document=], its host [SHOULD]

Upon receipt of a request to the [=Identity Document=], its host [SHOULD]

TallTed · 2023-02-13T13:48:15Z

proposals/specification/agent-management/amd-response.bs

+
+    </div>
+
+A host of [=Identity Documents=] [MUST] implement any of the above in order to


Suggested change

A host of [=Identity Documents=] [MUST] implement any of the above in order to

A host of [=Identity Documents=] [MUST] implement at least one of the above to

TallTed · 2023-02-13T14:40:47Z

proposals/specification/agent-management/terms.bs

+This document builds on the concepts and definitions of [RDF]. 
+For conformance, terms from [[!RFC9110|HTTP Semantics]] and [LINKS] are used. 
+[[WEBID|WebID's]] and [[DID|Decentralized Identifiers]] are used as examples. 
+References to all these are linked throughout the text, 


Suggested change

References to all these are linked throughout the text,

References to all of these are linked throughout the text,

TallTed · 2023-02-13T14:41:45Z

proposals/specification/agent-management/terms.bs

+    <dfn>RDF-Dereferenceable</dfn> [=Identifiers=] dereference to an [=RDF Document=].
+
+: <dfn>Agent</dfn> 
+:: An actor, i.e. an [=Entity=] that acts, does stuff, or has the power to. 


Suggested change

:: An actor, i.e. an [=Entity=] that acts, does stuff, or has the power to.

:: An actor (that is, an [=Entity=]) that acts, does stuff, or has the power to do so.

TallTed · 2023-02-13T14:42:05Z

proposals/specification/agent-management/terms.bs

+
+: <dfn>Agent</dfn> 
+:: An actor, i.e. an [=Entity=] that acts, does stuff, or has the power to. 
+    It can do this on its own, or mediated by some other [=Agent=]. 


Suggested change

It can do this on its own, or mediated by some other [=Agent=].

It can do this on its own, or through mediation by some other [=Agent=].

TallTed · 2023-02-13T14:44:57Z

proposals/specification/data-authorization.bs

@@ -185,27 +187,16 @@ are processed by the [=Authorization Agent=].

 ### Authorization Agent Discovery ### {#authorization-agent-discovery}

+This document extends the [Agent Manager Discovery](https://solid.github.io/data-interoperability-panel/specification/agent-management/index.html#sec-am-discovery) of the [[sai-am|Agent Manager]] specification,
+by defining `interop:hasAuthorizationAgent` as subproperty of `interop:hasAccessManager`.


Suggested change

by defining `interop:hasAuthorizationAgent` as subproperty of `interop:hasAccessManager`.

by defining `interop:hasAuthorizationAgent` as a subproperty of `interop:hasAccessManager`.

TallTed · 2023-02-13T14:45:26Z

proposals/specification/data-authorization.bs

@@ -185,27 +187,16 @@ are processed by the [=Authorization Agent=].

 ### Authorization Agent Discovery ### {#authorization-agent-discovery}

+This document extends the [Agent Manager Discovery](https://solid.github.io/data-interoperability-panel/specification/agent-management/index.html#sec-am-discovery) of the [[sai-am|Agent Manager]] specification,
+by defining `interop:hasAuthorizationAgent` as subproperty of `interop:hasAccessManager`.
+the [=Authorization Agent=] for a given [=Social Agent=] can be discovered


Suggested change

the [=Authorization Agent=] for a given [=Social Agent=] can be discovered

justinwb

Overall looks pretty good - a few comments / questions

justinwb · 2023-02-27T12:25:19Z

proposals/specification/agent-management/index.bs

+Abstract: 
+
+  This specification details how Agents can discover the Resource Discovery 
+  Hub of an Entity, and how they can interact with it in order to find 


As far as I can tell this is the only place in this PR where the term "Resource Discovery Hub" is used, but it is never defined anywhere else. For the purposes of Abstract, a more straightforward explanation would be better.

Correct, should be Agent Manager now.

justinwb · 2023-02-27T12:29:41Z

proposals/specification/agent-management/intro.bs

+this limited set of <dfn export>Agent-Specific Resources</dfn> &mdash; 
+[=Resources=] that are accessible by and possibly relevant for a specific [=Agent=] 
+&mdash; in a performant, secure, and privacy-minded manner, 
+without having to bother with all other, irrelevant [=Resources=].


What is the purpose of this last statement?

without having to bother with all other, irrelevant resources?

It stresses the efficiency gain of using an Agent Manager, instead of needing to traverse all Resources in order to find out which ones are accessible and relevant.

Do you think we should leave it out?

justinwb · 2023-02-27T12:30:46Z

proposals/specification/agent-management/intro.bs

+    NOTE: If the [=Entity=] is an [=Agent=] itself, 
+    it can of course manage its own [=Identity Document=], 
+    in which case there is no difference 
+    between the [=Entity=] and its [=Managing Agent=].


A short example of where this would be the case might be useful here.

justinwb · 2023-02-27T12:32:27Z

proposals/specification/agent-management/agent-manager.bs

+can use an [AGENT_MANAGER] ([=RDF Class=] `interop:AgentManager`): 
+a [=Resource=] linked uniquely to the [=Entity=], 
+at which each [=Agent=] can identify itself 
+in return for quick access to its [=Agent-Specific Resources=] (if it has any).


This is a bit tough to process. Suggest re-wording for clarity.

justinwb · 2023-02-27T12:36:20Z

proposals/specification/agent-management/amd-response.bs

+omitted, in which case the [=Identity Document=] [SHOULD] contain an [=RDF
+Triple=] linking the [=Entity's=] [=Identifier=] to the URL of its [=Agent
+Manager=] with the predicate `interop:hasAgentManager`. The predicate [MAY] also
+be substituted by `rdfs:seeAlso` or `pim:preferencesFile`.


Agree with the removal. Feels like very quickly an innocuous piece of code code be misconstrued as the trusted agent manager.

justinwb · 2023-02-27T12:50:57Z

proposals/specification/agent-management/ard-response.bs

+  - It [MAY] respond with status code [S200] including a [:Content-Location:] header 
+    with the URL of the [=Agent Registration=] URL as value. If the request method
+    was [:GET:], it [MUST] include a [[JSON-LD11|JSON-LD]] serialization of the 
+    [=Agent Registration=] in the body of the response.


What is the rationale behind the MUST on JSON-LD serialization here?

TallTed · 2023-02-27T15:03:48Z

proposals/specification/agent-management/intro.bs

+&mdash; in a performant, secure, and privacy-minded manner, 
+without having to bother with all other, irrelevant [=Resources=].


Suggested change

— in a performant, secure, and privacy-minded manner,

without having to bother with all other, irrelevant [=Resources=].

— in a performant, secure, and privacy-minded manner.

or possibly

Suggested change

— in a performant, secure, and privacy-minded manner,

without having to bother with all other, irrelevant [=Resources=].

— in a performant, secure, and privacy-minded manner,

without trying (and/or failing) to access all other, irrelevant [=Resources=].

woutermont · 2023-09-09T11:53:44Z

Closing this since I am no longer convinced that a separate discovery service is needed (cf. #315). An agent should at all times be able to request access to (types of) resources at an AS, and the combination of the AS's response and a token info endpoint should suffice to gain all necessary information. If not, a better approach than proposed in this PR would be to add a client/agent info endpoint that functions similarly to the OIDC user info endpoint.

add initial ASD document

dc907d0

woutermont self-assigned this Dec 6, 2022

add full ASD sequence diagram

3ba6cdf

woutermont commented Dec 6, 2022

View reviewed changes

proposals/specification/agent-specific-discovery/index.bs Outdated Show resolved Hide resolved

woutermont added 2 commits December 6, 2022 18:51

update ASD sequence diagram path

eb32836

update publish workflow

ede6f60

woutermont mentioned this pull request Dec 6, 2022

consider alternatives for app registration discovery #91

Closed

switch to SAI specific metadata

84c2792

elf-pavlik requested review from elf-pavlik and justinwb December 7, 2022 12:22

chore: clean up metadata

b0c48fb

Signed-off-by: Wouter Termont <woutermont@gmail.com>

woutermont added 4 commits December 27, 2022 16:09

feat: full rework

a995b6c

Signed-off-by: Wouter Termont <woutermont@gmail.com>

chore: renamed directory

75f1743

Signed-off-by: Wouter Termont <woutermont@gmail.com>

feat: align with main spec

e1cb78a

Signed-off-by: Wouter Termont <woutermont@gmail.com>

chore: update diagram terminology

4405cd0

Signed-off-by: Wouter Termont <woutermont@gmail.com>

fix: correct header layout

9f8ec9c

Signed-off-by: Wouter Termont <woutermont@gmail.com>

elf-pavlik requested changes Jan 9, 2023

View reviewed changes

unfold prefixes in link headers

117fe35

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

elf-pavlik mentioned this pull request Feb 12, 2023

2023-02-13 Meeting Agenda #295

Closed

TallTed suggested changes Feb 13, 2023

View reviewed changes

elf-pavlik mentioned this pull request Feb 13, 2023

Access Needs for Public Resources #254

Draft

3 tasks

justinwb requested changes Feb 27, 2023

View reviewed changes

TallTed reviewed Feb 27, 2023

View reviewed changes

woutermont closed this Sep 9, 2023


		#### Error Responses #### {#sec-ard-response-error}

		- If no [:Authorization:] header is present, the [=Agent Manager=] [MUST] respond with status code [S401], including a [:WWW-Authenticate:] header with the [:DPoP:] scheme. This response [MUST NOT] include an [:error:] parameter.

	achieved (e.g. automatically via an API, interactively via a user interface).
	achieved (such as automatically via an API, or interactively via a user interface).

	Target=], e.g. as specified in an extension to this document.
	Target=], such as those specified in an extension to this document.

	e.g. `https://my.id/doc#me`.
	for instance, `https://my.id/doc#me`.


		### Discovery Response ### {#sec-amd-response}

		Upon reception of a request to the [=Identity Document=], its host [SHOULD]

	Upon reception of a request to the [=Identity Document=], its host [SHOULD]
	Upon receipt of a request to the [=Identity Document=], its host [SHOULD]


		</div>

		A host of [=Identity Documents=] [MUST] implement any of the above in order to

	References to all these are linked throughout the text,
	References to all of these are linked throughout the text,

	:: An actor, i.e. an [=Entity=] that acts, does stuff, or has the power to.
	:: An actor (that is, an [=Entity=]) that acts, does stuff, or has the power to do so.

	It can do this on its own, or mediated by some other [=Agent=].
	It can do this on its own, or through mediation by some other [=Agent=].

	by defining `interop:hasAuthorizationAgent` as subproperty of `interop:hasAccessManager`.
	by defining `interop:hasAuthorizationAgent` as a subproperty of `interop:hasAccessManager`.

		— in a performant, secure, and privacy-minded manner,
		without having to bother with all other, irrelevant [=Resources=].

Agent-Specific Discovery #291

Agent-Specific Discovery #291

Conversation

woutermont commented Dec 6, 2022

woutermont commented Dec 14, 2022

justinwb commented Dec 19, 2022

woutermont commented Dec 19, 2022

woutermont commented Dec 28, 2022

elf-pavlik left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

woutermont commented Jan 10, 2023 • edited by elf-pavlik Loading

TallTed left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

justinwb left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TallTed Mar 8, 2023 • edited Loading

Choose a reason for hiding this comment

woutermont commented Sep 9, 2023

woutermont commented Jan 10, 2023 •

edited by elf-pavlik

Loading

TallTed Mar 8, 2023 •

edited

Loading