Sharing proposal: federated sharing with acceptance from consumer

[dvh]

This issue describes the proposed scenario where the owner of a resource (provider) wants to share his/her resource with someone else (consumer) and the consumer needs to accept that this resource is being shared with him/her.

The image above illustrates the global workflow for this scenario:

1. The provider sends a 'ShareOffer' to the consumer.
2. If the consumer rejects or accepts the offer, the provider should be notified by this event.
3. If the offer is expired, already accepted or invalid for any other reason, the provider should report this to the consumer.
4. If the offer is still valid, the provider grants access to the resource by issuing an access token to the consumer.

Provider wants to share a resource

The next image illustrates the interaction between consumer (left) and provider (right) for the part of the flow where the provider wants to share a resource. To distinguish the contexts of 'Share' between both parties, we use the term 'Invitation' instead of a 'ShareOffer'. Security, communication, authentication and authorization between two parties are dealt with the proposal of issue #23 and there left out of the scope of this particular issue.

1. The rounded rectangle represents the starting point of this process. The provider creates a share where the consumer can reference to. It's probably stored in an internal database, but as we are not interested in vendor specific logic, we'll just illustrate this 'black box' as a database with the title 'Vendor specific internals'.
2. Whether it's stored in a database or not, the provider performs a POST request to the consumers /invitations endpoint. If the request is successful (possible errors and the structure of the invitation object are described in the Open API Specification), the consumer should notify the provider by returning the correct response. Both parties can then do whatever they want in their vendor specific logic, but we now know that succesful communication between the two parties has been established.

Consumer accepts the invitation

If there is an invitation pending at the consumers side, a consumer can accept the invitation to obtain actual access to the file and to notify the provider that the invitation has been accepted:

Once again the rounded rectangle is the start of the flow, and this time it starts on the left side where the consumer wants to accept the pending invitation.

1. The consumer performs a POST request to the providers /shares/{id}/accept endpoint.
2. The provider checks if the invitation is still valid and might do additional vendor specific business logic (which we are not interested in) before returning a succesful response (or an error) to the consumer. Possible errors and the structure of the Acceptance and Share object are described in the Open API Specification.

Consumer rejects the invitation

If there is an invitation pending at the consumers side, a consumer can reject the invitation as well. To notify the provider of this event, the consumer should do a similar request as described above, but then to the providers /shares/{id}/reject endpoint.

[dvh]

Proposal rejected, we've decided to accept proposal #25 instead.