RequestShare: Introduce the notion of a share request

IETF-RFC.md

@@ -454,6 +454,28 @@ The Receiving Server MAY discard the notification if any of the following hold t
 * the Receiving Server is unable to act as an API client for (any of) the protocol(s) listed for accessing the resource
 * an initial check shows that the resource cannot successfully be accessed through (any of) the protocol(s) listed
 
+# Request for a share
+If the Recieving Party knows of a resource that has not yet been shared, the Recieving Party MAY make a HTTP POST to request a share
+
+* to the `/request-share` path in the Sending Server's OCM API
+* using `application/json` as the `Content-Type` HTTP request header
+* its request body containing a JSON document representing an object with the fields as described below
+* using TLS
+* using [httpsig](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12)
+
+## Fields
+* REQUIRED sender (string)
+          OCM Address of the user who will be requested to share the resource.
+* REQUIRED shareWith (string) 
+          OCM Address of the user, group or federation that
+          wants to receive a share of the resource.
+        Example: "[email protected]"
+* REQUIRED shareId (string)
+          A unique identifier for the resource.
+        Example: 1234567890abcdef
+
+After receiving a request for a Share, the Sending Party MAY send a Share Creation Notification to the Sending Party using the OCM address in the shareWith field.
+
 # Receiving Party Notification
 If the Share Creation Notification is not discarded by the Receiving Server, they MAY notify the Receiving Party passively by adding the Share to some inbox list, and MAY also notify them actively through for instance a push notification or an email message.
 

spec.yaml

@@ -42,6 +42,54 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Discovery"
+  /request-share:
+    post:
+      summary: Request access to a share
+      description: >
+        This endpoint is used to request access to a share.
+        The request MUST contain the share ID and the OCM address of the party
+        who wants to receive the share.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RequestShare"
+        description: The JSON object to request access to a share.
+        required: true
+      responses:
+        "201":
+          description: >
+            Consumer successfully received request.
+        "400":
+          description: >
+            Bad request due to invalid parameters, e.g. when `shareId` is missing.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/400"
+        "501":
+          description: The server doesn't support requesting shares.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "503":
+          description: The server is temporary unavailable (e.g. due to planned
+            maintenance).
+          headers:
+            Retry-After:
+              description: >
+                Indication for the client when the service could be requested
+                again in HTTP Date format as used by the  Internet Message
+                Format [RFC5322] (e.g. `Wed, 21 Oct 2015 07:28:00 GMT`) or the
+                number of seconds  (e.g. 3000 if you the service is expected to
+                be available again within 50 minutes).
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
   /shares:
     post:
       summary: Create a new share
@@ -848,6 +896,22 @@ components:
           type: string
           description: Name of the Invite Sender.
           example: John Doe
+    RequestShare:
+      type: object
+      required:
+        - shareWith
+        - shareId
+      properties:
+        shareWith:
+          type: string
+          description: >
+            Consumer specific identifier of the user, group or federation that
+            wants to recive a share of the resource.
+          example: [email protected]
+        shareId:
+          type: string
+          description: A unique identifier for the resource.
+          example: 1234567890abcdef
     TokenRequest:
       type: object
       properties: