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

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

@@ -14,26 +14,32 @@ directives under the current RTD Node.
   octets:context: images
 ```
 
-## `octets:store`
+## `octets:put`
 
 Stores the content of the request body into a storage, under the request path with
 specified `content-type`.
 
 If request's `content-type` is not acceptable, or if the request body does not pass
-the [validation](/extensions/storages/readme.md#async-putpath-string-stream-readable-type-typecontrol-maybeentry),
+the [validation](/extensions/storages/readme.md#async-putpath-string-stream-readable-options-options-maybeentry),
 the request is rejected with a `415 Unsupported Media Type` response.
 
-The value of the directive is `null` or an object with the following properties:
+The value of the directive must be `null` (defaults) or an object with the following optional
+properties:
 
+- `location`: a string that represents the path to store the
+  content.
+  If not specified, the path is the same as the request path.
+- `limit`: [maximum size](#stream-size-limit) of the incoming stream.
 - `accept`: a media type or an array of media types that are acceptable.
   If the `accept` property is not specified, any media type is acceptable (which is the default).
 - `workflow`: [workflow](#workflows) to be executed once the content is successfully stored.
+- `trust`: a list of [trusted origins](#downloading-external-content).
 
 ```yaml
 /images:
   octets:context: images
   POST:
-    octets:store:
+    octets:put:
       accept:
         - image/jpeg
         - image/png
@@ -43,31 +49,97 @@ The value of the directive is `null` or an object with the following properties:
         analyze: images.analyze
 ```
 
-Non-standard `content-meta` header can be used
+### Headers
+
+`content-id` header can be used to set the ID of the Entry.
+The value must match the following regular expression `^[a-zA-Z0-9-_]{1,16}$`.
+
+Non-standard `content-attributes` header can be used
 to set initial [metadata](/extensions/storages/readme.md#entry) value for the Entry.
 
-The value of the `content-meta` header is a comma-separated list of key-value string pairs.
+The value of the `content-attributes` header is a comma-separated list of key-value string pairs.
 If no value is provided for a key, the string `true` is used.
 
 ```http
 POST /images/ HTTP/1.1
 content-type: image/jpeg
-content-meta: foo, bar=baz
-content-meta: baz=1
+content-id: example-id
+content-attributes: foo, bar=baz
+content-attributes: baz=1
 ```
 
 ```yaml
-meta:
+attributes:
   foo: 'true'
   bar: 'baz'
   baz: '1'
 ```
 
-If the Entry already exists, the `content-meta` header is ignored.
+If the Entry already exists, the `content-attributes` header is ignored.
+
+### Location
+
+The `location` property can be used to store the content under a different path.
+
+```yaml
+/images:
+  octets:context: images
+  POST:
+    octets:put:
+      location: /archive
+```
+
+Physical storage path is constructed by resolving the `location`
+property [relative](https://datatracker.ietf.org/doc/html/rfc3986#section-5) to the request path.
+
+### Stream size limit
+
+The `limit` property can be used to set the maximum size of the incoming stream in bytes.
+
+The property value can be specified as a number
+(representing bytes) or a string that combines a number with a unit (e.g., `1MB`).
+Both [binary and decimal prefixes](https://en.wikipedia.org/wiki/Binary_prefix) are supported.
+If the prefix or unit is specified _incorrectly_ (e.g., `1mb`),
+it will default to a binary prefix interpretation.
+
+- `1b`, `1B`: 1 byte
+- `1KB`: 1000 bytes
+- `1KiB`: 1024 bytes
+- `1kb`: 1024 bytes
+
+The default value is `64MiB`.
+
+### Downloading external content
+
+The `octets:put` directive can be used to download external content:
+
+```http
+POST /images/ HTTP/1.1
+content-location: https://example.com/image.jpg
+content-length: 0
+```
+
+Requests with `content-location` header must have an empty body (`content-length: 0` header).
+
+Target origin must be allowed by the `trust` property,
+which can contain a list of trusted origins or regular expressions to match the full URL.
+
+URL of the downloaded content is stored in the `origin` property of
+the [Entry](/extensions/storages/readme.md#entry).
+
+```yaml
+/images:
+  octets:context: images
+  POST:
+    octets:put:
+      trust:
+        - https://example.com
+        - ^https://example\.com/[a-z]+\.jpe?g$
+```
 
 ### Response
 
-The response of the `octets:store` directive is the created Entry.
+The response of the `octets:put` directive is the created Entry.
 
 ```
 201 Created
@@ -78,12 +150,13 @@ type: image/jpeg
 created: 1698004822358
 ```
 
-If the `octets:store` directive contains a `workflow`, the response
+If the `octets:put` directive contains a `workflow`, the response
 is [multipart](protocol.md#multipart-types).
 The first part represents the created Entry, which is sent immediately after the BLOB is stored,
 while subsequent parts are results from the workflow endpoints, sent as soon as they are available.
 
-In case a workflow endpoint returns an `Error`, the error part is sent, and the response is closed.
+In case a workflow endpoint returns an `Error`, the error part is sent,
+and the response is closed.
 Error's properties are added to the error part, among with the `step` identifier.
 
 ```
