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

package/documentation/consent.md

@@ -0,0 +1,101 @@
+# Consent
+
+The one endpoint of the [authorization server](oauth.md) that needs a person, and so the one this
+extension does not serve. An application serves it at the URL its `exposition.oauth.authorize`
+names.
+
+The page is reached by a client opening it in the user's browser. It authenticates the user, shows
+them who is asking, and on their assent redirects back to the client with a code.
+
+## What the page receives
+
+```
+GET https://app.example.com/oauth/authorize
+  ?response_type=code
+  &client_id=https%3A%2F%2Fclaude.ai%2Foauth%2Fclaude-code-client-metadata
+  &redirect_uri=http%3A%2F%2Flocalhost%3A3118%2Fcallback
+  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
+  &code_challenge_method=S256
+  &state=af0ifjsldkj
+  &resource=https%3A%2F%2Fapi.example.com%2Fmcp
+  &scope=app:notes
+```
+
+`state` is the client's and is returned untouched. `code_challenge`, `code_challenge_method`,
+`client_id`, `redirect_uri` and `resource` are passed on as they arrived.
+
+## What the page does
+
+The user is authenticated by whatever means the application already offers. The page then holds
+that identity's own `Token`, and makes two calls with it.
+
+Who is asking:
+
+```http
+GET /identity/clients/https%3A%2F%2Fclaude.ai%2Foauth%2Fclaude-code-client-metadata/ HTTP/1.1
+authorization: Token …
+```
+
+```yaml
+client_id: https://claude.ai/oauth/claude-code-client-metadata
+client_name: Claude Code
+client_uri: https://claude.ai
+logo_uri: https://claude.ai/logo.png
+redirect_uris: [http://localhost/callback, http://127.0.0.1/callback]
+```
+
+The page displays `client_name`, and **the host of `redirect_uri`**. A loopback redirect is
+indistinguishable from any other local process, so the user is told where the code will be sent.
+
+On assent:
+
+```http
+POST /identity/grants/:identity/ HTTP/1.1
+authorization: Token …
+content-type: application/json
+
+{"client": "…", "redirect": "…", "challenge": "…", "method": "S256",
+ "scope": ["app:notes"], "resource": ["https://api.example.com/mcp"]}
+```
+
+```http
+201 Created
+cache-control: no-store
+
+{"code": "SplxlOBeZQQYbYS6WxSbIA", "expires_in": 60}
+```
+
+`:identity` is the id of the identity that consents, which is the one the page authenticated.
+
+## What the page answers
+
+On assent, a redirect carrying the code, the client's `state`, and the issuer:
+
+```
+302 Found
+location: http://localhost:3118/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkj&iss=https%3A%2F%2Fapi.example.com
+```
+
+A single-page application does this with `location.assign`; nothing requires a server redirect.
+
+`iss` is [RFC 9207](https://www.rfc-editor.org/rfc/rfc9207), and the metadata declares that it is
+sent, so a client rejects a response without it. Its value is the `issuer` of
+`/.well-known/oauth-authorization-server`, which the page may read.
+
+On refusal, a redirect saying so, not an error page:
+
+```
+302 Found
+location: http://localhost:3118/callback?error=access_denied&state=af0ifjsldkj&iss=https%3A%2F%2Fapi.example.com
+```
+
+## Errors
+
+`400` with `error` and `error_description` is answered when the client is unknown, when the
+redirect is not one that client may receive a code at, or when the challenge method is not `S256`.
+A redirect that was not registered must not be redirected to; the page states the refusal itself.
+
+## Consent is asked every time
+
+A grant is recorded, and `GET /identity/grants/:identity/` lists what a user allowed, but it is
+not consulted to skip this page.

package/documentation/identity.md

@@ -83,7 +83,9 @@ the request path.
 
 ### Bearer scheme
 
-OpenID tokens issued by trusted providers.
+OpenID tokens issued by trusted providers, and access tokens issued by
+[this authorization server](oauth.md) to OAuth clients. Both are presented the same way, and each
+provider says which credentials are its own; a credential neither claims is refused.
 For more information, refer
 to [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html),
 [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750).

package/documentation/io.md

@@ -1,7 +1,7 @@
 # I/O restrictions
 
 The Exposition comes with `io` directives to control access to the operation's input and output
-properties.
+properties, and to let an operation state the status of its reply.
 
 ## Input
 
@@ -53,7 +53,41 @@ GET:
   io:output: false
 ```
 
-Output restrictions are not applied to stream responses and errors.
+Output restrictions are not applied to stream responses, nor to a reply the gateway built out of an
+exception — an operation that returns an error is answered with a code and a message of the
+gateway's own, and a list of permitted properties has nothing to say about those. A reply the
+operation returned is restricted whatever status it carries, see [Status](#status).
+
+## Status
+
+The `io:status` optional directive names a property of the reply that carries the status of the
+response. The property is removed from the body.
+
+```yaml
+POST:
+  endpoint: register
+  io:status: status
+  io:output: [client_id, client_name, error, error_description]
+```
+
+```javascript
+return { status: 400, error: 'invalid_redirect_uri' }
+```
+
+```http
+400 Bad Request
+
+error: invalid_redirect_uri
+```
+
+A reply that does not carry the property is answered with the status it would have been. A property
+that is not a number is an error.
+
+This is for an outcome the operation knows and the transport does not — a protocol that states its
+error as a body rather than as a status of its own, or a request that created where it might have
+updated. Such an operation returns no error: both replies are its output, and `io:output` permits
+the properties of both. An operation that does return an error is unaffected — that reply is the
+gateway's, and is not restricted.
 
 ## Throttling
 

package/documentation/oauth.md

@@ -0,0 +1,179 @@
+# OAuth 2.1 Authorization Server
+
+An application exposes an authorization server by annotating one, and none without it. A client
+authorized this way holds a token of the identity that consented, and presents it as `Bearer`.
+
+## Annotation
+
+```yaml
+exposition:
+  authorities:
+    local: api.example.com
+  oauth:
+    authorize: https://app.example.com/oauth/authorize
+    resources: ['/mcp/']
+    scopes: [app:notes, app:notes:read]
+    registration: closed
+```
+
+<dl>
+<dt><code>authorize</code></dt>
+<dd>Required. The absolute URL of the consent page. The application serves it; see
+<a href="consent.md">Consent</a>.</dd>
+<dt><code>resources</code></dt>
+<dd>Paths advertised as protected resources, each with a document of its own and named by the
+challenge a request to it is refused with. A token is not yet bound to one, see
+<a href="#audience">Audience</a>.</dd>
+<dt><code>scopes</code></dt>
+<dd>Advertised as what a client may ask for. Each is a <a href="access.md#roles">role</a>, or a
+scope within one.</dd>
+<dt><code>registration</code></dt>
+<dd><code>open</code> advertises the registration endpoint, <code>closed</code> does not.
+Defaults to <code>closed</code>.</dd>
+</dl>
+
+The issuer is the authority's configured host, over `https` unless the host is a loopback one.
+
+## Discovery
+
+Two documents are served, at the paths their specifications fix, to anyone.
+
+`/.well-known/oauth-authorization-server` is
+[RFC 8414](https://www.rfc-editor.org/rfc/rfc8414) metadata:
+
+```yaml
+issuer: https://api.example.com
+authorization_endpoint: https://app.example.com/oauth/authorize
+token_endpoint: https://api.example.com/identity/grants/
+registration_endpoint: https://api.example.com/identity/clients/
+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
+```
+
+`/.well-known/oauth-protected-resource` is
+[RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) metadata. Each configured resource has one of
+its own, at the path the well-known segment is followed by: `/mcp/` is read at
+`/.well-known/oauth-protected-resource/mcp`.
+
+```yaml
+resource: https://api.example.com/mcp
+authorization_servers: [https://api.example.com]
+bearer_methods_supported: [header]
+```
+
+`/.well-known/openid-configuration` answers with the authorization server metadata, for a client
+that reads only that.
+
+A reply of `401` carries the challenge that names the document:
+
+```http
+401 Unauthorized
+www-authenticate: Bearer resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp", scope="app:notes"
+```
+
+## Clients
+
+A `client_id` that is an `https` URL is a
+[Client ID Metadata Document](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-00):
+the client publishes what it is at that URL, and the document is read from there. Only origins
+`identity.clients` is configured to trust are read, and an empty list reads none:
+
+```yaml
+configuration:
+  identity.clients:
+    trust:
+      - https://claude.ai
+```
+
+Anything else was registered through
+[RFC 7591](https://www.rfc-editor.org/rfc/rfc7591), which `registration: open` advertises:
+
+```http
+POST /identity/clients/ HTTP/1.1
+content-type: application/json
+
+{"client_name": "Claude", "redirect_uris": ["https://claude.ai/api/mcp/auth_callback"]}
+```
+
+```http
+201 Created
+
+{"client_id": "c8f3a1e4d8c9b2f6a0e5d7c3b1a9f8e2", "client_name": "Claude", …}
+```
+
+A registration is addressed by a hash of what it says, so the same metadata is one client however
+many times it arrives. A registration cannot be changed: a revision is a different client.
+
+Only public clients are supported. `token_endpoint_auth_method` other than `none` is refused.
+
+`redirect_uris` are matched exactly, except for a loopback address, where the port is ignored
+([RFC 8252 §7.3](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3)).
+
+`GET /identity/clients/:id/` returns a client to any authenticated identity, which is what the
+consent page reads.
+
+## Token endpoint
+
+`POST /identity/grants/`, anonymous, `application/x-www-form-urlencoded`.
+
+```http
+POST /identity/grants/ HTTP/1.1
+content-type: application/x-www-form-urlencoded
+
+grant_type=authorization_code&code=SplxlO&code_verifier=dBjftJeZ&redirect_uri=…&client_id=…
+```
+
+```http
+200 OK
+cache-control: no-store
+
+{"access_token": "…", "token_type": "Bearer", "expires_in": 2592000}
+```
+
+`code_verifier` is required: the code was issued against its `S256` hash
+([RFC 7636](https://www.rfc-editor.org/rfc/rfc7636)). A code may be redeemed once, and is spent
+whether or not the verifier matches. Every refusal is `invalid_grant`.
+
+A code is valid for `identity.grants.lifetime` seconds, 60 by default. A token is valid for
+`identity.grants.token` seconds, 30 days by default; `0` is until it is revoked.
+
+## Grants
+
+A grant is what a user allowed a client. One is held per identity per client.
+
+`GET /identity/grants/:identity/` lists them. `DELETE /identity/grants/:identity/:id/` revokes one,
+which disables the key its token was issued under: the token stops being one within
+`identity.tokens.cache.ttl`.
+
+## Tokens
+
+An access token is a token of the identity that consented, carrying the
+[roles](access.md#roles) that identity holds, or the subset the client asked for as `scope`. It is
+presented as `Bearer`, which `identity.federation` also answers to — see
+[Bearer scheme](identity.md#bearer-scheme).
+
+A `scope` a client asks for is not checked against `scopes_supported`: it is granted if the
+consenting identity holds it, and refused as `invalid_scope` otherwise. What is advertised says
+what an application means to offer, not what the server will refuse.
+
+## Audience
+
+`resource` ([RFC 8707](https://www.rfc-editor.org/rfc/rfc8707)) is accepted at both endpoints and
+recorded on the grant. **It does not yet restrict the token.** An access token carries the rights
+of the identity that consented, over every path that identity may reach, whichever resource it was
+asked for.
+
+Restricting it is a `permissions` argument at the `identity.tokens.issue` call in
+`identity.grants.exchange` — `{'/mcp/**': ['*']}` for a resource at `/mcp/` — enforced by
+`permits()`, which is already what reads a token's permissions on every request. It waits on the
+resource that will check the audience itself.
+
+## References
+
+- [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1)
+- [Consent](consent.md), the page an application serves
+- [Features](../features/oauth.grants.feature)

package/documentation/protocol.md

@@ -9,6 +9,10 @@ The following media types are supported for both requests and responses:
 - `application/msgpack` using [msgpackr](https://github.com/kriszyp/msgpackr)
 - `text/plain`
 
+A request may also be sent as `application/x-www-form-urlencoded`. A form is read and never
+written, so it is not a format a response is negotiated to. A name repeated in a form is read as
+the list it is.
+
 The response format is determined by content negotiation
 using [negotiator](https://github.com/jshttp/negotiator).
 

package/features/auth.bearer.feature

@@ -0,0 +1,120 @@
+@security
+Feature: More than one provider claims Bearer
+
+  An OpenID `id_token` and a token this gateway issued are both presented as `Bearer`,
+  and only their own provider can verify either. The gateway asks each in turn.
+
+  Background:
+    Given local IDP is running
+    And the `identity.basic` database contains:
+      | _id                              | authority | username  | password                                                     |
+      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
+    And the annotation:
+      """yaml
+      /:
+        io:output: true
+        /hello/:id:
+          auth:id: id
+          GET:
+            dev:stub: Hello
+      """
+
+  Scenario: A token this gateway issued is presented as Bearer
+    When the following request is received:
+      """
+      GET /hello/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: text/plain
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      authorization: Token ${{ token }}
+      content-type: text/plain
+
+      Hello
+      """
+    When the following request is received:
+      """
+      GET /hello/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer ${{ token }}
+      accept: text/plain
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: text/plain
+
+      Hello
+      """
+    # the token was answered by its own provider, so nothing rotates it
+    And the reply does not contain:
+      """
+      authorization: Token
+      """
+
+  Scenario: A Bearer this gateway did not issue is answered by federation
+    Given the IDP token for Stranger is issued
+    When the following request is received:
+      """
+      GET /hello/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer ${{ Stranger.id_token }}
+      accept: text/plain
+      """
+    # `identity.tokens` declines it, and federation rejects an issuer it does not trust
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      """
+
+  Scenario: A malformed Bearer is rejected, not an error
+    When the following request is received:
+      """
+      GET /hello/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer not.a.token
+      accept: text/plain
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      """
+
+  Scenario: Both kinds of Bearer against one authority
+    Given the `identity.federation` configuration:
+      """yaml
+      trust:
+        - iss: http://localhost:44444
+          aud: test
+      """
+    And the IDP token for User is issued
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer ${{ User.id_token }}
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      authorization: Token ${{ federated }}
+
+      id: ${{ User.id }}
+      """
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer ${{ federated }}
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      id: ${{ User.id }}
+      """

package/features/cache.feature

@@ -320,3 +320,49 @@ Feature: Caching
       200 OK
       cache-control: private, no-cache
       """
+
+  Scenario: An exact value is set whatever the method
+    Given the annotation:
+      """yaml
+      /:
+        io:output: true
+        /tokens/:
+          anonymous: true
+          cache:exact: no-store
+          POST:
+            dev:stub: issued
+      """
+    When the following request is received:
+      """
+      POST /tokens/ HTTP/1.1
+      host: nex.toa.io
+      accept: text/plain
+      """
+    # whether a reply may be stored is not a question about the method's cacheability
+    Then the following reply is sent:
+      """
+      201 Created
+      cache-control: no-store
+      """
+
+  Scenario: Cacheability is still asked of safe methods only
+    Given the annotation:
+      """yaml
+      /:
+        io:output: true
+        /notes/:
+          anonymous: true
+          cache:control: max-age=60000, public
+          POST:
+            dev:stub: created
+      """
+    When the following request is received:
+      """
+      POST /notes/ HTTP/1.1
+      host: nex.toa.io
+      accept: text/plain
+      """
+    Then the reply does not contain:
+      """
+      cache-control:
+      """