# Social Agent Invitation and Identity Verification

## Prior work and Issues

### SAI Invitation Draft

https://github.com/solid/data-interoperability-panel/tree/main/proposals/invitation

### SAI Issues

* [Use invitation to validate the source of an incoming request #214](https://github.com/solid/data-interoperability-panel/issues/214)
* [authorization agent should check Resource Owner's address book if it includes requesting End-user's WebID #96](https://github.com/solid/data-interoperability-panel/issues/96)
* [On phishing with a WebID #161](https://github.com/solid/authentication-panel/issues/161)

## Use Cases

### Alice shares data with Bob, but she doesn't know Bob's WebID (Bob might not even have WebID yet)

This will be a very common scenario as Solid and WebID start gaining adoption. People who have pre-established communication channels with their social peers will want to share data with them and help them onboard.

### Alice receives data sharing receipt from Bob, she want's to confirm that Bob's WebID in that receipt

## Proposed Solution

* We will leverage [Social Agent Registration](https://solid.github.io/data-interoperability-panel/specification/#social-agent-registration) which is well defined in SAI. As well as mutual `interop:reciprocalRegistration` relation between two Social Agent Registrations.
* We will limit use of AccessInbox, which is discoverable from WebID Document and allows AuthenticatedAgents to post messages. Once agents establish matching reciprocal Social Agent Registrations they use it as private channel using [Solid Notifications](https://solidproject.org/TR/notifications-protocol).
* We will take adavantage from existing Authentication mechanism like [Solid-OIDC](https://solidproject.org/TR/oidc). Where incoming requests include authenticated WebID.

### Evaluation for use cases

#### Alice shares data with Bob, but she doesn't know Bob's WebID (Bob might not even have WebID yet

* Alice's Authorization Agent creates Social Agent Invitation in their Agent Registry, instread of Social Agent Registration.
* It generates temporary IRI which will be used as `interop:registeredAgent` value, as well as `interop:grantee` value in [Access Authorization](https://solid.github.io/data-interoperability-panel/specification/#access-authorization)
* Access Grant is NOT generated for Social Agent Invitation based on the Access Authorization
* Alice's Authorization Agent creates [Capability URL](https://www.w3.org/TR/capability-urls/) which Alice needs to share with Bob over a pre-established trusted and secure communication channel (phone IM, email, SMS etc.) It gets associated with Social Agent Invitation created for Bob.
* Bob needs WebID, if he doesn't have one yet, the message from Alice may also include link to instructions on how to get a WebID.
* Bob provides Capability URL from the message to a Solid Client capable of making authenticated requests. Prefereably Bob's Authorization Agent. [Web Share API](https://w3c.github.io/web-share/) and [Web Share Target API](https://w3c.github.io/web-share-target/level-2/#share_target-member) can be used to optimise the UX.
* When Alice's Authorization Agent receives authenticated request to the Capability URL associated with Social Agent Invitation created for Bob.
* It replaces Social Agent Invitaiton with Social Agent Registration and uses WebID from authenticated request as `interop:registeredAgent` value.
* It replaces Data Authorization with equivalet one and uses WebID from authenticated request as `interop:grantee`
* It generates Access Grant based on new Access Authorization and adds it to Social Agent Registration
* Delivers Access Receipt to Bob's Authorization Inbox, Bob's AA can already discover Social Agent Registration created for Bob.

Response from request to Capability URL could include Alice's WebID to allow Bob discover his registration and verify Alice's WebID already

#### Bob receives an Access Receipt from Alice, he want's to confirm that it is Alice's WebID in that receipt

* Bob's Authorization Agent creates Social Agent Registration using WebID from the Access Receipt in their Agent Registry. Marking it as **unverified**.
* Bob's Authorization Agent generates Capability URL and associates it with this Unverified Social Agent Registration.
* Bob shares that Capability URL with Alice over a pre-established trusted and secure communication channel (phone IM, email, SMS etc.).
* Alice provides Capability URL from the message to a Soclid Client capable of making authenticated requests, preferably Alice's Authorization Agent. (Web Share for UX)
* When Bob's Authorization Agent receives authenticated request to the Capability URL associated with Unverified Agent Registration, if the WebID from incoming request matches the value of `interop:registeredAgent` it can mark it as verified. Otherwise flag it and warn Bob.

### Further improvements

We could require more than one Capability URL to be used for multi-channel verification. For example one would be send over the email and the other one over phone IM.