@@ -91,20 +164,53 @@ Error's properties are added to the error part, among with the `step` identifier
 content-type: multipart/yaml; boundary=cut
 
 --cut
+
 id: eecd837c
 type: image/jpeg
 created: 1698004822358
+
 --cut
-optimize: null
+
+step: optimize
+status: completed
+
 --cut
+
+step: resize
 error:
-  step: resize
   code: TOO_SMALL
   message: Image is too small
+status: completed
+
+--cut
+
+step: analyze
+status: exception
+
 --cut--
 ```
 
-## `octets:fetch`
+### What a client is told
+
+`octets:put` says what sending a file takes, where everything else about a method is said —
+[`OPTIONS`](introspection.md) and the [tree](discovery.md):
+
+```yaml
+POST:
+  octets:
+    accept: image/jpeg,image/png
+    limit: 64MiB
+    stream: true
+```
+
+`accept` is absent where the directive names no type, and anything may be sent. `limit` is
+written as the declaration writes it, and is what a `413` reports. `stream` says a workflow runs
+on what was stored, so the reply arrives as parts rather than as one object — the first part is
+the entry.
+
+Reading a file and deleting one say nothing: those requests are what they look like.
+
+## `octets:get`
 
 Fetches the content of a stored BLOB corresponding to the request path, and returns it as the
 response body with the corresponding `content-type`, `content-length`
@@ -116,22 +222,18 @@ The value of the directive is an object with the following properties:
 
 - `meta`: `boolean` indicating whether an Entry is accessible.
   Defaults to `false`.
-- `blob`: `boolean` indicating whether the original BLOB is accessible,
-  [BLOB variant](/extensions/storages/readme.md#async-fetchpath-string-maybereadable) must be
-  specified in the path otherwise.
-  Defaults to `true`.
 
 ```yaml
 /images:
   octets:context: images
   /*:
     GET:
-      octets:fetch:
+      octets:get:
         blob: false # prevent access to the original BLOB
-        meta: true  # allow access to an Entry
+        meta: true # allow access to an Entry
 ```
 
-The `octets:fetch: ~` declaration is equivalent to defaults.
+The `octets:get: ~` declaration is equivalent to defaults.
 
 To access an Entry, the `accept` request header must contain the `octets.entry` subtype
 in
@@ -142,32 +244,6 @@ GET /images/eecd837c HTTP/1.1
 accept: application/vnd.toa.octets.entry+yaml
 ```
 
-## `octets:list`
-
-Lists the entries stored under the request path.
-
-The value of the directive is an object with the following properties:
-
-- `meta`: `boolean` indicating whether the list of Entries is accessible.
-  Defaults to `false`, which means that only entry identifiers are returned.
-
-```yaml
-/images:
-  octets:context: images
-  GET:
-    octets:list:
-      meta: true
-```
-
-The `octets:list: ~` declaration is equivalent to defaults.
-
-To access a list of Entries, the `accept` request header must contain the `octets.entries` subtype:
-
-```http
-GET /images/ HTTP/1.1
-accept: application/vnd.toa.octets.entries+yaml
-```
-
 ## `octets:delete`
 
 Delete the entry corresponding to the request path.
@@ -193,22 +269,6 @@ the entry is deleted.
 
 The error returned by the workflow prevents the deletion of the entry.
 
-## `octets:permute`
-
-Performs
-a [permutation](/extensions/storages/readme.md#async-permutepath-string-ids-string-maybevoid) on the
-entries
-under the request path.
-
-```yaml
-/images:
-  octets:context: images
-  PUT:
-    octets:permute: ~
-```
-
-The request body must be a list of entry identifiers.
-
 ## `octets:workflow`
 
 Execute a [workflow](#workflows) on the entry under the request path.
@@ -227,21 +287,23 @@ A workflow is a list of endpoints to be called.
 The following input will be passed to each endpoint:
 
 ```yaml
+authority: string
 storage: string
 path: string
 entry: Entry
 parameters: Record<string, string> # route parameters
 ```
 
-See [Entry](/extensions/storages/readme.md#entry) and an
-example [workflow step processor](../features/steps/components/octets.tester).
+- [Storages](/extensions/storages/readme.md)
+- [Authorities](authorities.md)
+- Example [workflow step processor](../features/steps/components/octets.tester)
 
 A _workflow unit_ is an object with keys referencing the workflow step identifier, and an endpoint
 as value.
 Steps within a workflow unit are executed in parallel.
 
 ```yaml
-octets:store:
+octets:put:
   workflow:
     resize: images.resize
     analyze: images.analyze
@@ -251,11 +313,22 @@ A workflow can be a single unit, or an array of units.
 If it's an array, the workflow units are executed in sequence.
 
 ```yaml
-octets:store:
+octets:put:
   workflow:
-    - optimize: images.optimize   # executed first
-    - resize: images.resize       # executed second
-      analyze: images.analyze     # executed in parallel with `resize`
+    - optimize: images.optimize # executed first
+    - resize: images.resize # executed second
+      analyze: images.analyze # executed in parallel with `resize`
 ```
 
-If one of the workflow units returns an error, the execution of the workflow is interrupted.
+If one of the workflow units returns or throws an error,
+the execution of the workflow is interrupted.
+
+### Workflow tasks
+
+A workflow unit which value starts with `task:` prefix will be executed as a Task.
+
+```yaml
+octets:put:
+  workflow:
+    optimize: task:images.optimize
+```

package/documentation/passkeys.md

@@ -0,0 +1,11 @@
+# Web Authentication
+
+- [Standard](https://www.w3.org/TR/webauthn-2/)
+- [Features](../features/passkeys.feature)
+- [Credential management](credentials.md#passkeys)
+
+## Origin
+
+The relying party is the client. The origin a passkey is registered under, and the RP ID derived
+from it, come from the request, so a passkey belongs to the origin of the client that registered
+it, and a client on another origin does not see it.

package/documentation/protocol.md

@@ -4,11 +4,15 @@
 
 The following media types are supported for both requests and responses:
 
-- `application/msgpack` using [msgpackr](https://github.com/kriszyp/msgpackr)
-- `application/yaml` using [js-yaml](https://github.com/nodeca/js-yaml)
 - `application/json`
+- `application/yaml` using [js-yaml](https://github.com/nodeca/js-yaml)
+- `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).
 
@@ -26,18 +30,21 @@ foo: bar
 
 ### Multipart types
 
-Multipart responses are endoded using content negotiation,
+Multipart responses are encoded using content negotiation,
 and the `content-type` of the response is set to one of the custom `multipart/` subtypes,
 corresponding to the type of
 the parts:
 
 | Response type       | Part type             |
-|---------------------|-----------------------|
+| ------------------- | --------------------- |
 | `multipart/msgpack` | `application/msgpack` |
 | `multipart/yaml`    | `application/yaml`    |
 | `multipart/json`    | `application/json`    |
 | `multipart/text`    | `text/plain`          |
 
+Multipart responses are started with a text chunk `ACK`, and finished with a text
+chunk `FIN`.
+
 Example:
 
 ```
@@ -49,19 +56,47 @@ accept: application/yaml
 200 OK
 content-type: multipart/yaml; boundary=cut
 
+--cut
+ACK
 --cut
 foo: bar
 --cut
 baz: qux
+--cut
+FIN
 --cut--
 ```
 
 See also:
 
 - [Multipart Content-Type](https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html) at W3C
-- [Content-Type: multipart](https://learn.microsoft.com/en-us/previous-versions/office/developer/exchange-server-2010/aa493937(v=exchg.140))
+- [Content-Type: multipart](<https://learn.microsoft.com/en-us/previous-versions/office/developer/exchange-server-2010/aa493937(v=exchg.140)>)
   at Microsoft
 
+## HTTP version
+
+The gateway serves HTTP/1.1 by default. `protocol: h2c` serves cleartext HTTP/2 instead.
+
+```yaml
+exposition:
+  protocol: h2c
+  service:
+    annotations:
+      projectcontour.io/upstream-protocol.h2c: '8000'
+```
+
+`h2c` requires an ingress controller that proxies cleartext HTTP/2 upstream, and the
+annotation that controller reads to do so. Contour, Traefik and Envoy-based controllers
+proxy it; ingress-nginx does not. A cleartext HTTP/2 server answers nothing else on the
+same port: there is no ALPN to negotiate with, so a controller that speaks HTTP/1.1 upstream
+reaches nothing.
+
+Under `h2c` a request refused before its body is read is answered and then cancelled with
+`RST_STREAM(NO_ERROR)`. The reply arrives; the upload stops where it is. A client streaming
+a request body sees that body cancelled — in Node, `ERR_STREAM_PREMATURE_CLOSE` on the stream
+it passed, which throws if nothing handles it. A real failure shows in the reply, or in the
+request rejecting because no reply came. A buffered body is unaffected.
+
 ## CORS
 
 [CORS](https://www.w3.org/TR/2020/SPSD-cors-20200602/) is supported,
@@ -75,7 +110,7 @@ The following request headers are allowed:
 - `etag`
 - `if-match`
 - `if-none-match`
-- headers used by the [`vary:embed` directive](vary.md#embeddings)
+- headers used by the [`map` directive family](map.md)
 
 The following response headers are exposed: