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

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/introspection.md

@@ -1,14 +1,21 @@
 # Resource introspection
 
 Any resource can be introspected by sending an `OPTIONS` request to the resource's path.
-The response will contain the resource's input and output schemas for each supported method.
+
+What it answers is what the route's directives leave of what the operation declared, for each
+method the request may reach. A method it may not is not there, nor in `Allow`; a resource whose
+every method it may not reach is `403`.
 
 Introspection properties:
 
-- `route` route parameters
+- `description` what the route states this method is, from [`mcp:tool`](mcp.md#what-a-tool-is).
+  The operation states what it is too, and that is not this: it is written without knowledge of
+  any route, and the same operation mounted twice is two methods
+- `route` route parameters, including what `map:segments` names differently
 - `query` query parameters
-- `input` input schema
-- `output` output schema
+- `headers` properties `map:headers` reads from a request header, and which header
+- `input` input schema, restricted by `io:input`, without what the gateway fills itself
+- `output` output schema, restricted by `io:output`; absent where the reply is not sent at all
 - `errors` error codes
 
 ```http
@@ -18,9 +25,10 @@ accept: application/yaml
 
 ```http
 200 OK
-Allow: GET, POST, OPTIONS
+Allow: GET, POST
 
 GET:
+  description: Every pot there is, newest first.
   route:
     id:
       type: string

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
 
@@ -125,3 +159,9 @@ io:throttle:
 
 An address may probe for twenty missing paths at once, and thereafter for one every thirty seconds.
 Requests that find something are served and never counted against it.
+
+## Introspection
+
+What these admit is what [`OPTIONS`](introspection.md) states: `io:input` restricts the input
+schema, `io:output` the output schema, and a method declaring no `io:output` states no output at
+all — nothing of the reply is sent.

package/documentation/map.md

@@ -113,3 +113,11 @@ the names of the claims.
 
 If the claim is not present in the token or the request is not authenticated using
 the [`Bearer` scheme](identity.md#bearer-scheme), the input properties are not set.
+
+## Introspection
+
+A property a mapping fills is not the caller's to send, so [`OPTIONS`](introspection.md) takes it
+out of the input. `map:headers` states it under `headers`, naming the header it is read from, and
+`map:segments` under `route`, named as the property rather than as the segment. The rest —
+`map:claims`, `map:authority`, `map:language`, `map:buffer` — come from the request itself, and a
+caller has nowhere to put one.

package/documentation/mcp.md

@@ -0,0 +1,180 @@
+# Model Context Protocol
+
+An application annotates it, and the methods it names as tools are what a model may call.
+
+```yaml
+exposition:
+  mcp:
+    name: Teapots
+    instructions: A pot is read by its id. A pot that is brewing cannot be emptied.
+    origins: [https://claude.ai]
+```
+
+<dl>
+<dt><code>name</code></dt>
+<dd>Required. What the server calls itself, which a client shows a user.</dd>
+<dt><code>instructions</code></dt>
+<dd>What a model is told before it calls anything here.</dd>
+<dt><code>origins</code></dt>
+<dd>Browser origins the endpoint answers. A request carrying an <code>Origin</code> that is not
+listed is <code>403</code>, and an empty list admits none; a request carrying none is unaffected.</dd>
+<dt><code>anonymous</code></dt>
+<dd>Whether the endpoint answers without a credential. It does not unless it says so.</dd>
+</dl>
+
+Without the annotation `/.mcp` is a path like any other, and nothing answers there. The path is
+fixed: one an application could choose is one it could collide with a route of its own.
+
+## What a tool is
+
+A tool is an RTD method that says it is one, named as the [procedure](rpc.md#the-name) it is:
+
+```yaml
+/pots:
+  GET:
+    mcp:tool: Every pot there is, newest first.
+    endpoint: enumerate
+  /hot:
+    GET:
+      query: { criteria: temperature=gt=80 }
+      mcp:tool: The pots that are too hot to pour.
+      endpoint: enumerate
+```
+
+A default denies, and a tree holds everything an application serves — its identity endpoints, its
+uploads, the machinery of the authorization flow the model already came through. Publishing all of
+it would spend a model's context on what it has no business calling.
+
+The value is what the tool is, and stating it is what publishes it — there is no way to publish one
+that says nothing, because a tool a model cannot read the purpose of is one it cannot choose.
+
+An operation [states what it is](/documentation/component/declaration.md) as well, and that is not
+this: it is written without knowledge of any route, and a tool is an operation and a route together.
+The two routes above are one operation and two tools, and one sentence is not true of both. The
+operation's own is the Introspection's to read, and the gateway does not use it.
+
+A declaration is inherited by everything below it, as every directive is, and the nearer one wins.
+Since what it carries is what one method is, it belongs on a method: a node stating one would say
+the same thing of everything under it.
+
+A route whose name a client [cannot spell](rpc.md#what-has-a-name) is refused where the directive
+is built, rather than served as a tool that is quietly never listed.
+
+`tools/list` answers every published method this caller may reach — a method whose directives refuse
+them is not listed, and a route with [no name](rpc.md#what-has-a-name) is not either. `tools/call`
+answers `404` to a name that is not published, whether or not a route would have taken it: what an
+application did not publish is not reachable by guessing what it would have been called.
+
+`annotations` are read from the verb: `GET` and `HEAD` are `readOnlyHint`, `DELETE` is
+`destructiveHint`, `PUT` and `DELETE` are `idempotentHint`.
+
+## What a tool takes
+
+`inputSchema` is the procedure's `params`, which is what the method
+[says of itself](introspection.md): a route variable by the name the template gives it, the
+querystring under `query`, and what is left is the body. `io:input` restricts it, and a property
+`map` fills is not there — a call carries no headers of its own.
+
+```yaml
+type: object
+properties:
+  id: { type: string, pattern: ^[a-fA-F0-9]{32}$ }
+  query:
+    type: object
+    properties:
+      criteria: { type: string }
+      sort: { type: string }
+      limit: { type: integer, minimum: 1, maximum: 100, default: 10 }
+      omit: { type: integer, minimum: 0, maximum: 1000, default: 0 }
+required: [id]
+additionalProperties: false
+```
+
+## What a tool answers
+
+`content` carries one `text` block holding the reply's JSON, and `structuredContent` the reply
+itself. A reply of nothing is an empty `content`.
+
+`outputSchema` is what the operation declares, restricted by `io:output`. An operation's `output` is
+optional and normalizes to `{}`, which describes nothing, and none is stated for it — an
+application that wants the schema declares the operation's `output`.
+
+An operation that refuses answers a result with `isError: true` carrying its message, not an error
+of the protocol: it is something a model reads and may correct itself by.
+
+## Two revisions
+
+Both are answered from one endpoint that remembers nothing between requests.
+[`2026-07-28`](https://modelcontextprotocol.io/specification/2026-07-28) carries the version and
+the client's capabilities in every request; `2025-11-25` opens with `initialize`. Which one a
+request is, is read from `MCP-Protocol-Version`, or from
+`_meta['io.modelcontextprotocol/protocolVersion']` where the header is absent; `initialize` is one
+by itself, and a request naming no version is of a revision that sent none.
+
+| method | |
+| --- | --- |
+| `server/discover` | what is served, and who serves it |
+| `tools/list` | every tool this caller may reach, in a stable order |
+| `tools/call` | the call the tool is |
+| `initialize` | the same as `server/discover`, in the shape a client of `2025-11-25` reads |
+| `notifications/initialized` | `202`, and nothing done |
+| `ping` | `{}` |
+
+`POST` only, one message per request; `GET` and `DELETE` are `405`. An `Mcp-Session-Id` is ignored
+and none is minted, a `Last-Event-ID` is ignored, and `accept` is negotiated as everywhere else.
+
+Of the modern revision, `MCP-Protocol-Version` and `Mcp-Method` are required, and `Mcp-Name` for a
+`tools/call`; each must say what the body says. `_meta` states the protocol version and the client's
+capabilities. Every result carries `resultType` and names the server in its own `_meta`, and a
+`server/discover` or a `tools/list` carries how long it may be held: half an hour, `public` for the
+first and `private` for the second, which is filtered by the identity that asked.
+
+Neither `listChanged` nor a subscription is declared: both are a stream held open, and this endpoint
+holds none.
+
+## Authorization
+
+The endpoint is a protected resource, and an application advertises it as one:
+
+```yaml
+exposition:
+  oauth:
+    authorize: https://app.example.com/oauth/authorize
+    resources: ['/.mcp']
+```
+
+Its RFC 9728 document is then read at `/.well-known/oauth-protected-resource/.mcp`, and the
+canonical URI of the resource is `https://api.example.com/.mcp`. See [OAuth](oauth.md).
+
+A request without a credential is `401`, carrying the challenge that names that document — which is
+where the flow starts. A call the identity is not authorized to make is `403` with
+`error="insufficient_scope"`. Each tool is authorized as the resource it is, against the path and
+the verb its name states.
+
+A route that is [`anonymous`](access.md#anonymous) is reached here whatever the client presented:
+the rule that refuses a credentialed request is about a cacheable reply, and what a tool answers is
+not one. So a resource that is public over HTTP is a public tool, and nothing in a manifest has to
+say it twice.
+
+## What refuses
+
+| | |
+| --- | --- |
+| `-32700` | the body is not readable |
+| `-32600` | the body is not one JSON-RPC message |
+| `-32601` | no method of that name, at `404` |
+| `-32602` | the arguments do not fit, or `_meta` states too little |
+| `-32603` | anything the gateway did not mean to answer |
+| `-32020` | a header says one thing and the body another |
+| `-32022` | a revision neither served, naming both |
+
+The codes MCP reserves for itself are `-32020` to `-32099`, and it has an implementation use none of
+`-32000` to `-32019` — which is where [JSON-RPC](rpc.md#what-refuses) has this gateway's own, so none
+of those is answered here.
+
+## References
+
+- [The specification](https://modelcontextprotocol.io/specification/2026-07-28)
+- [JSON-RPC](rpc.md), where a procedure gets its name
+- [Introspection](introspection.md), which is what a tool's schemas are
+- [Features](../features/mcp.feature)

package/documentation/oauth.md

@@ -0,0 +1,180 @@
+# 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. <code>/.mcp</code> is where
+<a href="mcp.md">MCP</a> is served. 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).