From 1f45ffda96cfc3bbb44d051e5be94d0a5773dd36 Mon Sep 17 00:00:00 2001 From: Luca Giorgino <19236900+lucagiorgino@users.noreply.github.com> Date: Tue, 26 Mar 2024 15:51:30 +0100 Subject: [PATCH 1/2] Update mediterraneus APIs spec --- apis/spec/connector.yaml | 419 ++++++++++++++++++++++++++++++--------- apis/spec/issuer.yaml | 131 ++++++++---- 2 files changed, 412 insertions(+), 138 deletions(-) diff --git a/apis/spec/connector.yaml b/apis/spec/connector.yaml index 0c2b834..5ca4486 100644 --- a/apis/spec/connector.yaml +++ b/apis/spec/connector.yaml @@ -13,11 +13,19 @@ tags: description: Everything about user identities. - name: Assets description: Everything about user assets. +- name: Other paths: - # Identities APIs + +################################################################ +# # +# Identites # +# # +################################################################ + /identities: post: summary: Creates a user identity. + description: In detail, it creates a new Did embedding in the document an identity public key and an ethereum address provided by the user in the request. tags: - Identities requestBody: @@ -29,25 +37,28 @@ paths: responses: '201': description: Created - /identities/{ethAddress}: - parameters: - - name: ethAddress - description: The unique identifier of the spacecraft - in: path - required: true - schema: - $ref: '#/components/schemas/ethAddress' + content: + application/json: + schema: + $ref: '#/components/schemas/IdentityResponse' get: - summary: Read a spacecraft + summary: Find an identity by wallet address. tags: - Identities + parameters: + - name: ethAddress + description: The wallet address of the user. + in: query + required: true + schema: + $ref: '#/components/schemas/EthAddress' responses: 200: - description: The spacecraft corresponding to the provided `ethAddress` + description: The identity corresponding to the provided `ethAddress` content: application/json: schema: - $ref: '#/components/schemas/Spacecraft' + $ref: '#/components/schemas/IdentityResponse' 404: description: No spacecraft found for the provided `ethAddress` content: @@ -60,70 +71,189 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /identities/{ethAddress}/sign-data: - parameters: + patch: + summary: Stores the verifiable credential issued by the Issuer. + description: Update the identity credential value corresponding to the provided `ethAddress`. + tags: + - Identities + parameters: - name: ethAddress - description: The unique identifier of the spacecraft - in: path + description: The wallet address of the user. + in: query required: true schema: - $ref: '#/components/schemas/ethAddress' - post: - summary: Creates a user identity. - tags: - - Identities + $ref: '#/components/schemas/EthAddress' requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/IdentityRequest' + properties: + credentialJwt: + description: The verifiable credential in JWT format. + type: string + example: "eyJraWQiOiJkaWQ6aW90YTpybXM6MHhhMTM2Yjk1YTFmMzc0ZWQwN2M1NDkzOTQ0ZmMwYWYyZjM5NmU3YzExNTAzNDhhZmJhZGVlYmI5ZmVkNjExYzMxI3BjT0lUbnUxSTBqSm9HM3JJNnFaZGtrVTVLaDUwNnctYnExc2t5QjBXOTAiLCJ0eXAiOiJKV1QiLCJhbGciOiJFZERTQSJ9.eyJleHAiOjE3NDI4OTMyNDUsImlzcyI6ImRpZDppb3RhOnJtczoweGExMzZiOTVhMWYzNzRlZDA3YzU0OTM5NDRmYzBhZjJmMzk2ZTdjMTE1MDM0OGFmYmFkZWViYjlmZWQ2MTFjMzEiLCJuYmYiOjE3MTEyNzA4NDUsImp0aSI6Imh0dHBzOi8vZXhhbXBsZS5tYXJrZXQvY3JlZGVudGlhbHMvMSIsInN1YiI6ImRpZDppb3RhOnJtczoweGIwYTVjNTM5NTNhMjhhZDJmMzg4MGIwOTg3ODI2NWU5OGRiMGJkM2Y5NmQxNjZiMjMzZWM4NGNkYWRiYjI0MmIiLCJ2YyI6eyJAY29udGV4dCI6Imh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL3YxIiwidHlwZSI6WyJWZXJpZmlhYmxlQ3JlZGVudGlhbCIsIk1hcmtldHBsYWNlQ3JlZGVudGlhbCJdLCJjcmVkZW50aWFsU3ViamVjdCI6eyJuYW1lIjoiSm9obiIsInN1cm5hbWUiOiJEb2UgRG9lIiwidXNlck9mIjoiU0VESU1BUksgbWFya2V0cGxhY2UifX19.-6dTIWJUwmaOQq6IJz4hh3SEwBz2lKnUmY19av4nZY3wcTi7hp0TY2rn3G8vsMYIft4VFZCwSlAHi28GwpiBAQ" responses: - '201': - description: Created - /identities/{ethAddress}/gen-presentation: - parameters: - - name: ethAddress - description: The unique identifier of the spacecraft + 200: + description: The updated identity corresponding to the provided `ethAddress`. + content: + application/json: + schema: + $ref: '#/components/schemas/IdentityResponse' + /identities/{identityId}/sign-data: + post: + summary: Sign the provided data with the identity private key. + tags: + - Identities + parameters: + - name: identityId in: path + description: ID of the identity. required: true schema: - $ref: '#/components/schemas/ethAddress' + type: number + requestBody: + required: true + content: + application/json: + schema: + required: + - payload + properties: + payload: + description: The data to be signed + type: string # todo: change in bytes also in the code + nonce: + description: Optional nonce + type: string + responses: + 200: + description: Data signed with the identity private key + content: + application/json: + schema: + properties: + ssiSignature: + description: Signature in JWS format + type: string + /identities/{identityId}/gen-presentation: post: - summary: Creates a user identity. + summary: Generate a verifiable presentation for the corresponding identity. tags: - Identities + parameters: + - name: identityId + in: path + description: ID of the identity used to generate the presentation + required: true + schema: + type: number requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/IdentityRequest' + required: + - payload + properties: + challenge: + description: Challenge of the verifier + type: string + ethSignature: + description: Optional challenge signature using the wallet's private key to embed in the presentation + type: string responses: - '201': - description: Created - # Assets APIs + 200: + description: Verifiable presentation generated. + content: + application/json: + schema: + properties: + presentation: + description: The verifiable presentation in JWT format + type: string + +################################################################ +# # +# Assets # +# # +################################################################ + /assets: post: summary: Upload an asset of the user + description: "In detail, two file are uploaded: the asset and its description. The description is uploaded on an IPFS local node" tags: - Assets requestBody: - required: true content: - application/json: + multipart/form-data: schema: - $ref: '#/components/schemas/IdentityRequest' + type: object + properties: + ethAddress: + type: string + alias: + description: The alias of the asset + type: string + filename: + description: The asset and descriptions files. + type: array + items: + type: string + format: binary responses: - '201': - description: Created + 200: + description: "Upload ok" + content: + application/json: + schema: + $ref: '#/components/schemas/AssetResponse' get: - summary: Upload an asset of the user + summary: Find an asset by alias. tags: - Assets + parameters: + - name: alias + description: The alias of the asset to access. + in: query + required: true + schema: + type: string responses: - '201': - description: Created + 200: + description: The asset information. + content: + application/json: + schema: + $ref: '#/components/schemas/AssetResponse' + patch: + summary: Update the NFT address of the asset. + tags: + - Assets + parameters: + - name: alias + description: The alias of the asset to access. + in: query + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + properties: + nftAddress: + description: The address of the NFT that represent the asset. + type: string + responses: + 200: + description: The updated asset information. + content: + application/json: + schema: + $ref: '#/components/schemas/AssetResponse' /assets/{assetId}: parameters: - name: assetId @@ -133,80 +263,180 @@ paths: schema: $ref: '#/components/schemas/assetId' get: - summary: Upload an asset of the user + summary: Get the asset information. tags: - Assets responses: - '201': - description: Created - patch: - summary: Upload an asset of the user + 200: + description: The asset information. + content: + application/json: + schema: + $ref: '#/components/schemas/AssetResponse' + /assets/aliases: + parameters: + - name: ethAddress + description: The wallet address of the user. + in: query + required: true + schema: + $ref: '#/components/schemas/EthAddress' + get: + summary: Get all the asset aliases. tags: - Assets responses: - '201': - description: Created - /assets/{assetId}/challenge: + 200: + description: The list of aliases. + content: + application/json: + schema: + properties: + aliases: + description: An array of string. + type: array + + /assets/download: parameters: - - name: assetId - description: The unique identifier of the asset - in: path + - name: alias + description: The alias of the asset to access. + in: query required: true schema: - $ref: '#/components/schemas/assetId' + type: string get: - summary: Upload an asset of the user + summary: Download the asset + description: Asset download, verifiable presentation and proof of purchase verification are performed tags: - Assets responses: - '201': - description: Created - /assets/{assetId}/download: - parameters: - - name: assetId - description: The unique identifier of the asset - in: path + '200': + description: Return the file read from IPFS + +################################################################ +# # +# Other # +# # +################################################################ + + /challenges: + get: + summary: Get a challenge to access a service + tags: + - Other + parameters: + - in: query + name: did + description: The did of the user who has to sign the challenge. required: true schema: - $ref: '#/components/schemas/assetId' - post: - summary: Upload an asset of the user + $ref: '#/components/schemas/Did' + responses: + 200: + description: The challenge to be signed. + content: + application/json: + schema: + $ref: '#/components/schemas/Challenge' + 429: + description: Too Many Requests + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + 500: + description: Unexpected error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /cids/{cid}: + parameters: + - name: cid + in: path + description: Content Identifier + required: true + schema: + type: string + get: + summary: Read the contents of a file that has been added to IPFS. tags: - - Assets + - Other + security: + - bearerAuth: [] + responses: - '201': - description: Created + '200': + description: Return the file read from IPFS + +################################################################ +# # +# COMPONENTS # +# # +################################################################ + components: schemas: - ethAddress: - description: The unique identifier of a spacecraft + Did: + description: A a new type of identifier that enables verifiable, decentralized digital identity. type: string - assetId: - description: The unique identifier of an asset + example: did:iota:rms:0xb0a5c53953a28ad2f3880b09878265e98db0bd3f96d166b233ec84cdadbb242b + EthAddress: + description: The wallet address of the user. The address is in EIP-55. type: string - Spacecraft: + example: "0xf9692336d7f37336c2061a545d8b2895b1415efe" + Challenge: + description: A random challenge type: object required: - - id - - name - - type + - nonce properties: - id: - $ref: '#/components/schemas/ethAddress' - name: + nonce: + description: A random challenge type: string - type: + + assetId: + description: The unique identifier of an asset + type: string + + IdentityResponse: + type: object + properties: + id: + description: The id of the identity + type: number + example: 1 + ethAddress: + $ref: '#/components/schemas/EthAddress' + did: + $ref: '#/components/schemas/Did' + fragment: + description: Fragment of the identity key pair inside the DID document. type: string - enum: - - capsule - - probe - - satellite - - spaceplane - - station - description: + credential: + description: The verifiable credential of the user in JWT format (Upon identity creation, its value is undefined, the credential must be requested to an Issuer). type: string IdentityRequest: type: object + properties: + ethAddress: + $ref: '#/components/schemas/EthAddress' + AssetResponse: + type: object + properties: + id: + description: The id of the asset + type: number + NftAddress: + description: The wallet address of the user. The address is in EIP-55. + type: string + example: "0xf9692336d7f37336c2061a545d8b2895b1415efe" + cid: + description: Content Identifier + type: string + alias: + description: The alias of the asset + type: string Error: type: object required: @@ -215,10 +445,11 @@ components: message: description: A human readable error message type: string - securitySchemes: - ApiKey: - type: apiKey - in: header - name: X-Api-Key -security: - - ApiKey: [] \ No newline at end of file + + # securitySchemes: + # ApiKey: + # type: apiKey + # in: header + # name: X-Api-Key +# security: +# - ApiKey: [] \ No newline at end of file diff --git a/apis/spec/issuer.yaml b/apis/spec/issuer.yaml index 2d170ec..3feb1ac 100644 --- a/apis/spec/issuer.yaml +++ b/apis/spec/issuer.yaml @@ -8,20 +8,17 @@ externalDocs: url: https://github.com/Cybersecurity-LINKS/mediterraneus-issuer-rs servers: - url: http://localhost:3213/api -tags: -- name: Credentials - description: Everything about Verifiable Credentials. paths: /challenges: get: - summary: Get a challenge that the client should sign and send back in a short time. + summary: Get a challenge to request a credential parameters: - in: query name: did - description: The did of the user who have to sign the challenge. + description: The did of the user who has to sign the challenge. required: true schema: - $ref: '#/components/schemas/did' + $ref: '#/components/schemas/Did' responses: 200: description: The challenge to be signed. @@ -43,65 +40,111 @@ paths: $ref: '#/components/schemas/Error' /credentials: post: - summary: Get a challenge that the client should sign and send back in a short time. - parameters: - - in: query - name: did - description: The did of the user who have to sign the challenge. - required: true - schema: - $ref: '#/components/schemas/did' + summary: Issue a verifiable credential for the user + description: Issue a verifiable credential for the user, the credential is signed with the issuer private key and it is encoded as JWT + operationId: "create_credential" responses: - '200': - description: The spacecraft corresponding to the provided `spacecraftId` - content: - application/json: - schema: - $ref: '#/components/schemas/Spacecraft' - 404: - description: No spacecraft found for the provided `spacecraftId` + 200: + description: Sccessful operation, return the verifiable credential as JWT content: application/json: schema: - $ref: '#/components/schemas/Error' + $ref: '#/components/schemas/CredentialIssuedResponse' 500: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CredentialRequestDTO' components: schemas: - did: + Did: description: The unique identifier of a spacecraft type: string Challenge: - description: The unique identifier of a spacecraft - type: string - SpacecraftId: - description: The unique identifier of a spacecraft - type: string - Spacecraft: + description: A random challenge type: object required: - - id - - name - - type + - nonce properties: - id: - $ref: '#/components/schemas/SpacecraftId' - name: + nonce: + description: A random challenge + type: string + CredentialIssuedResponse: + description: The response of the Issuer + type: object + required: + - issuerDid + - credentialId + - credentialJwt + properties: + message: + description: A human readable message + type: string + issuerDid: + description: The issuer did + type: string + credentialId: + description: The id of the credential + type: number + credentialJwt: + description: The credential in JWT format + type: string + CredentialRequestDTO: + description: The request of the user when requesting a credential + type: object + required: + - issuerDid + - credentialId + - credentialJwt + properties: + did: + description: The user did + type: string + nonce: + description: The challenge that has been signed type: string - type: + identitySignature: + description: Signature of the challenge with the identity private key type: string - enum: - - capsule - - probe - - satellite - - spaceplane - - station - description: + walletSignature: + description: Signature of the challenge with the wallet private key type: string + credentialSubject: + description: Information about the user + type: object + example: + name: "Mario" + surname: "Rossi" + # SpacecraftId: + # description: The unique identifier of a spacecraft + # type: string + # Spacecraft: + # type: object + # required: + # - id + # - name + # - type + # properties: + # id: + # $ref: '#/components/schemas/SpacecraftId' + # name: + # type: string + # type: + # type: string + # enum: + # - capsule + # - probe + # - satellite + # - spaceplane + # - station + # description: + # type: string Error: type: object required: From 2e34477383e18eb45ee152ead710f377d166a36c Mon Sep 17 00:00:00 2001 From: Luca Giorgino <19236900+lucagiorgino@users.noreply.github.com> Date: Tue, 26 Mar 2024 17:33:38 +0100 Subject: [PATCH 2/2] Update version number --- apis/spec/connector.yaml | 2 +- apis/spec/issuer.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/apis/spec/connector.yaml b/apis/spec/connector.yaml index 5ca4486..6b7e280 100644 --- a/apis/spec/connector.yaml +++ b/apis/spec/connector.yaml @@ -1,6 +1,6 @@ openapi: '3.0.1' info: - version: '1.0.0' + version: '0.1.0' title: 'Connector API' description: This document specifies the REST API for the Connector service. externalDocs: diff --git a/apis/spec/issuer.yaml b/apis/spec/issuer.yaml index 3feb1ac..9b1f71a 100644 --- a/apis/spec/issuer.yaml +++ b/apis/spec/issuer.yaml @@ -1,6 +1,6 @@ openapi: '3.0.0' info: - version: '1.0.0' + version: '0.1.0' title: 'Issuer API' description: This document specifies the REST API for the Issuer service. externalDocs: