Agent-Specific Discovery

.github/workflows/publish-proposals.yml

@@ -32,14 +32,15 @@ jobs:
       - name: run bikeshed
         run: |
           bikeshed spec proposals/specification/index.bs
+          bikeshed spec proposals/specification/agent-management/index.bs
           bikeshed spec proposals/primer/application.bs
           bikeshed spec proposals/primer/authorization-agent.bs
 
       - name: generate svg
-        run: for diagram in proposals/*/diagrams/*.seq.mmd; do docker run --rm -v "$PWD:/data" minlag/mermaid-cli -i /data/$diagram; done
+        run: for diagram in proposals/**/diagrams/*.seq.mmd; do docker run --rm -v "$PWD:/data" minlag/mermaid-cli -i /data/$diagram; done
 
       - name: generate png
-        run: for diagram in proposals/*/diagrams/*.flow.mmd; do docker run --rm -v "$PWD:/data" minlag/mermaid-cli -i /data/$diagram -o /data/$diagram.png; done
+        run: for diagram in proposals/**/diagrams/*.flow.mmd; do docker run --rm -v "$PWD:/data" minlag/mermaid-cli -i /data/$diagram -o /data/$diagram.png; done
 
 
       - name: deploy

proposals/primer/application.bs

@@ -93,7 +93,7 @@ as link relation.
     Authorization: DPoP ....
   </pre>
   <pre highlight=http line-highlight=3>
-    HTTP/1.1 200 OK
+    HTTP/1.1 204 OK
     Link: &lt;https://projectron.example/#app&gt;;
       anchor="https://auth.alice.example/bcf22534-0187-4ae4-b88f-fe0f9fa96659";
       rel="http://www.w3.org/ns/solid/interop#registeredAgent"

proposals/primer/authorization-agent.bs

@@ -198,7 +198,7 @@ The reference to reciprocal registration can be created after receiving an [[#ac
 from another Social Agent and performing [[#agent-registration-discovery]]
 
 In the case of Social Agent Registration for ACME, created in Alice's Agent Registry. The reciprocal registration
-will be the Social Agent Reigstration for Alice, created in ACME's Agent Registry.
+will be the Social Agent Registration for Alice, created in ACME's Agent Registry.
 
 <img class="flowchart-diagram" src="diagrams/reciprocal-registration.flow.mmd.png" />
 
@@ -226,7 +226,7 @@ own Authorization Agent. The response will include a link to the Application reg
     Authorization: DPoP ....
   </pre>
   <pre highlight=http line-highlight=3>
-    HTTP/1.1 200 OK
+    HTTP/1.1 204 OK
     Link: &lt;https://projectron.example/#app&gt;;
       anchor="https://auth.alice.example/bcf22534-0187-4ae4-b88f-fe0f9fa96659";
       rel="http://www.w3.org/ns/solid/interop#registeredAgent"
@@ -244,7 +244,7 @@ another's social agent Authorization Agent. The response will include a link to
     Authorization: DPoP ....
   </pre>
   <pre highlight=http line-highlight=3>
-    HTTP/1.1 200 OK
+    HTTP/1.1 204 OK
     Link: &lt;https://bob.example/#id&gt;;
       anchor="https://auth.alice.example/92868ad4-a9e6-42df-9cb0-883350c62769";
       rel="http://www.w3.org/ns/solid/interop#registeredAgent"

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

@@ -0,0 +1,23 @@
+
+# Agent Manager # {#sec-agent-manager}
+
+[=Entities=] for which the [=Managing Agent=] wants to tailor 
+the presentation of information [=Resources=] 
+to the [=Agent=] trying to discover them, 
+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).
+
+Each [=Identity Document=] of an [=Entity=] 
+[SHOULD] only have a single [=Agent Manager=] related to it. 
+The URL of that [=Agent Manager=] [MUST] be unique to that [=Entity=]. 
+In scenarios where an [=Agent Manager=] services [=Agents=] for multiple [=Entities=], 
+this may be facilitated through a unique sub-domain or path.
+
+
+## Agent Manager Discovery ## {#sec-am-discovery}
+
+<pre class=include>path: amd-request.bs</pre>
+<pre class=include>path: amd-response.bs</pre>
+<pre class=include>path: amd-result.bs</pre>

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

@@ -0,0 +1,43 @@
+
+# Registering a New Agent # {#sec-agent-registering}
+
+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).
+Both will differ between contexts; it is therefore left up to each
+implementation to decide on such a mechanism and its constraints. This document
+does, however, specify a framework in which such <span id=dfn-arr><dfn
+export>Agent Registration Requests</dfn> [SHOULD] take place. 
+
+[=Agent Managers=] supporting this feature [MUST] respond to valid but unknown
+[=Agents=] with status code [S403], including a
+[:WWW-Authenticate:] header with the [:DPoP:] scheme and the [:error:] parameter
+set to `insufficient_scope`, as well as a [:Link:] header with the URL of the
+[=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.
+
+    EXAMPLE: One trivial implementation of an [=Agent Registration Request=] 
+    process could be to use an [OAUTH] server with [DCR], and signal that to 
+    the [=Agent=] with the [=Relation Type=] `oidc:registration_endpoint`.
+
+    <div class=example id=ex-ard-response-arr>
+
+        Example response from an [=Agent Manager=] when no [=Agent-Specific 
+        Resource=] is found for the requesting [=Agent=].
+
+        <pre highlight=http>
+            HTTP/1.1 403 Forbidden
+            Location: new-ar
+            Link: &lt;https://my.id/agent-manager/agents/&gt;; 
+              rel="http://www.w3.org/ns/solid/oidc#registration_endpoint"; 
+              anchor="https://my.id/agent-manager"
+        </pre>  
+
+    </div>
+
+<pre class=include>path: arr-request.bs</pre>
+<pre class=include>path: arr-response.bs</pre>
+<pre class=include>path: arr-result.bs</pre>

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

@@ -0,0 +1,101 @@
+
+# Agent Registry #  {#sec-agent-registry}
+
+In order to present [=Agents=] with their [=Agent-Specific Resources=], 
+the [=Agent Manager=] keeps track of them in an [AGENT-REGISTRY]
+([=RDF-SCHEMA|RDF Class=] `interop:AgentRegistry`):
+an [LDP] [=Container=] which [=contains=] an [=Agent Registration=]
+for each [#sec-ar-requests|registered] [=Agent=].
+
+    ISSUE: Should there be a level where the entity can keep 
+    information about the agent that is not accessible to the agent?
+
+
+## Agent Registrations ## {#sec-agent-registrations}
+
+An [AGENT-REGISTRATION] ([=RDF-SCHEMA|RDF Classes=] `interop:AgentRegistration`) 
+for an [=Agent=] is the initial [=Agent-Specific Resource=]
+of that [=Agent=] in the context of the [=Entity=].
+It encodes an [=RDF Graph=] containing information 
+about the [=Entity=] and the [=Agent=], 
+and relates them to other[=Agent-Specific Resources=].
+
+There can be only one [=Agent Registration=] for any given [=Agent=] in an [=Agent Registry=].
+The URL for each [=Agent Registration=] [SHOULD] be unpredictable,
+in order to avoid giving away any information without authorization.
+The [=Agent=] [#sec-ar-requests|registered] in a given [=Agent Registration=] 
+[SHOULD] have authorization to [:GET:] its contents.
+
+Each [=Agent Registration=] [SHOULD] include the following metadata parameters,
+encoded as [=RDF Triples=], with the parameter names in the `interop:` namespace,
+and the [=Agent Registration=] itself as the subject.
+It [MUST] at least record the [=Agent=] in question with `interop:registeredAgent`.
+
+  <table class="params data" align="left" id="params-agent-registry">
+    <thead>
+      <tr>
+        <th>Property</th>
+        <th>Range</th>
+        <th>Description</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>registeredAgent</td>
+        <td>[=foaf:Agent=]</td>
+        <td>The [=Agent=] that was registered.</td>
+      </tr>
+      <tr>
+        <td>registeredBy</td>
+        <td>[=foaf:Agent=]</td>
+        <td>The managing [=Agent=] that registered the [=Agent Registration=].</td>
+      </tr>
+      <tr>
+        <td>registeredWith</td>
+        <td>[=interop:AgentManager=]</td>
+        <td>The [=Agent Manager=] used to create the [=Agent Registration=]. <br />
+            This can be used to record versioning info.</td>
+      </tr>
+      <tr>
+        <td>registeredAt</td>
+        <td>xsd:dateTime</td>
+        <td>Date and time the [=Agent Registration=] was created.</td>
+      </tr>
+      <tr>
+        <td>updatedAt</td>
+        <td>xsd:dateTime</td>
+        <td>Date and time the [=Agent Registration=] was last updated.</td>
+      </tr>
+      <tr>
+        <td>reciprocalRegistration</td>
+        <td>[=interop:AgentRegistration=]</td>
+        <td>`OPTIONAL` In case the [=Entity=] is an [=Agent=] itself, this points <br />
+            to the [=Agent Registration=] that the registered [=Agent=] maintains <br />
+            for the [=Entity=].</td>
+      </tr>
+    </tbody>
+  </table>
+
+  <div class=example id=ex-agent-registry>
+
+    [[TURTLE]] representation of the [=RDF Triples=] of a minimal [=Agent Registration=]
+
+    <pre highlight=turtle>
+      alice:\/agents\/2f2f3628
+        a interop:AgentRegistration ;
+        interop:registeredAgent projectron:\#id ;
+        interop:registeredBy alice:\#id ;
+        interop:registeredWith jarvis:\#id ;
+        interop:registeredAt "2020-04-04T20:15:47.000Z"^^xsd:dateTime ;
+        interop:updatedAt "2020-04-04T21:11:33.000Z"^^xsd:dateTime ;
+        interop:reciprocalRegistration projectron:\/agents\/1e45be90 .
+    </pre>
+
+  </div>
+
+
+## Agent Registration Discovery ## {#sec-agent-registration-discovery}
+
+<pre class=include>path: ard-request.bs</pre>
+<pre class=include>path: ard-response.bs</pre>
+<pre class=include>path: ard-result.bs</pre>

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

@@ -0,0 +1,16 @@
+
+### Discovery Request ### {#sec-amd-request}
+
+[=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`.
+
+    <div class=example id=ex-amd-request>
+
+        Example [:GET:] request to an [=Entity=] [=Identifier=].
+
+        <pre highlight=http>
+            GET [L]https://my.id/profile#me[R] HTTP/1.1
+        </pre>
+
+    </div>

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

@@ -0,0 +1,51 @@
+
+### Discovery Response ### {#sec-amd-response}
+
+Upon reception of a request to the [=Identity Document=], its host [SHOULD]
+respond with a representation of the [=Identity Document=], and an [HTTP]
+[:Link:] header of [=Relation Type=] `http://www.w3.org/ns/solid/interop#hasAgentManager` with the
+[=Entity's=] [=Identifier=] as [=Link Context=] and the URL of its [=Agent
+Manager=] as [=Link Target=].
+
+    <div class=example id=ex-amd-response-canon>
+
+        Canonical example response of an [=Entity's=] [=Identity Document=]
+        during Agent Manager Discovery.
+
+        <pre highlight=http>
+            HTTP/1.1 200 OK
+            Link: [L]https://my.id/agent-manager[R]; 
+              rel="http://www.w3.org/ns/solid/interop#hasAgentManager";
+              anchor="https://my.id/profile#me"
+        </pre>
+
+    </div>
+
+Alternatively, if the [=Identity Document=] is an [=RDF Document=] &mdash; the
+[=Identifier=] is [=RDF-Dereferenceable=] &mdash; the [:Link:] header [MAY] be
+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`.
+
+    <div class=example id=ex-amd-response-alt>
+
+        Alternative example response of an [=Entity's=] [=Identity Document=]
+        during Agent Manager Discovery.
+
+        <pre highlight=http>
+            HTTP/1.1 200 OK
+            &nbsp;
+            [L]https://my.id/profile#me[R] 
+                [L]https://www.w3.org/TR/rdf-schema/##seeAlso[R]
+                    [L]https://my.id/agent-manager[R] .
+        </pre>
+
+    </div>
+
+A host of [=Identity Documents=] [MUST] implement any of the above in order to
+comply with this specification.
+
+    ADVISEMENT: Because of security concerns, it is advisable to implement the canonical version of this step in Agent Manager Discovery. Relying on an
+    [=RDF Triple=] in a writable [=Identity Document=] might lead to unwanted
+    changes to or loss of the link to the [=Agent Manager=].

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

@@ -0,0 +1,23 @@
+
+### Discovery Result ### {#sec-amd-result}
+
+If the response to dereferencing an [=Entity's=] [=Identifier=] contains an
+[HTTP] [:Link:] header, the [=Link Context=] of which is the [=Entity's=]
+[=Identifier=] (e.g. `https://my.id/doc#me`), and the [=Relation Type=] of which
+is `http://www.w3.org/ns/solid/interop#hasAgentManager`, the [=Agent=] [SHOULD] take the [=Link Target=] of
+the header to be the URL of the [=Agent Manager=] of that [=Entity=]. 
+
+If no such header is present, and the response contains an [=RDF Document=]
+— the [=Identifier=] is [=RDF-Dereferenceable=] — the [=Agent=]
+[MAY] parse it. If the document contains an [=RDF Triple=] linking the
+[=Identifier=] of the [=Entity=] to a URL with the predicate
+`interop:hasAgentManager`, `rdfs:seeAlso`, or `pim:preferencesFile`, the
+[=Agent=] [SHOULD] take the object value to be the URL of the [=Entity's=]
+[=Agent Manager=]. 
+
+In case an [=Agent=] has found no [=Agent Manager=] in the response header or
+response body after dereferencing an [=Entity's=] [=Identifier=] to its
+[=Identity Document=], the requesting [=Agent=] [SHOULD] take there to be no
+[=Agent Manager=] for that [=Identifier=], and the [=Agent=] [SHOULD] take the
+public [=Resources=] discoverable from the [=Identity Document=] to contain the
+only information immediately available.

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

@@ -0,0 +1,24 @@
+
+### Discovery Request ### {#sec-ard-request}
+
+Once the [=Agent Manager=] of an [=Entity=] is known, an [=Agent=] wishing to
+discover its [=Agent-Specific Resources=] related to that [=Entity=] [SHOULD]
+query the [=Agent Manager=] by sending a [:HEAD:] or [:GET:] request to the
+[=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=].
+
+    <div class=example id=ex-am-request>
+
+        Example [:HEAD:] request to an [=Agent Manager=].
+
+        <pre highlight=http>
+            HEAD [L]https://my.id/agent-manager[R] HTTP/1.1
+            Authorization: DPoP [...Identity Token...]
+            DPoP: [...DPoP Proof...]
+        </pre>
+
+    </div>
+
+    ISSUE: TODO: Add decoded ID Token and DPoP Proof examples