From 8ae5a7de40ff2e5a2c13cfc37c0d890d31b65467 Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Fri, 13 Jun 2025 09:20:15 +0200 Subject: [PATCH 1/4] RequestShare: Introduce the notion of a share request Signed-off-by: Micke Nordin --- IETF-RFC.md | 21 ++++++++++++++++++ spec.yaml | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 85 insertions(+) diff --git a/IETF-RFC.md b/IETF-RFC.md index 5e0a122d..491878a0 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -454,6 +454,27 @@ 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 shareWith (string) + Consumer specific identifier of the user, group or federation that + wants to recive 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 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. diff --git a/spec.yaml b/spec.yaml index 3ceb8729..55b16999 100644 --- a/spec.yaml +++ b/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: 51dc30ddc473d43a6011e9ebba6ca770@geant.org + shareId: + type: string + description: A unique identifier for the resource. + example: 1234567890abcdef TokenRequest: type: object properties: From d0db6d4ec2f97201b95b77af740b2f0af9371337 Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Fri, 22 Aug 2025 17:11:39 +0200 Subject: [PATCH 2/4] Update IETF-RFC.md Co-authored-by: Giuseppe Lo Presti --- IETF-RFC.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/IETF-RFC.md b/IETF-RFC.md index 491878a0..e5cc7b6d 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -466,7 +466,7 @@ If the Recieving Party knows of a resource that has not yet been shared, the Rec ## Fields * REQUIRED shareWith (string) - Consumer specific identifier of the user, group or federation that + OCM Address of the user, group or federation that wants to recive a share of the resource. Example: "51dc30ddc473d43a6011e9ebba6ca770@geant.org" * REQUIRED shareId (string) From 3eacbbdfad7476e0206bfa9d76bbd61d8d15dfcc Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Tue, 9 Sep 2025 11:13:52 +0200 Subject: [PATCH 3/4] Update IETF-RFC.md Co-authored-by: Giuseppe Lo Presti --- IETF-RFC.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/IETF-RFC.md b/IETF-RFC.md index e5cc7b6d..177921f2 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -467,7 +467,7 @@ If the Recieving Party knows of a resource that has not yet been shared, the Rec * REQUIRED shareWith (string) OCM Address of the user, group or federation that - wants to recive a share of the resource. + wants to receive a share of the resource. Example: "51dc30ddc473d43a6011e9ebba6ca770@geant.org" * REQUIRED shareId (string) A unique identifier for the resource. From 1fb6942268468a6c91872fde29fcbede659201b4 Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Tue, 9 Sep 2025 11:14:11 +0200 Subject: [PATCH 4/4] Update IETF-RFC.md Co-authored-by: Giuseppe Lo Presti --- IETF-RFC.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/IETF-RFC.md b/IETF-RFC.md index 177921f2..c97e3159 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -464,7 +464,8 @@ If the Recieving Party knows of a resource that has not yet been shared, the Rec * 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.