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

package/documentation/components.md

@@ -1,472 +0,0 @@
-# Components and resources
-
-Exposition comes with a set of components that run within the same process. These components are
-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.
-
-### Password hashing
-
-Passwords are hashed using the [bcrypt](https://github.com/dcodeIO/bcrypt.js) algorithm with salt
-and pepper.
-
-```yaml
-# context.toa.yaml
-
-configuration:
-  identity.basic:
-    rounds: 10 # salt rounds
-    pepper: $IDENTITY_BASIC_PEPPER # hashing pepper, a secret
-```
-
-### Credentials constraints
-
-Credential constraints are defined using a set of regular expressions (values must match all of
-them).
-
-```yaml
-# context.toa.yaml
-
-configuration:
-  identity.basic:
-    username:
-      - ^\S{1,128}$
-    password:
-      - ^\S{8,32}$
-```
-
-> Values in the example above are the default values.
-
-### Principal
-
-When an application is deployed for the first time, there are no credentials, and therefore, there
-is no Identity that
-could have a Role to manage Roles of other Identities.
-
-This issue is addressed by using the `principal` key in the configuration:
-
-```yaml
-# context.toa.yaml
-
-configuration:
-  identity.basic:
-    principal:
-      authority: example
-      username: root
-```
-
-`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.
-
-### Resources
-
-#### `/identity/basic/`
-
-<code>POST</code> Create new Identity with Basic credentials. Request body is as follows:
-
-```yaml
-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/`
-
-> `:id` placeholder refers to an Identity.
-
-<code>PUT</code> Update basic credentials. Request body is as follows:
-
-```yaml
-username?: string
-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.
-
-Both implicit identities creation and forced [identity inception](./identity.md) are supported
-as in case with basic credentials. `principal` is also working in the same way.
-
-The configuration schema alongside default values is described in
-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.
-
-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
-
-configuration:
-  identity.federation:
-    trust:
-      - iss: https://token.actions.githubusercontent.com
-        aud:
-          - https://github.com/tinovyatkin
-          - https://github.com/temich
-
-      - iss: https://accounts.google.com
-        aud: <GOOGLE_CLIENT_ID>
-```
-
-## Local tokens
-
-The `identity.tokens` component manages local authentication tokens.
-
-These tokens carry the information required to authenticate the Identity and authorize access.
-
-### Issuing tokens
-
-The new token is issued each time the request is made:
-
-1. Using authentication scheme other than `Token`.
-2. Using `Token` authentication scheme with an [obsolete token](#token-rotation).
-
-When the token is issued it is sent in the `authorization` response header and the `cache-control`
-is set to `no-store`.
-
-```http
-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 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:
-    keys:
-      - id: 2026q3
-        key: $IDENTITY_TOKENS_ENCRYPTION_KEY0
-      - id: legacy
-        key: $IDENTITY_TOKENS_KEY0
-        format: paseto
-```
-
-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).
-
-### Token rotation
-
-Issued tokens are valid for a `lifetime` period defined in the configuration. After the `refresh`
-period, the token is considered obsolete (yet still valid), and a new token
-is [issued](#issuing-tokens) unless the provided one has been [revoked](#token-revocation).
-
-This essentially means that if the client uses the token at least once every `lifetime` period, it
-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.
-
-```yaml
-# context.toa.yaml
-
-configuration:
-  identity.tokens:
-    lifetime: 2592000 # seconds, 30 days
-    refresh: 600 # seconds, 10 minutes
-```
-
-> Values in the example above are the default values.
-
-### Token revocation
-
-All currently issued tokens of an Identity are revoked when:
-
-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 first JWE entry of the `keys` array and decrypted by the
-entry in the corresponding format branch whose `id` matches the token's `kid`.
-
-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.
-
-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.
-
-> 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:
-    keys:
-      - id: 2026q3
-        key: $TOKEN_ENCRYPTION_KEY_2026Q3
-      - id: 2026q4
-        key: $TOKEN_ENCRYPTION_KEY_2026Q4
-```
-
-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:
-    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/`
-
-`POST` Issue a new token for the Identity. Request body is as follows:
-
-```yaml
-lifetime?: number # seconds
-```
-
-Providing a value of `0` will result in the token being issued with no expiration.
-However, it will still become invalid once the encryption key used is out
-of [rotation](#secret-rotation).
-
-## Roles
-
-The `identity.roles` component manages roles of an Identity used
-by [access authorization](access.md#role).
-
-### `/identity/roles/:id/`
-
-`GET` Get roles of an Identity.
-
-Access requires credentials of the Identity or `system:identity:roles` role.
-
-`POST` Add a role to an Identity. Request body is as follows:
-
-```yaml
-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)), 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](#local-tokens) within the `refresh` period).
-
-```http
-PUT /identity/bans/:id/
-authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
-content-type: application/yaml
-
-banned: true
-comment: Bye bye
-```
-
-Access requires `system:identity:bans` role.
-
-## Authentication echo
-
-Exposition implements a predefined resource `/identity/` with the `GET` method, which returns the
-Identity resolved by the provided credentials.
-
-```http
-GET /identity/
-authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
-accept: application/yaml
-```
-
-```
-200 OK
-
-id: fc8e66ddd51d45eea89602c9dd38a542
-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

@@ -1,101 +0,0 @@
-# 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

@@ -1,88 +0,0 @@
-# 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

@@ -1,30 +0,0 @@
-# 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]
-```