@toa.io/extensions.exposition 1.0.0-alpha.253 → 1.0.0-alpha.256

package/components/identity.tokens/source/authenticate.test.ts

@@ -12,9 +12,10 @@ const authority = generate()
 
 beforeEach(() => {
   configuration = {
-    keys: {
-      key0: 'k3.local.m28p8SrbS467t-2IUjQuSOqmjvi24TbXhyjAW_dOrog'
-    },
+    keys: [
+      { id: 'key0', key: 'sTxL6qVOadKkUJwh3FveU53XgTEo3Sdfg7k2FfiIKfs' },
+      { id: 'legacy0', key: 'k3.local.m28p8SrbS467t-2IUjQuSOqmjvi24TbXhyjAW_dOrog', format: 'paseto' }
+    ],
     lifetime: 2592000,
     refresh: 600,
     cache: {

package/components/identity.tokens/source/decrypt.test.ts

@@ -1,4 +1,5 @@
 import { generate } from 'randomstring'
+import { V3 } from 'paseto'
 import { Effect as Encrypt } from './encrypt'
 import { Computation as Decrypt } from './decrypt'
 import { type Configuration, type Context, type Identity } from './lib'
@@ -8,15 +9,17 @@ let context: Context
 let encrypt: Encrypt
 let decrypt: Decrypt
 
-const remote = { identity: { keys: null } }
+const remote = { identity: { keys: { observe: jest.fn(async () => null) } } }
 const authority = generate()
 
 beforeEach(() => {
   configuration = {
-    keys: {
-      key0: 'k3.local.m28p8SrbS467t-2IUjQuSOqmjvi24TbXhyjAW_dOrog',
-      key1: 'k3.local.-498jfWenrZH-Dqw3-zQJih_hKzDgBgUMfe37OCqSOA'
-    },
+    keys: [
+      { id: 'key0', key: 'sTxL6qVOadKkUJwh3FveU53XgTEo3Sdfg7k2FfiIKfs' },
+      { id: 'key1', key: '5I0iSKw3yfBkQ4AXfA8eR-tWR0Q1dpn4x3bPrPzHkP0' },
+      { id: 'legacy0', key: 'k3.local.m28p8SrbS467t-2IUjQuSOqmjvi24TbXhyjAW_dOrog', format: 'paseto' },
+      { id: 'legacy1', key: 'k3.local.-498jfWenrZH-Dqw3-zQJih_hKzDgBgUMfe37OCqSOA', format: 'paseto' }
+    ],
     lifetime: 1000,
     refresh: 500,
     cache: {
@@ -51,9 +54,7 @@ it('should decrypt', async () => {
 it('should decrypt with key1', async () => {
   const k1context = {
     configuration: {
-      keys: {
-        key1: configuration.keys.key1
-      }
+      keys: [configuration.keys[1]]
     }
   } as unknown as Context
 
@@ -72,3 +73,63 @@ it('should decrypt with key1', async () => {
 
   expect(decrypted).toMatchObject({ identity, refresh: true })
 })
+
+it('should decrypt legacy PASETO and require refresh', async () => {
+  const identity: Identity = { id: generate(), roles: [] }
+
+  const token = await V3.encrypt({ iss: authority, identity }, configuration.keys[2].key, {
+    footer: { kid: 'legacy0' }
+  })
+
+  await expect(decrypt.execute(token)).resolves.toMatchObject({
+    iss: authority,
+    identity,
+    refresh: true
+  })
+})
+
+it('should separate JWE and PASETO keys with the same id by format', async () => {
+  configuration.keys[2].id = 'key0'
+
+  decrypt = new Decrypt()
+  decrypt.mount(context)
+
+  const identity: Identity = { id: generate(), roles: [] }
+
+  const token = await V3.encrypt({ iss: authority, identity }, configuration.keys[2].key, {
+    footer: { kid: 'key0' }
+  })
+
+  await expect(decrypt.execute(token)).resolves.toMatchObject({ identity, refresh: true })
+})
+
+it('should reject a tampered JWE', async () => {
+  const token = await encrypt.execute({
+    authority,
+    identity: { id: generate(), roles: [] }
+  })
+
+  if (token instanceof Error)
+    throw token
+
+  const parts = token.split('.')
+
+  parts[3] = (parts[3].startsWith('A') ? 'B' : 'A') + parts[3].slice(1)
+
+  const tampered = parts.join('.')
+
+  await expect(decrypt.execute(tampered)).resolves.toMatchObject({ code: 'INVALID_TOKEN' })
+})
+
+it('should reject JWE with an unknown key', async () => {
+  const token = await encrypt.execute({
+    authority,
+    identity: { id: generate(), roles: [] },
+    key: { id: 'missing', key: configuration.keys[0].key, label: 'missing' }
+  })
+
+  if (token instanceof Error)
+    throw token
+
+  await expect(decrypt.execute(token)).resolves.toMatchObject({ code: 'INVALID_KEY' })
+})

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

@@ -1,38 +1,52 @@
 import { V3 } from 'paseto'
 import { Err } from 'error-value'
 import { LRUCache } from 'lru-cache'
+import { jweKey } from './lib'
+import { load } from './lib/jose'
 import type { Maybe, Operation } from '@toa.io/types'
-import type { Context, Claims, DecryptOutput } from './lib'
+import type { Context, Claims, DecryptOutput, JWEClaims } from './lib'
 
 export class Computation implements Operation {
-  private keys: Record<string, Key> = {}
+  private readonly keys: Record<string, Key> = {}
+  private readonly legacy: Record<string, Key> = {}
   private cache!: LRUCache<string, KeyEntry>
   private latest!: string
   private remote!: Context['remote']['identity']['keys']
   private logs!: Context['logs']
 
   public mount (context: Context): void {
-    this.latest = Object.keys(context.configuration.keys)[0]
+    const latest = context.configuration.keys.find(({ format }) => format !== 'paseto')
+
+    if (latest === undefined)
+      throw new TypeError('At least one JWE key must be configured')
+
+    this.latest = latest.id
     this.remote = context.remote.identity.keys
     this.cache = new LRUCache<string, KeyEntry>(context.configuration.cache)
     this.logs = context.logs
 
-    for (const [kid, key] of Object.entries(context.configuration.keys))
-      this.keys[kid] = { key }
+    for (const { id, key, format } of context.configuration.keys) {
+      const branch = format === 'paseto' ? this.legacy : this.keys
+
+      branch[id] = { key }
+    }
   }
 
   public async execute (token: string): Promise<Maybe<DecryptOutput>> {
-    const kid = this.kid(token)
+    const legacy = token.startsWith('v3.local.')
+    const kid = legacy ? this.pasetoKid(token) : await this.jweKid(token)
 
     if (kid instanceof Error)
       return kid
 
-    const key = await this.key(kid)
+    const key = await this.key(kid, legacy)
 
     if (key instanceof Error)
       return key
 
-    const claims = await decrypt(token, key.key)
+    const claims = legacy
+      ? await decryptPaseto(token, key.key)
+      : await decryptJWE(token, key.key)
 
     if (claims instanceof Error)
       return claims
@@ -47,11 +61,11 @@ export class Computation implements Operation {
       iat: claims.iat,
       exp: claims.exp,
       identity: claims.identity,
-      refresh: kid !== this.latest && key.identity === undefined
+      refresh: legacy || (kid !== this.latest && key.identity === undefined)
     }
   }
 
-  private kid (token: string): Maybe<string> {
+  private pasetoKid (token: string): Maybe<string> {
     const [, , , footer] = token.split('.')
 
     if (footer === undefined)
@@ -70,9 +84,26 @@ export class Computation implements Operation {
     }
   }
 
-  private async key (kid: string): Promise<Maybe<Key>> {
-    if (kid in this.keys)
-      return this.keys[kid]
+  private async jweKid (token: string): Promise<Maybe<string>> {
+    try {
+      const { decodeProtectedHeader } = await load()
+      const header = decodeProtectedHeader(token)
+
+      if (header.alg !== 'dir' || header.enc !== 'A256GCM' || header.typ !== 'JWT' ||
+        typeof header.kid !== 'string')
+        return ERR_INVALID_TOKEN
+
+      return header.kid
+    } catch {
+      return ERR_INVALID_TOKEN
+    }
+  }
+
+  private async key (kid: string, legacy: boolean): Promise<Maybe<Key>> {
+    const configured = legacy ? this.legacy : this.keys
+
+    if (kid in configured)
+      return configured[kid]
 
     if (!this.cache.has(kid)) {
       const value = await this.remote.observe({ query: { id: kid } })
@@ -86,7 +117,7 @@ export class Computation implements Operation {
   }
 }
 
-async function decrypt (token: string, key: string): Promise<Maybe<Claims>> {
+async function decryptPaseto (token: string, key: string): Promise<Maybe<Claims>> {
   try {
     return await V3.decrypt<Claims>(token, key)
   } catch {
@@ -94,6 +125,33 @@ async function decrypt (token: string, key: string): Promise<Maybe<Claims>> {
   }
 }
 
+async function decryptJWE (token: string, key: string): Promise<Maybe<Claims>> {
+  try {
+    const { jwtDecrypt } = await load()
+
+    const { payload } = await jwtDecrypt<JWEClaims>(token, jweKey(key), {
+      keyManagementAlgorithms: ['dir'],
+      contentEncryptionAlgorithms: ['A256GCM']
+    })
+
+    if (typeof payload.iss !== 'string' || typeof payload.iat !== 'number' ||
+      typeof payload.identity !== 'object' || payload.identity === null)
+      return ERR_INVALID_TOKEN
+
+    if (payload.exp !== undefined && payload.exp * 1000 <= Date.now())
+      return ERR_INVALID_TOKEN
+
+    return {
+      iss: payload.iss,
+      iat: new Date(payload.iat * 1000).toISOString(),
+      ...(payload.exp === undefined ? {} : { exp: new Date(payload.exp * 1000).toISOString() }),
+      identity: payload.identity
+    }
+  } catch {
+    return ERR_INVALID_TOKEN
+  }
+}
+
 interface Key {
   key: string
   identity?: string

package/components/identity.tokens/source/encrypt.test.ts

@@ -17,9 +17,10 @@ const authority = generate()
 
 beforeEach(() => {
   context.configuration = {
-    keys: {
-      key0: 'k3.local.m28p8SrbS467t-2IUjQuSOqmjvi24TbXhyjAW_dOrog'
-    },
+    keys: [
+      { id: 'key0', key: 'sTxL6qVOadKkUJwh3FveU53XgTEo3Sdfg7k2FfiIKfs' },
+      { id: 'legacy0', key: 'k3.local.m28p8SrbS467t-2IUjQuSOqmjvi24TbXhyjAW_dOrog', format: 'paseto' }
+    ],
     lifetime: 1,
     refresh: 2,
     cache: {
@@ -35,6 +36,32 @@ beforeEach(() => {
   decrypt.mount(context)
 })
 
+it('should use the first encryption key as active and expose its id as kid', async () => {
+  context.configuration.keys.unshift({
+    id: 'legacy-first',
+    key: 'k3.local.m28p8SrbS467t-2IUjQuSOqmjvi24TbXhyjAW_dOrog',
+    format: 'paseto'
+  })
+  context.configuration.keys.push({
+    id: 'key1',
+    key: '5I0iSKw3yfBkQ4AXfA8eR-tWR0Q1dpn4x3bPrPzHkP0'
+  })
+
+  encrypt.mount(context)
+
+  const encrypted = await encrypt.execute({
+    authority,
+    identity: { id: generate(), roles: [] }
+  })
+
+  if (encrypted instanceof Error)
+    throw encrypted
+
+  const header = JSON.parse(Buffer.from(encrypted.split('.')[0], 'base64url').toString())
+
+  expect(header).toMatchObject({ kid: 'key0', alg: 'dir', enc: 'A256GCM' })
+})
+
 it('should encrypt with configured lifetime by default', async () => {
   const identity: Identity = { id: generate(), roles: [] }
 

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

@@ -1,29 +1,31 @@
-import { V3 } from 'paseto'
 import { Err } from 'error-value'
+import { jweKey } from './lib'
+import { load } from './lib/jose'
 import type { Operation, Maybe } from '@toa.io/types'
-import type { Identity, Claims, Context, EncryptInput, Key } from './lib'
+import type { Identity, Context, EncryptInput, Key } from './lib'
 
 export class Effect implements Operation {
   private key!: Pick<Key, 'id' | 'key'>
   private lifetime!: number
 
   public mount (context: Context): void {
-    const [id, secret] = Object.entries(context.configuration.keys)[0]
+    const key = context.configuration.keys.find(({ format }) => format !== 'paseto')
 
-    this.key = { id, key: secret }
+    if (key === undefined)
+      throw new TypeError('At least one JWE key must be configured')
+
+    this.key = key
     this.lifetime = context.configuration.lifetime * 1000
   }
 
   public async execute (input: EncryptInput): Promise<Maybe<string>> {
+    const { EncryptJWT } = await load()
+
     if (input.scopes?.some((scope) => !within(scope, input.identity.roles)) === true)
       return ERR_INACCESSIBLE_SCOPE
 
     const lifetime = input.lifetime === undefined ? this.lifetime : (input.lifetime * 1000)
 
-    const exp = lifetime === 0
-      ? undefined
-      : new Date(Date.now() + lifetime).toISOString()
-
     const identity: Identity = {
       id: input.identity.id,
       roles: input.scopes ?? input.identity.roles
@@ -32,17 +34,17 @@ export class Effect implements Operation {
     if (input.permissions !== undefined)
       identity.permissions = input.permissions
 
-    const payload: Partial<Claims> = {
-      identity,
-      iss: input.authority
-    }
+    const key = input.key ?? this.key
 
-    if (exp !== undefined)
-      payload.exp = exp
+    let token = new EncryptJWT({ identity })
+      .setProtectedHeader({ alg: 'dir', enc: 'A256GCM', typ: 'JWT', kid: key.id })
+      .setIssuer(input.authority)
+      .setIssuedAt(Date.now() / 1000)
 
-    const key = input.key ?? this.key
+    if (lifetime !== 0)
+      token = token.setExpirationTime((Date.now() + lifetime) / 1000)
 
-    return await V3.encrypt(payload, key.key, { footer: { kid: key.id } })
+    return await token.encrypt(jweKey(key.key))
   }
 }
 

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

@@ -1,2 +1,3 @@
 export * from './pad'
 export * from './types'
+export { jweKey } from './key'

package/components/identity.tokens/source/lib/jose.d.ts

@@ -0,0 +1 @@
+export function load (): Promise<typeof import('jose')>

package/components/identity.tokens/source/lib/jose.js

@@ -0,0 +1,5 @@
+'use strict'
+
+const load = async () => await import('jose')
+
+exports.load = load

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

@@ -0,0 +1,8 @@
+export function jweKey (value: string): Uint8Array {
+  const key = Buffer.from(value, 'base64url')
+
+  if (key.length !== 32 || key.toString('base64url') !== value)
+    throw new TypeError('JWE key must be a base64url-encoded 256-bit secret')
+
+  return new Uint8Array(key)
+}

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

@@ -22,7 +22,7 @@ export interface Context {
 }
 
 export interface Configuration {
-  readonly keys: Record<string, string>
+  readonly keys: ConfiguredKey[]
   readonly lifetime: number
   readonly refresh: number
   readonly cache: {
@@ -31,6 +31,10 @@ export interface Configuration {
   }
 }
 
+export interface ConfiguredKey extends Pick<Key, 'id' | 'key'> {
+  format?: 'jwe' | 'paseto'
+}
+
 export interface Entity {
   revokedAt?: number
 }
@@ -75,6 +79,13 @@ export interface Claims {
   exp?: string
 }
 
+export interface JWEClaims {
+  identity: Identity
+  iss: string
+  iat: number
+  exp?: number
+}
+
 export interface Key {
   id: string
   key: string

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/documentation/authorities.md

@@ -19,7 +19,7 @@ exposition:
 
 ## Mappings
 
-To pass the requested authority to the operation call, [`map:authority` directive](map#embeddings)
+To pass the requested authority to the operation call, [`map:authority` directive](map.md#authority)
 can be used.
 
 ```yaml

package/documentation/components.md

@@ -128,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
@@ -142,10 +144,8 @@ 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>
 ```
 
 ## Local tokens
@@ -187,6 +187,7 @@ accept: application/yaml
 content-type: application/yaml
 
 lifetime: 3600
+label: CI deployment token
 scopes: [app:developer]
 permissions:
   /users/fc8e66dd/: [GET, PUT]
@@ -197,6 +198,8 @@ permissions:
 201 Created
 content-type: application/yaml
 
+kid: <key-id>
+exp: <unix-time-ms>
 token: <token>
 ```
 
@@ -204,6 +207,7 @@ token: <token>
   (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)
@@ -223,19 +227,35 @@ DELETE /identity/keys/<identity>/<key.id>/
 authorization: ...
 ```
 
-Token secret key `id` can be obtained from the list of issued tokens (or from the footer of the
-token itself).
+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 first key from the `keys` configuration value.
+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
@@ -243,10 +263,15 @@ using the first key from the `keys` configuration value.
 configuration:
   identity.tokens:
     keys:
-      2024q1: $TOKEN_SECRET_2024Q1
+      - id: 2026q3
+        key: $IDENTITY_TOKENS_ENCRYPTION_KEY0
+      - id: legacy
+        key: $IDENTITY_TOKENS_KEY0
+        format: paseto
 ```
 
-At least one key in the `keys` 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).
 
@@ -279,48 +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 first key from the `keys` configuration value,
-and decrypted by the key used to encrypt them.
+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`.
 
-To rotate the secret key, a new key must be added to the top of the `keys` configuration value, that
-is, it will be used to encrypt new tokens.
+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 be removed only after the `refresh` period of the previously issued tokens has
-expired.
+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 from the configuration only when the `refresh` period after
-> the new key `2024Q2` was added has expired.
+> 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/`
@@ -361,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/