UNPKG

@i3m/wallet-desktop-openapi

Version:

i3M-Wallet Developers API that can be used to interact with the i3M-Wallet. In production it is encapsulated inside a secure connection. Please use the @i3m/wallet-protocol-api to interact with the wallet.

1,235 lines (1,218 loc) 36.4 kB
openapi: 3.0.3 info: version: v2 title: i3M-Wallet Developers API description: >- i3M-Wallet Developers API that can be used to interact with the i3M-Wallet. In production it is encapsulated inside a secure connection. Please use the @i3m/wallet-protocol-api to interact with the wallet. license: name: EUPL-1.2 url: >- https://joinup.ec.europa.eu/sites/default/files/custom-page/attachment/2020-03/EUPL-1.2%20EN.txt contact: name: Juan Hernández Serrano email: j.hernandez@upc.edu url: https://github.com/juanelas tags: - name: identities description: | Endpoints to manage identities (DIDs). - name: resources description: > Besides identities, the wallet MAY securely store arbitrary resources in a secure vault, which may be selectively disclosed upon request. Currently storing verifiable credentials - name: selectiveDisclosure description: > Ednpoints for the selective disclosure process (used to present verifiable credentials) - name: transaction description: > Endpoints for deploying signed transactions to the DLT the wallet is connected to. - name: utils description: | Additional helpler functions paths: /identities: get: summary: List all DIDs operationId: identityList x-eov-operation-handler: identities tags: - identities parameters: - in: query name: alias schema: type: string description: An alias for the identity responses: '200': description: An array of identities content: application/json: schema: $ref: '#/components/schemas/IdentityListInput' default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/ApiError' post: summary: Create an account operationId: identityCreate x-eov-operation-handler: identities tags: - identities requestBody: description: Create a DID. required: false content: application/json: schema: $ref: '#/components/schemas/IdentityCreateInput' responses: '201': description: the ID and type of the created account content: application/json: schema: $ref: '#/components/schemas/IdentityCreateOutput' default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/ApiError' /identities/select: get: summary: Gets an identity selected by the user. operationId: identitySelect x-eov-operation-handler: identities tags: - identities parameters: - in: query name: reason schema: type: string description: Message to show to the user with the reason to pick an identity responses: '200': description: Selected identity content: application/json: schema: $ref: '#/components/schemas/IdentitySelectOutput' default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/ApiError' /identities/{did}/sign: post: summary: Signs a message operationId: identitySign x-eov-operation-handler: identities tags: - identities parameters: - in: path name: did schema: $ref: '#/components/schemas/did' required: true requestBody: description: Data to sign. required: true content: application/json: schema: $ref: '#/components/schemas/SignInput' responses: '200': description: Signed data content: application/json: schema: $ref: '#/components/schemas/SignOutput' default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/ApiError' /identities/{did}/info: get: summary: Gets extra information of an identity. operationId: identityInfo x-eov-operation-handler: identities tags: - identities parameters: - in: path name: did schema: $ref: '#/components/schemas/did' required: true responses: '200': description: Identity data content: application/json: schema: $ref: '#/components/schemas/IdentityData' default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/ApiError' /identities/{did}/deploy-tx: post: summary: Signs and deploys a transaction operationId: identityDeployTransaction x-eov-operation-handler: identities tags: - identities parameters: - in: path name: did schema: $ref: '#/components/schemas/did' required: true requestBody: description: Transaction to sign and deploy required: true content: application/json: schema: $ref: '#/components/schemas/Transaction' responses: '200': description: Selected identity content: application/json: schema: $ref: '#/components/schemas/Receipt' default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/ApiError' /resources: get: summary: >- Lists the resources that match the filter specified in the query parameters. operationId: resourceList x-eov-operation-handler: resources tags: - resources parameters: - in: query name: type example: Contract required: false schema: $ref: '#/components/schemas/ResourceType' description: Filter the resources by resource type. - in: query name: identity example: >- did:ethr:i3m:0x031bee96cfae8bad99ea0dd3d08d1a3296084f894e9ddfe1ffe141133e81ac5863 allowEmptyValue: true required: false schema: $ref: '#/components/schemas/did' description: >- Filter the resource associated to an identity DID. Send empty value to get all the resources that are not associated to any identity. - in: query name: parentResource required: false schema: type: string description: Get only resources with the given parent resource id. responses: '200': description: >- A paged array of resources. Only the props requested will be returned. Security policies may prevent some props from being returned. content: application/json: schema: $ref: '#/components/schemas/ResourceListOutput' default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/ApiError' post: summary: Create a resource operationId: resourceCreate x-eov-operation-handler: resources tags: - resources requestBody: description: >- Create a resource. Nowadays it only supports storage of verifiable credentials. content: application/json: schema: $ref: '#/components/schemas/Resource' responses: '201': description: the ID and type of the created resource content: application/json: schema: $ref: '#/components/schemas/ResourceId' default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/ApiError' /disclosure/{jwt}: get: summary: Request selective disclosure of resources operationId: selectiveDisclosure x-eov-operation-handler: disclosure tags: - selectiveDisclosure parameters: - in: path name: jwt schema: type: string pattern: ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$ required: true description: "A JWT containing a selective disclosure object. The payload MUST contain:\n\n```json\n{\n \"type\": \"selectiveDisclosureReq\", // MUST be selectiveDisclosureReq\n \"iss\": \"did:\", // the DID of the OIDC Provider\n \"aud\": \"\", // DID of the OIDC RP\n \"iat\": 4354535,\t// The time of issuance\n \"exp\": 3452345, // [OPTIONAL] Expiration time of JWT\n callback: \"https://...\", // Callback URL for returning the response to a request\n resources: [\n { \"id\": \"id\", \"mandatory\": true, \"iss\": [ { did: or url:} ], \"reason\": \"\" }\n ]\n}\n```\n" responses: '200': description: Disclosure ok (mandatory claims provided) content: application/json: schema: type: object properties: jwt: type: string default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/ApiError' /transaction/deploy: post: summary: Deploy a signed transaction operationId: transactionDeploy x-eov-operation-handler: transaction tags: - transaction requestBody: description: Create a resource. content: application/json: schema: $ref: '#/components/schemas/SignedTransaction' responses: '200': description: Deployment OK default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/ApiError' /did-jwt/verify: post: summary: > Use the wallet to verify a JWT. The Wallet only supports DID issuers and the 'ES256K1' algorithm. Useful to verify JWT created by another wallet instance. operationId: didJwtVerify x-eov-operation-handler: did-jwt tags: - utils requestBody: description: >- Verify a JWT resolving the public key from the signer DID and optionally check values for expected payload claims required: true content: application/json: schema: type: object properties: jwt: type: string pattern: ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$ example: >- eyJhbGciOiJFUzI1NksiLCJ0eXAiOiJKV1QifQ.eyJmaWVsZDEiOiJzYWRzYWQ3NSIsImZpZWxkMiI6ImFmZnNhczlmODdzIiwiaXNzIjoiZGlkOmV0aHI6aTNtOjB4MDNmOTcwNjRhMzUzZmFmNWRkNTQwYWE2N2I2OTE2YmY1NmMwOWM1MGNjODAzN2E0NTNlNzg1ODdmMjdmYjg4ZTk0IiwiaWF0IjoxNjY1NDAwMzYzfQ.IpQ7WprvDMk6QWcJXuPBazat-2657dWIK-iGvOOB5oAhAmMqDBm8OEtKordqeqcEWwhWw_C7_ziMMZkPz1JIkw expectedPayloadClaims: type: object additionalProperties: true description: > The expected values of the proof's payload claims. An expected value of '' can be used to just check that the claim is in the payload. An example could be: ```json { iss: 'orig', exchange: { id: '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d', orig: '{"kty":"EC","x":"rPMP39e-o8cU6m4WL8_qd2wxo-nBTjWXZtPGBiiGCTY","y":"0uvxGEebFDxKOHYUlHREzq4mRULuZvQ6LB2I11yE1E0","crv":"P-256"}', // Public key in JSON.stringify(JWK) of the block origin (sender) dest: '{"kty":"EC","x":"qf_mNdy57ia1vAq5QLpTPxJUCRhS2003-gL0nLcbXoA","y":"H_8YwSCKJhDbZv17YEgDfAiKTaQ8x0jpLYCC2myxAeY","crv":"P-256"}', // Public key in JSON.stringify(JWK) of the block destination (receiver) hash_alg: 'SHA-256', cipherblock_dgst: 'IBUIstf98_afbiuh7UaifkasytNih7as-Jah61ls9UI', // hash of the cipherblock in base64url with no padding block_commitment: '', // hash of the plaintext block in base64url with no padding secret_commitment: '' // hash of the secret that can be used to decrypt the block in base64url with no padding } } ``` required: - jwt responses: '200': description: > A verification object. If `verification` equals `success` all checkings have passed; if it is `failed`, you can access the error message in `error`. Unless the JWT decoding fails (invalid format), the decoded JWT payload can be accessed in `payload`. Example of success: ```json { "verification": "success", "payload": { "iss": "did:ethr:i3m:0x02d846307c9fd53106eb20db5a774c4b71f25c59c7bc423990f942e3fdb02c5898", "iat": 1665138018, "action": "buy 1457adf6" } } ``` Example of failure: ```json { "verification": "failed", "error": "invalid_jwt: JWT iss is required" "payload": { "iat": 1665138018, "action": "buy 1457adf6" } } ``` content: application/json: schema: $ref: '#/components/schemas/VerificationOutput' default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/ApiError' /providerinfo: get: summary: Gets info of the DLT provider the wallet is using operationId: providerinfoGet x-eov-operation-handler: providerinfo tags: - utils responses: '200': description: A JSON object with information of the DLT provider currently in use. content: application/json: schema: $ref: '#/components/schemas/ProviderData' default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/ApiError' components: schemas: IdentitySelectOutput: title: IdentitySelectOutput type: object properties: did: $ref: '#/components/schemas/did' required: - did SignInput: title: SignInput oneOf: - $ref: '#/components/schemas/SignTransaction' - $ref: '#/components/schemas/SignRaw' - $ref: '#/components/schemas/SignJWT' SignRaw: title: SignRaw type: object properties: type: enum: - Raw data: type: object properties: payload: description: Base64Url encoded data to sign type: string pattern: ^[A-Za-z0-9_-]+$ required: - payload required: - type - data SignTransaction: title: SignTransaction type: object properties: type: enum: - Transaction data: $ref: '#/components/schemas/Transaction' required: - type - data SignJWT: title: SignJWT type: object properties: type: enum: - JWT data: type: object properties: header: description: >- header fields to be added to the JWS header. "alg" and "kid" will be ignored since they are automatically added by the wallet. type: object additionalProperties: true payload: description: >- A JSON object to be signed by the wallet. It will become the payload of the generated JWS. 'iss' (issuer) and 'iat' (issued at) will be automatically added by the wallet and will override provided values. type: object additionalProperties: true required: - payload required: - type - data Transaction: title: Transaction type: object additionalProperties: true properties: from: type: string to: type: string nonce: type: number SignOutput: title: SignOutput type: object properties: signature: type: string required: - signature Receipt: title: Receipt type: object properties: receipt: type: string required: - receipt SignTypes: title: SignTypes type: string enum: - Transaction - Raw - JWT IdentityListInput: title: IdentityListInput description: A list of DIDs type: array items: type: object properties: did: $ref: '#/components/schemas/did' required: - did IdentityCreateInput: title: IdentityCreateInput description: > Besides the here defined options, provider specific properties should be added here if necessary, e.g. "path" for BIP21 wallets, or the key algorithm (if the wallet supports multiple algorithm). type: object properties: alias: type: string additionalProperties: true IdentityCreateOutput: title: IdentityCreateOutput description: | It returns the account id and type type: object properties: did: $ref: '#/components/schemas/did' additionalProperties: true required: - did ResourceListOutput: title: ResourceListOutput description: A list of resources type: array items: $ref: '#/components/schemas/Resource' Resource: title: Resource anyOf: - $ref: '#/components/schemas/VerifiableCredential' - $ref: '#/components/schemas/ObjectResource' - $ref: '#/components/schemas/KeyPair' - $ref: '#/components/schemas/Contract' - $ref: '#/components/schemas/NonRepudiationProof' - $ref: '#/components/schemas/DataExchangeResource' VerifiableCredential: title: VerifiableCredential type: object properties: type: example: VerifiableCredential enum: - VerifiableCredential name: type: string example: Resource name resource: type: object properties: '@context': type: array items: type: string example: - https://www.w3.org/2018/credentials/v1 id: type: string example: http://example.edu/credentials/1872 type: type: array items: type: string example: - VerifiableCredential issuer: type: object properties: id: $ref: '#/components/schemas/did' additionalProperties: true required: - id issuanceDate: type: string format: date-time example: '2021-06-10T19:07:28.000Z' credentialSubject: type: object properties: id: $ref: '#/components/schemas/did' required: - id additionalProperties: true proof: type: object properties: type: type: string enum: - JwtProof2020 required: - type additionalProperties: true additionalProperties: true required: - '@context' - type - issuer - issuanceDate - credentialSubject - proof required: - type - resource ObjectResource: title: ObjectResource type: object properties: type: example: Object enum: - Object name: type: string example: Resource name parentResource: type: string identity: $ref: '#/components/schemas/did' resource: type: object additionalProperties: true required: - type - resource KeyPair: title: JWK pair type: object properties: type: example: KeyPair enum: - KeyPair name: type: string example: Resource name identity: $ref: '#/components/schemas/did' resource: type: object properties: keyPair: $ref: '#/components/schemas/JwkPair' required: - keyPair required: - type - resource Contract: title: Contract type: object properties: type: example: Contract enum: - Contract name: type: string example: Resource name identity: $ref: '#/components/schemas/did' resource: type: object properties: dataSharingAgreement: $ref: '#/components/schemas/DataSharingAgreement' keyPair: $ref: '#/components/schemas/JwkPair' required: - dataSharingAgreement required: - type - resource DataExchangeResource: title: DataExchangeResource type: object properties: type: example: DataExchange enum: - DataExchange name: type: string example: Resource name resource: $ref: '#/components/schemas/DataExchange' required: - type - resource NonRepudiationProof: title: NonRepudiationProof type: object properties: type: example: NonRepudiationProof enum: - NonRepudiationProof name: type: string example: Resource name resource: description: >- a non-repudiation proof (either a PoO, a PoR or a PoP) as a compact JWS required: - type - resource ResourceId: type: object properties: id: type: string required: - id ResourceType: type: string enum: - VerifiableCredential - Object - KeyPair - Contract - DataExchange - NonRepudiationProof SignedTransaction: title: SignedTransaction description: A list of resources type: object properties: transaction: type: string pattern: ^0x(?:[A-Fa-f0-9])+$ DecodedJwt: title: JwtPayload type: object properties: header: type: object properties: typ: type: string enum: - JWT alg: type: string enum: - ES256K required: - typ - alg additionalProperties: true payload: type: object properties: iss: $ref: '#/components/schemas/did' required: - iss additionalProperties: true signature: type: string format: ^[A-Za-z0-9_-]+$ data: type: string format: ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$ description: <base64url(header)>.<base64url(payload)> required: - signature - data VerificationOutput: title: VerificationOutput type: object properties: verification: type: string enum: - success - failed description: whether verification has been successful or has failed error: type: string description: error message if verification failed decodedJwt: description: the decoded JWT required: - verification ProviderData: title: ProviderData description: A JSON object with information of the DLT provider currently in use. type: object properties: provider: type: string example: did:ethr:i3m network: type: string example: i3m rpcUrl: oneOf: - type: string example: http://95.211.3.250:8545 - type: array items: type: string uniqueItems: true example: - http://95.211.3.249:8545 - http://95.211.3.250:8545 additionalProperties: true EthereumAddress: description: Ethereum Address in EIP-55 format (with checksum) type: string pattern: ^0x([0-9A-Fa-f]){40}$ example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F' did: description: a DID using the ethr resolver type: string pattern: ^did:ethr:(\w+:)?0x[0-9a-fA-F]{40}([0-9a-fA-F]{26})?$ example: >- did:ethr:i3m:0x031bee96cfae8bad99ea0dd3d08d1a3296084f894e9ddfe1ffe141133e81ac5863 IdentityData: title: Identity Data type: object properties: did: type: string example: >- did:ethr:i3m:0x03142f480f831e835822fc0cd35726844a7069d28df58fb82037f1598812e1ade8 alias: type: string example: identity1 provider: type: string example: did:ethr:i3m addresses: type: array items: $ref: '#/components/schemas/EthereumAddress' example: - '0x8646cAcF516de1292be1D30AB68E7Ea51e9B1BE7' required: - did ApiError: type: object title: Error required: - code - message properties: code: type: integer format: int32 message: type: string JwkPair: type: object properties: privateJwk: type: string description: > A stringified JWK with alphabetically sorted claims that represents a private key (complementary to `publicJwk`) example: >- {"alg":"ES256","crv":"P-256","d":"rQp_3eZzvXwt1sK7WWsRhVYipqNGblzYDKKaYirlqs0","kty":"EC","x":"sMGSjfIlRJRseMpx3iHhCx4uh-6N4-AUKX18lmoeSD8","y":"Hu8EcpyH2XrCd-oKqm9keEhnMx2v2QaPs6P4Vs8OkpE"} publicJwk: type: string description: > A stringified JWK with alphabetically sorted claims that represents the public key (complementary to `privateJwk`). example: >- {"alg":"ES256","crv":"P-256","kty":"EC","x":"sMGSjfIlRJRseMpx3iHhCx4uh-6N4-AUKX18lmoeSD8","y":"Hu8EcpyH2XrCd-oKqm9keEhnMx2v2QaPs6P4Vs8OkpE"} required: - privateJwk - publicJwk CompactJWS: title: CompactJWS type: string pattern: ^[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+$ DataExchangeAgreement: type: object required: - orig - dest - encAlg - signingAlg - hashAlg - ledgerContractAddress - ledgerSignerAddress - pooToPorDelay - pooToPopDelay - pooToSecretDelay properties: orig: type: string description: A stringified JWK with alphabetically sorted claims example: >- {"alg":"ES256","crv":"P-256","kty":"EC","x":"t0ueMqN9j8lWYa2FXZjSw3cycpwSgxjl26qlV6zkFEo","y":"rMqWC9jGfXXLEh_1cku4-f0PfbFa1igbNWLPzos_gb0"} dest: type: string description: A stringified JWK with alphabetically sorted claims example: >- {"alg":"ES256","crv":"P-256","kty":"EC","x":"sI5lkRCGpfeViQzAnu-gLnZnIGdbtfPiY7dGk4yVn-k","y":"4iFXDnEzPEb7Ce_18RSV22jW6VaVCpwH3FgTAKj3Cf4"} encAlg: type: string enum: - A128GCM - A256GCM example: A256GCM signingAlg: type: string enum: - ES256 - ES384 - ES512 example: ES256 hashAlg: type: string enum: - SHA-256 - SHA-384 - SHA-512 example: SHA-256 ledgerContractAddress: $ref: '#/components/schemas/EthereumAddress' ledgerSignerAddress: $ref: '#/components/schemas/EthereumAddress' pooToPorDelay: description: >- Maximum acceptable time in milliseconds between issued PoO and verified PoR type: integer minimum: 1 example: 10000 pooToPopDelay: description: >- Maximum acceptable time in milliseconds between issued PoO and issued PoP type: integer minimum: 1 example: 20000 pooToSecretDelay: description: >- Maximum acceptable time between issued PoO and secret published on the ledger type: integer minimum: 1 example: 180000 schema: description: A stringified JSON-LD schema describing the data format type: string DataSharingAgreement: type: object required: - dataOfferingDescription - parties - purpose - duration - intendedUse - licenseGrant - dataStream - personalData - pricingModel - dataExchangeAgreement - signatures properties: dataOfferingDescription: type: object required: - dataOfferingId - version - active properties: dataOfferingId: type: string version: type: integer category: type: string active: type: boolean title: type: string parties: type: object required: - providerDid - consumerDid properties: providerDid: $ref: '#/components/schemas/did' consumerDid: $ref: '#/components/schemas/did' purpose: type: string duration: type: object required: - creationDate - startDate - endDate properties: creationDate: type: integer startDate: type: integer endDate: type: integer intendedUse: type: object required: - processData - shareDataWithThirdParty - editData properties: processData: type: boolean shareDataWithThirdParty: type: boolean editData: type: boolean licenseGrant: type: object required: - transferable - exclusiveness - paidUp - revocable - processing - modifying - analyzing - storingData - storingCopy - reproducing - distributing - loaning - selling - renting - furtherLicensing - leasing properties: transferable: type: boolean exclusiveness: type: boolean paidUp: type: boolean revocable: type: boolean processing: type: boolean modifying: type: boolean analyzing: type: boolean storingData: type: boolean storingCopy: type: boolean reproducing: type: boolean distributing: type: boolean loaning: type: boolean selling: type: boolean renting: type: boolean furtherLicensing: type: boolean leasing: type: boolean dataStream: type: boolean personalData: type: boolean pricingModel: type: object required: - basicPrice - currency - hasFreePrice properties: paymentType: type: string pricingModelName: type: string basicPrice: type: number format: float currency: type: string fee: type: number format: float hasPaymentOnSubscription: type: object properties: paymentOnSubscriptionName: type: string paymentType: type: string timeDuration: type: string description: type: string repeat: type: string hasSubscriptionPrice: type: number hasFreePrice: type: object properties: hasPriceFree: type: boolean dataExchangeAgreement: $ref: '#/components/schemas/DataExchangeAgreement' signatures: type: object required: - providerSignature - consumerSignature properties: providerSignature: $ref: '#/components/schemas/CompactJWS' consumerSignature: $ref: '#/components/schemas/CompactJWS' DataExchange: allOf: - $ref: '#/components/schemas/DataExchangeAgreement' - type: object properties: cipherblockDgst: type: string description: hash of the cipherblock in base64url with no padding pattern: ^[a-zA-Z0-9_-]+$ blockCommitment: type: string description: hash of the plaintext block in base64url with no padding pattern: ^[a-zA-Z0-9_-]+$ secretCommitment: type: string description: >- ash of the secret that can be used to decrypt the block in base64url with no padding pattern: ^[a-zA-Z0-9_-]+$ required: - cipherblockDgst - blockCommitment - secretCommitment