@toa.io/extensions.exposition 1.0.0-alpha.29 → 1.0.0-alpha.291

package/features/methods.feature

@@ -0,0 +1,48 @@
+Feature: Supported methods
+
+  Scenario Outline: <method> is supported
+    Given the annotation:
+      """yaml
+      /:
+        <method>:
+          dev:stub:
+            hello: world
+      """
+    And the `greeter` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          <method>:
+            dev:stub:
+              hello: world
+      """
+    Examples:
+      | method |
+      | GET    |
+      | POST   |
+      | PUT    |
+      | DELETE |
+      | PATCH  |
+      | LOCK   |
+      | UNLOCK |
+
+  Scenario: CORS allowed methods
+    Given the annotation:
+      """yaml
+      /:
+        GET:
+          dev:stub:
+            hello: world
+      """
+    When the following request is received:
+      """
+      OPTIONS / HTTP/1.1
+      access-control-request-method: GET
+      host: nex.toa.io
+      origin: https://hello.world
+      """
+    Then the following reply is sent:
+      """
+      204 No Content
+      access-control-allow-methods: GET, POST, PUT, PATCH, DELETE, LOCK, UNLOCK, OPTIONS
+      """

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,164 @@
+@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]
+      mcp:
+        name: Teapots
+      """
+
+  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:
+      """
+      POST /.mcp HTTP/1.1
+      host: nex.toa.io
+      accept: text/plain
+      content-type: application/json
+
+      {"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}
+      """
+    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,301 @@
+@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
+      mcp:
+        name: Teapots
+      /:
+        io:output: true
+        /pots:
+          anyone: true
+          GET:
+            mcp:tool: true
+            help:method:
+              description: Every pot there is.
+            dev:stub: Kettles and teapots.
+      """
+    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:
+      """
+      POST /.mcp HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/json
+
+      {"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}
+      """
+    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:
+      """
+      POST /.mcp HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer ${{ access_token }}
+      accept: application/yaml
+      content-type: application/json
+
+      {"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      jsonrpc: '2.0'
+      id: 1
+      result:
+        tools:
+          - name: pots.GET
+      """
+
+  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
+      """