feat: add holder presentation endpoints

impierce · Dec 17, 2024 · efbafd0 · efbafd0
1 parent 197dc67
commit efbafd0
Show file tree

Hide file tree

Showing 3 changed files with 156 additions and 30 deletions.
diff --git a/agent_api_rest/openapi.yaml b/agent_api_rest/openapi.yaml
@@ -325,11 +325,11 @@ paths:
             examples:
               openbadges:
                 summary: Open Badges 3.0
-                description: s0me descr1pti0n
+                description: An badge following the Open Badges Specification 3.0
                 externalValue: res/open-badge-request.json
               w3c-vc:
-                summary: W3C v1.1
-                description: s0me descr1pti0n
+                summary: W3C VC Data Model v1.1
+                description: A credential following the W3C Verifiable Credentials Data Model v1.1
                 value:
                   offerId: '123'
                   credentialConfigurationId: w3c_vc_credential
@@ -356,7 +356,30 @@ paths:
                   summary: Open Badges 3.0
                   description: An badge following the Open Badges Specification 3.0
                   value:
-                    foo: bar
+                    '@context':
+                    - https://www.w3.org/2018/credentials/v1
+                    - https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.2.json
+                    id: https://acme.example.org/1a2b3c4d5e6f
+                    type:
+                    - VerifiableCredential
+                    - OpenBadgeCredential
+                    name: ImpierceCredential
+                    credentialSubject:
+                      type:
+                      - AchievementSubject
+                      achievement:
+                        id: https://example.com/achievements/21st-century-skills/teamwork
+                        type: Achievement
+                        criteria:
+                          narrative: TeammembersarenominatedforthisbadgebytheirpeersandrecognizeduponreviewbyExampleCorpmanagement.
+                        description: Thisbadgerecognizesthedevelopmentofthecapacitytocollaboratewithinagroupenvironment.
+                        name: Teamwork
+                    issuer:
+                      id: http://localhost:3033/
+                      type: Profile
+                      name: UniCore
+                    issuanceDate: 2024-12-17T22:37:59Z
+                    expirationDate: 2028-04-12T09:15:23Z
                 w3c-vc-1-1:
                   summary: W3C VC Data Model v1.1
                   description: A credential following the W3C Verifiable Credentials Data Model v1.1
@@ -421,18 +444,20 @@ paths:
         '200':
           description: Successfully posted a credential.
   /v0/holder/credentials/{id}:
-    post:
+    get:
       tags:
       - Holder
       summary: Get a credential from UniCore's Holder wallet
-      description: Directly upload a credential to the UniCore's Holder wallet.
+      description: Get a specific credential from UniCore's Holder wallet by ID.
       operationId: credential
       parameters:
       - name: id
         in: path
+        description: Unique identifier of the Credential
         required: true
         schema:
           type: string
+        example: 57ea9bf4-3a50-4b34-a340-7ef969bfab12
       responses:
         '200':
           description: Successfully retrieved a credential.
@@ -447,76 +472,118 @@ paths:
         '200':
           description: Successfully retrieved all pending offers.
   /v0/holder/offers/{id}:
-    post:
+    get:
       tags:
       - Holder
       summary: Get an offer by ID
-      description: TODO
+      description: Retrieve an offer for a given ID.
       operationId: offer
       parameters:
       - name: id
         in: path
+        description: Unique identifier of the Offer
         required: true
         schema:
           type: string
+        example: 57ea9bf4-3a50-4b34-a340-7ef969bfab12
       responses:
         '200':
           description: Successfully retrieved an offer.
-  /v0/holder/offers/{offer_id}/accept:
+  /v0/holder/offers/{id}/accept:
     post:
       tags:
       - Holder
       summary: Accept an offer
       description: Accept a pending credential offer. UniCore will then make a request to the Issuer to receive the offer.
       operationId: accept
       parameters:
-      - name: offer_id
+      - name: id
         in: path
+        description: Unique identifier of the Offer
         required: true
         schema:
           type: string
+        example: 57ea9bf4-3a50-4b34-a340-7ef969bfab12
       responses:
         '200':
           description: Successfully accepted a pending offer.
-  /v0/holder/offers/{offer_id}/reject:
+  /v0/holder/offers/{id}/reject:
     post:
       tags:
       - Holder
       summary: Reject an offer
       description: Reject a pending credential offer. UniCore will not make any further requests to the Issuer.
       operationId: reject
       parameters:
-      - name: offer_id
+      - name: id
         in: path
+        description: Unique identifier of the Offer
         required: true
         schema:
           type: string
+        example: 57ea9bf4-3a50-4b34-a340-7ef969bfab12
       responses:
         '200':
           description: Successfully rejected a pending offer.
-  /v0/offers:
+  /v0/holder/presentations:
     get:
       tags:
-      - Issuance
-      summary: List all offers
-      description: Retrieve all available credential offers.
-      operationId: all_offers
+      - Holder
+      summary: List all Presentations
+      description: |-
+        Retrieve all presentations that this UniCore instance currently holds.
+        A Presentation contains one or more Credentials.
+      operationId: get_presentations
+      responses:
+        '200':
+          description: Successfully retrieved all presentations.
+    post:
+      tags:
+      - Holder
+      summary: Create new Presentation for given Credentials
+      description: |-
+        One or more Credentials in UniCore's Holder wallet can be made available to be verified by other parties.
+        Depending on the content of the Credentials, this can increase the trustworthiness of this UniCore instance.
+      operationId: post_presentations
       requestBody:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/OffersEndpointRequest'
-            example:
-              offerId: '0001'
+              $ref: '#/components/schemas/PresentationsEndpointRequest'
         required: true
       responses:
         '200':
-          description: Successfully created a new credential offer. Response value is standard-compliant and can be interpreted by an identity wallet.
-          content:
-            application/x-www-form-urlencoded:
-              schema:
-                type: string
-              example: openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Fcredential-issuer.example.com%2F%22%2C%22credentials%22%3A%5B%7B%22format%22%3A%22ldp_vc%22%2C%22credential_definition%22%3A%7B%22%40context%22%3A%5B%22https%3A%2F%2Fwww.w3.org%2F2018%2Fcredentials%2Fv1%22%2C%22https%3A%2F%2Fwww.w3.org%2F2018%2Fcredentials%2Fexamples%2Fv1%22%5D%2C%22type%22%3A%5B%22VerifiableCredential%22%2C%22UniversityDegreeCredential%22%5D%7D%7D%5D%7D
+          description: Successfully created a presentation.
+  /v0/holder/presentations/{id}:
+    get:
+      tags:
+      - Holder
+      summary: Get a Presentation by ID
+      description: |-
+        Retrieves a presentation for a given ID.
+        A Presentation contains one or more Credentials.
+      operationId: presentation
+      parameters:
+      - name: id
+        in: path
+        description: Unique identifier of the Presentation
+        required: true
+        schema:
+          type: string
+        example: 57ea9bf4-3a50-4b34-a340-7ef969bfab12
+      responses:
+        '200':
+          description: Successfully retrieved the presentation.
+  /v0/offers:
+    get:
+      tags:
+      - Issuance
+      summary: List all offers
+      description: Retrieve all available credential offers.
+      operationId: all_offers
+      responses:
+        '200':
+          description: Successfully retrieved all credential offers.
     post:
       tags:
       - Issuance
@@ -677,8 +744,10 @@ components:
         expiresAt:
           oneOf:
           - type: string
+            title: Credential expires at a fixed date
             format: date-time
           - type: string
+            title: Credential never expires
             enum:
             - never
         isSigned:
@@ -742,16 +811,26 @@ components:
           type:
           - string
           - 'null'
