add SocialAgentInvitation

solid · Mar 3, 2024 · 0229828 · 0229828
1 parent 22289b3
commit 0229828
Show file tree

Hide file tree

Showing 7 changed files with 181 additions and 29 deletions.
diff --git a/proposals/primer/authorization-agent.bs b/proposals/primer/authorization-agent.bs
@@ -200,6 +200,17 @@ will be the Social Agent Reigstration for Alice, created in ACME's Agent Registr
 
 <img class="flowchart-diagram" src="diagrams/reciprocal-registration.flow.mmd.png">
 
+## Social Agent Invitation
+
+Social Agent Invitation represents an invitation for a Social Agent. It takes advantage of an existing and secure
+communication channel between two agents to pass a secret link that allows accepting the invitation.
+This flow results in both agents establishing a pair of [[#reciprocal-registration|Reciprocal Registrations]].
+If the platform supports it, the Authorization Agent of the sender can use [[WEB-SHARE]] to pass the secret
+link to the user's messaging app. On the other side, the Authorization Agent of the recipient can use
+[[WEB-SHARE-TARGET]] to register with the platform and receive a secret link from the user's messaging app.
+Independent of the platform, Authorization Agents should always allow a simple copy of the link by the sender
+(e.g., `navigator.clipboard.writeText`) and paste it by the recipient.
+
 ## Application Registration
 
 Application Registrations are created by the End-user for applications they use.

diff --git a/proposals/specification/agent-registrations.bs b/proposals/specification/agent-registrations.bs
@@ -8,6 +8,77 @@ When a given [=Agent=] is the subject of an [=Access Authorization=],
 an [=Access Grant=] is generated and [[#ar-hierarchy|stored]] 
 in the [=Agent Registration=] for that [=Agent=].
 
+## Application Registration ## {#application-registration}
+
+An <dfn>Application Registration</dfn> provides the [=Social Agent=]
+with a place to maintain metadata, state, preferences, and
+other application-specific data associated with a given [=Application=] they
+have elected to use.
+
+[=Application Registrations=] are stored in an [=Agent Registry=].
+
+[Class Definition](interop.ttl#ApplicationRegistration) -
+[Shape Definition](interop.shex#ApplicationRegistrationShape) -
+[Shape Tree Definition](interop.tree#ApplicationRegistrationTree)
+
+<table class="classinfo data" align="left" id="classApplicationRegistration">
+  <colgroup></colgroup>
+  <colgroup></colgroup>
+  <colgroup></colgroup>
+  <thead>
+    <tr>
+      <th>Property</th>
+      <th>Range</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>registeredBy</td>
+      <td>[SocialAgent](#classSocialAgent)</td>
+      <td>[=Social Agent=] that registered the [=Application Registration=]</td>
+    </tr>
+    <tr>
+      <td>registeredWith</td>
+      <td>[Application](#classApplication)</td>
+      <td>[=Application=] used to create the [=Application Registration=]</td>
+    </tr>
+    <tr>
+      <td>registeredAt</td>
+      <td>xsd:dateTime</td>
+      <td>Date and time the [=Application Registration=] was created</td>
+    </tr>
+    <tr>
+      <td>updatedAt</td>
+      <td>xsd:dateTime</td>
+      <td>Date and time the [=Application Registration=] was updated</td>
+    </tr>
+    <tr>
+      <td>registeredAgent</td>
+      <td>[Application](#classApplication)</td>
+      <td>The [=Application=] that was registered</td>
+    </tr>
+    <tr>
+      <td>hasAccessGrant</td>
+      <td>[AccessGrant](#classAccessGrant)</td>
+      <td>Links to an [=Access Grant=] describing the access that has been
+      granted to the `registeredAgent`</td>
+    </tr>
+  </tbody>
+</table>
+
+<figure>
+  <figcaption>Alice's [=Application Registration=] for Projectron at
+  https://alice.pod.example/agents/2f2f3628/ -
+  <a href="snippets/alice.example/2f2f3628.ttl">View</a></figcaption>
+  <pre class=include-code>
+  path: snippets/alice.example/2f2f3628.ttl
+  highlight: turtle
+  show: 11-18
+  </pre>
+</figure>
+
+
 ## Social Agent Registration ## {#social-agent-registration}
 
 A <dfn>Social Agent Registration</dfn> provides the [=Social Agent=]
@@ -69,6 +140,16 @@ interact with.
       <td>Links to an [=Access Grant=] describing the access that has been
       granted to the `registeredAgent`</td>
     </tr>
+    <tr>
+      <td>skos:prefLabel</td>
+      <td>xsd:string</td>
+      <td>Human readable label assigned by the user creating the registration</td>
+    </tr>
+    <tr>
+      <td>skos:note</td>
+      <td>xsd:string</td>
+      <td>Optional note which can further help with recognising the agent</td>
+    </tr>
   </tbody>
 </table>
 
@@ -84,20 +165,18 @@ interact with.
   </pre>
 </figure>
 
-## Application Registration ## {#application-registration}
+## Social Agent Invitation ## {#social-agent-invitation}
 
-An <dfn>Application Registration</dfn> provides the [=Social Agent=]
-with a place to maintain metadata, state, preferences, and
-other application-specific data associated with a given [=Application=] they
-have elected to use.
+A <dfn>Social Agent Invitation</dfn> provides the [=Social Agent=]
+with a simple and secure way to establish data sharing with other [=Social Agents=].
 
-[=Application Registrations=] are stored in an [=Agent Registry=].
+[=Social Agent Invitations=] are stored in an [=Agent Registry=].
 
-[Class Definition](interop.ttl#ApplicationRegistration) -
-[Shape Definition](interop.shex#ApplicationRegistrationShape) -
-[Shape Tree Definition](interop.tree#ApplicationRegistrationTree)
+[Class Definition](interop.ttl#SocialAgentInvitation) -
+[Shape Definition](interop.shex#SocialAgentInvitationShape) -
+[Shape Tree Definition](interop.tree#SocialAgentInvitationTree)
 
-<table class="classinfo data" align="left" id="classApplicationRegistration">
+<table class="classinfo data" align="left" id="classSocialAgentInvitation">
   <colgroup></colgroup>
   <colgroup></colgroup>
   <colgroup></colgroup>
@@ -112,48 +191,67 @@ have elected to use.
     <tr>
       <td>registeredBy</td>
       <td>[SocialAgent](#classSocialAgent)</td>
-      <td>[=Social Agent=] that registered the [=Application Registration=]</td>
+      <td>[=Social Agent=] that registered the [=Social Agent Invitation=]</td>
     </tr>
     <tr>
       <td>registeredWith</td>
       <td>[Application](#classApplication)</td>
-      <td>[=Application=] used to create the [=Application Registration=]</td>
+      <td>[=Application=] used to create the [=Social Agent Invitation=]</td>
     </tr>
     <tr>
       <td>registeredAt</td>
       <td>xsd:dateTime</td>
-      <td>Date and time the [=Application Registration=] was created</td>
+      <td>Date and time the [=Social Agent Invitation=] was created</td>
     </tr>
     <tr>
       <td>updatedAt</td>
       <td>xsd:dateTime</td>
-      <td>Date and time the [=Application Registration=] was updated</td>
+      <td>Date and time the [=Social Agent Invitation=] was updated</td>
     </tr>
     <tr>
-      <td>registeredAgent</td>
-      <td>[Application](#classApplication)</td>
-      <td>The [=Application=] that was registered</td>
+      <td>capabilityUrl</td>
+      <td>[[!capability-urls|Capability URL]]</td>
+      <td>Secure link used to accept the invitation</td>
     </tr>
     <tr>
-      <td>hasAccessGrant</td>
-      <td>[AccessGrant](#classAccessGrant)</td>
-      <td>Links to an [=Access Grant=] describing the access that has been
-      granted to the `registeredAgent`</td>
+      <td>skos:prefLabel</td>
+      <td>xsd:string</td>
+      <td>Human readable label assigned by the user creating the invitation</td>
+    </tr>
+    <tr>
+      <td>skos:note</td>
+      <td>xsd:string</td>
+      <td>Optional note which can further help with understanding who is being invited</td>
     </tr>
   </tbody>
 </table>
 
 <figure>
-  <figcaption>Alice's [=Application Registration=] for Projectron at
-  https://alice.pod.example/agents/2f2f3628/ -
-  <a href="snippets/alice.example/2f2f3628.ttl">View</a></figcaption>
+  <figcaption>Alice's [=Social Agent Invitation=] for Yori at
+  https://alice.pod.example/agents/a1umr5yx/ -
+  <a href="snippets/alice.example/a1umr5yx.ttl">View</a>
+  </figcaption>
   <pre class=include-code>
-  path: snippets/alice.example/2f2f3628.ttl
+  path: snippets/alice.example/a1umr5yx.ttl
   highlight: turtle
-  show: 11-18
+  show: 14-99
   </pre>
 </figure>
 
+[=Authorization Agent=] accepting an authenticated request, targeting the `capabilityUrl`
+from a [=Social Agent Invitation=]
+* MUST respond with the [[!WEBID]] of the [=Social Agent=] who created the [=Social Agent Invitation=], using `Content-Type: text/plain`
+* MUST use the identity of the [=Social Agent=], from the incoming request,
+    as the `registeredAgent` for newly created [=Social Agent Registration=].
+* SHOULD use the `skos:prefLabel` from the [=Social Agent Invitation=] for the new [=Social Agent Registration=].
+* SHOULD use the `skos:note` from the [=Social Agent Invitation=] for the new [=Social Agent Registration=].
+* SHOULD schedule [[#agent-registration-discovery]] on the `registeredAgent` from the new  [=Social Agent Registration=].
+    After the successful discovery, add it as `reciprocalRegistration`
+
+Note: Commonly the [=Authorization Agent=], making the request on behalf of the [=Social Agent=] accepting the invitation,
+    will create corresponding [=Social Agent Registration=] after receiving the [[!WEBID]] in the response,
+    which means that it is not available before receiving the response.
+
 ## Agent Registry ## {#ar-registry}
 
 An <dfn>Agent Registry</dfn> is a collection of <dfn>Agent Registrations</dfn>.

diff --git a/proposals/specification/index.bs b/proposals/specification/index.bs
@@ -3,7 +3,7 @@ Title: Solid Application Interoperability
 Shortname: interop
 Level: 1
 Max ToC Depth: 2
-Status: w3c/ED
+Status: w3c/CG-DRAFT
 Group: w3c
 URL: https://solid.github.io/data-interoperability-panel/specification/
 Repository: https://github.com/solid/data-interoperability-panel

diff --git a/proposals/specification/interop.shex b/proposals/specification/interop.shex
@@ -38,7 +38,17 @@ PREFIX skos: <http://www.w3.org/2004/02/skos/core#>
   &<#CommonRegistrationProperties> ;
   interop:registeredAgent                   IRI  // shex:reference <#AgentShape> ;
   interop:hasAccessGrant                    IRI  // shex:reference <#AccessGrantShape> ;
-  interop:reciprocalRegistration            IRI? // shex:reference <#SocialAgentShape>
+  interop:reciprocalRegistration            IRI? // shex:reference <#SocialAgentShape> ;
+  skos:prefLabel                            xsd:string ;
+  skos:note                                 xsd:string?
+}
+
+<#SocialAgentInvitationShape> {
+  a [ interop:SocialAgentInvitation ] ;
+  &<#CommonRegistrationProperties
+  interop:capabilityUrl                     IRI ;
+  skos:prefLabel                            xsd:string ;
+  skos:note                                 xsd:string?
 }
 
 <#ApplicationRegistrationShape> {

diff --git a/proposals/specification/interop.tree b/proposals/specification/interop.tree
@@ -42,7 +42,8 @@ PREFIX interops: <http://www.w3.org/ns/solid/interop-schema#>
   st:expectsType    st:Container ;
   st:shape          interops:AgentRegistryShape ;
   st:contains       <#ApplicationRegistrationTree> ,
-                    <#SocialAgentRegistrationTree> .
+                    <#SocialAgentRegistrationTree> ,
+                    <#SocialAgentInvitationTree> .
 
 <#ApplicationRegistrationTree>
   a st:ShapeTree ;
@@ -57,6 +58,10 @@ PREFIX interops: <http://www.w3.org/ns/solid/interop-schema#>
   st:shape          interops:SocialAgentRegistrationShape ;
   st:contains       <#AccessGrantTree> ,
                     <#DataGrantTree> .
+<#SocialAgentInvitationTree>
+  a st:ShapeTree ;
+  st:expectsType    st:Container ;
+  st:shape          interops:SocialAgentInvitationShape .
 
 <#AccessGrantTree>
   a st:ShapeTree ;

diff --git a/proposals/specification/interop.ttl b/proposals/specification/interop.ttl
@@ -182,6 +182,12 @@ rdfs:label "Terms for application interoperability in Solid"@en .
   rdfs:isDefinedBy <> ;
   rdfs:label "Social Agent Registration"@en .
 
+:SocialAgentInvitation
+  rdfs:subClassOf :AgentRegistration ;
+  rdfs:comment "An invited Social Agent in an Agent Registry"@en ;
+  rdfs:isDefinedBy <> ;
+  rdfs:label "Social Agent Invitation"@en .
+
 :ApplicationRegistration
   rdfs:subClassOf :AgentRegistration ;
   rdfs:comment "A registered Application in an Agent Registry"@en ;

diff --git a/proposals/specification/snippets/alice.example/a1umr5yx.ttl b/proposals/specification/snippets/alice.example/a1umr5yx.ttl
@@ -0,0 +1,22 @@
+PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
+PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
+PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
+PREFIX skos: <http://www.w3.org/2004/02/skos/core#>
+PREFIX acl: <http://www.w3.org/ns/auth/acl#>
+PREFIX interop: <http://www.w3.org/ns/solid/interop#>
+PREFIX pm-shapetrees: <http://data.example/shapetrees/pm#>
+PREFIX alice: <https://alice.example/>
+PREFIX jarvis: <https://jarvis.example/>
+PREFIX bob: <https://bob.example>
+PREFIX alice-agents: <https://alice.example/agents/>
+PREFIX bob-agents: <https://bob.example/agents/>
+
+alice-agents:a1umr5yx\/
+  a interop:SocialAgentInvitation ;
+  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:capabilityUrl jarvis:invitations\/z8tms2zzq3d9vfpo1a6yk5jkgn5y4aem ;
+  skos:prefLabel "Yori" ;
+  skos:note "A friend from my D&D club" .