@toa.io/extensions.exposition 1.0.0-alpha.282 → 1.0.0-alpha.283

package/features/oauth.clients.feature

@@ -0,0 +1,195 @@
+@security
+Feature: Client registration
+
+  A client that speaks nothing else registers what it is and is given an identifier for it.
+  The identifier is a hash of the metadata, so a client that cannot remember it registered
+  here does not leave another row every time it connects.
+
+  Background:
+    Given the `identity.clients` database is empty
+    And the `identity.basic` database contains:
+      | _id                              | authority | username  | password                                                     |
+      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
+    And the annotation:
+      """yaml
+      authorities:
+        nex: nex.toa.io
+      oauth:
+        authorize: https://app.nex.toa.io/oauth/authorize
+        registration: open
+      """
+
+  Scenario: A client registers what it is
+    When the following request is received:
+      """
+      POST /identity/clients/ HTTP/1.1
+      host: nex.toa.io
+      content-type: application/yaml
+      accept: application/yaml
+
+      client_name: Claude
+      redirect_uris:
+        - https://claude.ai/api/mcp/auth_callback
+      token_endpoint_auth_method: none
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+      cache-control: no-store
+
+      client_id: ${{ client }}
+      client_name: Claude
+      redirect_uris:
+        - https://claude.ai/api/mcp/auth_callback
+      grant_types:
+        - authorization_code
+      response_types:
+        - code
+      token_endpoint_auth_method: none
+      """
+
+  Scenario: The same client is the same client
+    When the following request is received:
+      """
+      POST /identity/clients/ HTTP/1.1
+      host: nex.toa.io
+      content-type: application/yaml
+      accept: application/yaml
+
+      client_name: Claude
+      redirect_uris:
+        - https://claude.ai/api/mcp/auth_callback
+        - http://localhost/callback
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+
+      client_id: ${{ first }}
+      """
+    # the same metadata, written in another order
+    When the following request is received:
+      """
+      POST /identity/clients/ HTTP/1.1
+      host: nex.toa.io
+      content-type: application/yaml
+      accept: application/yaml
+
+      client_name: Claude
+      redirect_uris:
+        - http://localhost/callback
+        - https://claude.ai/api/mcp/auth_callback
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+
+      client_id: ${{ first }}
+      """
+
+  Scenario: A redirect a code must not be sent to
+    When the following request is received:
+      """
+      POST /identity/clients/ HTTP/1.1
+      host: nex.toa.io
+      content-type: application/yaml
+      accept: application/yaml
+
+      client_name: Insecure
+      redirect_uris:
+        - http://example.com/callback
+      """
+    Then the following reply is sent:
+      """
+      400 Bad Request
+      cache-control: no-store
+
+      error: invalid_redirect_uri
+      """
+
+  Scenario: A client that would authenticate at the token endpoint
+    When the following request is received:
+      """
+      POST /identity/clients/ HTTP/1.1
+      host: nex.toa.io
+      content-type: application/yaml
+      accept: application/yaml
+
+      client_name: Confidential
+      redirect_uris:
+        - https://claude.ai/api/mcp/auth_callback
+      token_endpoint_auth_method: client_secret_post
+      """
+    Then the following reply is sent:
+      """
+      400 Bad Request
+
+      error: invalid_client_metadata
+      """
+
+  Scenario: Registration is advertised once it is opened
+    When the following request is received:
+      """
+      GET /.well-known/oauth-authorization-server HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      registration_endpoint: https://nex.toa.io/identity/clients/
+      """
+
+  Scenario: The consent page reads who is asking
+    When the following request is received:
+      """
+      POST /identity/clients/ HTTP/1.1
+      host: nex.toa.io
+      content-type: application/yaml
+      accept: application/yaml
+
+      client_name: Claude
+      client_uri: https://claude.ai
+      redirect_uris:
+        - https://claude.ai/api/mcp/auth_callback
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+
+      client_id: ${{ client }}
+      """
+    # the page is authenticated by the time it asks, so this is not anonymous
+    When the following request is received:
+      """
+      GET /identity/clients/${{ client }}/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      client_id: ${{ client }}
+      client_name: Claude
+      client_uri: https://claude.ai
+      redirect_uris:
+        - https://claude.ai/api/mcp/auth_callback
+      """
+
+  Scenario: A client nobody registered
+    When the following request is received:
+      """
+      GET /identity/clients/00000000000000000000000000000000/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      422 Unprocessable Entity
+
+      code: UNKNOWN_CLIENT
+      """

package/features/oauth.discovery.feature

@@ -0,0 +1,165 @@
+@security
+Feature: Authorization server discovery
+
+  What a client reads before it can authenticate. Both documents are public, are a
+  function of the annotation alone, and are answered before anything is routed.
+
+  Background:
+    Given the annotation:
+      """yaml
+      authorities:
+        nex: nex.toa.io
+      oauth:
+        authorize: https://app.nex.toa.io/oauth/authorize
+        resources: ['/mcp/']
+        scopes: [app:notes]
+      /:
+        io:output: true
+        /mcp/**:
+          anyone: true
+          GET:
+            dev:stub: Tools
+      """
+
+  Scenario: The authorization server names its endpoints
+    When the following request is received:
+      """
+      GET /.well-known/oauth-authorization-server HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      issuer: https://nex.toa.io
+      authorization_endpoint: https://app.nex.toa.io/oauth/authorize
+      token_endpoint: https://nex.toa.io/identity/grants/
+      response_types_supported:
+        - code
+      grant_types_supported:
+        - authorization_code
+      code_challenge_methods_supported:
+        - S256
+      token_endpoint_auth_methods_supported:
+        - none
+      client_id_metadata_document_supported: true
+      authorization_response_iss_parameter_supported: true
+      scopes_supported:
+        - app:notes
+      """
+
+  Scenario: Registration is not advertised unless it is opened
+    When the following request is received:
+      """
+      GET /.well-known/oauth-authorization-server HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the reply does not contain:
+      """
+      registration_endpoint
+      """
+
+  Scenario: The protected resource is named by the path it is reached at
+    When the following request is received:
+      """
+      GET /.well-known/oauth-protected-resource/mcp HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      resource: https://nex.toa.io/mcp
+      authorization_servers:
+        - https://nex.toa.io
+      bearer_methods_supported:
+        - header
+      scopes_supported:
+        - app:notes
+      """
+
+  Scenario: The origin has a document of its own
+    When the following request is received:
+      """
+      GET /.well-known/oauth-protected-resource HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      resource: https://nex.toa.io
+      authorization_servers:
+        - https://nex.toa.io
+      bearer_methods_supported:
+        - header
+      scopes_supported:
+        - app:notes
+      """
+
+  Scenario: A client holding a stale token still reads discovery
+    When the following request is received:
+      """
+      GET /.well-known/oauth-authorization-server HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer expired.and.useless
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      issuer: https://nex.toa.io
+      """
+
+  Scenario: The challenge names the resource the request was refused at
+    When the following request is received:
+      """
+      GET /mcp/tools/ HTTP/1.1
+      host: nex.toa.io
+      accept: text/plain
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      www-authenticate: Bearer resource_metadata="https://nex.toa.io/.well-known/oauth-protected-resource/mcp", scope="app:notes"
+      """
+
+  Scenario: A host named after a property a plain object answers on its own
+    When the following request is received:
+      """
+      GET /.well-known/oauth-authorization-server HTTP/1.1
+      host: constructor
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      404 Not Found
+      """
+
+  Scenario: An authorization server nobody annotated is not discovered
+    Given the annotation:
+      """yaml
+      authorities:
+        nex: nex.toa.io
+      /:
+        io:output: true
+        /hello/:
+          anonymous: true
+          GET:
+            dev:stub: Hello
+      """
+    When the following request is received:
+      """
+      GET /.well-known/oauth-authorization-server HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      404 Not Found
+      """

package/features/oauth.grants.feature

@@ -0,0 +1,286 @@
+@security
+Feature: Authorization code flow
+
+  A client is refused, finds the authorization server, registers, is consented to by a user,
+  and exchanges the code it was given for a token it can come back with. The consent page is
+  the application's own — the two calls in the background are what it would make.
+
+  Background:
+    Given the `identity.clients` database is empty
+    And the `identity.grants` database is empty
+    And the `identity.basic` database contains:
+      | _id                              | authority | username  | password                                                     |
+      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
+    And the annotation:
+      """yaml
+      authorities:
+        nex: nex.toa.io
+      oauth:
+        authorize: https://app.nex.toa.io/oauth/authorize
+        resources: ['/mcp/']
+        registration: open
+      /:
+        io:output: true
+        /mcp/**:
+          anyone: true
+          GET:
+            dev:stub: Tools
+      """
+    When the following request is received:
+      """
+      POST /identity/clients/ HTTP/1.1
+      host: nex.toa.io
+      content-type: application/yaml
+      accept: application/yaml
+
+      client_name: Claude
+      redirect_uris:
+        - https://claude.ai/api/mcp/auth_callback
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+
+      client_id: ${{ client }}
+      """
+    When the following request is received:
+      """
+      POST /identity/grants/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      content-type: application/yaml
+      accept: application/yaml
+
+      client: ${{ client }}
+      redirect: https://claude.ai/api/mcp/auth_callback
+      challenge: E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
+      method: S256
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+      cache-control: no-store
+
+      code: ${{ code }}
+      expires_in: 60
+      """
+
+  Scenario: A client comes back with the token it was given
+    # nothing yet, and the client is told where to get one
+    When the following request is received:
+      """
+      GET /mcp/tools/ HTTP/1.1
+      host: nex.toa.io
+      accept: text/plain
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      www-authenticate: Bearer resource_metadata="https://nex.toa.io/.well-known/oauth-protected-resource/mcp"
+      """
+    When the following request is received:
+      """
+      POST /identity/grants/ HTTP/1.1
+      host: nex.toa.io
+      content-type: application/x-www-form-urlencoded
+      accept: application/yaml
+
+      grant_type=authorization_code&code=${{ code }}&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk&redirect_uri=https%3A%2F%2Fclaude.ai%2Fapi%2Fmcp%2Fauth_callback&client_id=${{ client }}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      cache-control: no-store
+
+      access_token: ${{ access_token }}
+      token_type: Bearer
+      """
+    When the following request is received:
+      """
+      GET /mcp/tools/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer ${{ access_token }}
+      accept: text/plain
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      Tools
+      """
+
+  Scenario: A code is spent once
+    When the following request is received:
+      """
+      POST /identity/grants/ HTTP/1.1
+      host: nex.toa.io
+      content-type: application/x-www-form-urlencoded
+      accept: application/yaml
+
+      grant_type=authorization_code&code=${{ code }}&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """
+    When the following request is received:
+      """
+      POST /identity/grants/ HTTP/1.1
+      host: nex.toa.io
+      content-type: application/x-www-form-urlencoded
+      accept: application/yaml
+
+      grant_type=authorization_code&code=${{ code }}&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
+      """
+    Then the following reply is sent:
+      """
+      400 Bad Request
+
+      error: invalid_grant
+      """
+
+  Scenario: A verifier that did not make that challenge
+    When the following request is received:
+      """
+      POST /identity/grants/ HTTP/1.1
+      host: nex.toa.io
+      content-type: application/x-www-form-urlencoded
+      accept: application/yaml
+
+      grant_type=authorization_code&code=${{ code }}&code_verifier=this-is-not-the-verifier-that-made-that-challenge
+      """
+    Then the following reply is sent:
+      """
+      400 Bad Request
+
+      error: invalid_grant
+      """
+    # the code was spent trying, so guessing at it buys nothing
+    When the following request is received:
+      """
+      POST /identity/grants/ HTTP/1.1
+      host: nex.toa.io
+      content-type: application/x-www-form-urlencoded
+      accept: application/yaml
+
+      grant_type=authorization_code&code=${{ code }}&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
+      """
+    Then the following reply is sent:
+      """
+      400 Bad Request
+
+      error: invalid_grant
+      """
+
+  Scenario: A redirect swapped between authorizing and exchanging
+    When the following request is received:
+      """
+      POST /identity/grants/ HTTP/1.1
+      host: nex.toa.io
+      content-type: application/x-www-form-urlencoded
+      accept: application/yaml
+
+      grant_type=authorization_code&code=${{ code }}&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk&redirect_uri=https%3A%2F%2Fevil.example%2Fcallback
+      """
+    Then the following reply is sent:
+      """
+      400 Bad Request
+
+      error: invalid_grant
+      """
+
+  Scenario: A grant nobody may be sent a code for
+    When the following request is received:
+      """
+      POST /identity/grants/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      content-type: application/yaml
+      accept: application/yaml
+
+      client: ${{ client }}
+      redirect: https://evil.example/callback
+      challenge: E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
+      method: S256
+      """
+    Then the following reply is sent:
+      """
+      400 Bad Request
+
+      error: invalid_request
+      """
+
+  Scenario: A challenge method that proves nothing
+    When the following request is received:
+      """
+      POST /identity/grants/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      content-type: application/yaml
+      accept: application/yaml
+
+      client: ${{ client }}
+      redirect: https://claude.ai/api/mcp/auth_callback
+      challenge: E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
+      method: plain
+      """
+    Then the following reply is sent:
+      """
+      400 Bad Request
+
+      error: invalid_request
+      """
+
+  Scenario: A grant only its own identity may see
+    When the following request is received:
+      """
+      GET /identity/grants/00000000000000000000000000000000/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      403 Forbidden
+      """
+
+  Scenario: Taking back what was allowed
+    When the following request is received:
+      """
+      POST /identity/grants/ HTTP/1.1
+      host: nex.toa.io
+      content-type: application/x-www-form-urlencoded
+      accept: application/yaml
+
+      grant_type=authorization_code&code=${{ code }}&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      access_token: ${{ access_token }}
+      """
+    When the following request is received:
+      """
+      GET /identity/grants/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      - id: ${{ grant }}
+        client: ${{ client }}
+      """
+    When the following request is received:
+      """
+      DELETE /identity/grants/efe3a65ebbee47ed95a73edd911ea328/${{ grant }}/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      """
+    Then the following reply is sent:
+      """
+      204 No Content
+      """

package/features/steps/Gateway.ts

@@ -29,7 +29,7 @@ export class Gateway {
       process.env.TOA_EXPOSITION = JSON.stringify(tree)
     }
 
-    const { debug, authorities, bouncer, ip } = annotation
+    const { debug, authorities, bouncer, ip, oauth } = annotation
     const properties = Object.assign({}, DEFAULT_PROPERTIES)
 
     if (debug !== undefined)
@@ -44,6 +44,9 @@ export class Gateway {
     if (authorities !== undefined)
       properties.authorities = authorities
 
+    if (oauth !== undefined)
+      properties.oauth = oauth
+
     process.env.TOA_EXPOSITION_PROPERTIES = JSON.stringify(properties)
 
     await Gateway.stop()
@@ -215,6 +218,8 @@ const DEFAULT_CONFIGURATION: Record<string, object> = {
   // features do not run; the variable is the local override that stands in for it
   'realtime.streams': {},
   'identity.basic': {},
+  'identity.clients': {},
+  'identity.grants': {},
   'identity.federation': {},
   'identity.otp': {},
   'identity.passkeys': {},

package/features/steps/Parameters.ts

@@ -16,6 +16,10 @@ setDefaultTimeout(60 * 1000)
 
 process.env.TOA_DEV = '1'
 
+// a reply is checked against what the operation declares, so the suite runs Toa under the
+// contract it asks applications to keep
+process.env.TOA_ENV ??= 'local'
+
 // the gateway answers for itself, as it does in a deployment: telemetry's probe tracks the
 // nested composition, which connects before route discovery settles
 process.env.TOA_TELEMETRY_READY ??= JSON.stringify(false)

package/features/steps/components/echo/manifest.toa.yaml

@@ -54,3 +54,5 @@ operations:
       properties:
         buf:
           type: string
+  error:
+    errors: [CODE]

package/features/steps/components/octets.tester/manifest.toa.yaml

@@ -5,6 +5,7 @@ storages: octets
 
 operations:
   foo: &operation
+    errors: [ERROR, NOT_FOUND]
     input:
       properties:
         identity:
@@ -38,6 +39,7 @@ operations:
   authority: *operation
   identity: *operation
   redirect:
+    errors: [ERROR]
     input:
       properties:
         parameters: