RequestShare: Introduce the notion of a share request

IETF-RFC.md

@@ -1015,6 +1015,36 @@ They could give the Receiving Party the option to accept or reject the
 share, or add the share automatically and only send an informational
 notification that this happened.
 
+# Request for a Share
+
+If the Receiving Party knows of a resource that has not yet
+been shared, the Receiving Party MAY make an HTTP POST request
+
+* 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 [RFC9421]
+
+## 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: "51dc30ddc473d43a6011e9ebba6ca770@geant.org"
+* 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 Receiving Party
+using the OCM address in the shareWith field.
+
 
 # Share Acceptance Notification
 

spec.yaml

@@ -36,6 +36,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: Share Creation Notification endpoint
@@ -843,6 +891,29 @@ components:
           type: string
           description: Name of the Invite Sender.
           example: John Doe
+    RequestShare:
+      type: object
+      required:
+        - sender
+        - shareWith
+        - shareId
+      properties:
+        sender:
+          type: string
+          description: >
+            OCM Address of the user who will be requested to share
+            the resource.
+          example: 527bd5b5d689e2c32ae974c6229ff785@apiwise.nl
+        shareWith:
+          type: string
+          description: >
+            OCM Address of the user, group or federation that
+            wants to receive a share of the resource.
+          example: 51dc30ddc473d43a6011e9ebba6ca770@geant.org
+        shareId:
+          type: string
+          description: A unique identifier for the resource.
+          example: 1234567890abcdef
     TokenRequest:
       type: object
       required: