@venizia/ignis-docs 0.2.1-0 → 0.2.1-1

package/content/extensions/components/authentication/api.md

@@ -10,9 +10,21 @@ Every option, binding key, class, and method the Authentication component expose
 
 **Files:**
 
-- [`packages/core/src/components/auth/authenticate/`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authenticate) - component, services, strategies, controllers
-- [`packages/core/src/components/auth/models/`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/models) - entity column helpers + request schemas
-- [`packages/core/src/components/auth/base/abstract-auth-registry.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/base/abstract-auth-registry.ts) - `AbstractAuthRegistry`
+- [`packages/core-server/src/components/auth/authenticate/`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authenticate) - component, services, strategies, controllers
+- [`packages/core-server/src/components/auth/models/`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/models) - entity column helpers + request schemas
+- [`packages/core-server/src/components/auth/base/abstract-auth-registry.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/base/abstract-auth-registry.ts) - `AbstractAuthRegistry`
+
+## Find what you need
+
+| You want to | Go to |
+|---|---|
+| See how the pieces fit together | [Architecture](#architecture) |
+| Look up a binding key or option field | [Binding keys](#binding-keys), [Option interfaces](#option-interfaces) |
+| Check what `IAuthUser` / `IAuthService` require | [IAuthUser / IJWTTokenPayload](#iauthuser-ijwttokenpayload), [IAuthService](#iauthservice) |
+| Understand the JWS/JWKS/Basic class hierarchy | [Service class hierarchy](#service-class-hierarchy) |
+| Register or resolve a strategy programmatically | [Strategy registry](#strategy-registry) |
+| See exactly what the built-in `/auth` controller builds | [Controller factory](#controller-factory) |
+| Find a file on disk | [File structure](#file-structure) |
 
 ## Import paths
 
@@ -26,6 +38,7 @@ import {
   AuthenticationModes,
   AuthenticationTokenTypes,
   AuthenticationStrategyRegistry,
+  ServiceAssertion,
 
   // JOSE standards + constants
   JOSEStandards,
@@ -38,6 +51,7 @@ import {
   JWKSIssuerAuthenticationStrategy,
   JWKSVerifierAuthenticationStrategy,
   BasicAuthenticationStrategy,
+  ServiceAuthenticationStrategy,
 
   // Services
   AbstractBearerTokenService,
@@ -69,6 +83,9 @@ import type {
   IJWKSVerifierOptions,
   TJWKSTokenServiceOptions,
   TBasicTokenServiceOptions,
+  IServiceAuthOptions,
+  IServiceAssertionClaims,
+  TServiceCallerEntry,
   IAuthenticateOptions,
   IAuthUser,
   IJWTTokenPayload,
@@ -134,13 +151,14 @@ Bearer token service hierarchy:
 | Method | Purpose |
 |--------|---------|
 | `defineJWSAuth(opts)` | Validates `jwtSecret` and `getTokenExpiresFn`, binds `IJWSTokenServiceOptions` to `JWT_OPTIONS`, registers `JWSTokenService` |
-| `defineJWKSAuth(opts)` | Switches on `mode`. Issuer: validates keys/format/kid/getTokenExpiresFn, binds to `JWKS_OPTIONS`, registers `JWKSIssuerTokenService` + `JWKSController`. Verifier: validates `jwksUrl`, binds to `JWKS_OPTIONS`, registers `JWKSVerifierTokenService` |
+| `defineJWKSAuth(opts)` | Switches on `mode`.<br>**Issuer:** validates keys/format/kid/getTokenExpiresFn, binds to `JWKS_OPTIONS`, registers `JWKSIssuerTokenService` + `JWKSController`.<br>**Verifier:** validates `jwksUrl`, binds to `JWKS_OPTIONS`, registers `JWKSVerifierTokenService` |
+| `defineServiceAuth(opts)` | Validates `name` and `resolvePrincipal`, registers the verifier and the `service` strategy. With `keys` present it also registers the signer and mounts the certs route. Absent options: does nothing |
 | `defineBasicAuth(opts)` | Validates `verifyCredentials` presence, registers `BasicTokenService`. Skips (debug log) if `basicOptions` not bound |
 | `defineControllers(opts)` | Requires `jwtOptions` when `useAuthController: true`. Calls `defineAuthController()` and registers the generated controller |
 | `defineOAuth2()` | Public stub, called during `binding()`, performs no action - not yet implemented |
 
 > [!NOTE]
-> The component reads the discriminated union from `JWT_OPTIONS`, then re-binds just the inner options object (`IJWSTokenServiceOptions` or `IJWKSIssuerOptions`/`IJWKSVerifierOptions`) to `JWKS_OPTIONS` or back to `JWT_OPTIONS`, so the token service can resolve it via a plain `@inject`.
+> The component reads the discriminated union from `JWT_OPTIONS`. It then re-binds only the inner options object - `IJWSTokenServiceOptions`, or `IJWKSIssuerOptions`/`IJWKSVerifierOptions` - to `JWKS_OPTIONS` or back to `JWT_OPTIONS`. The token service resolves it with a plain `@inject`.
 
 ## Binding keys
 
@@ -150,9 +168,11 @@ Bearer token service hierarchy:
 | `AuthenticateBindingKeys.JWT_OPTIONS` | `@app/authenticate/jwt-options` | `TJWTTokenServiceOptions` | Conditional | -- |
 | `AuthenticateBindingKeys.JWKS_OPTIONS` | `@app/authenticate/jwks-options` | `IJWKSIssuerOptions \| IJWKSVerifierOptions` | Internal | Bound by the component from `JWT_OPTIONS` |
 | `AuthenticateBindingKeys.BASIC_OPTIONS` | `@app/authenticate/basic-options` | `TBasicTokenServiceOptions` | Conditional | -- |
+| `AuthenticateBindingKeys.SERVICE_OPTIONS` | `@app/authenticate/service-options` | `IServiceAuthOptions` | Conditional | -- |
+| `AuthenticateBindingKeys.SERVICE_CERTS_PATH` | `@app/authenticate/service-certs-path` | `string` | Internal | Bound by the component from `serviceOptions.rest.path` |
 
 > [!IMPORTANT]
-> At least one of `JWT_OPTIONS` or `BASIC_OPTIONS` must be bound, or `AuthenticateComponent.binding()` throws.
+> At least one of `JWT_OPTIONS`, `BASIC_OPTIONS` or `SERVICE_OPTIONS` must be bound, or `AuthenticateComponent.binding()` throws. A service that only VERIFIES assertions needs neither jwt nor basic.
 
 ## Option interfaces
 
@@ -178,9 +198,11 @@ type TJWKSTokenServiceOptions = IJWKSIssuerOptions | IJWKSVerifierOptions; // di
 | `aesAlgorithm` | `AESAlgorithmType` | `'aes-256-cbc'` | No | AES algorithm for payload encryption |
 | `headerAlgorithm` | `string` | `'HS256'` | No | JWT signing algorithm |
 | `fieldCodecs` | `IPayloadFieldCodec[]` | `[]` | No | Custom serialize/deserialize per field name |
+| `verify` | `IJWTVerifyOptions` | -- | No | Claim checks on verify: `audience`, `issuer`, `subject`, `algorithms`, `clockTolerance`, `maxTokenAge`, `typ`, `requiredClaims`. Unset means signature and time claims only |
+| `sign` | `{ issuer?, audience? }` | -- | No | Claims stamped on every issued token. A configured value WINS over one supplied in the payload |
 
 > [!WARNING]
-> `jwtSecret` is mandatory - the component throws if it is missing or equals the placeholder `'unknown_secret'`. `applicationSecret` is optional: when omitted, the JWT payload is standard plaintext; standard fields (`iss`, `sub`, `aud`, `jti`, `nbf`, `exp`, `iat`) are never encrypted either way.
+> `jwtSecret` is mandatory - the component throws if it's missing or equals the placeholder `'unknown_secret'`. `applicationSecret` is optional. When you omit it, the JWT payload stays standard plaintext. Standard fields (`iss`, `sub`, `aud`, `jti`, `nbf`, `exp`, `iat`) are never encrypted either way.
 
 ### IJWKSIssuerOptions
 
@@ -198,6 +220,8 @@ type TJWKSTokenServiceOptions = IJWKSIssuerOptions | IJWKSVerifierOptions; // di
 | `aesAlgorithm` | `AESAlgorithmType` | `'aes-256-cbc'` | No | AES algorithm for payload encryption |
 | `applicationSecret` | `string` | -- | No | Enables AES payload field encryption when set |
 | `fieldCodecs` | `IPayloadFieldCodec[]` | `[]` | No | Custom serialize/deserialize per field name |
+| `verify` | `IJWTVerifyOptions` | -- | No | Claim checks on verify: `audience`, `issuer`, `subject`, `algorithms`, `clockTolerance`, `maxTokenAge`, `typ`, `requiredClaims`. Unset means signature and time claims only |
+| `sign` | `{ issuer?, audience? }` | -- | No | Claims stamped on every issued token. A configured value WINS over one supplied in the payload |
 
 ### IJWKSVerifierOptions
 
@@ -210,6 +234,7 @@ type TJWKSTokenServiceOptions = IJWKSIssuerOptions | IJWKSVerifierOptions; // di
 | `aesAlgorithm` | `AESAlgorithmType` | `'aes-256-cbc'` | No | AES algorithm for payload decryption |
 | `applicationSecret` | `string` | -- | No | Must match the issuer's secret to decrypt payloads |
 | `fieldCodecs` | `IPayloadFieldCodec[]` | `[]` | No | Must match the issuer's codecs to decrypt custom fields |
+| `verify` | `IJWTVerifyOptions` | -- | No | Claim checks on verify: `audience`, `issuer`, `subject`, `algorithms`, `clockTolerance`, `maxTokenAge`, `typ`, `requiredClaims`. Unset means signature and time claims only |
 
 > [!IMPORTANT]
 > `JWKSVerifierTokenService` cannot sign tokens - `getSigner()`, `getSigningKey()`, and `getDefaultTokenExpiresFn()` all throw. Only `verify()` and `extractCredentials()` are functional.
@@ -254,7 +279,7 @@ type TRouteAuthenticateConfig =
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `authenticate.strategies` | `TAuthStrategy[]` | -- | Strategy names to try, e.g. `['jwt']`, `['jwt', 'basic']` |
+| `authenticate.strategies` | `TAuthStrategy[]` | -- | Strategy names to try - for example, `['jwt']` or `['jwt', 'basic']`. Any name you register works too; `'jwt'` and `'basic'` are the ones the framework ships |
 | `authenticate.mode` | `'any' \| 'all'` | `'any'` | `'any'`: first success wins. `'all'`: every strategy must pass |
 | `authenticate.skip` | `true` | -- | Skips authentication for this route entirely |
 
@@ -400,7 +425,7 @@ export const authenticate = (opts: { strategies: string[]; mode?: TAuthMode }) =
 5. On failure, throws `401`
 
 > [!NOTE]
-> `'any'` mode discards each failing strategy's error (logs at debug) and only throws once every strategy is exhausted. `'all'` mode uses the **first** strategy's user payload as the identity source; if that payload has no `userId`, it throws `401` even though every strategy technically passed.
+> `'any'` mode logs each failing strategy at debug and discards the error. It only throws once every strategy is exhausted. `'all'` mode uses the **first** strategy's user payload as the identity source. If that payload has no `userId`, it throws `401` even though every strategy technically passed.
 
 ## Service class hierarchy
 
@@ -430,7 +455,7 @@ AbstractBearerTokenService<E>          (extends BaseService)
 
 ### AbstractBearerTokenService
 
-**File:** [`packages/core/src/components/auth/authenticate/services/bearer/abstract.service.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authenticate/services/bearer/abstract.service.ts)
+**File:** [`packages/core-server/src/components/auth/authenticate/services/bearer/abstract.service.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authenticate/services/bearer/abstract.service.ts)
 
 | Method | Signature | Description |
 |--------|-----------|-------------|
@@ -446,21 +471,26 @@ Static: `JWT_COMMON_FIELDS: Set<'iss'|'sub'|'aud'|'jti'|'nbf'|'exp'|'iat'>` - ne
 
 ### JWSTokenService
 
-**File:** [`packages/core/src/components/auth/authenticate/services/bearer/jws.service.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authenticate/services/bearer/jws.service.ts)
+**File:** [`packages/core-server/src/components/auth/authenticate/services/bearer/jws.service.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authenticate/services/bearer/jws.service.ts)
 
-Constructor validates `jwtSecret` and `getTokenExpiresFn` (throws `500` if missing), encodes the secret to `Uint8Array`, calls `configurePayloadEncryption()`. `doVerify` calls `jose.jwtVerify()` with the shared secret; `getSigner` signs with header `HS256` (or `headerAlgorithm` override).
+The constructor validates `jwtSecret` and `getTokenExpiresFn`, throwing `500` if either is missing. It encodes the secret to `Uint8Array` and calls `configurePayloadEncryption()`. `doVerify` calls `jose.jwtVerify()` with the shared secret. `getSigner` signs with header `HS256`, or `headerAlgorithm` if you set one.
 
 ### AbstractJWKSTokenService
 
-**File:** [`packages/core/src/components/auth/authenticate/services/bearer/jwks/abstract.service.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authenticate/services/bearer/jwks/abstract.service.ts)
+**File:** [`packages/core-server/src/components/auth/authenticate/services/bearer/jwks/abstract.service.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authenticate/services/bearer/jwks/abstract.service.ts)
 
-`ensureInitialized()` lazily runs `initialize()` on first call; concurrent callers share the pending promise. If `initialize()` rejects, the promise is reset so the next call retries instead of caching the failure.
+`ensureInitialized()` lazily runs `initialize()` on the first call. Concurrent callers share the pending promise. If `initialize()` rejects, the promise resets - the next call retries instead of caching the failure.
 
 ### JWKSIssuerTokenService
 
-**File:** [`packages/core/src/components/auth/authenticate/services/bearer/jwks/issuer.service.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authenticate/services/bearer/jwks/issuer.service.ts)
+**File:** [`packages/core-server/src/components/auth/authenticate/services/bearer/jwks/issuer.service.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authenticate/services/bearer/jwks/issuer.service.ts)
 
-`initialize()`: reads key content (file via `readFile` or inline text, per `keys.driver`) → imports it (`importPKCS8`/`importSPKI` for PEM, `importJWK` for JWK) → exports the public JWK with `kid`/`alg`/`use: 'sig'` → caches `{ keys: [publicJWK] }`.
+`initialize()` runs in order:
+
+1. Reads the key content - `readFile` for `keys.driver: 'file'`, inline text for `'text'`.
+2. Imports it - `importPKCS8`/`importSPKI` for PEM, `importJWK` for JWK.
+3. Exports the public JWK with `kid`, `alg`, and `use: 'sig'` set.
+4. Caches the result as `{ keys: [publicJWK] }`.
 
 | Method | Signature | Description |
 |--------|-----------|-------------|
@@ -469,13 +499,13 @@ Constructor validates `jwtSecret` and `getTokenExpiresFn` (throws `500` if missi
 
 ### JWKSVerifierTokenService
 
-**File:** [`packages/core/src/components/auth/authenticate/services/bearer/jwks/verifier.service.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authenticate/services/bearer/jwks/verifier.service.ts)
+**File:** [`packages/core-server/src/components/auth/authenticate/services/bearer/jwks/verifier.service.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authenticate/services/bearer/jwks/verifier.service.ts)
 
 `initialize()` calls `createRemoteJWKSet(jwksUrl, { cacheMaxAge: cacheTtlMs ?? 43_200_000, cooldownDuration: cooldownMs ?? 30_000 })`. `getSigner`/`getSigningKey`/`getDefaultTokenExpiresFn` all throw - this service is verify-only.
 
 ### BasicTokenService
 
-**File:** [`packages/core/src/components/auth/authenticate/services/basic/service.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authenticate/services/basic/service.ts)
+**File:** [`packages/core-server/src/components/auth/authenticate/services/basic/service.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authenticate/services/basic/service.ts)
 
 | Method | Signature | Description |
 |--------|-----------|-------------|
@@ -486,23 +516,28 @@ Constructor throws `500` if `verifyCredentials` is missing from the injected opt
 
 ## Strategy classes
 
-All four strategies extend `BaseHelper`, implement `IAuthenticationStrategy<E>`, and follow the same shape: a `name` field, a `standard` field (Bearer strategies only), one injected token service, and an `authenticate(context)` method that calls `extractCredentials()` then `verify()`.
+All four strategies extend `BaseHelper` and implement `IAuthenticationStrategy<E>`. Each one carries:
+
+- A `name` field.
+- A `standard` field (Bearer strategies only).
+- One injected token service.
+- An `authenticate(context)` method that calls `extractCredentials()`, then `verify()`.
 
 | Strategy | `name` | Injects | File |
 |----------|--------|---------|------|
-| `JWSAuthenticationStrategy` | `Authentication.STRATEGY_JWT` | `JWSTokenService` | [`strategies/jws.strategy.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authenticate/strategies/jws.strategy.ts) |
-| `JWKSIssuerAuthenticationStrategy` | `Authentication.STRATEGY_JWT` | `JWKSIssuerTokenService` | [`strategies/jwks.strategy.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authenticate/strategies/jwks.strategy.ts) |
+| `JWSAuthenticationStrategy` | `Authentication.STRATEGY_JWT` | `JWSTokenService` | [`strategies/jws.strategy.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authenticate/strategies/jws.strategy.ts) |
+| `JWKSIssuerAuthenticationStrategy` | `Authentication.STRATEGY_JWT` | `JWKSIssuerTokenService` | [`strategies/jwks.strategy.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authenticate/strategies/jwks.strategy.ts) |
 | `JWKSVerifierAuthenticationStrategy` | `Authentication.STRATEGY_JWT` | `JWKSVerifierTokenService` | same file |
-| `BasicAuthenticationStrategy` | `Authentication.STRATEGY_BASIC` | `BasicTokenService` | [`strategies/basic.strategy.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authenticate/strategies/basic.strategy.ts) |
+| `BasicAuthenticationStrategy` | `Authentication.STRATEGY_BASIC` | `BasicTokenService` | [`strategies/basic.strategy.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authenticate/strategies/basic.strategy.ts) |
 
 > [!NOTE]
-> Choose the strategy class matching your JOSE standard - `JWKSIssuerAuthenticationStrategy` and `JWKSVerifierAuthenticationStrategy` both register under the same `'jwt'` name, so a JWKS issuer service uses only one of the two.
+> Choose the strategy class that matches your JOSE standard. `JWKSIssuerAuthenticationStrategy` and `JWKSVerifierAuthenticationStrategy` both register under the same `'jwt'` name - use only one of the two per service.
 
 ## JWKSController
 
 Serves the JWKS endpoint (default path `/certs`, configurable via `rest.path`). Intentionally unauthenticated - it serves the public keys external verifiers need.
 
-**File:** [`packages/core/src/components/auth/authenticate/controllers/jwks/controller.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authenticate/controllers/jwks/controller.ts)
+**File:** [`packages/core-server/src/components/auth/authenticate/controllers/jwks/controller.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authenticate/controllers/jwks/controller.ts)
 
 ```typescript
 class JWKSController extends BaseRestController {
@@ -529,16 +564,16 @@ The component applies `@controller({ path })` to `JWKSController` dynamically at
 
 `defineAuthController(opts: TDefineAuthControllerOpts): typeof AuthController` builds a `BaseRestController` subclass at runtime.
 
-**File:** [`packages/core/src/components/auth/authenticate/controllers/factory.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authenticate/controllers/factory.ts)
+**File:** [`packages/core-server/src/components/auth/authenticate/controllers/factory.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authenticate/controllers/factory.ts)
 
 **How it works:**
 
 1. **Class creation.** `class AuthController extends BaseRestController {}` inside the factory closure, decorated with `@controller({ path: restPath })`, `isStrict: true`.
 2. **Service injection.** `inject({ key: serviceKey })(AuthController, undefined, 0)` is applied *after* class definition - the programmatic equivalent of decorating constructor parameter 0. The constructor throws `400` if the resolved service is falsy.
 3. **Routes.** Defined in `binding()` via `this.defineRoute()` - see the endpoint table in [Usage & Examples](./usage#api-endpoints).
-4. **Schemas.** Each endpoint uses `payload.<name>.{request,response}.schema` if provided, else a built-in default (or `AnyObjectSchema` for responses with no built-in schema).
+4. **Schemas.** Each endpoint uses `payload.<name>.{request,response}.schema` if you provide it. Otherwise it falls back to a built-in default, or `AnyObjectSchema` where there's no built-in schema for that response.
 
-Also exports `JWTTokenPayloadSchema`, the Zod schema backing `/who-am-i`'s response - extended at runtime with an optional `userInformation` field typed from `payload.getUserInformation.response.schema` (or `AnyObjectSchema`).
+Also exports `JWTTokenPayloadSchema`, the Zod schema backing `/who-am-i`'s response. It's extended at runtime with an optional `userInformation` field, typed from `payload.getUserInformation.response.schema` (or `AnyObjectSchema` if you don't provide one).
 
 ## Entity column helper types
 
@@ -564,13 +599,14 @@ type TPolicyDefinitionCommonColumns = {
   action: ReturnType<typeof text>;
   effect: ReturnType<typeof text>;
   domain: ReturnType<typeof text>;
+  metadata: ReturnType<typeof jsonb>;
 };
 ```
 
 ## File structure
 
 ```
-packages/core/src/components/auth/
+packages/core-server/src/components/auth/
 ├── authenticate/
 │   ├── common/
 │   │   ├── codecs.ts             # AuthenticationFieldCodecs (ROLES_CODEC, build() factory)

package/content/extensions/components/authentication/errors.md

@@ -8,10 +8,24 @@ difficulty: intermediate
 
 Every error message the Authentication component and its services throw, with cause and fix. See the [Overview](./) for initial setup.
 
+## Find what you need
+
+| Error is thrown by | Go to |
+|---|---|
+| Startup, while wiring the component | [AuthenticateComponent (startup)](#authenticatecomponent-startup) |
+| `verify`/`generate`/`extractCredentials`, shared by JWS, JWKS, and Basic | [Bearer token services (runtime)](#bearer-token-services-runtime) |
+| The `JWSTokenService` constructor | [JWSTokenService (constructor)](#jwstokenservice-constructor) |
+| `JWKSIssuerTokenService` init or key parsing | [JWKSIssuerTokenService (init + runtime)](#jwksissuertokenservice-init-runtime) |
+| `JWKSVerifierTokenService` signing calls | [JWKSVerifierTokenService (runtime)](#jwksverifiertokenservice-runtime) |
+| Basic auth credential decoding | [BasicTokenService (runtime)](#basictokenservice-runtime) |
+| "Descriptor not found" or a strategy registration issue | [AuthenticationStrategyRegistry (startup + runtime)](#authenticationstrategyregistry-startup-runtime) |
+| "Authentication failed" at request time | [AuthenticationProvider (runtime)](#authenticationprovider-runtime) |
+| The built-in `/auth` controller | [Auth controller factory](#auth-controller-factory) |
+
 - **Startup errors (400 unless noted)** come from `AuthenticateComponent.binding()` and stop the application before it serves traffic.
 - **Runtime errors (401)** come from request-time credential extraction, verification, or strategy exhaustion.
-- **Structural errors (500)** come from calling an unsupported operation (e.g. signing on a verify-only service) or accessing uninitialized state.
-- All of them go through `getError()`, which defaults `statusCode` to `400` when not given explicitly - so every "startup" error below is a 400 unless the table says otherwise.
+- **Structural errors (500)** come from calling an unsupported operation - signing on a verify-only service, for example - or accessing uninitialized state.
+- All of them go through `getError()`. It defaults `statusCode` to `400` when you don't set one - so every "startup" error below is a 400 unless the table says otherwise.
 
 ```mermaid
 flowchart LR
@@ -38,7 +52,7 @@ Thrown during `binding()` while validating options and wiring services.
 |---------|--------|-------|-----|
 | `[AuthenticateComponent] At least one of jwtOptions or basicOptions must be provided` | 400 | Neither `JWT_OPTIONS` nor `BASIC_OPTIONS` bound before `this.component(AuthenticateComponent)` | Bind at least one before registering the component - see [Setup](./#common-tasks) |
 | `[AuthenticateComponent] Unknown JOSE standard: {standard}` | 400 | `jwtOptions.standard` is not `'JWS'` or `'JWKS'` | Use `JOSEStandards.JWS` or `JOSEStandards.JWKS` |
-| `[defineJWSAuth] Invalid jwtSecret \| Provided: {jwtSecret}` | 400 | `jwtSecret` falsy or equals placeholder `'unknown_secret'` | Set a real secret, e.g. `APP_ENV_JWT_SECRET` |
+| `[defineJWSAuth] Invalid jwtSecret \| Provided: {jwtSecret}` | 400 | `jwtSecret` falsy or equals placeholder `'unknown_secret'` | Set a real secret - `APP_ENV_JWT_SECRET`, for example |
 | `[defineJWSAuth] getTokenExpiresFn is required` | 400 | `getTokenExpiresFn` missing from JWS options | Provide `() => Number(process.env.APP_ENV_JWT_EXPIRES_IN \|\| 86400)` |
 | `[defineJWKSAuth] keys.private and keys.public are required for issuer mode` | 400 | Issuer mode missing one or both keys | Provide `keys.private` and `keys.public` |
 | `[defineJWKSAuth] keys.format is required and must be one of: pem, jwk` | 400 | `keys.format` missing or invalid | Use `JWKSKeyFormats.PEM` or `JWKSKeyFormats.JWK` |
@@ -50,7 +64,7 @@ Thrown during `binding()` while validating options and wiring services.
 | `[defineControllers] Auth controller requires jwtOptions to be configured` | 400 | `useAuthController: true` but no `jwtOptions` bound | Bind `JWT_OPTIONS` before enabling the auth controller |
 
 > [!NOTE]
-> `applicationSecret` is optional and not validated. The component and every token service treat it as optional - omitting it simply disables AES payload encryption. It is never checked for presence.
+> `applicationSecret` is optional and not validated. Every token service treats it as optional - omitting it disables AES payload encryption, nothing more. Its presence is never checked.
 
 ## Bearer token services (runtime)
 
@@ -145,7 +159,7 @@ The middleware that executes strategies in the configured mode.
 | `Failed to identify authenticated user!` | 401 | `executeAllMode` | All strategies passed in `'all'` mode, but the first strategy's `userId` is falsy |
 | `Invalid authentication mode \| mode: {mode}` | 500 | `createAuthenticateMiddleware` | `mode` is not `'any'` or `'all'` |
 
-**Fix for "Authentication failed":** verify the client sends the right header (`Bearer <token>` or `Basic <base64>`); common causes are an expired token, a token signed with a different key, or the wrong strategy name in the route config.
+**Fix for "Authentication failed":** verify the client sends the right header - `Bearer <token>` or `Basic <base64>`. Common causes: an expired token, a token signed with a different key, or the wrong strategy name in the route config.
 
 ## Auth controller factory
 

package/content/extensions/components/authentication/index.md

@@ -6,7 +6,7 @@ difficulty: intermediate
 
 # Authentication
 
-`AuthenticateComponent` wires up JWT and/or Basic HTTP authentication - token services, route-level strategies, and an optional built-in `/auth` controller for sign-in, sign-up, and password change.
+`AuthenticateComponent` wires up JWT and/or Basic HTTP authentication. It configures token services, route-level strategies, and an optional built-in `/auth` controller for sign-in, sign-up, and password change.
 
 ## In one example
 
@@ -57,19 +57,20 @@ const SECURE_ROUTE = {
 
 ## How it works
 
-- **One component, three auth mechanisms.** `AuthenticateComponent.binding()` reads `JWT_OPTIONS` (JWS or JWKS, via a discriminated `standard` field) and `BASIC_OPTIONS` from the DI container and registers whichever token services their presence implies. At least one of the two must be bound, or the component throws at startup.
-- **Strategies are manual, on purpose.** The component registers *token services* (JWS/JWKS/Basic), not *strategies*. You register strategies yourself via `AuthenticationStrategyRegistry.getInstance().register(...)` after `this.component(AuthenticateComponent)` - this is what gives routes a `Authentication.STRATEGY_JWT` / `'basic'` name to reference.
-- **The registry is a DI-backed singleton.** `AuthenticationStrategyRegistry` binds each registered strategy into the container as a singleton under `authentication.strategy.<name>` and resolves it by name when a route's `authenticate.strategies` list is checked.
-- **`authenticate()` is the middleware entry point.** Route-level `authenticate: { strategies, mode }` config and the standalone `authenticate()` function both go through the same `AuthenticationProvider`, which tries strategies in `'any'` (first success wins) or `'all'` (every strategy must pass) mode and sets `Authentication.CURRENT_USER` on the Hono context.
-- **The auth controller is optional and generated.** Setting `REST_OPTIONS.useAuthController: true` calls `defineAuthController()`, which builds a `BaseRestController` subclass at runtime with `/sign-in`, `/sign-up`, `/change-password`, `/token/refresh`, `/who-am-i`, and `/me` routes, backed by your own `IAuthService` implementation.
+- **One component, three auth mechanisms.** `AuthenticateComponent.binding()` reads `JWT_OPTIONS` (JWS or JWKS) and `BASIC_OPTIONS` from the DI container, and registers the token services their presence implies.
+  - Bind at least one of the two - the component throws at startup if neither is set.
+- **Strategies are manual, on purpose.** The component registers *token services* - JWS, JWKS, Basic - never *strategies*. Register strategies yourself after the component, via `AuthenticationStrategyRegistry.getInstance().register(...)`.
+- **The registry is a DI-backed singleton.** `AuthenticationStrategyRegistry` binds each strategy into the container as a singleton, under the key `authentication.strategy.<name>`. A route's `authenticate.strategies` list references strategies by that same name.
+- **`authenticate()` is the middleware entry point.** Route-level `authenticate: { strategies, mode }` config and the standalone `authenticate()` function both run through the same `AuthenticationProvider`, which sets `Authentication.CURRENT_USER` on success. See [Multi-strategy authentication](./usage#multi-strategy-authentication) for what `'any'` and `'all'` mode do.
+- **The auth controller is optional and generated.** Set `REST_OPTIONS.useAuthController: true` to call `defineAuthController()`, which builds a `BaseRestController` subclass at runtime - routes for `/sign-in`, `/sign-up`, `/change-password`, `/token/refresh`, `/who-am-i`, and `/me`. You back it with your own `IAuthService` implementation.
 
 **JOSE standards**
 
 | Standard | Class | Keying | Use case |
 |----------|-------|--------|----------|
 | JWS | `JWSTokenService` | Shared secret (HS256) | Single service signs and verifies |
-| JWKS Issuer | `JWKSIssuerTokenService` | Private + public key (ES256/RS256/EdDSA) | This service issues tokens and serves `/certs` |
-| JWKS Verifier | `JWKSVerifierTokenService` | Remote JWKS URL | This service only verifies tokens from another issuer |
+| JWKS Issuer | `JWKSIssuerTokenService` | Private + public key (ES256/RS256/EdDSA) | Issues tokens, serves `/certs` |
+| JWKS Verifier | `JWKSVerifierTokenService` | Remote JWKS URL | Verifies tokens from another issuer, only |
 
 ## Common tasks
 
@@ -100,7 +101,7 @@ this.bind<TJWTTokenServiceOptions>({ key: AuthenticateBindingKeys.JWT_OPTIONS })
 });
 ```
 
-**Add Basic auth.** Provide a `verifyCredentials` callback; it becomes the `'basic'` strategy's source of truth.
+**Add Basic auth.** Provide a `verifyCredentials` callback. It becomes the `'basic'` strategy's source of truth.
 
 ```typescript
 this.bind<TBasicTokenServiceOptions>({ key: AuthenticateBindingKeys.BASIC_OPTIONS }).toValue({
@@ -128,7 +129,7 @@ this.bind<TAuthenticationRestOptions>({ key: AuthenticateBindingKeys.REST_OPTION
 });
 ```
 
-**Secure a route with multiple strategies.** `mode: 'any'` (default) falls back through strategies; `mode: 'all'` requires every one to pass.
+**Secure a route with multiple strategies.** `mode: 'any'` (default) falls back through strategies. `mode: 'all'` requires every one to pass.
 
 ```typescript
 const FALLBACK_AUTH_CONFIG = {
@@ -142,11 +143,11 @@ const FALLBACK_AUTH_CONFIG = {
 **Add auth entity columns to a Drizzle table.** Spread helper functions into `pgTable()` for User/Role/Permission/PolicyDefinition columns.
 
 ```typescript
-import { extraUserColumns } from '@venizia/ignis';
+import { extraUserColumns, generateIdColumnDefs, generateTzColumnDefs } from '@venizia/ignis';
 
 export const users = pgTable('users', {
-  ...withSerialId(),
-  ...withTimestamps(),
+  ...generateIdColumnDefs(),
+  ...generateTzColumnDefs(),
   ...extraUserColumns(),
   username: text('username').unique().notNull(),
 });
@@ -163,8 +164,8 @@ export const users = pgTable('users', {
 
 **Files:**
 
-- [`packages/core/src/components/auth/authenticate/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authenticate/component.ts) - `AuthenticateComponent`
-- [`packages/core/src/components/auth/authenticate/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authenticate/common/types.ts) - all option interfaces
-- [`packages/core/src/components/auth/authenticate/common/keys.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authenticate/common/keys.ts) - `AuthenticateBindingKeys`
-- [`packages/core/src/components/auth/authenticate/common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authenticate/common/constants.ts) - `Authentication`, `JOSEStandards`, `JWKSModes`, `JWKSKeyDrivers`, `JWKSKeyFormats`
-- [`packages/core/src/components/auth/models/entities`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/models/entities) - `extraUserColumns`, `extraRoleColumns`, `extraPermissionColumns`, `extraPolicyDefinitionColumns`
+- [`packages/core-server/src/components/auth/authenticate/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authenticate/component.ts) - `AuthenticateComponent`
+- [`packages/core-server/src/components/auth/authenticate/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authenticate/common/types.ts) - all option interfaces
+- [`packages/core-server/src/components/auth/authenticate/common/keys.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authenticate/common/keys.ts) - `AuthenticateBindingKeys`
+- [`packages/core-server/src/components/auth/authenticate/common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authenticate/common/constants.ts) - `Authentication`, `JOSEStandards`, `JWKSModes`, `JWKSKeyDrivers`, `JWKSKeyFormats`
+- [`packages/core-server/src/components/auth/models/entities`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/models/entities) - `extraUserColumns`, `extraRoleColumns`, `extraPermissionColumns`, `extraPolicyDefinitionColumns`

package/content/extensions/components/authentication/usage.md

@@ -8,6 +8,20 @@ difficulty: intermediate
 
 Task-oriented examples for the Authentication component. See the [Overview](./) for initial setup and the [API Reference](./api) for every option and class.
 
+## Find what you need
+
+| You want to | Go to |
+|---|---|
+| Require auth on a route, or make one public | [Securing routes](#securing-routes) |
+| Implement sign-in, sign-up, or change-password | [Implementing IAuthService](#implementing-iauthservice) |
+| Split issuer and verifier across services | [JWKS microservice patterns](#jwks-microservice-patterns) |
+| See what happens on each request, step by step | [Auth flows](#auth-flows) |
+| Accept both JWT and Basic on one route | [Multi-strategy authentication](#multi-strategy-authentication) |
+| Encrypt JWT payload fields | [Token encryption (optional AES)](#token-encryption-optional-aes) |
+| Read `CURRENT_USER` in a handler, with types | [Hono context extension](#hono-context-extension) |
+| Call the built-in `/auth` endpoints | [API endpoints](#api-endpoints) |
+| Add auth columns to a Drizzle table | [Entity column helpers](#entity-column-helpers) |
+
 ## Securing routes
 
 **Require one strategy.** Add `authenticate` to the route config.
@@ -21,7 +35,7 @@ const SECURE_ROUTE_CONFIG = {
 } as const;
 ```
 
-**Accept multiple strategies with fallback.** `mode: 'any'` (default) tries each in order; the first success wins.
+**Accept multiple strategies with fallback.** `mode: 'any'` (default) tries each strategy in order. The first success wins.
 
 ```typescript
 const FALLBACK_AUTH_CONFIG = {
@@ -43,7 +57,7 @@ const PUBLIC_ROUTE_CONFIG = {
 } as const;
 ```
 
-**Use `authenticate()` as raw Hono middleware.** Outside of route configs - e.g. for a plain Hono sub-app.
+**Use `authenticate()` as raw Hono middleware.** Use this outside route configs - for a plain Hono sub-app, for example.
 
 ```typescript
 import { authenticate, Authentication, AuthenticationModes } from '@venizia/ignis';
@@ -83,7 +97,7 @@ const conditionalAuthMiddleware = createMiddleware(async (c, next) => {
 
 ## Implementing IAuthService
 
-The built-in auth controller (`useAuthController: true`) delegates every route to a service you provide, implementing `IAuthService`.
+The built-in auth controller (`useAuthController: true`) delegates every route to a service you provide. That service implements `IAuthService`.
 
 **JWS-backed service.**
 
@@ -130,7 +144,7 @@ constructor(
 ) { super({ scope: AuthenticationService.name }); }
 ```
 
-**Implement `refreshToken` (optional).** Re-issues a token from the currently valid one - there is no separate refresh token.
+**Implement `refreshToken` (optional).** It re-issues a token from the caller's currently valid one. IGNIS has no separate refresh token.
 
 ```typescript
 async refreshToken(context: TContext<Env>): Promise<{ token: string }> {
@@ -257,8 +271,8 @@ sequenceDiagram
 
 | Mode | Behavior | Use case |
 |------|----------|----------|
-| `'any'` (default) | Strategies tried in order; first success wins; failures discarded (debug log); `401` with the tried-strategy list only if all fail | Fallback auth (JWT primary, Basic for legacy clients) |
-| `'all'` | Every strategy must pass; first failure rejects immediately; the **first** strategy's user payload is the identity source | Multi-factor authentication |
+| `'any'` (default) | Tried in order.<br>First success wins.<br>Failures are logged at debug, not returned.<br>All fail -> `401` listing the tried strategies. | Fallback auth (JWT primary, Basic for legacy clients) |
+| `'all'` | Every strategy must pass.<br>First failure rejects immediately.<br>The **first** strategy's user payload is the identity source. | Multi-factor authentication |
 
 ```mermaid
 flowchart TD
@@ -279,11 +293,16 @@ flowchart TD
 
 ## Token encryption (optional AES)
 
-- **Off by default.** AES payload encryption only activates when `applicationSecret` is set on the JWS/JWKS options - otherwise payloads are standard plaintext JWT.
-- **Standard fields untouched.** `iss`, `sub`, `aud`, `jti`, `nbf`, `exp`, `iat` are never encrypted, on either side.
-- **Everything else, key and value.** Every other payload field has both its key and its value AES-encrypted; `null`/`undefined` values are skipped.
-- **Serialization is `JSON.stringify` unless you supply a codec.** `AuthenticationFieldCodecs.ROLES_CODEC` is a ready-made codec that serializes `roles` as pipe-separated `id|identifier|priority` strings - it is opt-in, not automatic. Pass it via `fieldCodecs: [AuthenticationFieldCodecs.ROLES_CODEC]` if you want that format instead of the default JSON array.
-- **Secret must stay constant.** Changing `applicationSecret` invalidates every existing token. Issuer and verifier must share the identical secret (and identical `fieldCodecs`, if used).
+AES payload encryption is off by default. It only activates when you set `applicationSecret` on the JWS/JWKS options.
+
+| Aspect | Behavior |
+|---|---|
+| Default | Off. Without `applicationSecret`, payloads stay standard plaintext JWT. |
+| Standard fields | `iss`, `sub`, `aud`, `jti`, `nbf`, `exp`, `iat` are never encrypted, on either side. |
+| Other fields | Both the key and the value are AES-encrypted. `null` and `undefined` values are skipped. |
+| Serialization | `JSON.stringify` by default. Opt in to `AuthenticationFieldCodecs.ROLES_CODEC` for `roles` - it serializes as pipe-separated `id\|identifier\|priority` strings instead. |
+| Secret | Must stay constant. Changing `applicationSecret` invalidates every existing token. |
+| Issuer/verifier match | Both sides need the identical secret, and identical `fieldCodecs` if you use them. |
 
 ```typescript
 this.bind<TJWTTokenServiceOptions>({ key: AuthenticateBindingKeys.JWT_OPTIONS }).toValue({
@@ -331,7 +350,7 @@ The built-in auth controller exists only when `REST_OPTIONS.useAuthController: t
 | `GET` | `/certs` | No | JWKS endpoint (Issuer mode only) |
 
 > [!NOTE]
-> `/auth` is configurable via `controllerOpts.restPath`; `/certs` via `rest.path` in `IJWKSIssuerOptions`. `/certs` is intentionally unauthenticated.
+> `/auth` is configurable via `controllerOpts.restPath`. `/certs` is configurable via `rest.path` in `IJWKSIssuerOptions`, and is intentionally unauthenticated.
 
 **`POST /auth/sign-in`** - body defaults to `SignInRequestSchema` (nested `identifier`/`credential`), overridable via `payload.signIn`.
 
@@ -339,22 +358,22 @@ The built-in auth controller exists only when `REST_OPTIONS.useAuthController: t
 { "token": "eyJhbGciOiJFUzI1NiIsImtpZCI6Im15LWtleS1pZC0xIn0..." }
 ```
 
-**`POST /auth/sign-up`** - public unless `requireAuthenticatedSignUp: true`. Body defaults to a flat `SignUpRequestSchema` (`username`, `credential` - unlike sign-in's nested shape).
+**`POST /auth/sign-up`** - public unless `requireAuthenticatedSignUp: true`. Body defaults to a flat `SignUpRequestSchema` (`username`, `credential`) - unlike sign-in, the shape isn't nested.
 
 **`POST /auth/change-password`** - always requires JWT. Body defaults to `ChangePasswordRequestSchema` (`scheme`, `oldCredential`, `newCredential`, `userId`).
 
 **`POST /auth/token/refresh`** - always requires JWT, no request body. Returns `501` if `IAuthService.refreshToken` isn't implemented.
 
-**`GET /auth/who-am-i`** - always requires JWT. Query param `withUserInformation` (`true`/`false`/`1`/`0`, default `false`) attaches a `userInformation` field from `getUserInformation`; returns `501` if that method is truthy-requested but not implemented.
+**`GET /auth/who-am-i`** - always requires JWT. The `withUserInformation` query param (`true`, `false`, `1`, `0`; default `false`) attaches a `userInformation` field from `getUserInformation`. Returns `501` if you request that field without implementing `getUserInformation`.
 
 ```json
 { "userId": "123", "roles": [{ "id": "1", "identifier": "admin", "priority": 0 }] }
 ```
 
-**`GET /auth/me`** - always requires JWT. Delegates entirely to `getUserInformation(context, {})` - the response is not merged with the JWT payload. Returns `501` if not implemented.
+**`GET /auth/me`** - always requires JWT, delegating entirely to `getUserInformation(context, {})`. The response is not merged with the JWT payload. Returns `501` if `getUserInformation` isn't implemented.
 
 > [!TIP]
-> One `getUserInformation` implementation backs both routes: use `GET /me` for the raw profile, `GET /who-am-i?withUserInformation=true` to get it merged with the principal in one round-trip.
+> One `getUserInformation` implementation backs both routes. Use `GET /me` for the raw profile. Use `GET /who-am-i?withUserInformation=true` to get it merged with the principal in one round-trip.
 
 **`GET /certs`** (Issuer mode only) - public, returns the JSON Web Key Set with `Cache-Control: public, max-age=3600, stale-while-revalidate=86400`.
 
@@ -368,19 +387,22 @@ Column helper functions return pre-configured Drizzle columns for auth-related t
 
 ```typescript
 import { pgTable, text } from 'drizzle-orm/pg-core';
-import { extraUserColumns, extraRoleColumns, extraPermissionColumns, extraPolicyDefinitionColumns, withSerialId, withTimestamps } from '@venizia/ignis';
+import {
+  extraUserColumns, extraRoleColumns, extraPermissionColumns, extraPolicyDefinitionColumns,
+  generateIdColumnDefs, generateTzColumnDefs,
+} from '@venizia/ignis';
 
 export const users = pgTable('users', {
-  ...withSerialId(),
-  ...withTimestamps(),
+  ...generateIdColumnDefs(),
+  ...generateTzColumnDefs(),
   ...extraUserColumns(),
   username: text('username').unique().notNull(),
   passwordHash: text('password_hash').notNull(),
 });
 
-export const roles = pgTable('roles', { ...withSerialId(), ...withTimestamps(), ...extraRoleColumns() });
-export const permissions = pgTable('permissions', { ...withSerialId(), ...withTimestamps(), ...extraPermissionColumns() });
-export const policyDefinitions = pgTable('policy_definitions', { ...withSerialId(), ...withTimestamps(), ...extraPolicyDefinitionColumns() });
+export const roles = pgTable('roles', { ...generateIdColumnDefs(), ...generateTzColumnDefs(), ...extraRoleColumns() });
+export const permissions = pgTable('permissions', { ...generateIdColumnDefs(), ...generateTzColumnDefs(), ...extraPermissionColumns() });
+export const policyDefinitions = pgTable('policy_definitions', { ...generateIdColumnDefs(), ...generateTzColumnDefs(), ...extraPolicyDefinitionColumns() });
 ```
 
 **`extraUserColumns(opts?: { idType })`**
@@ -398,7 +420,7 @@ export const policyDefinitions = pgTable('policy_definitions', { ...withSerialId
 
 | Column | DB column | Type | Default | Description |
 |--------|-----------|------|---------|-------------|
-| `identifier` | `identifier` | `text` (unique) | -- | e.g. `'admin'`, `'editor'` |
+| `identifier` | `identifier` | `text` (unique) | -- | For example, `'admin'`, `'editor'` |
 | `name` | `name` | `text` | -- | Human-readable name |
 | `description` | `description` | `text` | `null` | Optional |
 | `priority` | `priority` | `integer` | -- | Lower = higher priority |
@@ -410,9 +432,9 @@ export const policyDefinitions = pgTable('policy_definitions', { ...withSerialId
 |--------|-----------|------|---------|-------------|
 | `code` | `code` | `text` (unique) | -- | Unique permission code |
 | `name` | `name` | `text` | -- | Display name |
-| `subject` | `subject` | `text` | -- | e.g. `'User'`, `'Order'` |
-| `method` | `method` | `text` | -- | e.g. `'GET'`, `'POST'` |
-| `action` | `action` | `text` | -- | e.g. `'read'`, `'write'` |
+| `subject` | `subject` | `text` | -- | For example, `'User'`, `'Order'` |
+| `method` | `method` | `text` | -- | For example, `'GET'`, `'POST'` |
+| `action` | `action` | `text` | -- | For example, `'read'`, `'write'` |
 | `scope` | `scope` | `text` | -- | Permission scope |
 | `description` | `description` | `text` | `null` | Optional |
 | `parentId` | `parent_id` | `text` or `integer` | `null` | Depends on `idType` |
@@ -421,16 +443,19 @@ export const policyDefinitions = pgTable('policy_definitions', { ...withSerialId
 
 | Column | DB column | Type | Nullable | Description |
 |--------|-----------|------|----------|-------------|
-| `variant` | `variant` | `text` | No | `'p'` (policy) or `'g'` (grouping) |
-| `subjectType` | `subject_type` | `text` | No | e.g. `'user'`, `'role'` |
-| `targetType` | `target_type` | `text` | No | e.g. `'permission'`, `'role'` |
+| `variant` | `variant` | `text` | No | One of the seven `AuthorizationPolicyVariants` edge kinds: `grant`, `assign_role`, `role_inherits`, `join_domain`, `domain_inherits`, `resource_inherits`, `action_inherits` |
+| `subjectType` | `subject_type` | `text` | No | For example, `'user'`, `'Role'` |
+| `targetType` | `target_type` | `text` | No | For example, `'Permission'`, `'Role'` |
 | `action` | `action` | `text` | Yes | Policy action |
 | `effect` | `effect` | `text` | Yes | `'allow'` / `'deny'` |
 | `domain` | `domain` | `text` | Yes | Multi-tenancy domain |
 | `subjectId` | `subject_id` | `text` or `integer` | No | Depends on `idType` |
 | `targetId` | `target_id` | `text` or `integer` | No | Depends on `idType` |
+| `metadata` | `metadata` | `jsonb` | Yes | Free-form metadata. Only some grants populate it |
+
+All `idType` options default to `'number'` (`integer` columns). Pass `'string'` for `text` columns - UUID primary keys, for example.
 
-All `idType` options default to `'number'` (`integer` columns); pass `'string'` for `text` (e.g. UUID) columns.
+`'p'` and `'g'` are Casbin rule prefixes, not `variant` values - each `variant` maps to one of them internally. See the [Authorization component](../authorization/) to build these tables end to end. Its [Usage guide](../authorization/usage) covers policy definitions, domain scoping, and the adapter that reads this table.
 
 ## See also