+    PresentationsEndpointRequest:
+      type: object
+      required:
+      - credentialIds
+      properties:
+        credentialIds:
+          type: array
+          items:
+            type: string
     SendOfferEndpointRequest:
       type: object
       required:
-      - offer_id
-      - target_url
+      - offerId
+      - targetUrl
       properties:
-        offer_id:
+        offerId:
           type: string
-        target_url:
+        targetUrl:
           type: string
+          format: uri
     TokenRequest:
       type: object
       required:
@@ -773,6 +852,10 @@ tags:
   externalDocs:
     url: https://docs.impierce.com
     description: Issuance API Documentation
+- name: Verification
+  description: Request holders to present credentials that meet certain criteria and verify the received presentations.
+- name: Holder
+  description: Manage credentials and presentations for UniCore itself to enhance trustworthiness.
 externalDocs:
   url: https://docs.impierce.com
   description: Official Documentation
diff --git a/agent_api_rest/src/holder/holder/presentations/mod.rs b/agent_api_rest/src/holder/holder/presentations/mod.rs
@@ -15,6 +15,18 @@ use serde_json::{json, Value};
 use tracing::info;
 use utoipa::ToSchema;
 
+/// List all Presentations
+///
+/// Retrieve all presentations that this UniCore instance currently holds.
+/// A Presentation contains one or more Credentials.
+#[utoipa::path(
+    get,
+    path = "/holder/presentations",
+    tag = "Holder",
+    responses(
+        (status = 200, description = "Successfully retrieved all presentations."),
+    )
+)]
 #[axum_macros::debug_handler]
 pub(crate) async fn get_presentations(State(state): State<HolderState>) -> Response {
     match query_handler("all_presentations", &state.query.all_presentations).await {
@@ -28,6 +40,21 @@ pub(crate) async fn get_presentations(State(state): State<HolderState>) -> Respo
     }
 }
 
+/// Get a Presentation by ID
+///
+/// Retrieves a presentation for a given ID.
+/// A Presentation contains one or more Credentials.
+#[utoipa::path(
+    get,
+    path = "/holder/presentations/{id}",
+    params(
+        ("id" = String, Path, description = "Unique identifier of the Presentation", example = "57ea9bf4-3a50-4b34-a340-7ef969bfab12"),
+    ),
+    tag = "Holder",
+    responses(
+        (status = 200, description = "Successfully retrieved the presentation."),
+    )
+)]
 #[axum_macros::debug_handler]
 pub(crate) async fn presentation(State(state): State<HolderState>, Path(presentation_id): Path<String>) -> Response {
     match query_handler(&presentation_id, &state.query.presentation).await {
@@ -43,6 +70,19 @@ pub struct PresentationsEndpointRequest {
     pub credential_ids: Vec<String>,
 }
 
+/// Create new Presentation for given Credentials
+///
+/// One or more Credentials in UniCore's Holder wallet can be made available to be verified by other parties.
+/// Depending on the content of the Credentials, this can increase the trustworthiness of this UniCore instance.
+#[utoipa::path(
+    post,
+    path = "/holder/presentations",
+    request_body = PresentationsEndpointRequest,
+    tag = "Holder",
+    responses(
+        (status = 200, description = "Successfully created a presentation."),
+    )
+)]
 #[axum_macros::debug_handler]
 pub(crate) async fn post_presentations(State(state): State<HolderState>, Json(payload): Json<Value>) -> Response {
     info!("Request Body: {}", payload);

diff --git a/agent_api_rest/src/openapi.rs b/agent_api_rest/src/openapi.rs
@@ -51,6 +51,9 @@ pub(crate) struct VerificationApi;
         holder::offers::offers,
         holder::offers::accept::accept,
         holder::offers::reject::reject,
+        holder::presentations::presentation,
+        holder::presentations::get_presentations,
+        holder::presentations::post_presentations,
     ),
     components(schemas(openid4vci::Oid4vciOfferEndpointRequestSchema))
 )]