Skip to content

Commit 0229828

Browse files
elf-pavlikelf-pavlik
committed
add SocialAgentInvitation
1 parent 22289b3 commit 0229828

7 files changed

Lines changed: 181 additions & 29 deletions

File tree

‎proposals/primer/authorization-agent.bs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -200,6 +200,17 @@ will be the Social Agent Reigstration for Alice, created in ACME's Agent Registr
200200

201201
<img class="flowchart-diagram" src="diagrams/reciprocal-registration.flow.mmd.png">
202202

203+
## Social Agent Invitation
204+
205+
Social Agent Invitation represents an invitation for a Social Agent. It takes advantage of an existing and secure
206+
communication channel between two agents to pass a secret link that allows accepting the invitation.
207+
This flow results in both agents establishing a pair of [[#reciprocal-registration|Reciprocal Registrations]].
208+
If the platform supports it, the Authorization Agent of the sender can use [[WEB-SHARE]] to pass the secret
209+
link to the user's messaging app. On the other side, the Authorization Agent of the recipient can use
210+
[[WEB-SHARE-TARGET]] to register with the platform and receive a secret link from the user's messaging app.
211+
Independent of the platform, Authorization Agents should always allow a simple copy of the link by the sender
212+
(e.g., `navigator.clipboard.writeText`) and paste it by the recipient.
213+
203214
## Application Registration
204215

205216
Application Registrations are created by the End-user for applications they use.

‎proposals/specification/agent-registrations.bs‎

Lines changed: 124 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,77 @@ When a given [=Agent=] is the subject of an [=Access Authorization=],
88
an [=Access Grant=] is generated and [[#ar-hierarchy|stored]]
99
in the [=Agent Registration=] for that [=Agent=].
1010

11+
## Application Registration ## {#application-registration}
12+
13+
An <dfn>Application Registration</dfn> provides the [=Social Agent=]
14+
with a place to maintain metadata, state, preferences, and
15+
other application-specific data associated with a given [=Application=] they
16+
have elected to use.
17+
18+
[=Application Registrations=] are stored in an [=Agent Registry=].
19+
20+
[Class Definition](interop.ttl#ApplicationRegistration) -
21+
[Shape Definition](interop.shex#ApplicationRegistrationShape) -
22+
[Shape Tree Definition](interop.tree#ApplicationRegistrationTree)
23+
24+
<table class="classinfo data" align="left" id="classApplicationRegistration">
25+
<colgroup></colgroup>
26+
<colgroup></colgroup>
27+
<colgroup></colgroup>
28+
<thead>
29+
<tr>
30+
<th>Property</th>
31+
<th>Range</th>
32+
<th>Description</th>
33+
</tr>
34+
</thead>
35+
<tbody>
36+
<tr>
37+
<td>registeredBy</td>
38+
<td>[SocialAgent](#classSocialAgent)</td>
39+
<td>[=Social Agent=] that registered the [=Application Registration=]</td>
40+
</tr>
41+
<tr>
42+
<td>registeredWith</td>
43+
<td>[Application](#classApplication)</td>
44+
<td>[=Application=] used to create the [=Application Registration=]</td>
45+
</tr>
46+
<tr>
47+
<td>registeredAt</td>
48+
<td>xsd:dateTime</td>
49+
<td>Date and time the [=Application Registration=] was created</td>
50+
</tr>
51+
<tr>
52+
<td>updatedAt</td>
53+
<td>xsd:dateTime</td>
54+
<td>Date and time the [=Application Registration=] was updated</td>
55+
</tr>
56+
<tr>
57+
<td>registeredAgent</td>
58+
<td>[Application](#classApplication)</td>
59+
<td>The [=Application=] that was registered</td>
60+
</tr>
61+
<tr>
62+
<td>hasAccessGrant</td>
63+
<td>[AccessGrant](#classAccessGrant)</td>
64+
<td>Links to an [=Access Grant=] describing the access that has been
65+
granted to the `registeredAgent`</td>
66+
</tr>
67+
</tbody>
68+
</table>
69+
70+
<figure>
71+
<figcaption>Alice's [=Application Registration=] for Projectron at
72+
https://alice.pod.example/agents/2f2f3628/ -
73+
<a href="snippets/alice.example/2f2f3628.ttl">View</a></figcaption>
74+
<pre class=include-code>
75+
path: snippets/alice.example/2f2f3628.ttl
76+
highlight: turtle
77+
show: 11-18
78+
</pre>
79+
</figure>
80+
81+
1182
## Social Agent Registration ## {#social-agent-registration}
1283

1384
A <dfn>Social Agent Registration</dfn> provides the [=Social Agent=]
@@ -69,6 +140,16 @@ interact with.
69140
<td>Links to an [=Access Grant=] describing the access that has been
70141
granted to the `registeredAgent`</td>
71142
</tr>
143+
<tr>
144+
<td>skos:prefLabel</td>
145+
<td>xsd:string</td>
146+
<td>Human readable label assigned by the user creating the registration</td>
147+
</tr>
148+
<tr>
149+
<td>skos:note</td>
150+
<td>xsd:string</td>
151+
<td>Optional note which can further help with recognising the agent</td>
152+
</tr>
72153
</tbody>
73154
</table>
74155

@@ -84,20 +165,18 @@ interact with.
84165
</pre>
85166
</figure>
86167

87-
## Application Registration ## {#application-registration}
168+
## Social Agent Invitation ## {#social-agent-invitation}
88169

89-
An <dfn>Application Registration</dfn> provides the [=Social Agent=]
90-
with a place to maintain metadata, state, preferences, and
91-
other application-specific data associated with a given [=Application=] they
92-
have elected to use.
170+
A <dfn>Social Agent Invitation</dfn> provides the [=Social Agent=]
171+
with a simple and secure way to establish data sharing with other [=Social Agents=].
93172

94-
[=Application Registrations=] are stored in an [=Agent Registry=].
173+
[=Social Agent Invitations=] are stored in an [=Agent Registry=].
95174

96-
[Class Definition](interop.ttl#ApplicationRegistration) -
97-
[Shape Definition](interop.shex#ApplicationRegistrationShape) -
98-
[Shape Tree Definition](interop.tree#ApplicationRegistrationTree)
175+
[Class Definition](interop.ttl#SocialAgentInvitation) -
176+
[Shape Definition](interop.shex#SocialAgentInvitationShape) -
177+
[Shape Tree Definition](interop.tree#SocialAgentInvitationTree)
99178

100-
<table class="classinfo data" align="left" id="classApplicationRegistration">
179+
<table class="classinfo data" align="left" id="classSocialAgentInvitation">
101180
<colgroup></colgroup>
102181
<colgroup></colgroup>
103182
<colgroup></colgroup>
@@ -112,48 +191,67 @@ have elected to use.
112191
<tr>
113192
<td>registeredBy</td>
114193
<td>[SocialAgent](#classSocialAgent)</td>
115-
<td>[=Social Agent=] that registered the [=Application Registration=]</td>
194+
<td>[=Social Agent=] that registered the [=Social Agent Invitation=]</td>
116195
</tr>
117196
<tr>
118197
<td>registeredWith</td>
119198
<td>[Application](#classApplication)</td>
120-
<td>[=Application=] used to create the [=Application Registration=]</td>
199+
<td>[=Application=] used to create the [=Social Agent Invitation=]</td>
121200
</tr>
122201
<tr>
123202
<td>registeredAt</td>
124203
<td>xsd:dateTime</td>
125-
<td>Date and time the [=Application Registration=] was created</td>
204+
<td>Date and time the [=Social Agent Invitation=] was created</td>
126205
</tr>
127206
<tr>
128207
<td>updatedAt</td>
129208
<td>xsd:dateTime</td>
130-
<td>Date and time the [=Application Registration=] was updated</td>
209+
<td>Date and time the [=Social Agent Invitation=] was updated</td>
131210
</tr>
132211
<tr>
133-
<td>registeredAgent</td>
134-
<td>[Application](#classApplication)</td>
135-
<td>The [=Application=] that was registered</td>
212+
<td>capabilityUrl</td>
213+
<td>[[!capability-urls|Capability URL]]</td>
214+
<td>Secure link used to accept the invitation</td>
136215
</tr>
137216
<tr>
138-
<td>hasAccessGrant</td>
139-
<td>[AccessGrant](#classAccessGrant)</td>
140-
<td>Links to an [=Access Grant=] describing the access that has been
141-
granted to the `registeredAgent`</td>
217+
<td>skos:prefLabel</td>
218+
<td>xsd:string</td>
219+
<td>Human readable label assigned by the user creating the invitation</td>
220+
</tr>
221+
<tr>
222+
<td>skos:note</td>
223+
<td>xsd:string</td>
224+
<td>Optional note which can further help with understanding who is being invited</td>
142225
</tr>
143226
</tbody>
144227
</table>
145228

146229
<figure>
147-
<figcaption>Alice's [=Application Registration=] for Projectron at
148-
https://alice.pod.example/agents/2f2f3628/ -
149-
<a href="snippets/alice.example/2f2f3628.ttl">View</a></figcaption>
230+
<figcaption>Alice's [=Social Agent Invitation=] for Yori at
231+
https://alice.pod.example/agents/a1umr5yx/ -
232+
<a href="snippets/alice.example/a1umr5yx.ttl">View</a>
233+
</figcaption>
150234
<pre class=include-code>
151-
path: snippets/alice.example/2f2f3628.ttl
235+
path: snippets/alice.example/a1umr5yx.ttl
152236
highlight: turtle
153-
show: 11-18
237+
show: 14-99
154238
</pre>
155239
</figure>
156240

241+
[=Authorization Agent=] accepting an authenticated request, targeting the `capabilityUrl`
242+
from a [=Social Agent Invitation=]
243+
* MUST respond with the [[!WEBID]] of the [=Social Agent=] who created the [=Social Agent Invitation=], using `Content-Type: text/plain`
244+
* MUST use the identity of the [=Social Agent=], from the incoming request,
245+
as the `registeredAgent` for newly created [=Social Agent Registration=].
246+
* SHOULD use the `skos:prefLabel` from the [=Social Agent Invitation=] for the new [=Social Agent Registration=].
247+
* SHOULD use the `skos:note` from the [=Social Agent Invitation=] for the new [=Social Agent Registration=].
248+
* SHOULD schedule [[#agent-registration-discovery]] on the `registeredAgent` from the new [=Social Agent Registration=].
249+
After the successful discovery, add it as `reciprocalRegistration`
250+
251+
Note: Commonly the [=Authorization Agent=], making the request on behalf of the [=Social Agent=] accepting the invitation,
252+
will create corresponding [=Social Agent Registration=] after receiving the [[!WEBID]] in the response,
253+
which means that it is not available before receiving the response.
254+
157255
## Agent Registry ## {#ar-registry}
158256

159257
An <dfn>Agent Registry</dfn> is a collection of <dfn>Agent Registrations</dfn>.

‎proposals/specification/index.bs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ Title: Solid Application Interoperability
33
Shortname: interop
44
Level: 1
55
Max ToC Depth: 2
6-
Status: w3c/ED
6+
Status: w3c/CG-DRAFT
77
Group: w3c
88
URL: https://solid.github.io/data-interoperability-panel/specification/
99
Repository: https://github.com/solid/data-interoperability-panel

‎proposals/specification/interop.shex‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,17 @@ PREFIX skos: <http://www.w3.org/2004/02/skos/core#>
3838
&<#CommonRegistrationProperties> ;
3939
interop:registeredAgent IRI // shex:reference <#AgentShape> ;
4040
interop:hasAccessGrant IRI // shex:reference <#AccessGrantShape> ;
41-
interop:reciprocalRegistration IRI? // shex:reference <#SocialAgentShape>
41+
interop:reciprocalRegistration IRI? // shex:reference <#SocialAgentShape> ;
42+
skos:prefLabel xsd:string ;
43+
skos:note xsd:string?
44+
}
45+
46+
<#SocialAgentInvitationShape> {
47+
a [ interop:SocialAgentInvitation ] ;
48+
&<#CommonRegistrationProperties
49+
interop:capabilityUrl IRI ;
50+
skos:prefLabel xsd:string ;
51+
skos:note xsd:string?
4252
}
4353

4454
<#ApplicationRegistrationShape> {

‎proposals/specification/interop.tree‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,8 @@ PREFIX interops: <http://www.w3.org/ns/solid/interop-schema#>
4242
st:expectsType st:Container ;
4343
st:shape interops:AgentRegistryShape ;
4444
st:contains <#ApplicationRegistrationTree> ,
45-
<#SocialAgentRegistrationTree> .
45+
<#SocialAgentRegistrationTree> ,
46+
<#SocialAgentInvitationTree> .
4647

4748
<#ApplicationRegistrationTree>
4849
a st:ShapeTree ;
@@ -57,6 +58,10 @@ PREFIX interops: <http://www.w3.org/ns/solid/interop-schema#>
5758
st:shape interops:SocialAgentRegistrationShape ;
5859
st:contains <#AccessGrantTree> ,
5960
<#DataGrantTree> .
61+
<#SocialAgentInvitationTree>
62+
a st:ShapeTree ;
63+
st:expectsType st:Container ;
64+
st:shape interops:SocialAgentInvitationShape .
6065

6166
<#AccessGrantTree>
6267
a st:ShapeTree ;

‎proposals/specification/interop.ttl‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -182,6 +182,12 @@ rdfs:label "Terms for application interoperability in Solid"@en .
182182
rdfs:isDefinedBy <> ;
183183
rdfs:label "Social Agent Registration"@en .
184184

185+
:SocialAgentInvitation
186+
rdfs:subClassOf :AgentRegistration ;
187+
rdfs:comment "An invited Social Agent in an Agent Registry"@en ;
188+
rdfs:isDefinedBy <> ;
189+
rdfs:label "Social Agent Invitation"@en .
190+
185191
:ApplicationRegistration
186192
rdfs:subClassOf :AgentRegistration ;
187193
rdfs:comment "A registered Application in an Agent Registry"@en ;

‎proposals/specification/snippets/alice.example/a1umr5yx.ttl‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
2+
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
3+
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
4+
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>
5+
PREFIX acl: <http://www.w3.org/ns/auth/acl#>
6+
PREFIX interop: <http://www.w3.org/ns/solid/interop#>
7+
PREFIX pm-shapetrees: <http://data.example/shapetrees/pm#>
8+
PREFIX alice: <https://alice.example/>
9+
PREFIX jarvis: <https://jarvis.example/>
10+
PREFIX bob: <https://bob.example>
11+
PREFIX alice-agents: <https://alice.example/agents/>
12+
PREFIX bob-agents: <https://bob.example/agents/>
13+
14+
alice-agents:a1umr5yx\/
15+
a interop:SocialAgentInvitation ;
16+
interop:registeredBy alice:\#id ;
17+
interop:registeredWith jarvis:\#id ;
18+
interop:registeredAt "2020-04-04T20:15:47.000Z"^^xsd:dateTime ;
19+
interop:updatedAt "2020-04-04T21:11:33.000Z"^^xsd:dateTime ;
20+
interop:capabilityUrl jarvis:invitations\/z8tms2zzq3d9vfpo1a6yk5jkgn5y4aem ;
21+
skos:prefLabel "Yori" ;
22+
skos:note "A friend from my D&D club" .

0 commit comments

Comments
 (0)