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

package/documentation/components.md

@@ -5,6 +5,9 @@ configured in the same
 way as if they were a part of the Context. Resources exposed by the components
 are [isolated](tree.md#directives).
 
+See [Persistent credentials](credentials.md) for the centralized Basic, federation, and passkey
+management API.
+
 ## Basic credentials
 
 The `identity.basic` component stores basic credentials.
@@ -20,7 +23,7 @@ and pepper.
 configuration:
   identity.basic:
     rounds: 10 # salt rounds
-    pepper: '' # hashing pepper
+    pepper: $IDENTITY_BASIC_PEPPER # hashing pepper, a secret
 ```
 
 ### Credentials constraints
@@ -54,12 +57,17 @@ This issue is addressed by using the `principal` key in the configuration:
 
 configuration:
   identity.basic:
-    principal: root
+    principal:
+      authority: example
+      username: root
 ```
 
-The value of the `principal` key corresponds to the `username` of the basic credentials. Once these
-credentials are
-created, the associated Identity will be assigned the `system` Role.
+`principal` names the authority and the `username` of the basic credentials. Once these
+credentials are created in that authority, the associated Identity is assigned the `system` Role.
+The same username in another authority is ordinary credentials.
+
+Credentials created by inception are granted the Role before the reply, so the token that reply
+carries already holds it.
 
 Once created, the username of the principal cannot be modified.
 
@@ -74,6 +82,12 @@ username: string
 password: string
 ```
 
+Returns `201 Created` if the Identity is created,
+or `422 Unprocessable Entity` with one of the error codes:
+
+- `INVALID_USERNAME` - `username` does not match constraints
+- `INVALID_PASSWORD` - `password` does not match constraints
+
 Access is [anonymous](access.md#anonymous).
 
 #### `/identity/basic/:id/`
@@ -89,6 +103,23 @@ password?: string
 
 Access requires basic credentials of the modified Identity or `system:identity:basic` role.
 
+<code>POST</code> Incept new basic credentials. Request body is as follows:
+
+```yaml
+username: string
+password: string
+```
+
+Identity should not have associated basic credentials. Access requires any credentials of the Identity.
+
+#### `/identity/basic/usernames/:username/`
+
+<code>GET</code> Check if the username is available.
+
+`username` must be Base64 URL encoded.
+
+Returns empty response with status `204` if the username is already taken or `404` if it is available.
+
 ## Identity federation (OpenID connect)
 
 The `identity.federation` component manages OpenID Connect federated identities.
@@ -102,8 +133,10 @@ the [component manifest](../components/identity.federation/manifest.toa.yaml).
 No federated tokens are accepted by default until at least one entry is added to the `trust`
 configuration.
 
-Toa supports either asymmetric RS256 or symmetric HS256 / HS384 / HS512 tokens with pre-shared
-secrets.
+Issuer metadata is loaded from `<iss>/.well-known/openid-configuration`; signing keys are then
+loaded from its `jwks_uri`. These requests, including Authorization Code token exchange, use the
+built-in `context.fetch`, so they participate in standard HTTP telemetry and connection pooling.
+JWKS resolvers are cached per fetch instance and issuer.
 
 ```yaml
 # context.toa.yaml
@@ -116,15 +149,13 @@ configuration:
           - https://github.com/tinovyatkin
           - https://github.com/temich
 
-      - issuer: some.private.issuer
-        secrets:
-          HS256:
-            k1: <secret-to-be-used-for-hs256>
+      - iss: https://accounts.google.com
+        aud: <GOOGLE_CLIENT_ID>
 ```
 
-## Stateless tokens
+## Local tokens
 
-The `identity.tokens` component manages stateless authentication tokens.
+The `identity.tokens` component manages local authentication tokens.
 
 These tokens carry the information required to authenticate the Identity and authorize access.
 
@@ -143,21 +174,114 @@ authorization: Token ...
 cache-control: no-store
 ```
 
+### Custom tokens
+
+Custom tokens can be issued with a specific set of permissions and scopes for the own Identity or by
+an Identity with the `system:identity:tokens` role.
+
+Tokens are issued with custom secret keys and are not subject to [token rotation](#token-rotation).
+To invalidate a custom token, its secret key must be deleted.
+
+Custom tokens have no `refresh` period, that is, never become obsolete and never refreshed.
+
+```
+POST /identity/tokens/<identity>/
+host: nex.toa.io
+authorization: ...
+accept: application/yaml
+content-type: application/yaml
+
+lifetime: 3600
+label: CI deployment token
+scopes: [app:developer]
+permissions:
+  /users/fc8e66dd/: [GET, PUT]
+  /posts/fc8e66dd/**/comments/: [*]
+```
+
+```
+201 Created
+content-type: application/yaml
+
+kid: <key-id>
+exp: <unix-time-ms>
+token: <token>
+```
+
+- `lifetime`: Issued token will be valid for this period
+  (default is specified in [the configuration](#token-rotation)).
+  The value of `0` means the token will not expire, which is supported, but
+  **strongly not recommended** for production environments.
+- `label`: Required human-readable name used when listing and revoking issued tokens.
+- `scopes`: Issued token will assume only specified [role scopes](access.md#roles).
+- `permissions`: Issued token will have permissions to access only specified resources and methods.
+  Supports [glob patterns](https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html)
+  and a wildcard method.
+  Patterns are matched against the request path as it is routed: normalized, without the query
+  string.
+
+> `roles` and `permissions` are additional restrictions applied on top of the Identity’s inherent
+> privileges.
+
+### Custom token invalidation
+
+A custom token is invalidated through its secret key. The key is revoked, and every token issued
+with it is refused, when the Identity is [banned](#banned-identities), its
+[Basic credentials](#basic-credentials) are modified, or one of its [roles](#roles) is revoked.
+The key can also be deleted by the Identity that issued the token or by an Identity with the
+`system:identity:keys` role.
+
+```
+DELETE /identity/keys/<identity>/<key.id>/
+authorization: ...
+```
+
+The key `id` is returned as `kid` when the token is issued, is visible in the JWE protected header,
+and can also be obtained by listing issued token keys. The secret key itself is never returned by
+the listing endpoint.
+
+```
+GET /identity/keys/<identity>/
+authorization: ...
+```
+
+The listing returns `id`, `label`, optional `expires`, `revokedAt` where the key is revoked, and
+`CREATED`. Revocation and deletion prevent new cache lookups from finding a usable key. A runtime
+that already cached it can continue accepting the token for up to `identity.tokens.cache.ttl`
+milliseconds (10 minutes by default).
+
+Both listing and deletion require credentials of the owning Identity or the
+`system:identity:keys` role. Key creation is internal to `identity.tokens`; there is no public
+endpoint that returns a stored secret.
+
 ### Token encryption
 
-Issued tokens are encrypted
-with [PASETO V3 encryption](https://github.com/panva/paseto/blob/main/docs/README.md#v3encryptpayload-key-options)
-using the `key0` configuration value as a secret.
+Issued tokens are compact JWE tokens encrypted with direct symmetric encryption. Their protected
+header is `{ alg: 'dir', enc: 'A256GCM', typ: 'JWT', kid: <key id> }`. Keys are configured in one
+`keys` array. The first entry whose `format` is `jwe` or omitted is the active issuance key.
+Keys are 256-bit secrets encoded with base64url and can be generated with `toa key`.
+
+The optional `format` is `jwe` by default. Entries with `format: paseto` contain legacy PASETO
+V3.local secrets and are used only to read old tokens. Legacy tokens are always marked for refresh;
+only JWE tokens are issued.
+The `format` property is transitional and can be removed together with the PASETO entries after the
+legacy compatibility window ends.
 
 ```yaml
 # context.toa.yaml
 
 configuration:
   identity.tokens:
-    key0: $TOKEN_ENCRYPTION_KEY
+    keys:
+      - id: 2026q3
+        key: $IDENTITY_TOKENS_ENCRYPTION_KEY0
+      - id: legacy
+        key: $IDENTITY_TOKENS_KEY0
+        format: paseto
 ```
 
-The `key0` configuration value is required.
+At least one JWE entry is required. PASETO entries are required only while previously issued legacy
+tokens must remain readable.
 
 > Valid secret key may be generated using the [`toa key` command](/runtime/cli/readme.md#key).
 
@@ -172,6 +296,9 @@ will always have a valid token to authenticate with.
 Also, token revocation or changing roles of an Identity will take effect once the `refresh` period
 of the currently issued tokens has expired.
 
+A change of what an Identity may do reaches every credential it holds: a token issued by the
+gateway within `refresh`, a [custom token](#custom-tokens) within `cache.ttl`.
+
 Adjusting these two values is a delicate trade-off between security, performance and client
 convenience.
 
@@ -181,7 +308,7 @@ convenience.
 configuration:
   identity.tokens:
     lifetime: 2592000 # seconds, 30 days
-    refresh: 600      # seconds, 10 minutes
+    refresh: 600 # seconds, 10 minutes
 ```
 
 > Values in the example above are the default values.
@@ -190,73 +317,64 @@ configuration:
 
 All currently issued tokens of an Identity are revoked when:
 
-1. Basic credentials associated with the Identity are [modified](#identitybasicid).
+1. [Basic credentials](#basic-credentials) associated with the Identity are modified.
 2. Identity is [banned](#banned-identities).
 
 Token revocation takes effect once the `refresh` period of the currently issued tokens has expired.
+[Custom tokens](#custom-tokens) are revoked through their keys, within `cache.ttl`.
 
 ### Secret rotation
 
-Tokens are always encrypted using the `key0` configuration value, and they will be decrypted by
-attempting both
-the `key0` and `key1` values in order.
-
-`key0` is considered the "current key," and `key1` is considered the "previous key."
-
-```yaml
-# context.toa.yaml
-
-configuration:
-  identity.tokens:
-    key0: $TOKEN_ENCRYPTION_KEY_2023Q3
-    key1: $TOKEN_ENCRYPTION_KEY_2023Q2
-```
-
-Secret rotation is performed by adding a new key as the `key0` value and moving the existing `key0`
-to the `key1` value.
+Tokens are always encrypted using the first JWE entry of the `keys` array and decrypted by the
+entry in the corresponding format branch whose `id` matches the token's `kid`.
 
-When rolling out the new secret key, there will be a period of time when the new key is deployed to
-some Exposition
-instances. During this time, these instances will start using the new key to encrypt tokens, while
-other instances will
-continue using the current key and will not be able to decrypt tokens encrypted with the new key.
+Rotation uses array order rather than object property order: index `0` is active for issuance and
+the remaining entries are decrypt-only. Use the staged procedure below so every runtime knows the
+new key before it becomes active.
 
-To address this issue, the `key1` configuration value may be used as a "transient key."
+Old keys must remain configured until every token issued with them has expired. In the default
+configuration this means retaining them for at least `lifetime` (30 days) after making a new key
+active. The shorter `refresh` interval only controls replacement during active client use and is
+not a safe removal window for clients that remain idle.
 
-The secret rotation is a 2-step process:
-
-> The process **must not** be performed earlier than the `lifetime` period since the last rotation,
-> as it may invalidate
-> tokens before they expire. Therefore, it is guaranteed that there are no valid tokens issued with
-> the current `key1`
-> value.
-
-1. Deploy the new secret key to all Exposition instances as `key1`. This enables all instances to
-   decrypt tokens
-   encrypted with the new key while still using the current key for encryption.
+> Let's say you are adding a new secret key each quarter: `2024Q1`, `2024Q2` and so on.
+> The old key `2024Q1` must be removed only after the maximum lifetime of tokens issued with it has
+> elapsed.
 
 ```yaml
 # context.toa.yaml
 
 configuration:
   identity.tokens:
-    key0: $TOKEN_ENCRYPTION_KEY_2023Q3
-    key1: $TOKEN_ENCRYPTION_KEY_2023Q4
+    keys:
+      - id: 2026q3
+        key: $TOKEN_ENCRYPTION_KEY_2026Q3
+      - id: 2026q4
+        key: $TOKEN_ENCRYPTION_KEY_2026Q4
 ```
 
-2. Move the new secret key from `key1` to `key0`, and move the current key from `key0` to `key1`.
-   During this rollout,
-   all instances can decrypt tokens encrypted with both the new key and the current key.
+1. First deploy both keys everywhere with the current key at index `0`, as shown above.
+2. In an atomic rollout, move the new entry to index `0` and keep the current entry after it.
+   All instances can then decrypt tokens encrypted with both the new key and the current key.
 
 ```yaml
 # context.toa.yaml
 
 configuration:
   identity.tokens:
-    key0: $TOKEN_ENCRYPTION_KEY_2023Q4
-    key1: $TOKEN_ENCRYPTION_KEY_2023Q3
+    keys:
+      - id: 2026q4
+        key: $TOKEN_ENCRYPTION_KEY_2026Q4
+      - id: 2026q3
+        key: $TOKEN_ENCRYPTION_KEY_2026Q3
 ```
 
+3. Remove `2026q3` only after its last possible token has expired.
+
+The PASETO-to-JWE runtime migration must also be atomic: legacy runtimes cannot decrypt newly
+issued JWE tokens. Keep every `format: paseto` entry until its last token has expired;
+`toa key --format paseto` exists only for maintaining those legacy secrets.
+
 ### Token resources
 
 `/identity/tokens/`
@@ -291,13 +409,22 @@ role: string
 To assign arbitrary roles, the `system:identity:roles` role is required.
 
 An Identity having `system:identity:roles:delegation` role can delegate roles within its own
-Role Scopes (see [Role Hierarchies](access.md#hierarchies)).
+Role Scopes (see [Role Hierarchies](access.md#hierarchies)), except roles within the
+`system:identity:roles` scope: the right to delegate is not delegated.
+
+### `/identity/roles/:id/:role/`
+
+`DELETE` Revoke a role of an Identity. The `system:identity:roles` role is required.
+
+A Token carries the roles it was issued with; a change reaches its holder when the token is
+[refreshed](#token-rotation). Revoking a role also revokes the [custom tokens](#custom-tokens) of
+the Identity, which are issued again with the roles it has left.
 
 ## Banned Identities
 
 The `identity.bans` component manages banned identities.
 A banned identity will fail to authenticate with any associated credentials
-(except [tokens](#stateless-tokens) within the `refresh` period).
+(except [tokens](#local-tokens) within the `refresh` period).
 
 ```http
 PUT /identity/bans/:id/
@@ -329,3 +456,17 @@ roles:
   - developer
   - system:identity:roles
 ```
+
+When no credentials are provided, transient Identity is created.
+
+```http
+GET /identity/
+accept: application/yaml
+```
+
+```
+201 Created
+
+id: 332017649c814649b25ee466c1fe4534
+roles: []
+```

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/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]
+```