@toa.io/extensions.exposition 1.0.0-alpha.26 → 1.0.0-alpha.262

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.
@@ -74,6 +77,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 +98,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 +128,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 +144,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 +169,109 @@ 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.
+
+> `roles` and `permissions` are additional restrictions applied on top of the Identity’s inherent
+> privileges.
+
+### Custom token invalidation
+
+Custom tokens can be invalidated by deleting the secret key used to issue them.
+This can be done 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`, and `_created`. Deletion prevents new cache
+lookups from finding the 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).
 
@@ -190,73 +304,63 @@ 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.
 
 ### 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
+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`.
 
-configuration:
-  identity.tokens:
-    key0: $TOKEN_ENCRYPTION_KEY_2023Q3
-    key1: $TOKEN_ENCRYPTION_KEY_2023Q2
-```
+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.
 
-Secret rotation is performed by adding a new key as the `key0` value and moving the existing `key0`
-to the `key1` value.
+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.
 
-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.
-
-To address this issue, the `key1` configuration value may be used as a "transient key."
-
-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/`
@@ -297,7 +401,7 @@ Role Scopes (see [Role Hierarchies](access.md#hierarchies)).
 
 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 +433,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/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>