From 9b2ffcf9e63c61ad503a15e400bb7b628f3d87bd Mon Sep 17 00:00:00 2001 From: Sabine Schaller Date: Tue, 18 Oct 2022 01:11:41 +0200 Subject: [PATCH] chore(auth-spec): split auth spec (#188) * chore(auth-spec): split auth spec * chore(auth-spec): add folder structure, use shared schema file * chore: update github workflows * fix: github workflows * chore: merge gh workflow jobs * refactor(auth): use shared schemas also for OP spec, delete old spec files * refactor: simplify gh workflow * style(auth-spec): undo double quotes * refactor(OP-spec): share assetCode assetScale schemas * feat(auth-spec): add .prettierrc, single quotes * feat(auth-spec): use shared `access` * chore(specs): move RS spec into RS folder * chore: rename directory `openapi-specs` -> `openapi` * chore: update workflow paths * chore: add linting to workflow * chore: update spec publishing workflow * chore: split openapi workflows --- .../publish-as-api-to-readme-io.yaml | 21 - .github/workflows/publish-openapi.yaml | 30 + .../publish-rs-api-to-readme-io.yaml | 21 - .../{openapi.yaml => validate-openapi.yaml} | 17 +- .prettierrc.yaml | 1 + auth-server-open-api-spec.yaml | 948 ------------------ openapi/AS/IdP/openapi.yaml | 160 +++ openapi/AS/RS/openapi.yaml | 111 ++ openapi/AS/client/openapi.yaml | 439 ++++++++ open-api-spec.yaml => openapi/RS/openapi.yaml | 131 +-- openapi/shared/schemas.yaml | 282 ++++++ 11 files changed, 1066 insertions(+), 1095 deletions(-) delete mode 100644 .github/workflows/publish-as-api-to-readme-io.yaml create mode 100644 .github/workflows/publish-openapi.yaml delete mode 100644 .github/workflows/publish-rs-api-to-readme-io.yaml rename .github/workflows/{openapi.yaml => validate-openapi.yaml} (50%) create mode 100644 .prettierrc.yaml delete mode 100644 auth-server-open-api-spec.yaml create mode 100644 openapi/AS/IdP/openapi.yaml create mode 100644 openapi/AS/RS/openapi.yaml create mode 100644 openapi/AS/client/openapi.yaml rename open-api-spec.yaml => openapi/RS/openapi.yaml (93%) create mode 100644 openapi/shared/schemas.yaml diff --git a/.github/workflows/publish-as-api-to-readme-io.yaml b/.github/workflows/publish-as-api-to-readme-io.yaml deleted file mode 100644 index e708163d..00000000 --- a/.github/workflows/publish-as-api-to-readme-io.yaml +++ /dev/null @@ -1,21 +0,0 @@ -name: Deploy AS API spec to readme.io - -on: - push: - branches: - - main - paths: - - auth-server-open-api-spec.yaml - -jobs: - sync: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v3 - name: Check out repository - - - uses: readmeio/rdme@7.2.0 - name: Sync Auth Server API spec - with: - rdme: openapi auth-server-open-api-spec.yaml --key=${{ secrets.README_API_KEY }} --id=${{ secrets.README_AUTH_API_ID }} diff --git a/.github/workflows/publish-openapi.yaml b/.github/workflows/publish-openapi.yaml new file mode 100644 index 00000000..013bdceb --- /dev/null +++ b/.github/workflows/publish-openapi.yaml @@ -0,0 +1,30 @@ +name: OpenAPI Publisher + +on: + push: + branches: + - main + paths: + - openapi/** + +jobs: + publish: + workflow_run: + workflows: ['OpenAPI Validator'] + branches: [main] + types: + - completed + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + name: Check out repository + + - uses: readmeio/rdme@7.2.0 + name: Sync Open Payments API spec + with: + rdme: openapi openapi/RS/openapi.yaml --key=${{ secrets.README_API_KEY }} --id=${{ secrets.README_OP_API_ID }} + + - uses: readmeio/rdme@7.2.0 + name: Sync Auth Server API spec + with: + rdme: openapi openapi/AS/client/openapi.yaml --key=${{ secrets.README_API_KEY }} --id=${{ secrets.README_AUTH_API_ID }} diff --git a/.github/workflows/publish-rs-api-to-readme-io.yaml b/.github/workflows/publish-rs-api-to-readme-io.yaml deleted file mode 100644 index 8180b60b..00000000 --- a/.github/workflows/publish-rs-api-to-readme-io.yaml +++ /dev/null @@ -1,21 +0,0 @@ -name: Deploy RS API spec to readme.io - -on: - push: - branches: - - main - paths: - - open-api-spec.yaml - -jobs: - sync: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v3 - name: Check out repository - - - uses: readmeio/rdme@7.2.0 - name: Sync Open Payments API spec - with: - rdme: openapi open-api-spec.yaml --key=${{ secrets.README_API_KEY }} --id=${{ secrets.README_OP_API_ID }} diff --git a/.github/workflows/openapi.yaml b/.github/workflows/validate-openapi.yaml similarity index 50% rename from .github/workflows/openapi.yaml rename to .github/workflows/validate-openapi.yaml index be622a8f..1afb0d42 100644 --- a/.github/workflows/openapi.yaml +++ b/.github/workflows/validate-openapi.yaml @@ -5,14 +5,12 @@ on: branches: - main paths: - - auth-server-open-api-spec.yaml - - open-api-spec.yaml + - openapi/** pull_request: branches: - main paths: - - auth-server-open-api-spec.yaml - - open-api-spec.yaml + - openapi/** jobs: validate: @@ -21,11 +19,14 @@ jobs: - uses: actions/checkout@v2 - uses: actions/setup-node@v2 - - name: Validate open-api-spec.yaml + - name: Lint openapi.yaml + run: | + npx prettier --check openapi/**/openapi.yaml + + - name: AsyncAPI extension run: | echo "{\"extends\":[\"spectral:oas\",\"spectral:asyncapi\"]}" >> .spectral.json - npx @stoplight/spectral-cli lint open-api-spec.yaml - - name: Validate auth-server-open-api-spec.yaml + - name: Validate openapi.yaml run: | - npx @stoplight/spectral-cli lint auth-server-open-api-spec.yaml + npx @stoplight/spectral-cli lint openapi/**/openapi.yaml diff --git a/.prettierrc.yaml b/.prettierrc.yaml new file mode 100644 index 00000000..01769692 --- /dev/null +++ b/.prettierrc.yaml @@ -0,0 +1 @@ +singleQuote: true diff --git a/auth-server-open-api-spec.yaml b/auth-server-open-api-spec.yaml deleted file mode 100644 index 6fc3aca4..00000000 --- a/auth-server-open-api-spec.yaml +++ /dev/null @@ -1,948 +0,0 @@ -openapi: 3.1.0 -info: - title: Open Payments Authorization Server - version: '1.0' - license: - name: Apache 2.0 - identifier: Apache-2.0 - summary: Open Payments GNAP Authorization Server - description: 'The Open Payments API is secured via [GNAP](https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol). This specification describes the Open Payments Authorization Server API, which is an opinionated GNAP Server API.' - contact: - email: tech@interledger.org -servers: - - url: 'https://openpayments.guide/auth' -tags: - - name: grant - description: grant operations - - name: token - description: token operations - - name: interaction - description: User interaction endpoints -paths: - /: - post: - summary: Grant Request - operationId: post - responses: - '200': - description: OK - content: - application/json: - schema: - oneOf: - - properties: - interact: - $ref: '#/components/schemas/interact-response' - continue: - $ref: '#/components/schemas/continue' - required: - - interact - - continue - - properties: - access_token: - $ref: '#/components/schemas/access_token' - continue: - $ref: '#/components/schemas/continue' - required: - - access_token - - continue - type: object - examples: - Interaction instructions: - value: - interact: - redirect: 'https://openpayments.guide/auth/4CF492MLVMSW9MKMXKHQ' - finish: 4105340a-05eb-4290-8739-f9e2b463bfa7 - continue: - access_token: - value: 33OMUKMKSKU80UPRY5NM - uri: 'https://openpayments.guide/auth/continue/4CF492MLVMSW9MKMXKHQ' - wait: 30 - Grant: - value: - access_token: - value: OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 - manage: 'https://openpayments.guide/auth/token/dd17a202-9982-4ed9-ae31-564947fb6379' - expires_in: 3600 - access: - - type: incoming-payment - actions: - - create - - read - identifier: 'https://openpayments.guide/bob' - continue: - access_token: - value: 33OMUKMKSKU80UPRY5NM - uri: 'https://openpayments.guide/auth/continue/4CF492MLVMSW9MKMXKHQ' - '400': - description: Bad Request - requestBody: - content: - application/json: - schema: - description: '' - type: object - properties: - access_token: - type: object - required: - - access - properties: - access: - type: array - description: Describes the rights that the client instance is requesting for one or more access tokens to be used at RS's. Each access type must only be represented once within the access array. - items: - $ref: '#/components/schemas/access' - client: - $ref: '#/components/schemas/client' - interact: - $ref: '#/components/schemas/interact-request' - required: - - access_token - - client - examples: - Grant request for creating and reading recurring fixed payment: - value: - access_token: - access: - - type: outgoing-payment - actions: - - create - - read - identifier: 'https://openpayments.guide/alice' - limits: - receiver: 'https://openpayments.guide/connections/45a0d0ee-26dc-4c66-89e0-01fbf93156f7' - interval: 'R12/2019-08-24T14:15:22Z/P1M' - sendAmount: - value: '500' - assetCode: USD - assetScale: 2 - client: - display: - name: Webmonize - uri: 'https://webmonize.com' - key: - proof: httpsig - jwk: - alg: EdDSA - kid: 20f24ce2-a5f6-4f28-bf7d-ed52d0490187 - kty: OKP - use: sig - crv: Ed25519 - x: AAAAC3NzaC1lZDI1NTE5AAAAIK0wmN/Cr3JXqmLW7u+g9pTh+wyqDHpSQEIQczXkVx9q - interact: - start: - - redirect - finish: - method: redirect - uri: 'https://webmonize.com/return/876FGRD8VC' - nonce: 4edb2194-dbdf-46bb-9397-d5fd57b7c8a7 - Grant request for creating and reading incoming payments: - value: - access_token: - access: - - type: incoming-payment - actions: - - create - - read - identifier: 'http://openpayments.guide/bob' - client: - display: - name: Webmonize - uri: 'https://webmonize.com' - key: - proof: httpsig - jwk: - alg: EdDSA - kid: 20f24ce2-a5f6-4f28-bf7d-ed52d0490187 - kty: OKP - use: sig - crv: Ed25519 - x: AAAAC3NzaC1lZDI1NTE5AAAAIK0wmN/Cr3JXqmLW7u+g9pTh+wyqDHpSQEIQczXkVx9q - description: '' - description: Make a new grant request - security: [] - tags: - - grant - parameters: [] - '/continue/{id}': - parameters: - - schema: - type: string - name: id - in: path - required: true - post: - summary: Continuation Request - operationId: post-continue - responses: - '200': - description: Success - content: - application/json: - schema: - type: object - properties: - access_token: - $ref: '#/components/schemas/access_token' - continue: - $ref: '#/components/schemas/continue' - required: - - continue - examples: - Continuing After a Completed Interaction: - value: - access_token: - value: OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 - manage: 'https://openpayments.guide/auth/token/dd17a202-9982-4ed9-ae31-564947fb6379' - expires_in: 3600 - access: - - type: outgoing-payment - actions: - - create - - read - identifier: 'https://openpayments.guide/alice' - limits: - receiver: 'https://openpayments.guide/bob/incoming-payments/48884225-b393-4872-90de-1b737e2491c2' - interval: 'R12/2019-08-24T14:15:22Z/P1M' - sendAmount: - value: '500' - assetCode: USD - assetScale: 2 - continue: - access_token: - value: 33OMUKMKSKU80UPRY5NM - uri: 'https://openpayments.guide/auth/continue/4CF492MLVMSW9MKMXKHQ' - wait: 30 - Continuing During Pending Interaction: - value: - continue: - access_token: - value: 33OMUKMKSKU80UPRY5NM - uri: 'https://openpayments.guide/auth/continue/4CF492MLVMSW9MKMXKHQ' - wait: 30 - '401': - description: Unauthorized - '404': - description: Not Found - requestBody: - content: - application/json: - schema: - type: object - properties: - interact_ref: - type: string - description: |- - The interaction reference generated for this - interaction by the AS. - required: - - interact_ref - examples: - Interaction Reference: - value: - interact_ref: ad82597c-bbfa-4eb0-b72e-328e005b8689 - description: Continue a grant request during or after user interaction. - tags: - - grant - delete: - summary: Cancel Grant - operationId: delete-continue - responses: - '202': - description: Accepted - '401': - description: Unauthorized - '404': - description: Not Found - description: Cancel a grant request or delete a grant client side. - tags: - - grant - '/token/{id}': - parameters: - - schema: - type: string - name: id - in: path - required: true - post: - summary: Rotate Access Token - operationId: post-token - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - access_token: - $ref: '#/components/schemas/access_token' - required: - - access_token - examples: - New access token: - value: - access_token: - value: OZB8CDFONP219RP1LT0OS9M2PMHKUR64TB8N6BW7 - manage: 'https://openpayments.guide/auth/token/8f69de01-5bf9-4603-91ed-eeca101081f1' - expires_in: 3600 - access: - - type: outgoing-payment - actions: - - create - - read - identifier: 'https://openpayments.guide/alice' - limits: - interval: 'R12/2019-08-24T14:15:22Z/P1M' - receiver: 'https://openpayments.guide/bob/incoming-payments/48884225-b393-4872-90de-1b737e2491c2' - sendAmount: - value: '500' - assetCode: USD - assetScale: 2 - '401': - description: Unauthorized - '404': - description: Not Found - description: Management endpoint to rotate access token. - tags: - - token - delete: - summary: Revoke Access Token - operationId: delete-token - description: Management endpoint to revoke access token. - responses: - '204': - description: No Content - '401': - description: Unauthorized - tags: - - token - /introspect: - parameters: [] - post: - summary: Introspect Access Token - operationId: post-introspect - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - active: - type: boolean - grant: - type: string - access: - type: array - items: - $ref: '#/components/schemas/access' - key: - $ref: '#/components/schemas/key' - client_id: - type: string - description: Opaque client identifier. - required: - - active - examples: - Token Introspection: - value: - active: true - grant: 1ee48d97-8fa1-4ab4-b89d-95284b665517 - access: - - type: outgoing-payment - actions: - - create - - read - identifier: 'https://openpayments.guide/alice' - limits: - interval: 'R12/2019-08-24T14:15:22Z/P1M' - receiver: 'https://openpayments.guide/bob/incoming-payments/48884225-b393-4872-90de-1b737e2491c2' - sendAmount: - value: '500' - assetCode: USD - assetScale: 2 - key: - proof: httpsig - jwk: - alg: EdDSA - kid: 20f24ce2-a5f6-4f28-bf7d-ed52d0490187 - kty: OKP - use: sig - crv: Ed25519 - x: AAAAC3NzaC1lZDI1NTE5AAAAIK0wmN/Cr3JXqmLW7u+g9pTh+wyqDHpSQEIQczXkVx9q - client_id: 581a1dd9-aef5-4b1a-9d78-c1afc4a5fdbf - '404': - description: Not Found - description: Introspect an access token to get grant details. - requestBody: - content: - application/json: - schema: - type: object - properties: - access_token: - type: string - description: The access token value presented to the RS by the client instance. - proof: - type: string - description: The proofing method used by the client instance to bind the token to the RS request. - resource_server: - oneOf: - - $ref: '#/components/schemas/key' - - type: string - description: 'The identification used to authenticate the resource server making this call, either by value or by reference.' - access: - type: array - description: The minimum access rights required to fulfill the request. - items: - $ref: '#/components/schemas/access' - required: - - access_token - - resource_server - examples: - Introspect token: - value: - access_token: OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 - proof: httpsig - resource_server: 7C7C4AZ9KHRS6X63AJAO - tags: - - token - '/interact/{id}/{nonce}': - get: - summary: Start user interaction - tags: - - interaction - - grant - responses: - '302': - content: - text/html: - schema: - type: string - nullable: true - description: Found - headers: - Location: - schema: - type: string - description: Identity server endpoint - Cookie: - schema: - type: string - description: Interaction id - operationId: get-interact - parameters: - - schema: - type: string - name: id - in: path - required: true - description: Interaction id - - schema: - type: string - in: path - name: nonce - required: true - description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.' - description: 'To start the user interaction for grant approval, this endpoint redirects to identity server for authentication of the user.' - '/interact/{id}/{nonce}/finish': - get: - summary: Finish user interaction - operationId: get-finish-interaction - responses: - '302': - description: Found - headers: - Location: - schema: - type: string - description: Client finish endpoint - description: 'To finish the user interaction for grant approval, this endpoint redirects to the client''s finish url.' - tags: - - interaction - - grant - parameters: - - schema: - type: string - in: path - name: id - required: true - description: Interaction id - - schema: - type: string - in: path - name: nonce - required: true - description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.' - '/grant/{id}/{nonce}': - get: - summary: Lookup Grant - tags: - - interaction - - grant - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - access: - type: array - items: - $ref: '#/components/schemas/access' - '404': - description: Not Found - operationId: get-grant - description: Retrieve the grant associated with the provided interactId - parameters: - - schema: - type: string - name: id - in: path - required: true - description: Interaction id - - schema: - type: string - in: path - name: nonce - required: true - description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.' - '/grant/{id}/{nonce}/{choice}': - post: - summary: Accept or reject a grant - operationId: post-grant-choice - responses: - '202': - description: Accepted - '401': - description: Unauthorized - '404': - description: Not Found - description: Submit the RO's consent choice for a particular grant - tags: - - interaction - - grant - parameters: - - schema: - type: string - name: id - in: path - required: true - description: Interaction id - - schema: - type: string - in: path - name: nonce - required: true - description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.' - - schema: - type: string - enum: - - accept - - reject - in: path - name: choice - required: true - description: Indicates the consent choice for a grant (i.e. acceptance or rejection) -components: - schemas: - access: - discriminator: - propertyName: type - mapping: - incoming-payment: '#/components/schemas/access-incoming' - outgoing-payment: '#/components/schemas/access-outgoing' - quote: '#/components/schemas/access-quote' - oneOf: - - $ref: '#/components/schemas/access-incoming' - - $ref: '#/components/schemas/access-outgoing' - - $ref: '#/components/schemas/access-quote' - description: The access associated with the access token is described using objects that each contain multiple dimensions of access. - unevaluatedProperties: false - limits-outgoing: - title: limits-outgoing - description: Open Payments specific property that defines the limits under which outgoing payments can be created. - type: object - properties: - receiver: - $ref: '#/components/schemas/receiver' - sendAmount: - $ref: '#/components/schemas/amount' - receiveAmount: - $ref: '#/components/schemas/amount' - interval: - $ref: '#/components/schemas/interval' - anyOf: - - not: - required: - - interval - - required: - - sendAmount - - required: - - receiveAmount - amount: - title: amount - type: object - description: 'All amounts are maxima, i.e. multiple payments can be created under a grant as long as the total amounts of these payments do not exceed the maximum amount per interval as specified in the grant.' - properties: - value: - type: string - format: uint64 - description: 'The value is an unsigned 64-bit integer amount, represented as a string.' - assetCode: - type: string - description: The assetCode is a code that indicates the underlying asset. In most cases this SHOULD be a 3-character ISO 4217 currency code. - assetScale: - type: integer - minimum: 0 - maximum: 255 - description: 'The assetScale indicates how the value has been scaled relative to the natural scale of the asset. For example, an value of "1234" with an assetScale of 2 represents an amount of 12.34.' - required: - - value - - assetCode - - assetScale - interval: - title: Interval - type: string - description: '[ISO8601 repeating interval](https://en.wikipedia.org/wiki/ISO_8601#Repeating_intervals)' - examples: - - 'R11/2022-08-24T14:15:22Z/P1M' - - 'R/2017-03-01T13:00:00Z/2018-05-11T15:30:00Z' - - 'R-1/P1Y2M10DT2H30M/2022-05-11T15:30:00Z' - receiver: - title: Receiver - type: string - description: The URL of the incoming payment or ILP STREAM connection that is being paid. - format: uri - pattern: "^https:\/\/(.+)\/(incoming-payments|connections)\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" - examples: - - 'https://openpayments.guide/alice/incoming-payments/08394f02-7b7b-45e2-b645-51d04e7c330c' - - 'https://openpayments.guide/connections/016da9d5-c9a4-4c80-a354-86b915a04ff8' - client: - title: client - type: object - properties: - display: - type: object - description: 'An object containing additional information that the AS MAY display to the RO during interaction, authorization, and management.' - properties: - name: - type: string - uri: - type: string - format: uri - client_id: - type: string - description: An identifier string that the AS can use to identify the client software comprising this client instance. - key: - oneOf: - - $ref: '#/components/schemas/key' - - type: string - description: The public key of the client instance to be used in this request or a reference to a key. - description: |- - Describes the client instance that is making this request, including the key that the client instance will use to protect this request and any continuation requests at the AS and any user-facing information about the client instance used in interactions. - - When sending a non-continuation request to the AS, the client instance MUST identify itself by including the client field of the request and by signing the request. - key: - title: key - type: object - properties: - proof: - type: string - enum: - - httpsig - description: The form of proof that the client instance will use when presenting the key. - jwk: - type: object - description: 'The public key and its properties represented as a JSON Web Key [[RFC7517](https://datatracker.ietf.org/doc/html/rfc7517)].' - required: - - alg - - kty - - crv - - x - properties: - alg: - type: string - description: 'The cryptographic algorithm family used with the key. The only allowed value is `EdDSA`. ' - enum: - - EdDSA - kid: - type: string - description: A Key ID can be used to match a specific key. - kty: - type: string - enum: - - OKP - description: 'The Key Type. The only allowed value is `OKP`. ' - use: - type: string - enum: - - sig - description: The intended use of the key. - crv: - type: string - enum: - - Ed25519 - description: 'The cryptographic curve used with the key. The only allowed value is `Ed25519`. ' - x: - type: string - description: Public key encoded using the `base64url` encoding. - key_ops: - type: array - description: Array of allowed operations this key may be used for. - items: - type: string - enum: - - sign - - verify - nbf: - type: integer - description: UNIX timestamp indicating the earliest this key may be used. - exp: - type: integer - description: UNIX timestamp indicating the latest this key may be used. - revoked: - type: boolean - description: The revocation status of the key. - additionalProperties: false - required: - - proof - - jwk - description: A key presented by value MUST be a public key. - interact-request: - title: interact - type: object - properties: - start: - type: array - description: Indicates how the client instance can start an interaction. - items: - type: string - enum: - - redirect - finish: - type: object - description: Indicates how the client instance can receive an indication that interaction has finished at the AS. - properties: - method: - type: string - enum: - - redirect - description: The callback method that the AS will use to contact the client instance. - uri: - type: string - format: uri - description: Indicates the URI that the AS will either send the RO to after interaction or send an HTTP POST request. - nonce: - type: string - description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.' - required: - - method - - uri - - nonce - required: - - start - description: The client instance declares the parameters for interaction methods that it can support using the interact field. - interact-response: - title: interact-response - type: object - properties: - redirect: - type: string - format: uri - description: The URI to direct the end user to. - finish: - type: string - description: Unique key to secure the callback. - required: - - redirect - - finish - continue: - title: continue - type: object - description: 'If the AS determines that the request can be continued with additional requests, it responds with the continue field.' - properties: - access_token: - type: object - description: 'A unique access token for continuing the request, called the "continuation access token".' - required: - - value - properties: - value: - type: string - uri: - type: string - format: uri - description: The URI at which the client instance can make continuation requests. - wait: - type: integer - description: The amount of time in integer seconds the client instance MUST wait after receiving this request continuation response and calling the continuation URI. - required: - - access_token - - uri - access_token: - title: access_token - type: object - description: A single access token or set of access tokens that the client instance can use to call the RS on behalf of the RO. - properties: - value: - type: string - description: The value of the access token as a string. The value is opaque to the client instance. The value SHOULD be limited to ASCII characters to facilitate transmission over HTTP headers within other protocols without requiring additional encoding. - manage: - type: string - format: uri - description: The management URI for this access token. This URI MUST NOT include the access token value and SHOULD be different for each access token issued in a request. - expires_in: - type: integer - description: The number of seconds in which the access will expire. The client instance MUST NOT use the access token past this time. An RS MUST NOT accept an access token past this time. - access: - type: array - description: A description of the rights associated with this access token. - items: - $ref: '#/components/schemas/access' - allOf: - - contains: - properties: - type: - const: incoming-payment - minContains: 0 - maxContains: 1 - - contains: - properties: - type: - const: outgoing-payment - minContains: 0 - maxContains: 1 - - contains: - properties: - type: - const: quote - minContains: 0 - maxContains: 1 - required: - - value - - manage - - access - access-outgoing: - title: access-outgoing - type: object - properties: - type: - type: string - enum: - - outgoing-payment - description: The type of resource request as a string. This field defines which other fields are allowed in the request object. - actions: - type: array - description: The types of actions the client instance will take at the RS as an array of strings. - items: - type: string - enum: - - create - - read - - read-all - - list - - list-all - allOf: - - contains: - $ref: '#/components/schemas/read-actions' - minContains: 0 - maxContains: 1 - - contains: - $ref: '#/components/schemas/list-actions' - minContains: 0 - maxContains: 1 - uniqueItems: true - identifier: - type: string - format: uri - description: A string identifier indicating a specific resource at the RS. - limits: - $ref: '#/components/schemas/limits-outgoing' - required: - - type - - actions - - identifier - access-incoming: - title: access-incoming - type: object - properties: - type: - type: string - enum: - - incoming-payment - description: The type of resource request as a string. This field defines which other fields are allowed in the request object. - actions: - type: array - description: The types of actions the client instance will take at the RS as an array of strings. - items: - type: string - enum: - - create - - complete - - read - - read-all - - list - - list-all - allOf: - - contains: - $ref: '#/components/schemas/read-actions' - minContains: 0 - maxContains: 1 - - contains: - $ref: '#/components/schemas/list-actions' - minContains: 0 - maxContains: 1 - uniqueItems: true - identifier: - type: string - format: uri - description: A string identifier indicating a specific resource at the RS. - required: - - type - - actions - access-quote: - title: access-quote - type: object - properties: - type: - type: string - enum: - - quote - description: The type of resource request as a string. This field defines which other fields are allowed in the request object. - actions: - type: array - description: The types of actions the client instance will take at the RS as an array of strings. - items: - type: string - enum: - - create - - read - - read-all - allOf: - - contains: - $ref: '#/components/schemas/read-actions' - minContains: 0 - maxContains: 1 - uniqueItems: true - required: - - type - - actions - read-actions: - enum: - - read - - read-all - list-actions: - enum: - - list - - list-all - securitySchemes: - GNAP: - name: Authorization - type: apiKey - in: header diff --git a/openapi/AS/IdP/openapi.yaml b/openapi/AS/IdP/openapi.yaml new file mode 100644 index 00000000..243f85bc --- /dev/null +++ b/openapi/AS/IdP/openapi.yaml @@ -0,0 +1,160 @@ +openapi: 3.1.0 +info: + title: Open Payments Authorization Server - Identity Provider Connection + version: '1.0' + license: + name: Apache 2.0 + identifier: Apache-2.0 + summary: Open Payments Authorization Server - Identity Provider Connection + description: 'The Open Payments API is secured via [GNAP](https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol). This specification describes the connection between the Open Payments Authorization Server and the Identity Provider.' + contact: + email: tech@interledger.org +servers: + - url: 'https://openpayments.guide/auth' +tags: + - name: front-channel + description: Redirect URLs + - name: back-channel + description: Endpoints to request or modify grant information +paths: + '/interact/{id}/{nonce}': + get: + summary: Start user interaction + responses: + '302': + content: + text/html: + schema: + type: string + nullable: true + description: Found + headers: + Location: + schema: + type: string + description: Identity server endpoint + Cookie: + schema: + type: string + description: Interaction id + operationId: get-interact + parameters: + - schema: + type: string + name: id + in: path + required: true + description: Interaction id + - schema: + type: string + in: path + name: nonce + required: true + description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.' + description: 'To start the user interaction for grant approval, this endpoint redirects the user to an Identity provider endpoint for authentication.' + tags: + - front-channel + '/interact/{id}/{nonce}/finish': + get: + summary: Finish user interaction + operationId: get-finish-interaction + responses: + '302': + description: Found + headers: + Location: + schema: + type: string + description: Client finish endpoint + description: "To finish the user interaction for grant approval, this endpoint redirects the user to the client's finish url." + parameters: + - schema: + type: string + in: path + name: id + required: true + description: Interaction id + - schema: + type: string + in: path + name: nonce + required: true + description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.' + tags: + - front-channel + '/grant/{id}/{nonce}': + get: + summary: Lookup Grant + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + access: + $ref: ../../shared/schemas.yaml#/access + '404': + description: Not Found + operationId: get-grant + description: | + The Identity Provider uses this endpoint to requests the grant details associated with the provided `interactId` on the front-channel. It will then display those details to the user to either accept or deny the grant. + parameters: + - schema: + type: string + name: id + in: path + required: true + description: Interaction id + - schema: + type: string + in: path + name: nonce + required: true + description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.' + tags: + - back-channel + '/grant/{id}/{nonce}/{choice}': + post: + summary: Accept or reject a grant + operationId: post-grant-choice + responses: + '202': + description: Accepted + '401': + description: Unauthorized + '404': + description: Not Found + description: The Identity Provider uses this endpoint to submit the user's choice regarding accepting or rejecting a grant to Authorization Server. + parameters: + - schema: + type: string + name: id + in: path + required: true + description: Interaction id + - schema: + type: string + in: path + name: nonce + required: true + description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.' + - schema: + type: string + enum: + - accept + - reject + in: path + name: choice + required: true + description: Indicates the consent choice for a grant (i.e. acceptance or rejection) + tags: + - back-channel +components: + schemas: {} + securitySchemes: + GNAP: + name: Authorization + type: apiKey + in: header diff --git a/openapi/AS/RS/openapi.yaml b/openapi/AS/RS/openapi.yaml new file mode 100644 index 00000000..58f6c1e6 --- /dev/null +++ b/openapi/AS/RS/openapi.yaml @@ -0,0 +1,111 @@ +openapi: 3.1.0 +info: + title: Open Payments Authorization Server - Resource Server Connection + version: '1.0' + license: + name: Apache 2.0 + identifier: Apache-2.0 + summary: Open Payments Authorization Server - Resource Server Connection + description: 'The Open Payments API is secured via [GNAP](https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol). This specification describes the connection between the Open Payments Authorization Server and the Open Payments Resource Server, which is an opinionated version of the [Grant Negotiation and Authorization Protocol Resource Server Connections](https://datatracker.ietf.org/doc/html/draft-ietf-gnap-resource-servers).' + contact: + email: tech@interledger.org +servers: + - url: 'https://openpayments.guide/auth' +tags: + - name: introspection + description: Token introspection +paths: + /introspect: + parameters: [] + post: + summary: Introspect Access Token + operationId: post-introspect + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + active: + type: boolean + grant: + type: string + access: + $ref: ../../shared/schemas.yaml#/access + key: + $ref: ../../shared/schemas.yaml#/key + client_id: + type: string + description: Opaque client identifier. + required: + - active + examples: + Token Introspection: + value: + active: true + grant: 1ee48d97-8fa1-4ab4-b89d-95284b665517 + access: + - type: outgoing-payment + actions: + - create + - read + identifier: 'https://openpayments.guide/alice' + limits: + interval: 'R12/2019-08-24T14:15:22Z/P1M' + receiver: 'https://openpayments.guide/bob/incoming-payments/48884225-b393-4872-90de-1b737e2491c2' + sendAmount: + value: '500' + assetCode: USD + assetScale: 2 + key: + proof: httpsig + jwk: + alg: EdDSA + kid: 20f24ce2-a5f6-4f28-bf7d-ed52d0490187 + kty: OKP + use: sig + crv: Ed25519 + x: AAAAC3NzaC1lZDI1NTE5AAAAIK0wmN/Cr3JXqmLW7u+g9pTh+wyqDHpSQEIQczXkVx9q + client_id: 581a1dd9-aef5-4b1a-9d78-c1afc4a5fdbf + '404': + description: Not Found + description: Introspect an access token to get grant details. + requestBody: + content: + application/json: + schema: + type: object + properties: + access_token: + type: string + description: The access token value presented to the RS by the client instance. + proof: + type: string + description: The proofing method used by the client instance to bind the token to the RS request. + resource_server: + oneOf: + - $ref: ../../shared/schemas.yaml#/key + - type: string + description: 'The identification used to authenticate the resource server making this call, either by value or by reference.' + access: + $ref: ../../shared/schemas.yaml#/access + required: + - access_token + - resource_server + examples: + Introspect token: + value: + access_token: OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 + proof: httpsig + resource_server: 7C7C4AZ9KHRS6X63AJAO + tags: + - introspection +components: + schemas: {} + securitySchemes: + GNAP: + name: Authorization + type: apiKey + in: header diff --git a/openapi/AS/client/openapi.yaml b/openapi/AS/client/openapi.yaml new file mode 100644 index 00000000..baccb8cf --- /dev/null +++ b/openapi/AS/client/openapi.yaml @@ -0,0 +1,439 @@ +openapi: 3.1.0 +info: + title: Open Payments Authorization Server + version: '1.0' + license: + name: Apache 2.0 + identifier: Apache-2.0 + summary: Open Payments Authorization Server + description: 'The Open Payments API is secured via [GNAP](https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol). This specification describes the Open Payments Authorization Server API, which is an opinionated GNAP Server API.' + contact: + email: tech@interledger.org +servers: + - url: 'https://openpayments.guide/auth' +tags: + - name: grant + description: grant operations + - name: token + description: token operations +paths: + /: + post: + summary: Grant Request + operationId: post-request + responses: + '200': + description: OK + content: + application/json: + schema: + oneOf: + - properties: + interact: + $ref: '#/components/schemas/interact-response' + continue: + $ref: '#/components/schemas/continue' + required: + - interact + - continue + - properties: + access_token: + $ref: '#/components/schemas/access_token' + continue: + $ref: '#/components/schemas/continue' + required: + - access_token + - continue + type: object + examples: + Interaction instructions: + value: + interact: + redirect: 'https://openpayments.guide/auth/4CF492MLVMSW9MKMXKHQ' + finish: 4105340a-05eb-4290-8739-f9e2b463bfa7 + continue: + access_token: + value: 33OMUKMKSKU80UPRY5NM + uri: 'https://openpayments.guide/auth/continue/4CF492MLVMSW9MKMXKHQ' + wait: 30 + Grant: + value: + access_token: + value: OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 + manage: 'https://openpayments.guide/auth/token/dd17a202-9982-4ed9-ae31-564947fb6379' + expires_in: 3600 + access: + - type: incoming-payment + actions: + - create + - read + identifier: 'https://openpayments.guide/bob' + continue: + access_token: + value: 33OMUKMKSKU80UPRY5NM + uri: 'https://openpayments.guide/auth/continue/4CF492MLVMSW9MKMXKHQ' + '400': + description: Bad Request + requestBody: + content: + application/json: + schema: + description: '' + type: object + properties: + access_token: + type: object + required: + - access + properties: + access: + $ref: ../../shared/schemas.yaml#/access + client: + $ref: '#/components/schemas/client' + interact: + $ref: '#/components/schemas/interact-request' + required: + - access_token + - client + examples: + Grant request for creating and reading recurring fixed payment: + value: + access_token: + access: + - type: outgoing-payment + actions: + - create + - read + identifier: 'https://openpayments.guide/alice' + limits: + receiver: 'https://openpayments.guide/connections/45a0d0ee-26dc-4c66-89e0-01fbf93156f7' + interval: 'R12/2019-08-24T14:15:22Z/P1M' + sendAmount: + value: '500' + assetCode: USD + assetScale: 2 + client: + display: + name: Webmonize + uri: 'https://webmonize.com' + key: + proof: httpsig + jwk: + alg: EdDSA + kid: 20f24ce2-a5f6-4f28-bf7d-ed52d0490187 + kty: OKP + use: sig + crv: Ed25519 + x: AAAAC3NzaC1lZDI1NTE5AAAAIK0wmN/Cr3JXqmLW7u+g9pTh+wyqDHpSQEIQczXkVx9q + interact: + start: + - redirect + finish: + method: redirect + uri: 'https://webmonize.com/return/876FGRD8VC' + nonce: 4edb2194-dbdf-46bb-9397-d5fd57b7c8a7 + Grant request for creating and reading incoming payments: + value: + access_token: + access: + - type: incoming-payment + actions: + - create + - read + identifier: 'http://openpayments.guide/bob' + client: + display: + name: Webmonize + uri: 'https://webmonize.com' + key: + proof: httpsig + jwk: + alg: EdDSA + kid: 20f24ce2-a5f6-4f28-bf7d-ed52d0490187 + kty: OKP + use: sig + crv: Ed25519 + x: AAAAC3NzaC1lZDI1NTE5AAAAIK0wmN/Cr3JXqmLW7u+g9pTh+wyqDHpSQEIQczXkVx9q + description: '' + description: Make a new grant request + security: [] + tags: + - grant + parameters: [] + '/continue/{id}': + parameters: + - schema: + type: string + name: id + in: path + required: true + post: + summary: Continuation Request + operationId: post-continue + responses: + '200': + description: Success + content: + application/json: + schema: + type: object + properties: + access_token: + $ref: '#/components/schemas/access_token' + continue: + $ref: '#/components/schemas/continue' + required: + - continue + examples: + Continuing After a Completed Interaction: + value: + access_token: + value: OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 + manage: 'https://openpayments.guide/auth/token/dd17a202-9982-4ed9-ae31-564947fb6379' + expires_in: 3600 + access: + - type: outgoing-payment + actions: + - create + - read + identifier: 'https://openpayments.guide/alice' + limits: + receiver: 'https://openpayments.guide/bob/incoming-payments/48884225-b393-4872-90de-1b737e2491c2' + interval: 'R12/2019-08-24T14:15:22Z/P1M' + sendAmount: + value: '500' + assetCode: USD + assetScale: 2 + continue: + access_token: + value: 33OMUKMKSKU80UPRY5NM + uri: 'https://openpayments.guide/auth/continue/4CF492MLVMSW9MKMXKHQ' + wait: 30 + Continuing During Pending Interaction: + value: + continue: + access_token: + value: 33OMUKMKSKU80UPRY5NM + uri: 'https://openpayments.guide/auth/continue/4CF492MLVMSW9MKMXKHQ' + wait: 30 + '401': + description: Unauthorized + '404': + description: Not Found + requestBody: + content: + application/json: + schema: + type: object + properties: + interact_ref: + type: string + description: |- + The interaction reference generated for this + interaction by the AS. + required: + - interact_ref + examples: + Interaction Reference: + value: + interact_ref: ad82597c-bbfa-4eb0-b72e-328e005b8689 + description: Continue a grant request during or after user interaction. + tags: + - grant + delete: + summary: Cancel Grant + operationId: delete-continue + responses: + '202': + description: Accepted + '401': + description: Unauthorized + '404': + description: Not Found + description: Cancel a grant request or delete a grant client side. + tags: + - grant + '/token/{id}': + parameters: + - schema: + type: string + name: id + in: path + required: true + post: + summary: Rotate Access Token + operationId: post-token + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + access_token: + $ref: '#/components/schemas/access_token' + required: + - access_token + examples: + New access token: + value: + access_token: + value: OZB8CDFONP219RP1LT0OS9M2PMHKUR64TB8N6BW7 + manage: 'https://openpayments.guide/auth/token/8f69de01-5bf9-4603-91ed-eeca101081f1' + expires_in: 3600 + access: + - type: outgoing-payment + actions: + - create + - read + identifier: 'https://openpayments.guide/alice' + limits: + interval: 'R12/2019-08-24T14:15:22Z/P1M' + receiver: 'https://openpayments.guide/bob/incoming-payments/48884225-b393-4872-90de-1b737e2491c2' + sendAmount: + value: '500' + assetCode: USD + assetScale: 2 + '401': + description: Unauthorized + '404': + description: Not Found + description: Management endpoint to rotate access token. + tags: + - token + delete: + summary: Revoke Access Token + operationId: delete-token + description: Management endpoint to revoke access token. + responses: + '204': + description: No Content + '401': + description: Unauthorized + tags: + - token +components: + schemas: + client: + title: client + type: object + description: |- + Describes the client instance that is making this request, including the key that the client instance will use to protect this request and any continuation requests at the AS and any user-facing information about the client instance used in interactions. + + When sending a non-continuation request to the AS, the client instance MUST identify itself by including the client field of the request and by signing the request. + properties: + display: + type: object + description: 'An object containing additional information that the AS MAY display to the RO during interaction, authorization, and management.' + properties: + name: + type: string + uri: + type: string + format: uri + client_id: + type: string + description: An identifier string that the AS can use to identify the client software comprising this client instance. + key: + oneOf: + - $ref: ../../shared/schemas.yaml#/key + - type: string + description: The public key of the client instance to be used in this request or a reference to a key. + interact-request: + title: interact + type: object + properties: + start: + type: array + description: Indicates how the client instance can start an interaction. + items: + type: string + enum: + - redirect + finish: + type: object + description: Indicates how the client instance can receive an indication that interaction has finished at the AS. + properties: + method: + type: string + enum: + - redirect + description: The callback method that the AS will use to contact the client instance. + uri: + type: string + format: uri + description: Indicates the URI that the AS will either send the RO to after interaction or send an HTTP POST request. + nonce: + type: string + description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.' + required: + - method + - uri + - nonce + required: + - start + description: The client instance declares the parameters for interaction methods that it can support using the interact field. + interact-response: + title: interact-response + type: object + properties: + redirect: + type: string + format: uri + description: The URI to direct the end user to. + finish: + type: string + description: Unique key to secure the callback. + required: + - redirect + - finish + continue: + title: continue + type: object + description: 'If the AS determines that the request can be continued with additional requests, it responds with the continue field.' + properties: + access_token: + type: object + description: 'A unique access token for continuing the request, called the "continuation access token".' + required: + - value + properties: + value: + type: string + uri: + type: string + format: uri + description: The URI at which the client instance can make continuation requests. + wait: + type: integer + description: The amount of time in integer seconds the client instance MUST wait after receiving this request continuation response and calling the continuation URI. + required: + - access_token + - uri + access_token: + title: access_token + type: object + description: A single access token or set of access tokens that the client instance can use to call the RS on behalf of the RO. + properties: + value: + type: string + description: The value of the access token as a string. The value is opaque to the client instance. The value SHOULD be limited to ASCII characters to facilitate transmission over HTTP headers within other protocols without requiring additional encoding. + manage: + type: string + format: uri + description: The management URI for this access token. This URI MUST NOT include the access token value and SHOULD be different for each access token issued in a request. + expires_in: + type: integer + description: The number of seconds in which the access will expire. The client instance MUST NOT use the access token past this time. An RS MUST NOT accept an access token past this time. + access: + $ref: ../../shared/schemas.yaml#/access + required: + - value + - manage + - access + securitySchemes: + GNAP: + name: Authorization + type: apiKey + in: header diff --git a/open-api-spec.yaml b/openapi/RS/openapi.yaml similarity index 93% rename from open-api-spec.yaml rename to openapi/RS/openapi.yaml index bab3724b..8ca9a476 100644 --- a/open-api-spec.yaml +++ b/openapi/RS/openapi.yaml @@ -84,6 +84,7 @@ paths: The content should be slow changing and cacheable for long periods. Servers SHOULD use cache control headers. security: [] + x-internal: false '/connections/{id}': servers: - url: 'https://openpayments.guide/' @@ -169,7 +170,7 @@ paths: properties: incomingAmount: description: The maximum amount that should be paid into the payment pointer under this incoming payment. - $ref: '#/components/schemas/amount' + $ref: ../shared/schemas.yaml#/amount expiresAt: type: string description: The date and time when payments into the incoming payment must no longer be accepted. @@ -566,16 +567,16 @@ paths: assetScale: 2 schema: type: object + additionalProperties: false properties: receiver: - $ref: '#/components/schemas/receiver' + $ref: ../shared/schemas.yaml#/receiver receiveAmount: - $ref: '#/components/schemas/amount' + $ref: ../shared/schemas.yaml#/amount sendAmount: - $ref: '#/components/schemas/amount' + $ref: ../shared/schemas.yaml#/amount required: - receiver - additionalProperties: false description: |- A subset of the quotes schema is accepted as input to create a new quote. @@ -779,6 +780,13 @@ components: title: Payment Pointer type: object description: A **payment pointer** resource is the root of the API and contains the public details of the financial account represented by the Payment Pointer that is also the service endpoint URL. + additionalProperties: false + examples: + - id: 'https://openpayments.guide/alice' + publicName: Alice + assetCode: USD + assetScale: 2 + authServer: 'https://openpayments.guide/auth' properties: id: type: string @@ -790,12 +798,9 @@ components: description: A public name for the account. This should be set by the account holder with their provider to provide a hint to counterparties as to the identity of the account holder. readOnly: true assetCode: - $ref: '#/components/schemas/assetCode' - description: The asset code of the account. - readOnly: true + $ref: ../shared/schemas.yaml#/assetCode assetScale: - $ref: '#/components/schemas/assetScale' - readOnly: true + $ref: ../shared/schemas.yaml#/assetScale authServer: type: string format: uri @@ -806,17 +811,15 @@ components: - assetCode - assetScale - authServer - additionalProperties: false - examples: - - id: 'https://openpayments.guide/alice' - publicName: Alice - assetCode: USD - assetScale: 2 - authServer: 'https://openpayments.guide/auth' ilp-stream-connection: title: ILP Stream Connection type: object description: An **ILP STREAM Connection** is an endpoint that returns unique STREAM connection credentials to establish a STREAM connection to the underlying account. + additionalProperties: false + examples: + - id: 'https://openpayments.guide/connections/016da9d5-c9a4-4c80-a354-86b915a04ff8' + ilpApddress: g.ilp.iwuyge987y.98y08y + sharedSecret: 1c7eaXa4rd2fFOBl1iydvCT1tV5TbM3RW1WLCafu_JA properties: id: type: string @@ -831,26 +834,19 @@ components: readOnly: true sharedSecret: type: string - pattern: "^[a-zA-Z0-9-_]+$" + pattern: '^[a-zA-Z0-9-_]+$' description: The base64 url-encoded shared secret to use when establishing a STREAM connection. readOnly: true assetCode: - $ref: '#/components/schemas/assetCode' - description: The asset code of the amount. + $ref: ../shared/schemas.yaml#/assetCode assetScale: - $ref: '#/components/schemas/assetScale' - description: The scale of the amount. + $ref: ../shared/schemas.yaml#/assetScale required: - id - ilpAddress - sharedSecret - assetCode - assetScale - additionalProperties: false - examples: - - id: 'https://openpayments.guide/connections/016da9d5-c9a4-4c80-a354-86b915a04ff8' - ilpApddress: g.ilp.iwuyge987y.98y08y - sharedSecret: 1c7eaXa4rd2fFOBl1iydvCT1tV5TbM3RW1WLCafu_JA incoming-payment: title: Incoming Payment description: 'An **incoming payment** resource represents a payment that will be, is currently being, or has been received by the account.' @@ -902,10 +898,10 @@ components: default: false incomingAmount: description: The maximum amount that should be paid into the payment pointer under this incoming payment. - $ref: '#/components/schemas/amount' + $ref: ../shared/schemas.yaml#/amount receivedAmount: description: The total amount that has been paid into the payment pointer under this incoming payment. - $ref: '#/components/schemas/amount' + $ref: ../shared/schemas.yaml#/amount expiresAt: type: string description: The date and time when payments under this incoming payment will no longer be accepted. @@ -1055,16 +1051,16 @@ components: default: false receiver: description: The URL of the incoming payment or ILP STREAM Connection that is being paid. - $ref: '#/components/schemas/receiver' + $ref: ../shared/schemas.yaml#/receiver receiveAmount: description: The total amount that should be received by the receiver when this outgoing payment has been paid. - $ref: '#/components/schemas/amount' + $ref: ../shared/schemas.yaml#/amount sendAmount: description: The total amount that should be sent when this outgoing payment has been paid. - $ref: '#/components/schemas/amount' + $ref: ../shared/schemas.yaml#/amount sentAmount: description: The total amount that has been sent under this outgoing payment. - $ref: '#/components/schemas/amount' + $ref: ../shared/schemas.yaml#/amount description: type: string description: Human readable description of the outgoing payment that will be visible to the account holder and shared with the receiver. @@ -1120,6 +1116,7 @@ components: assetScale: 2 createdAt: '2022-03-12T23:20:50.52Z' expiresAt: '2022-04-12T23:20:50.52Z' + additionalProperties: false properties: id: type: string @@ -1132,14 +1129,11 @@ components: description: The URL of the payment pointer from which this quote's payment would be sent. readOnly: true receiver: - description: The URL of the incoming payment or ILP Stream Connection that would be paid. - $ref: '#/components/schemas/receiver' + $ref: ../shared/schemas.yaml#/receiver receiveAmount: - description: The total amount that should be received by the receiver. - $ref: '#/components/schemas/amount' + $ref: ../shared/schemas.yaml#/amount sendAmount: - description: The total amount that should be sent by the sender. - $ref: '#/components/schemas/amount' + $ref: ../shared/schemas.yaml#/amount expiresAt: type: string description: The date and time when the calculated `sendAmount` is no longer valid. @@ -1152,66 +1146,9 @@ components: - id - paymentPointer - receiver - - sendAmount - receiveAmount + - sendAmount - createdAt - additionalProperties: false - amount: - title: Amount - type: object - description: |- - All amounts in open payments are represented as a value and an asset code and scale. - - The `value` is an unsigned 64-bit integer amount, represented as a string. - - The `assetCode` is a code that indicates the underlying asset. In most cases this SHOULD be a 3-character ISO 4217 currency code. - - The `assetScale` indicates how the `value` has been scaled relative to the natural scale of the asset. For example, an `value` of `"1234"` with an `assetScale` of `2` represents an amount of 12.34. - examples: - - value: '2500' - assetCode: USD - assetScale: 2 - - value: '500' - assetCode: EUR - assetScale: 2 - - value: '123456789' - assetCode: BTC - assetScale: 8 - properties: - value: - type: string - format: uint64 - description: 'The amount, scaled by the given scale.' - assetCode: - $ref: '#/components/schemas/assetCode' - description: The asset code of the amount. - assetScale: - $ref: '#/components/schemas/assetScale' - description: The scale of the amount. - required: - - value - - assetCode - - assetScale - additionalProperties: false - assetCode: - title: Asset code - type: string - description: This SHOULD be an ISO4217 currency code. - assetScale: - title: Asset scale - type: integer - minimum: 0 - maximum: 255 - description: The scale of amounts denoted in the corresponding asset code. - receiver: - title: Receiver - type: string - description: The URL of the incoming payment or ILP STREAM connection that is being paid. - format: uri - pattern: '^https://(.+)/(incoming-payments|connections)/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' - examples: - - 'https://openpayments.guide/alice/incoming-payments/08394f02-7b7b-45e2-b645-51d04e7c330c' - - 'https://openpayments.guide/connections/016da9d5-c9a4-4c80-a354-86b915a04ff8' pagination: description: Pagination parameters oneOf: diff --git a/openapi/shared/schemas.yaml b/openapi/shared/schemas.yaml new file mode 100644 index 00000000..a3bcfb14 --- /dev/null +++ b/openapi/shared/schemas.yaml @@ -0,0 +1,282 @@ +access: + type: array + description: A description of the rights associated with this access token. + items: + $ref: '#/access-item' + allOf: + - contains: + properties: + type: + const: incoming-payment + minContains: 0 + maxContains: 1 + - contains: + properties: + type: + const: outgoing-payment + minContains: 0 + maxContains: 1 + - contains: + properties: + type: + const: quote + minContains: 0 + maxContains: 1 +access-item: + discriminator: + propertyName: type + mapping: + incoming-payment: '#/access-incoming' + outgoing-payment: '#/access-outgoing' + quote: '#/access-quote' + oneOf: + - $ref: '#/access-incoming' + - $ref: '#/access-outgoing' + - $ref: '#/access-quote' + description: The access associated with the access token is described using objects that each contain multiple dimensions of access. + unevaluatedProperties: false +access-incoming: + title: access-incoming + type: object + properties: + type: + type: string + enum: + - incoming-payment + description: The type of resource request as a string. This field defines which other fields are allowed in the request object. + actions: + type: array + description: The types of actions the client instance will take at the RS as an array of strings. + items: + type: string + enum: + - create + - complete + - read + - read-all + - list + - list-all + allOf: + - contains: + $ref: '#/read-actions' + minContains: 0 + maxContains: 1 + - contains: + $ref: '#/list-actions' + minContains: 0 + maxContains: 1 + uniqueItems: true + identifier: + type: string + format: uri + description: A string identifier indicating a specific resource at the RS. + required: + - type + - actions +access-outgoing: + title: access-outgoing + type: object + properties: + type: + type: string + enum: + - outgoing-payment + description: The type of resource request as a string. This field defines which other fields are allowed in the request object. + actions: + type: array + description: The types of actions the client instance will take at the RS as an array of strings. + items: + type: string + enum: + - create + - read + - read-all + - list + - list-all + allOf: + - contains: + $ref: '#/read-actions' + minContains: 0 + maxContains: 1 + - contains: + $ref: '#/list-actions' + minContains: 0 + maxContains: 1 + uniqueItems: true + identifier: + type: string + format: uri + description: A string identifier indicating a specific resource at the RS. + limits: + $ref: '#/limits-outgoing' + required: + - type + - actions + - identifier +access-quote: + title: access-quote + type: object + properties: + type: + type: string + enum: + - quote + description: The type of resource request as a string. This field defines which other fields are allowed in the request object. + actions: + type: array + description: The types of actions the client instance will take at the RS as an array of strings. + items: + type: string + enum: + - create + - read + - read-all + allOf: + - contains: + $ref: '#/read-actions' + minContains: 0 + maxContains: 1 + uniqueItems: true + required: + - type + - actions +amount: + title: amount + type: object + description: 'All amounts are maxima, i.e. multiple payments can be created under a grant as long as the total amounts of these payments do not exceed the maximum amount per interval as specified in the grant.' + properties: + value: + type: string + format: uint64 + description: 'The value is an unsigned 64-bit integer amount, represented as a string.' + assetCode: + $ref: '#/assetCode' + assetScale: + $ref: '#/assetScale' + required: + - value + - assetCode + - assetScale +assetCode: + title: Asset code + type: string + description: The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code. +assetScale: + title: Asset scale + type: integer + minimum: 0 + maximum: 255 + description: The scale of amounts denoted in the corresponding asset code. +interval: + title: Interval + type: string + description: '[ISO8601 repeating interval](https://en.wikipedia.org/wiki/ISO_8601#Repeating_intervals)' + examples: + - 'R11/2022-08-24T14:15:22Z/P1M' + - 'R/2017-03-01T13:00:00Z/2018-05-11T15:30:00Z' + - 'R-1/P1Y2M10DT2H30M/2022-05-11T15:30:00Z' +key: + title: key + type: object + description: A key presented by value MUST be a public key. + properties: + proof: + type: string + enum: + - httpsig + description: The form of proof that the client instance will use when presenting the key. + jwk: + type: object + description: 'The public key and its properties represented as a JSON Web Key [[RFC7517](https://datatracker.ietf.org/doc/html/rfc7517)].' + additionalProperties: false + required: + - alg + - kid + - kty + - crv + - x + properties: + alg: + type: string + description: 'The cryptographic algorithm family used with the key. The only allowed value is `EdDSA`. ' + enum: + - EdDSA + kid: + type: string + description: A Key ID can be used to match a specific key. + kty: + type: string + enum: + - OKP + description: 'The Key Type. The only allowed value is `OKP`. ' + use: + type: string + enum: + - sig + description: The intended use of the key. + crv: + type: string + enum: + - Ed25519 + description: 'The cryptographic curve used with the key. The only allowed value is `Ed25519`. ' + x: + type: string + description: Public key encoded using the `base64url` encoding. + key_ops: + type: array + description: Array of allowed operations this key may be used for. + items: + type: string + enum: + - sign + - verify + nbf: + type: integer + description: UNIX timestamp indicating the earliest this key may be used. + exp: + type: integer + description: UNIX timestamp indicating the latest this key may be used. + revoked: + type: boolean + description: The revocation status of the key. + required: + - proof + - jwk +limits-outgoing: + title: limits-outgoing + description: Open Payments specific property that defines the limits under which outgoing payments can be created. + type: object + properties: + receiver: + $ref: '#/receiver' + sendAmount: + $ref: '#/amount' + receiveAmount: + $ref: '#/amount' + interval: + $ref: '#/interval' + anyOf: + - not: + required: + - interval + - required: + - sendAmount + - required: + - receiveAmount +list-actions: + enum: + - list + - list-all +read-actions: + enum: + - read + - read-all +receiver: + title: Receiver + type: string + description: The URL of the incoming payment or ILP STREAM connection that is being paid. + format: uri + pattern: '^https://(.+)/(incoming-payments|connections)/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' + examples: + - 'https://openpayments.guide/alice/incoming-payments/08394f02-7b7b-45e2-b645-51d04e7c330c' + - 'https://openpayments.guide/connections/016da9d5-c9a4-4c80-a354-86b915a04ff8'