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

package/components/identity.tokens/source/lib/types.ts

@@ -0,0 +1,97 @@
+import type { Call, Maybe, Observation, telemetry } from '@toa.io/types'
+
+export interface Context {
+  local: {
+    observe: Observation<Entity>
+    encrypt: Call<Maybe<string>, EncryptInput>
+    decrypt: Call<Maybe<DecryptOutput>, string>
+  }
+  remote: {
+    identity: {
+      keys: {
+        observe: Observation<CustomKey>
+        create: Call<Key>
+      }
+      roles: {
+        list: Call<string[]>
+      }
+    }
+  }
+  configuration: Configuration
+  logs: telemetry.Logs
+}
+
+export interface Configuration {
+  readonly keys: ConfiguredKey[]
+  readonly lifetime: number
+  readonly refresh: number
+  readonly cache: {
+    max: number
+    ttl: number
+  }
+}
+
+export interface ConfiguredKey extends Pick<Key, 'id' | 'key'> {
+  format?: 'jwe' | 'paseto'
+}
+
+export interface Entity {
+  revokedAt?: number
+}
+
+export interface Identity extends Record<string, any> {
+  id: string
+  roles: string[]
+  permissions?: Record<string, string[]>
+}
+
+export interface AuthenticateInput {
+  authority: string
+  credentials: string
+}
+
+export interface AuthenticateOutput {
+  identity: Identity
+  refresh: boolean
+}
+
+export interface EncryptInput {
+  authority: string
+  identity: Identity
+  lifetime?: number
+  scopes?: string[]
+  permissions?: Record<string, string[]>
+  key?: Key
+}
+
+export interface DecryptOutput {
+  iss: string
+  iat: string
+  exp?: string
+  identity: Identity
+  refresh: boolean
+}
+
+export interface Claims {
+  identity: Identity
+  iss: string
+  iat: string
+  exp?: string
+}
+
+export interface JWEClaims {
+  identity: Identity
+  iss: string
+  iat: number
+  exp?: number
+}
+
+export interface Key {
+  id: string
+  key: string
+  label: string
+}
+
+export interface CustomKey extends Key {
+  identity: string
+}

package/components/identity.tokens/source/revoke.ts

@@ -1,5 +1,5 @@
-import { type Entity } from './types'
+import type { Entity } from './lib'
 
