fix(auth): bring in Open API schemas for IdP and RS (#684)

* fix: bring in Open API schemas for IdP and RS * fix: update path to schemas and README * fix: fix formatting * Update packages/auth/openapi/id-provider.yaml interledger/open-payments@b125873? - #689 Co-authored-by: Brandon Wilson <[email protected]> Co-authored-by: Brandon Wilson <[email protected]>
interledger · Nov 2, 2022 · 3807051 · 3807051
1 parent c8d42f6
commit 3807051
Show file tree

Hide file tree

Showing 6 changed files with 303 additions and 1 deletion.
diff --git a/packages/auth/.gitignore b/packages/auth/.gitignore
@@ -0,0 +1 @@
+/openapi/schemas.yaml
diff --git a/packages/auth/README.md b/packages/auth/README.md
@@ -3,11 +3,18 @@
 The authorization server used to issue authorizations for Open Payments actions.
 Implements Open Payments authorization endpoints in accordance with the GNAP spec for an AS:
 
-- https://github.com/interledger/open-payments/blob/master/auth-server-open-api-spec.yaml
+- https://github.com/interledger/open-payments/tree/main/openapi/auth-server.yaml
 - https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol
 
 ## Local Development
 
+Be sure to import the latest Open API spec schemas from the Open Payments repo:
+
+```shell
+# from the root
+pnpm --filter auth run fetch-schemas
+```
+
 ### Prerequisites
 
 - [Docker](https://docs.docker.com/engine/install/) configured to [run as non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)

diff --git a/packages/auth/openapi/id-provider.yaml b/packages/auth/openapi/id-provider.yaml
@@ -0,0 +1,167 @@
+openapi: 3.1.0
+info:
+  title: Rafiki Authorization Server - Identity Provider Connection
+  version: '1.0'
+  license:
+    name: Apache 2.0
+    identifier: Apache-2.0
+  summary: Rafiki 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 Rafiki Open Payments Authorization Server and an Identity Provider.'
+  contact:
+    email: [email protected]
+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':
+          content:
+            text/html:
+              schema:
+                type: string
+                nullable: true
+          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: ./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
+security:
+  - GNAP: []
diff --git a/packages/auth/openapi/resource-server.yaml b/packages/auth/openapi/resource-server.yaml
@@ -0,0 +1,113 @@
+openapi: 3.1.0
+info:
+  title: Rafiki Authorization Server - Resource Server Connection
+  version: '1.0'
+  license:
+    name: Apache 2.0
+    identifier: Apache-2.0
+  summary: Rafiki 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 Rafiki Open Payments Authorization Server and the Rafiki 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: [email protected]
+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: ./schemas.yaml#/access
+                  key:
+                    $ref: ./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: ./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: ./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
+security:
+  - GNAP: []
diff --git a/packages/auth/package.json b/packages/auth/package.json
@@ -10,6 +10,7 @@
     "build:deps": "pnpm --filter openapi build",
     "build": "pnpm build:deps && tsc --build tsconfig.json",
     "clean": "rm -fr dist/",
+    "fetch-schemas": "./scripts/get-op-schema.sh",
     "test": "jest --passWithNoTests --maxWorkers=50%",
     "prepack": "pnpm build"
   },

diff --git a/packages/auth/scripts/get-op-schema.sh b/packages/auth/scripts/get-op-schema.sh
@@ -0,0 +1,13 @@
+#!/bin/bash
+
+## https://stackoverflow.com/questions/59895/how-do-i-get-the-directory-where-a-bash-script-is-located-from-within-the-script
+SOURCE=${BASH_SOURCE[0]}
+while [ -L "$SOURCE" ]; do # resolve $SOURCE until the file is no longer a symlink
+  DIR=$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )
+  SOURCE=$(readlink "$SOURCE")
+  [[ $SOURCE != /* ]] && SOURCE=$DIR/$SOURCE # if $SOURCE was a relative symlink, we need to resolve it relative to the path where the symlink file was located
+done
+OUTDIR=$( cd -P "$( dirname "$SOURCE" )/../openapi" >/dev/null 2>&1 && pwd )
+
+curl -o "$OUTDIR/schemas.yaml" https://raw.githubusercontent.com/interledger/open-payments/main/openapi/schemas.yaml
+