@toa.io/extensions.exposition 1.0.0-alpha.27 → 1.0.0-alpha.270

package/documentation/credentials.md

@@ -0,0 +1,88 @@
+# Persistent credentials
+
+Persistent credentials associate an [Identity](identity.md) with a reusable authentication method.
+Exposition stores Basic, OpenID Connect federation, and WebAuthn passkey credentials. Local tokens
+and one-time passwords are not persistent credentials: tokens are stateless and OTP records expire.
+
+See [Features](../features/credentials.feature).
+
+## Listing credentials
+
+`GET /identity/credentials/:identity/` returns all persistent credentials associated with the
+Identity in the current authority. Access requires credentials of that Identity.
+
+```http
+GET /identity/credentials/fc8e66ddd51d45eea89602c9dd38a542/ HTTP/1.1
+authorization: Token ...
+accept: application/yaml
+```
+
+```yaml
+basic:
+  username: user@example.com
+federation:
+  - id: 09200d0bcc2448c5863e3f50ae18af84
+    iss: https://accounts.google.com
+    _created: 1754899200000
+passkeys:
+  - id: 54ed430804324e81b39756ea4708b546
+    aid: adce0002-35bc-c60a-648b-0b25f1f05503
+    synced: true
+    label: Personal iPhone
+    _created: 1754899200000
+```
+
+`basic` is `null` when Basic credentials do not exist. `federation` and `passkeys` are always
+arrays. Secret and authentication data, including password hashes, federation subjects, public
+keys, signature counters, and transports, are not returned.
+
+The federation issuer identifies the provider. For example, Google uses
+`https://accounts.google.com` and Apple uses `https://appleid.apple.com`. Applications should map
+trusted issuers to their own provider names and presentation.
+
+The passkey `aid` is its
+[AAGUID](https://www.w3.org/TR/webauthn-2/#aaguid), which can be resolved against an authenticator
+metadata catalog. `synced` indicates whether the credential was backed up and is therefore likely
+available on more than one device.
+
+## Basic credentials
+
+- `POST /identity/basic/:identity/` adds Basic credentials to an Identity.
+- `PATCH /identity/basic/:identity/` changes its username or password.
+- `DELETE /identity/basic/:identity/` removes its Basic credentials.
+
+An Identity can have at most one Basic credential in an authority. See
+[Basic credentials configuration](components.md#basic-credentials) for password hashing,
+constraints, and principal configuration.
+
+## Federated credentials
+
+- `POST /identity/federation/:identity/` associates credentials from a trusted issuer and returns
+  the associated credential as it is listed.
+- `GET /identity/federation/:identity/` lists federated credentials.
+- `DELETE /identity/federation/:identity/:credential/` removes one federated credential.
+
+If the credentials are already associated with the Identity, the existing credential is returned.
+
+An Identity can have credentials from multiple issuers and can have multiple subjects from the
+same issuer. The `:credential` segment is the `id` returned by any of these resources. Federation
+resources are provider-independent; issuer-specific authorization flows remain the responsibility
+of the application.
+
+## Passkeys
+
+Passkey registration consists of a challenge followed by credential creation:
+
+- `POST /identity/passkeys/challenges/:identity/` creates a registration challenge.
+- `POST /identity/passkeys/:identity/` verifies the response and stores the passkey.
+- `GET /identity/passkeys/:identity/` lists passkeys.
+- `DELETE /identity/passkeys/:identity/:credential/` removes one passkey.
+
+See [Web Authentication](passkeys.md) for standards and feature scenarios.
+
+## Removing the last credential
+
+Credential components intentionally do not coordinate with one another. Consequently, credentials
+can be removed without checking whether another persistent credential exists.
+Applications that require a recoverable login must prevent removal of the last usable credential
+in their client workflow.

package/documentation/dev.md

@@ -0,0 +1,30 @@
+# Development tools
+
+## `dev:stub`
+
+Returns a successful response with the given body.
+
+```yaml
+/foo:
+  dev:sub: Hello!
+/bar:
+  dev:sub:
+    hello: world
+```
+
+## `dev:sleep`
+
+Enables random delay before processing the request, up to given maximum time in milliseconds.
+
+Desired delay range can be set in the `sleep` request header as a JSON array of two numbers, the minimum
+and maximum delay in milliseconds.
+
+```yaml
+/foo:
+  dev:sleep: 1000
+```
+
+```http
+GET /foo/ HTTP/1.1
+sleep: [500, 1000]
+```

package/documentation/flow.md

@@ -0,0 +1,44 @@
+# Request flow
+
+## `flow:fetch`
+
+Fetches the content from the resource returned by the specified endpoint.
+
+The value of the directive is a `string` specifying endpoint to be called for the redirection
+request.
+
+Request `authority`, `path` and `parameters` are passed as input to the redirection endpoint,
+and it must return a URL `string`, an `Error` or an object with the following properties:
+
+```yaml
+url: string
+options?:
+  method?: string
+  headers?: Record<string, string>
+  body?: string
+```
+
+If it returns a URL or Request, then the response to the specified request is returned as the
+response to the original request, along with the `content-type`, `content-length`, and `etag`
+headers.
+
+## `flow:compose`
+
+Compose an object from a response stream in object mode.
+
+The value of the directive is an object whose values are JavaScript expressions
+accessing the response stream objects composed into an array named `$`.
+
+```yaml
+flow:compose:
+  one: $[0].status
+  two: $[1].data.foo
+  three: $[2].amount
+```
+
+```yaml
+flow:compose:
+  sum: $[0].value + $[1].value
+```
+
+Be careful.

package/documentation/identity.md

@@ -6,6 +6,9 @@ identifier** of an individual, organization, application or device.
 To prove its Identity, the request originator must provide a valid _credentials_ that are associated
 with that Identity.
 
+Persistent authentication methods and their management resources are described in
+[Persistent credentials](credentials.md).
+
 Identity is intrinsically linked to credentials, as an Identity is established only when the first
 set of credentials for that Identity is created.
 In other words, the creation of credentials marks the inception of an Identity.
@@ -38,19 +41,22 @@ See [`identity.basic` component](components.md#basic-credentials).
 
 ### Token scheme
 
-Tokens issued by the Authentication system. These tokens are [PASETO](https://paseto.io).
+Tokens issued by the Authentication system. New tokens are compact
+[JSON Web Encryption (JWE)](https://www.rfc-editor.org/rfc/rfc7516) values using direct symmetric
+encryption (`alg: dir`) and AES-256-GCM (`enc: A256GCM`). Legacy PASETO V3.local tokens remain
+accepted during migration and are always replaced on successful authentication.
 
 ```http
-Authrization: Token v4.local.eyJzdWIiOiJqb2hu...
+Authorization: Token eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwidHlwIjoiSldUIiwia2lkIjo...
 ```
 
 The `Token` is the **primary** authentication scheme.
 If request originators use an alternative authentication scheme, they will receive a response
-containing `Token`credentials and will be required to switch to the `Token` scheme for any
+containing `Token` credentials and will be required to switch to the `Token` scheme for any
 subsequent requests.
 Continued use of other authentication schemes will result in temporary blocking of requests.
 
-See [`identity.tokens` component](components.md#stateless-tokens).
+See [`identity.tokens` component](components.md#local-tokens).
 
 ### Bearer scheme
 
@@ -63,8 +69,8 @@ to [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.ht
 Authorization: Bearer eyJhbGciOiJIUzI1...
 ```
 
-Trusted providers are specified using the `identity.federation` property within the configuration
-annotation.
+Trusted providers are specified using the `identity.federation` configuration. Provider metadata
+and signing keys are discovered using OpenID Connect discovery and JWKS.
 
 ```yaml
 # context.toa.yaml
@@ -73,16 +79,93 @@ configuration:
   identity.federation:
     trust:
       - iss: https://accounts.google.com
-        aud:
-          - <GOOGLE_CLIENT_ID>
+        aud: <GOOGLE_CLIENT_ID>
 
       - iss: https://appleid.apple.com
+        aud: <APPLE_CLIENT_ID>
+        secret: <APPLE_CLIENT_SECRET> # enables Authorization Code Flow
+    principal:
+      iss: https://accounts.google.com
+      sub: 4218230498234
+    assert: true
+```
+
+`principal` specifies the values of the `iss` and `sub` claims of an Identity that will be granted
+with a `system` role.
+
+`assert` indicates whether the Identity should be implicitly created when valid credentials for a
+non-existent Identity are provided (default `true`).
+
+### Authorization Code Flow
+
+[OAuth 2.0 RFC 6749, section 4.1](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1)
+
+```
+GET /identity/
+authorization: Code <credentials>
+```
+
+`<credentials>` is a base64-encoded JSON containing the following properties:
+
+```yaml
+code: authorization code
+iss: code issuer
+for: redirect URI
+```
+
+Trust configuration for the issuer requires `aud` and either `secret` or `signature`
+values to enable the Authorization Code Flow.
+
+> If `aud` is an array, the first value is used.
+
+```yaml
+# context.toa.yaml
+configuration:
+  identity.federation:
+    trust:
+      - iss: https://accounts.google.com
+        aud: 1045282659797-n705sf85j4b2rodtpdn43od43tvseiet.apps.googleusercontent.com
+        secret: $GOOGLE_CLIENT_SECRET
+      - iss: https://appleid.apple.com
+        aud: io.toa.services.id
+        signature:
+          iss: team-id
+          kid: key-id
+          key: $APPLE_PRIVATE_KEY # PKCS8 PEM, as in the .p8 file
+```
+
+### OTP scheme
+
+One-time passwords.
+
+Passwords can be issued by calling `identity.otp.issue` operation, with the following input:
 
-      - iss: private.entity
-        secrets:
-          HS384:
-            key0: <THE-SECRET-STRING-FOR-HS384>
-            key1: <THE-SECRET-STRING-FOR-HS384> # selected by `kid` in the JWT header
+```yaml
+authority: string
+username: string
+```
+
+The reply will contain the `code` property of type `string` formed as a random 6-digit number,
+valid for 60 seconds by default.
+
+```yaml
+code: 123456
+```
+
+OTP can be used with `OTP` authentication formatted as `base64(username:password)`.
+
+```
+GET /identity/ HTTP/1.1
+authentication: OTP dXNlcm5hbWU6MTIzNDU2
+```
+
+OTP expiration time can be configured using the `identity.otp` configuration.
+
+```yaml
+# context.toa.yaml
+configuration:
+  identity.otp:
+    lifetime: 60 # seconds
 ```
 
 ## Identity inception
@@ -110,7 +193,7 @@ exposition:
 The value of the `auth:incept` directive refers to the name of the response property that will be
 returned by the `POST` operation, containing the created entity identifier.
 
-A request with Identity inception must contain (non-existent) credentials that will be associated
+A request with Identity inception may contain (non-existent) credentials that will be associated
 with the created Identity.
 
 ```http
@@ -132,6 +215,34 @@ id: 2428c31ecb6e4a51a24ef52f0c4181b9
 As a result of processing the above request, the provided Basic credentials associated with the
 Identity `2428c31ecb6e4a51a24ef52f0c4181b9` are created.
 
+> `auth:incept` directive may have a `null` value, which means that the Identity will be created
+> without any associated entity.
+
+Inception is supported for `Basic` and `Bearer` authentication schemes.
+
+## Identity assertion
+
+`auth:assert` directive is used to ensure that given credentials are associated with an existing
+Identity or to create a new Identity if it does not exist.
+The directive itself does not allow or deny access to the requested resource.
+
+> Used authentication scheme must support inception.
+
+```yaml
+  /accounts/echo:
+    auth:assert: true
+    auth:anyone: true
+    endpoint: echo
+```
+
+```http
+GET /accounts/echo/
+authorization: Basic new-or-existent-credentials
+```
+
+If new Identity is created and endpoint returns a successful response, the status code `201 Created`
+is returned.
+
 ## FAQ
 
 <dl>

package/documentation/introspection.md

@@ -0,0 +1,82 @@
+# 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.
+
+Introspection properties:
+
+- `route` route parameters
+- `query` query parameters
+- `input` input schema
+- `output` output schema
+- `errors` error codes
+
+```http
+OPTIONS /pots/:id/ HTTP/1.1
+accept: application/yaml
+```
+
+```http
+200 OK
+Allow: GET, POST, OPTIONS
+
+GET:
+  route:
+    id:
+      type: string
+      pattern: ^[a-fA-F0-9]{32}$
+  output:
+    type: array
+    items:
+      type: object
+      properties:
+        title:
+          type: string
+          maxLength: 64
+        volume:
+          type: number
+          exclusiveMinimum: 0
+          maximum: 1000
+        temperature:
+          type: number
+          exclusiveMinimum: 0
+          maximum: 300
+      additionalProperties: false
+      required:
+        - id
+        - title
+        - volume
+POST:
+  route:
+    id:
+      type: string
+      pattern: ^[a-fA-F0-9]{32}$
+  input:
+    type: object
+    properties:
+      title:
+        type: string
+        maxLength: 64
+      temperature:
+        type: number
+        exclusiveMinimum: 0
+        maximum: 300
+      volume:
+        type: number
+        exclusiveMinimum: 0
+        maximum: 1000
+    additionalProperties: false
+    required:
+      - title
+      - volume
+  output:
+    type: object
+    properties:
+      id:
+        type: string
+        pattern: ^[a-fA-F0-9]{32}$
+    additionalProperties: false
+  errors:
+    - NO_WAY
+    - WONT_CREATE
+```

package/documentation/io.md

@@ -3,7 +3,7 @@
 The Exposition comes with `io` directives to control access to the operation's input and output
 properties.
 
-## `io:input`
+## Input
 
 The `io:input` optional directive contains a list of properties that are allowed to be specified in
 the request body.
@@ -22,7 +22,7 @@ not in the list, the request will be rejected with a `400` status code.
 > Therefore, `io:input` is only applicable to operations which input is an object or an
 > array of objects.
 
-## `io:output`
+## Output
 
 The `io:output` mandatory directive contains a list of properties that are allowed to be included in
 the response body.
@@ -54,3 +54,74 @@ GET:
 ```
 
 Output restrictions are not applied to stream responses and errors.
+
+## Throttling
+
+The `io:throttle` directive limits the rate of requests meeting the specified criteria.
+
+```yaml
+exposition:
+  /:
+    io:throttle:
+      key:
+        - route
+        - ip
+      condition:
+        status: 404
+      requests: 500
+      interval: 30
+```
+
+Requests are metered per `key`. A key may spend `requests` at once, and earns them back at a rate of
+`requests` per `interval` seconds. A request carrying a key with nothing left to spend is answered
+`429 Too Many Requests`, with a `Retry-After` saying how long until one would be admitted again.
+`interval` is in seconds.
+
+So `requests` is the burst, and `requests / interval` the rate it is repaid at. There is no window to
+save a budget up in and spend twice across the edge of, and no lockout to sit out: a key that has
+overspent is admitted again as soon as it has earned a single request back, and a client that keeps
+asking meanwhile is not penalised for it.
+
+`requests` is a budget for the **whole group** of gateway instances, not for one of them. Instances
+reconcile through Redis on a timer, so they converge on one number rather than each enforcing the
+limit separately. Between two of those, an instance goes on what it alone has spent — so the group
+can overshoot by what the other instances admit within that window, and by no more. The window is a
+tenth of `interval`, between a quarter of a second and two seconds, whatever `interval` is. Precise
+per-request enforcement is not what this is for.
+
+An instance that cannot reach Redis keeps throttling on what it has seen itself and keeps serving,
+and reports what it could not the next time it gets through.
+
+### Key components
+
+What a request is metered against. Give one, or a list — a list keys on the combination, so
+`[route, ip]` meters each address separately on each route.
+
+- `ip` — the client address, read from `X-Forwarded-For` where it is set and not private,
+  and from the connection otherwise.
+- `path` — the path the request came in on, `/users/1`.
+- `route` — the route as declared, `/users/:id`. Every path matching the route shares one budget,
+  which `path` cannot do: keyed on `path`, walking ids is a way around the limit.
+- `identity` — the authenticated identity. Requests carrying none share a single budget between
+  them, so pair it with `ip` if that matters.
+- `segment: <name>` — the value bound to a named route segment, `1` for `:id` in `/users/:id`.
+
+### Conditions
+
+What is metered, as opposed to what it is metered against. A request that fails a condition is served
+and costs nothing. Conditions are evaluated against the response, so they cannot decide whether to
+refuse a request — only whether it is charged for, once it has been answered.
+
+- `status: <code>` — charge only for responses with this status.
+
+```yaml
+io:throttle:
+  key: ip
+  condition:
+    status: 404
+  requests: 20
+  interval: 600
+```
+
+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.

package/documentation/map.md

@@ -0,0 +1,115 @@
+# HTTP context mapping
+
+The `map` directive family is used to map HTTP request parts to operation call input properties.
+
+[Features](../features/map.feature).
+
+## TL;DR
+
+```yaml
+exposition:
+  /:group:
+    languages: [en, fr]   # supported languages
+    GET:
+      map:authority: hostname # request authority (e.g., hostname)
+      map:language: lang      # requested language
+      map:headers: # raw header values
+        token: x-access-token
+      map:buffer: body # unparsed request body
+      map:segments: # route parameters
+        group: group
+      map:claims: # Bearer token claims
+        address: email
+        verified: email_verified
+      endpoint: observe
+```
+
+The operation input type must be an object.
+If the input already contains the specified keys, they will be overwritten.
+
+## Authority
+
+The `map:authority` directive maps the [authority identifier](authorities.md) to an operation call
+input property specified by the directive value.
+
+### Language
+
+The `map:language` mapping sets the [most matching](https://github.com/jshttp/negotiator) language
+code based on the `accept-language` request header and a list of supported languages defined by
+the `map:languages` directive, and also adds `accept-language` to the `Vary` HTTP response header
+value.
+
+If none of the supported languages match, the first supported language is used.
+
+> `map:languages` has a shorthand form: `languages: [en, fr]`.
+
+## Header values
+
+The `map:headers` directive maps the values of HTTP request headers to operation call input
+properties.
+The value of the directive is a map where keys are the names of the input properties and values are
+the names of the HTTP request headers.
+
+The names of these headers are then included in the `Vary` HTTP response header
+and [Access-Control-Allow-Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers)
+of the [CORS](protocol.md#cors).
+
+[Multiple header fields](https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2) are combined
+as a comma-separated list.
+
+## Raw body
+
+The `map:buffer` directive maps the unparsed request body to an operation call input property.
+The directive value is the name of the input property.
+
+```yaml
+/webhook:
+  POST:
+    map:buffer: body
+    map:headers:
+      signature: x-signature
+    endpoint: verify
+```
+
+The body is read from the request stream as raw bytes and delivered as a UTF-8 string.
+
+Body parsing is bypassed, so the route does not depend on a supported `Content-Type` or format decoding. The request stream is consumed; a route with `map:buffer` cannot also receive a parsed body from the same request.
+
+## Route parameters
+
+The `map:segments` directive maps the values of route parameters to operation call input properties.
+The value of the directive is a map where keys are the names of the input properties, and values are
+the names of the route parameters.
+
+Parameter name may be prefixed with `~`
+to indicate that the parameter should not be available to the
+remaining directives or used as criteria in the operation call.
+
+```yaml
+/:id/:tag:
+  POST:
+    map:segments:
+      id: id
+      tag: ~tag
+    endpoint: create
+```
+
+Wildcard routes are supported by using `**` as the parameter name.
+
+```yaml
+/path/to/**:
+  GET:
+    map:segments:
+      path: '**'
+    endpoint: observe
+```
+
+## Bearer token claims
+
+The `map:claims` directive maps the values of
+the [token claims](https://datatracker.ietf.org/doc/html/rfc7519#section-4).
+The value of the directive is a map where keys are the names of the input properties and values are
+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.