-export function transition (_: never, object: Entity): void {
+export function transition (_: unknown, object: Entity): void {
   object.revokedAt = Date.now()
 }

package/{components/context.toa.yaml → context.toa.yaml}

@@ -1,7 +1,6 @@
 # used for development only
 
 name: exposition
-packages: '*'
 registry: localhost
 
 amqp: amqp://localhost
@@ -9,7 +8,12 @@ mongodb: mongodb://localhost
 
 configuration:
   identity.tokens:
-    key0: k3.local.pIZT8-9Fa6U_QtfQHOSStfGtmyzPINyKQq2Xk-hd7vA
+    keys:
+      - id: key0
+        key: sTxL6qVOadKkUJwh3FveU53XgTEo3Sdfg7k2FfiIKfs
+      - id: legacy0
+        key: k3.local.pIZT8-9Fa6U_QtfQHOSStfGtmyzPINyKQq2Xk-hd7vA
+        format: paseto
 
   identity.federation:
     trust:

package/cucumber.js

@@ -1,6 +1,6 @@
 module.exports = {
   default: {
-    requireModule: ['ts-node/register'],
+    requireModule: ['ts-node/register/transpile-only'],
     require: ['./features/**/*.ts'],
     failFast: true
   }

package/documentation/access.md

@@ -25,7 +25,11 @@ responds with an authorization error.
 Grants access if its value is `true` and no credentials were provided[^1].
 
 [^1]: Credentials in the request make the
-response [non-cachable](https://datatracker.ietf.org/doc/html/rfc7234#section-3).
+response [non-cacheable](https://datatracker.ietf.org/doc/html/rfc7234#section-3).
+
+### `anyone`
+
+Grants access if its value is `true` and valid credentials were provided.
 
 ### `id`
 
@@ -37,11 +41,8 @@ the directive's value.
 Given the Route declaration and corresponding HTTP request:
 
 ```yaml
-# context.toa.yaml
-
-exposition:
-  /users/:user-id:
-    id: "user-id"
+/users/:user-id:
+  id: "user-id"
 ```
 
 ```http
@@ -57,11 +58,8 @@ is `87480f2bd88048518c529d7957475ecd`.
 Grants access if resolved Identity has a role matching the directive's value or one of its values.
 
 ```yaml
-# context.toa.yaml
-
-exposition:
-  /code:
-    role: [developer, reviewer]
+/code:
+  role: [developer, reviewer]
 ```
 
 Access will be granted if the resolved Identity has a role that matches `developer` or `reviewer`.
@@ -73,11 +71,50 @@ Read [Roles](#roles) section for more details.
 The `role` directive can be used with a placeholder in the route.
 
 ```yaml
-# context.toa.yaml
+/:org-id:
+  role: app:{org-id}:moderator
+```
 
-exposition:
-  /:org-id:
-    role: app:{org-id}:moderator
+### `claims`
+
+Grants access if `Bearer` authentication scheme is used
+and the Token's claims matches the specified values.
+
+```yaml
+/:
+  auth:claims:
+    iss: https://id.example.com
+    sub: someone
+    aud: stars
+```
+
+> If OIDC token claim contains `aud`
+> as [an array](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation), the
+> directive will match if at least one value.
+
+At least one property is required.
+
+Values may refer to the Route parameters or the request authority:
+
+```yaml
+/secrets/:org-id:
+  auth:claims:
+    iss: https://id.org.com
+    sub: /:org-id
+    aud: :authority
+```
+
+An expression `:domain` will match if the domain in the value of `iss` matches the request
+authority, excluding the most specific subdomain.
+
+Issuer `https://accounts.example.com` matches request authorities `images.example.com`
+and `sub.images.example.com`, but not `images.another.com`.
+
+```yaml
+/images/:user-id:
+  auth:claims:
+    iss: :domain
+    sub: /:org-id
 ```
 
 ### `rule`
@@ -88,17 +125,34 @@ directives grant access. The value of the `rule` directive can be a single Rule
 #### Example
 
 ```yaml
-# context.toa.yaml
-
-exposition:
-  /commits/:user-id:
-    rule:
-      id: user-id
-      role: developer
+/commits/:user-id:
+  rule:
+    id: user-id
+    role: developer
 ```
 
 Access will be granted if an Identity matches a `user-id` placeholder and has a Role of `developer`.
 
+### `input`
+
+Restricts access based on the request body (which must be an object).
+
+```yaml
+/commits/:id:
+  PUT:
+    auth:role: [developer, reviewer]
+    auth:input:
+      - prop: approved
+        role: reviewer
+      - prop: message
+        role: developer
+```
+
+The example above restricts access to the `approved` property of the request body to the identity
+with the `reviewer` role, and the `message` property to the identity with the `developer` role.
+
+> `auth:input` directive does not grant access by itself.
+
 ### `delegate`
 
 Embeds the value of the current Identity into the request body as a property named after the value
@@ -124,11 +178,8 @@ directive.
 #### Example
 
 ```yaml
-# context.toa.yaml
-
-/exposition:
-  /commits/:user-id:
-    role: developer:senior
+/commits/:user-id:
+  role: developer:senior
 ```
 
 The example above defines a `role` directive with the specified `developer:senior` Role Scope.

package/documentation/authorities.md

@@ -17,16 +17,9 @@ exposition:
     two: the.two.com
 ```
 
-## Ingress
+## Mappings
 
-Each host in the authority definition is used to create a Kubernetes Ingress resource.
-
-> If the application is accessed with the `:authority` that does not match the authority definition,
-> the response with `404` status code is returned.
-
-## Embedding
-
-To pass the requested authority to the operation call, [`vary:embed` directive](vary.md#embeddings)
+To pass the requested authority to the operation call, [`map:authority` directive](map.md#authority)
 can be used.
 
 ```yaml
@@ -35,11 +28,13 @@ can be used.
 exposition:
   /:
     GET:
-      vary:embed:
-        app: authority
+      map:authority: hostname
       endpoint: observe
 ```
 
+If the value of the `authority` pseudo-header is not present in the `authorities` definition,
+then the value is embedded as is.
+
 ## Identity
 
 Credentials stored or issued by the [authentication system](identity.md) are associated with an

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: []
+```