@venizia/ignis-docs 0.0.6-3 → 0.0.7-1

package/wiki/references/components/authentication/usage.md

@@ -1,17 +1,17 @@
 # Authentication -- Usage & Examples
 
-> Securing routes, authentication flows, entity helpers, and API endpoint specifications. See [Setup & Configuration](./) for initial setup.
+> Securing routes, authentication flows, JWKS microservice patterns, entity helpers, and API endpoint specifications. See [Setup & Configuration](./) for initial setup.
 
 ## Securing Routes
 
-Use `authStrategies` and `authMode` in route configurations:
+Use the `authenticate` field in route configurations. The field accepts `TRouteAuthenticateConfig`:
 
 ```typescript
 // Single strategy
 const SECURE_ROUTE_CONFIG = {
   path: '/secure-data',
   method: HTTP.Methods.GET,
-  authStrategies: [Authentication.STRATEGY_JWT],
+  authenticate: { strategies: [Authentication.STRATEGY_JWT] },
   responses: jsonResponse({
     description: 'Protected data',
     schema: z.object({ message: z.string() }),
@@ -22,8 +22,10 @@ const SECURE_ROUTE_CONFIG = {
 const FALLBACK_AUTH_CONFIG = {
   path: '/api/data',
   method: HTTP.Methods.GET,
-  authStrategies: [Authentication.STRATEGY_JWT, Authentication.STRATEGY_BASIC],
-  authMode: AuthenticationModes.ANY,
+  authenticate: {
+    strategies: [Authentication.STRATEGY_JWT, Authentication.STRATEGY_BASIC],
+    mode: AuthenticationModes.ANY,
+  },
   responses: jsonResponse({
     description: 'Data accessible via JWT or Basic auth',
     schema: z.object({ data: z.any() }),
@@ -34,7 +36,7 @@ const FALLBACK_AUTH_CONFIG = {
 const PUBLIC_ROUTE_CONFIG = {
   path: '/public',
   method: HTTP.Methods.GET,
-  skipAuth: true,
+  authenticate: { skip: true },
   responses: jsonResponse({
     description: 'Public endpoint',
     schema: z.object({ message: z.string() }),
@@ -44,7 +46,7 @@ const PUBLIC_ROUTE_CONFIG = {
 
 ## Using the `authenticate()` Standalone Function
 
-The `authenticate()` function is a convenience wrapper around `AuthenticationStrategyRegistry.getInstance().authenticate()`. It returns a Hono `MiddlewareHandler` suitable for direct middleware usage:
+The `authenticate()` function creates an `AuthenticationProvider` instance and uses its middleware factory. It returns a Hono `MiddlewareHandler` suitable for direct middleware usage:
 
 ```typescript
 import { authenticate, Authentication, AuthenticationModes } from '@venizia/ignis';
@@ -97,7 +99,9 @@ const conditionalAuthMiddleware = createMiddleware(async (c, next) => {
 
 ## Implementing an AuthenticationService
 
-The `AuthenticateComponent` depends on a service implementing the `IAuthService` interface when using the built-in auth controller:
+The `AuthenticateComponent` depends on a service implementing the `IAuthService` interface when using the built-in auth controller.
+
+### JWS Example
 
 ```typescript
 import {
@@ -105,21 +109,29 @@ import {
   inject,
   IAuthService,
   IJWTTokenPayload,
-  JWTTokenService,
+  JWSTokenService,
+  BindingKeys,
+  BindingNamespaces,
   TSignInRequest,
-  getError,
+  TContext,
 } from '@venizia/ignis';
-import { Context } from 'hono';
+import { getError } from '@venizia/ignis-helpers';
+import { Env } from 'hono';
 
 export class AuthenticationService extends BaseService implements IAuthService {
   constructor(
-    @inject({ key: 'services.JWTTokenService' })
-    private _jwtTokenService: JWTTokenService,
+    @inject({
+      key: BindingKeys.build({
+        namespace: BindingNamespaces.SERVICE,
+        key: JWSTokenService.name,
+      }),
+    })
+    private _tokenService: JWSTokenService,
   ) {
     super({ scope: AuthenticationService.name });
   }
 
-  async signIn(context: Context, opts: TSignInRequest): Promise<{ token: string }> {
+  async signIn(context: TContext<Env>, opts: TSignInRequest): Promise<{ token: string }> {
     const { identifier, credential } = opts;
     const user = await this.userRepo.findByIdentifier(identifier);
 
@@ -132,20 +144,198 @@ export class AuthenticationService extends BaseService implements IAuthService {
       roles: user.roles,
     };
 
-    const token = await this._jwtTokenService.generate({ payload });
+    const token = await this._tokenService.generate({ payload });
     return { token };
   }
 
-  async signUp(context: Context, opts: any): Promise<any> {
+  async signUp(context: TContext<Env>, opts: any): Promise<any> {
     // Implement your sign-up logic
   }
 
-  async changePassword(context: Context, opts: any): Promise<any> {
+  async changePassword(context: TContext<Env>, opts: any): Promise<any> {
     // Implement your change password logic
   }
 }
 ```
 
+### JWKS Issuer Example
+
+```typescript
+import {
+  BaseService,
+  inject,
+  IAuthService,
+  IJWTTokenPayload,
+  JWKSIssuerTokenService,
+  BindingKeys,
+  BindingNamespaces,
+  TSignInRequest,
+  TContext,
+} from '@venizia/ignis';
+import { getError } from '@venizia/ignis-helpers';
+import { Env } from 'hono';
+
+export class AuthenticationService extends BaseService implements IAuthService {
+  constructor(
+    @inject({
+      key: BindingKeys.build({
+        namespace: BindingNamespaces.SERVICE,
+        key: JWKSIssuerTokenService.name,
+      }),
+    })
+    private _tokenService: JWKSIssuerTokenService,
+  ) {
+    super({ scope: AuthenticationService.name });
+  }
+
+  async signIn(context: TContext<Env>, opts: TSignInRequest): Promise<{ token: string }> {
+    const { identifier, credential } = opts;
+    // ... lookup and verify user ...
+
+    const payload: IJWTTokenPayload = {
+      userId: user.id,
+      roles: user.roles,
+    };
+
+    const token = await this._tokenService.generate({ payload });
+    return { token };
+  }
+
+  // ... signUp, changePassword ...
+}
+```
+
+## JWKS Microservice Patterns
+
+### Issuer + Verifier Architecture
+
+In a microservice architecture, one service issues tokens (issuer) and other services verify them (verifier):
+
+```mermaid
+flowchart LR
+    CLIENT["Client App"]
+
+    subgraph AUTH["Auth Service (JWKS Issuer)"]
+        SIGNIN["POST /auth/sign-in"]
+        CERTS["GET /certs"]
+    end
+
+    subgraph API["API Service (JWKS Verifier)"]
+        DATA["GET /api/data"]
+    end
+
+    CLIENT -->|"1. Sign in"| SIGNIN
+    SIGNIN -->|"2. JWT token"| CLIENT
+    CLIENT -->|"3. Request + Bearer token"| DATA
+    DATA -->|"4. Fetch JWKS"| CERTS
+    CERTS -->|"5. Public keys"| DATA
+    DATA -->|"6. Verified response"| CLIENT
+
+    style AUTH fill:#e8f4fd,stroke:#0d6efd
+    style API fill:#d4edda,stroke:#28a745
+```
+
+**Auth Service (Issuer):**
+```typescript
+this.bind<TJWTTokenServiceOptions>({ key: AuthenticateBindingKeys.JWT_OPTIONS }).toValue({
+  standard: JOSEStandards.JWKS,
+  options: {
+    mode: JWKSModes.ISSUER,
+    algorithm: 'ES256',
+    keys: {
+      driver: JWKSKeyDrivers.FILE,
+      format: JWKSKeyFormats.PEM,
+      private: './keys/private.pem',
+      public: './keys/public.pem',
+    },
+    kid: 'auth-key-1',
+    getTokenExpiresFn: () => 86400,
+  },
+});
+```
+
+**API Service (Verifier):**
+```typescript
+this.bind<TJWTTokenServiceOptions>({ key: AuthenticateBindingKeys.JWT_OPTIONS }).toValue({
+  standard: JOSEStandards.JWKS,
+  options: {
+    mode: JWKSModes.VERIFIER,
+    jwksUrl: 'https://auth-service.internal/certs',
+    cacheTtlMs: 43_200_000,  // Cache for 12 hours
+    cooldownMs: 30_000,       // Min 30s between refreshes
+  },
+});
+```
+
+### JWKS with AES Payload Encryption
+
+When using AES payload encryption across services, **both issuer and verifier must share the same `applicationSecret`**:
+
+**Issuer:**
+```typescript
+{
+  mode: JWKSModes.ISSUER,
+  algorithm: 'ES256',
+  keys: { /* ... */ },
+  kid: 'auth-key-1',
+  getTokenExpiresFn: () => 86400,
+  applicationSecret: process.env.APP_ENV_APPLICATION_SECRET,
+}
+```
+
+**Verifier:**
+```typescript
+{
+  mode: JWKSModes.VERIFIER,
+  jwksUrl: 'https://auth-service.internal/certs',
+  applicationSecret: process.env.APP_ENV_APPLICATION_SECRET, // Must match issuer
+}
+```
+
+### JWKS Key Generation
+
+Generate ES256 keys for JWKS:
+
+```bash
+# Generate private key
+openssl ecparam -genkey -name prime256v1 -noout -out private.pem
+
+# Generate public key from private key
+openssl ec -in private.pem -pubout -out public.pem
+```
+
+Generate RS256 keys:
+
+```bash
+# Generate private key
+openssl genrsa -out private.pem 2048
+
+# Generate public key from private key
+openssl rsa -in private.pem -pubout -out public.pem
+```
+
+> [!WARNING]
+> Never commit private keys to version control. The `.gitignore` includes patterns for `*.pem`, `*.key`, and `keys/` directories.
+
+### Inline Keys (Text Driver)
+
+For environments where file access is restricted (e.g., serverless), use the `text` driver:
+
+```typescript
+{
+  mode: JWKSModes.ISSUER,
+  algorithm: 'ES256',
+  keys: {
+    driver: JWKSKeyDrivers.TEXT,
+    format: JWKSKeyFormats.PEM,
+    private: process.env.JWKS_PRIVATE_KEY!, // PEM string from env
+    public: process.env.JWKS_PUBLIC_KEY!,   // PEM string from env
+  },
+  kid: 'auth-key-1',
+  getTokenExpiresFn: () => 86400,
+}
+```
+
 ## Entity Column Helpers
 
 The authentication module provides a set of **column helper functions** designed to be spread into Drizzle `pgTable()` definitions. These functions return pre-configured column objects for common auth-related entities, saving you from manually defining columns for users, roles, permissions, and their relationships.
@@ -332,24 +522,139 @@ Inherits all statuses from `CommonStatuses` (same values as `UserStatuses`):
 
 ## Auth Flows
 
-### JWT Authentication Flow
+### JWS Authentication Flow
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant MW as Auth Middleware
+    participant S as JWSAuthenticationStrategy
+    participant SVC as JWSTokenService
+    participant JOSE as jose library
+
+    C->>MW: Request + Authorization: Bearer <token>
+    MW->>S: authenticate(context)
+    S->>SVC: extractCredentials(context)
+    SVC-->>S: { type: "Bearer", token }
+    S->>SVC: verify({ type, token })
+    SVC->>JOSE: jwtVerify(token, jwtSecret)
+    JOSE-->>SVC: JWTVerifyResult
+    SVC->>SVC: decryptPayload() (if AES configured)
+    SVC-->>S: IJWTTokenPayload
+    S-->>MW: IAuthUser
+    MW->>MW: Set CURRENT_USER + AUDIT_USER_ID
+    MW->>C: Continue to handler
+```
 
 1. **Client sends request** with <code v-pre>Authorization: Bearer &lt;token&gt;</code> header
-2. **JWTAuthenticationStrategy.authenticate()** is called by the Hono middleware
-3. **JWTTokenService.extractCredentials()** extracts the token from the Authorization header
-4. **JWTTokenService.verify()** verifies the JWT signature using `jose.jwtVerify()`
-5. **JWTTokenService.decryptPayload()** decrypts the AES-encrypted payload fields
+2. **JWSAuthenticationStrategy.authenticate()** is called by the Hono middleware
+3. **AbstractBearerTokenService.extractCredentials()** extracts the token from the Authorization header
+4. **JWSTokenService.doVerify()** verifies the JWT signature using `jose.jwtVerify()` with the shared `jwtSecret`
+5. **AbstractBearerTokenService.decryptPayload()** decrypts the AES-encrypted payload fields (if AES configured)
 6. **User payload is set** on `context.get(Authentication.CURRENT_USER)`
 
-> [!NOTE]
-> JWT payloads are encrypted field-by-field for additional security. Standard JWT fields (`iss`, `sub`, `aud`, etc.) remain unencrypted, while custom fields like `userId` and `roles` are AES-encrypted.
+### JWKS Issuer Authentication Flow
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant MW as Auth Middleware
+    participant S as JWKSIssuerStrategy
+    participant SVC as JWKSIssuerTokenService
+    participant INIT as Lazy Init
+    participant JOSE as jose library
+
+    C->>MW: Request + Authorization: Bearer <token>
+    MW->>S: authenticate(context)
+    S->>SVC: extractCredentials(context)
+    SVC-->>S: { type: "Bearer", token }
+    S->>SVC: verify({ type, token })
+    SVC->>INIT: ensureInitialized()
+    Note over INIT: Load keys from file/text<br/>Parse PEM/JWK<br/>Cache JWKS
+    INIT-->>SVC: initialized
+    SVC->>JOSE: jwtVerify(token, publicKey)
+    JOSE-->>SVC: JWTVerifyResult
+    SVC->>SVC: decryptPayload() (if AES configured)
+    SVC-->>S: IJWTTokenPayload
+    S-->>MW: IAuthUser
+    MW->>C: Continue to handler
+```
+
+1. **Client sends request** with <code v-pre>Authorization: Bearer &lt;token&gt;</code> header
+2. **JWKSIssuerAuthenticationStrategy.authenticate()** is called by the Hono middleware
+3. **AbstractBearerTokenService.extractCredentials()** extracts the token from the Authorization header
+4. **JWKSIssuerTokenService.doVerify()** calls `ensureInitialized()` (lazy-loads keys on first call), then verifies the JWT using the public key
+5. **AbstractBearerTokenService.decryptPayload()** decrypts the AES-encrypted payload fields (if AES configured)
+6. **User payload is set** on `context.get(Authentication.CURRENT_USER)`
+
+### JWKS Verifier Authentication Flow
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant MW as Auth Middleware
+    participant S as JWKSVerifierStrategy
+    participant SVC as JWKSVerifierTokenService
+    participant INIT as Lazy Init
+    participant REMOTE as Remote JWKS URL
+
+    C->>MW: Request + Authorization: Bearer <token>
+    MW->>S: authenticate(context)
+    S->>SVC: extractCredentials(context)
+    SVC-->>S: { type: "Bearer", token }
+    S->>SVC: verify({ type, token })
+    SVC->>INIT: ensureInitialized()
+    INIT->>REMOTE: createRemoteJWKSet(jwksUrl)
+    REMOTE-->>INIT: JWKS verifier function
+    INIT-->>SVC: initialized
+    SVC->>SVC: jwtVerify(token, jwksVerifier)
+    SVC->>SVC: decryptPayload() (if AES configured)
+    SVC-->>S: IJWTTokenPayload
+    S-->>MW: IAuthUser
+    MW->>C: Continue to handler
+```
+
+1. **Client sends request** with <code v-pre>Authorization: Bearer &lt;token&gt;</code> header
+2. **JWKSVerifierAuthenticationStrategy.authenticate()** is called by the Hono middleware
+3. **AbstractBearerTokenService.extractCredentials()** extracts the token from the Authorization header
+4. **JWKSVerifierTokenService.doVerify()** calls `ensureInitialized()` (creates remote JWKS verifier on first call), then verifies the JWT using the remote JWKS
+5. **AbstractBearerTokenService.decryptPayload()** decrypts the AES-encrypted payload fields (if AES configured)
+6. **User payload is set** on `context.get(Authentication.CURRENT_USER)`
 
 ### Basic Authentication Flow
 
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant MW as Auth Middleware
+    participant S as BasicAuthStrategy
+    participant SVC as BasicTokenService
+    participant CB as verifyCredentials callback
+
+    C->>MW: Request + Authorization: Basic <base64>
+    MW->>S: authenticate(context)
+    S->>SVC: extractCredentials(context)
+    SVC->>SVC: Base64 decode
+    SVC-->>S: { username, password }
+    S->>SVC: verify({ credentials, context })
+    SVC->>CB: verifyCredentials({ credentials, context })
+    CB-->>SVC: IAuthUser | null
+    alt valid user
+        SVC-->>S: IAuthUser
+        S-->>MW: IAuthUser
+        MW->>MW: Set CURRENT_USER + AUDIT_USER_ID
+        MW->>C: Continue to handler
+    else null (invalid)
+        SVC-->>S: throw 401
+        S-->>MW: throw 401
+        MW->>C: 401 Unauthorized
+    end
+```
+
 1. **Client sends request** with <code v-pre>Authorization: Basic &lt;base64(username:password)&gt;</code> header
 2. **BasicAuthenticationStrategy.authenticate()** is called by the Hono middleware
 3. **BasicTokenService.extractCredentials()** decodes the Base64 credentials
-4. **BasicTokenService.verify()** calls the user-provided `verifyCredentials` callback
+4. **BasicTokenService.verify()** calls the user-provided `verifyCredentials` callback with `{ credentials, context }`
 5. **User payload is set** on `context.get(Authentication.CURRENT_USER)` if verification succeeds
 
 > [!IMPORTANT]
@@ -357,11 +662,39 @@ Inherits all statuses from `CommonStatuses` (same values as `UserStatuses`):
 
 ## Multi-Strategy Authentication
 
-When multiple strategies are configured on a route via `authStrategies: ['jwt', 'basic']`:
+When multiple strategies are configured on a route via `authenticate: { strategies: ['jwt', 'basic'] }`:
+
+```mermaid
+flowchart TD
+    REQ["Request arrives"] --> MODE{"mode?"}
+
+    MODE -->|"any (default)"| ANY["Try strategies in order"]
+    ANY --> S1{"Strategy 1"}
+    S1 -->|"Success"| WIN["Set user, continue"]
+    S1 -->|"Fail"| S2{"Strategy 2"}
+    S2 -->|"Success"| WIN
+    S2 -->|"Fail"| FAIL_ANY["401: Tried strategies: jwt, basic"]
+
+    MODE -->|"all"| ALL["Run all strategies"]
+    ALL --> A1{"Strategy 1"}
+    A1 -->|"Fail"| FAIL_ALL["Exception propagates"]
+    A1 -->|"Pass"| A2{"Strategy 2"}
+    A2 -->|"Fail"| FAIL_ALL
+    A2 -->|"Pass"| CHECK{"userId?"}
+    CHECK -->|"Yes"| WIN2["Set user, continue"]
+    CHECK -->|"No"| FAIL_ID["401: Failed to identify user"]
+
+    style WIN fill:#d4edda,stroke:#28a745
+    style WIN2 fill:#d4edda,stroke:#28a745
+    style FAIL_ANY fill:#f8d7da,stroke:#dc3545
+    style FAIL_ALL fill:#f8d7da,stroke:#dc3545
+    style FAIL_ID fill:#f8d7da,stroke:#dc3545
+```
 
 **`any` mode (default):**
 - Strategies are tried in the order specified
 - The first successful strategy wins
+- Errors from failing strategies are **discarded** (logged at debug level)
 - If all strategies fail, a `401 Unauthorized` error is thrown listing all tried strategies
 - **Use case:** Fallback authentication (try JWT, fallback to Basic)
 
@@ -374,41 +707,62 @@ When multiple strategies are configured on a route via `authStrategies: ['jwt',
 > [!TIP]
 > Use `'any'` mode for graceful fallback (e.g., allow mobile apps to use JWT while legacy systems use Basic). Use `'all'` mode for high-security endpoints requiring multiple forms of authentication.
 
-## Token Encryption
+## Token Encryption (Optional AES)
+
+```mermaid
+flowchart LR
+    subgraph GENERATE["generate() — Token Creation"]
+        direction TB
+        P["Payload: { userId, roles, email }"]
+        P --> CHECK1{"applicationSecret?"}
+        CHECK1 -->|"Yes"| ENC["encryptPayload()"]
+        ENC --> E1["Keep: iss, sub, aud, exp, iat"]
+        ENC --> E2["Encrypt keys + values"]
+        CHECK1 -->|"No"| PLAIN1["Use payload as-is"]
+    end
+
+    subgraph VERIFY["verify() — Token Verification"]
+        direction TB
+        T["Verified JWT payload"]
+        T --> CHECK2{"applicationSecret?"}
+        CHECK2 -->|"Yes"| DEC["decryptPayload()"]
+        DEC --> D1["Extract: iss, sub, aud, exp, iat"]
+        DEC --> D2["Decrypt keys + values"]
+        CHECK2 -->|"No"| PLAIN2["Use payload as-is"]
+    end
+
+    style GENERATE fill:#e8f4fd,stroke:#0d6efd
+    style VERIFY fill:#d4edda,stroke:#28a745
+```
+
+JWT payloads can optionally be encrypted field-by-field using AES (default `aes-256-cbc`) via the `@venizia/ignis-helpers` AES utility. This is configured by providing `applicationSecret` in the service options.
 
-JWT payloads are encrypted field-by-field using AES (default `aes-256-cbc`) via the `@venizia/ignis-helpers` AES utility:
+> [!NOTE]
+> AES payload encryption is **optional** for all JOSE standards (JWS and JWKS). When `applicationSecret` is not provided, payloads are stored in standard plaintext JWT format.
 
-**Encryption process:**
+**Encryption process (when `applicationSecret` is provided):**
 1. Standard JWT fields (`iss`, `sub`, `aud`, `jti`, `nbf`, `exp`, `iat`) are preserved as-is
 2. All other fields have both their **keys** and **values** AES-encrypted
 3. The `roles` field is serialized as `id|identifier|priority` pipe-separated strings before encryption
 4. `null` and `undefined` values are skipped during encryption
 
-**Encryption code walkthrough:**
-
-The `encryptPayload()` method processes each field:
-1. Standard JWT fields (`iss`, `sub`, `aud`, `jti`, `nbf`, `exp`, `iat`) are copied as-is
-2. `null`/`undefined` values are skipped entirely
-3. For the `roles` field: values are serialized as `"id|identifier|priority"` pipe-separated strings, then the array is JSON-stringified before encryption
-4. For all other fields: values are converted to string via template literal (<code v-pre>`${value}`</code>), then both key and value are AES-encrypted independently
-5. The encrypted key becomes the new field name, the encrypted value becomes its value
-
 **Decryption process:**
-1. Standard JWT fields are extracted directly
-2. Encrypted fields have their keys decrypted first, then their values
-3. The `roles` field is deserialized: JSON-parsed to a string array, then each entry is split on `|` to reconstruct objects with `id`, `identifier`, and `priority` (where `priority` is converted to integer via `int()`)
+1. If AES is not configured (`this.aes` is null), the payload is returned as-is
+2. Standard JWT fields are extracted directly
+3. Encrypted fields have their keys decrypted first, then their values
+4. The `roles` field is deserialized: JSON-parsed to a string array, then each entry is split on `|` to reconstruct objects with `id`, `identifier`, and `priority` (where `priority` is converted to integer via `int()`)
 
 > [!WARNING]
-> The `applicationSecret` must remain constant across all instances of your application. Changing it will invalidate all existing tokens, as they cannot be decrypted with a different secret.
+> The `applicationSecret` must remain constant across all instances of your application. Changing it will invalidate all existing tokens, as they cannot be decrypted with a different secret. In JWKS microservice setups, the issuer and all verifiers must share the same `applicationSecret`.
 
 ## Hono Context Extension
 
-The Authentication module extends Hono's `ContextVariableMap` to provide type-safe access to auth data:
+The Authentication module extends Hono's `ContextVariableMap` to provide type-safe access to auth data. Note: `ContextVariableMap` does **not** take a generic parameter — it is a plain interface augmentation:
 
 ```typescript
 declare module 'hono' {
-  interface ContextVariableMap<User extends IAuthUser = IAuthUser> {
-    [Authentication.CURRENT_USER]: User;
+  interface ContextVariableMap {
+    [Authentication.CURRENT_USER]: IAuthUser;
     [Authentication.AUDIT_USER_ID]: IdType;
   }
 }
@@ -451,32 +805,9 @@ const SignInRequestSchema = z.object({
 type TSignInRequest = z.infer<typeof SignInRequestSchema>;
 ```
 
-| Field | Type | Constraints |
-|-------|------|-------------|
-| `identifier.scheme` | `string` | Non-empty, min 4 chars |
-| `identifier.value` | `string` | Non-empty, min 8 chars |
-| `credential.scheme` | `string` | Non-empty |
-| `credential.value` | `string` | Non-empty, min 8 chars |
-| `clientId` | `string` | Optional |
-
-**OpenAPI examples** (from source):
-```json
-[
-  {
-    "identifier": { "scheme": "username", "value": "test_username" },
-    "credential": { "scheme": "basic", "value": "test_password" }
-  },
-  {
-    "identifier": { "scheme": "username", "value": "test_username" },
-    "credential": { "scheme": "basic", "value": "test_password" },
-    "clientId": "auth-provider"
-  }
-]
-```
-
 ### SignUpRequestSchema
 
-The built-in schema uses a **flat structure** -- not the nested `identifier`/`credential` pattern used by sign-in:
+The built-in schema uses a **flat structure**:
 
 ```typescript
 const SignUpRequestSchema = z.object({
@@ -487,25 +818,8 @@ const SignUpRequestSchema = z.object({
 type TSignUpRequest = z.infer<typeof SignUpRequestSchema>;
 ```
 
-| Field | Type | Constraints |
-|-------|------|-------------|
-| `username` | `string` | Non-empty, min 8 chars |
-| `credential` | `string` | Non-empty, min 8 chars |
-
-**OpenAPI examples** (from source):
-```json
-[
-  {
-    "username": "example_username",
-    "credential": "example_credential"
-  }
-]
-```
-
 ### ChangePasswordRequestSchema
 
-The built-in schema uses scheme-based credential naming with a `userId` field:
-
 ```typescript
 const ChangePasswordRequestSchema = z.object({
   scheme: z.string(),
@@ -517,24 +831,6 @@ const ChangePasswordRequestSchema = z.object({
 type TChangePasswordRequest = z.infer<typeof ChangePasswordRequestSchema>;
 ```
 
-| Field | Type | Constraints |
-|-------|------|-------------|
-| `scheme` | `string` | Required (e.g., `'basic'`) |
-| `oldCredential` | `string` | Non-empty, min 8 chars |
-| `newCredential` | `string` | Non-empty, min 8 chars |
-| `userId` | `string \| number` | Required |
-
-**OpenAPI examples** (from source):
-```json
-[
-  {
-    "scheme": "basic",
-    "oldCredential": "old_password",
-    "newCredential": "new_password"
-  }
-]
-```
-
 ### JWTTokenPayloadSchema
 
 Exported from the controller factory module. Used as the response schema for the `/who-am-i` endpoint:
@@ -555,36 +851,6 @@ const JWTTokenPayloadSchema = z.object({
 });
 ```
 
-### Custom Schema Example
-
-```typescript
-import { z } from 'zod';
-
-this.bind<TAuthenticationRestOptions>({ key: AuthenticateBindingKeys.REST_OPTIONS }).toValue({
-  useAuthController: true,
-  controllerOpts: {
-    restPath: '/auth',
-    payload: {
-      signIn: {
-        request: {
-          schema: z.object({
-            email: z.string().email(),
-            password: z.string().min(8),
-          }),
-        },
-        response: {
-          schema: z.object({
-            accessToken: z.string(),
-            refreshToken: z.string(),
-            expiresIn: z.number(),
-          }),
-        },
-      },
-    },
-  },
-});
-```
-
 ## API Endpoints
 
 The built-in auth controller is created by the `defineAuthController()` factory function and is only available when `useAuthController: true` is set in `REST_OPTIONS`.
@@ -595,9 +861,10 @@ The built-in auth controller is created by the `defineAuthController()` factory
 | `POST` | `/auth/sign-up` | Configurable | Create a new user account |
 | `POST` | `/auth/change-password` | JWT | Change the authenticated user's password |
 | `GET` | `/auth/who-am-i` | JWT | Return the current user's JWT payload |
+| `GET` | `/certs` | No | JWKS endpoint (JWKS Issuer mode only) |
 
 > [!NOTE]
-> The base path `/auth` is configurable via `controllerOpts.restPath`. All paths shown above use the default.
+> The base path `/auth` is configurable via `controllerOpts.restPath`. The `/certs` path is configurable via `rest.path` in `IJWKSIssuerOptions`. The `/certs` endpoint is intentionally unauthenticated — it serves the public keys needed by external verifiers.
 
 ### POST /auth/sign-in
 
@@ -607,171 +874,232 @@ The built-in auth controller is created by the `defineAuthController()` factory
 
 Uses `SignInRequestSchema` by default, or a custom schema via `payload.signIn.request.schema`.
 
-Default schema:
-```typescript
-{
-  identifier: {
-    scheme: string;  // min 4 chars, e.g., 'username', 'email'
-    value: string;   // min 8 chars
-  };
-  credential: {
-    scheme: string;  // e.g., 'basic', 'password'
-    value: string;   // min 8 chars
-  };
-  clientId?: string;
-}
-```
-
 **Response 200:**
 
 Uses `payload.signIn.response.schema` if provided, otherwise `AnyObjectSchema`.
 
 ```json
 {
-  "token": "eyJhbGciOiJIUzI1NiJ9..."
+  "token": "eyJhbGciOiJFUzI1NiIsImtpZCI6Im15LWtleS1pZC0xIn0..."
 }
 ```
 
-**Example:**
-```typescript
-const response = await fetch('/auth/sign-in', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    identifier: { scheme: 'email', value: 'user@example.com' },
-    credential: { scheme: 'password', value: 'my-password' },
-  }),
-});
+### POST /auth/sign-up
 
-const { token } = await response.json();
-```
+**Authentication:** Configurable via `requireAuthenticatedSignUp` (default: `false`)
 
+When `requireAuthenticatedSignUp: true`, requires JWT authentication. When `false`, the endpoint is public.
 
-### POST /auth/sign-up
+### POST /auth/change-password
 
-**Authentication:** Configurable via `requireAuthenticatedSignUp` (default: `false`)
+**Authentication:** Always requires JWT (`Authentication.STRATEGY_JWT`)
 
-When `requireAuthenticatedSignUp: true`, requires JWT authentication (strategy: `Authentication.STRATEGY_JWT`). When `false`, the `strategies` array is empty (public endpoint).
+### GET /auth/who-am-i
 
-**Request Body:**
+**Authentication:** Always requires JWT (`Authentication.STRATEGY_JWT`)
 
-Uses `SignUpRequestSchema` by default, or a custom schema via `payload.signUp.request.schema`.
+Returns the current user's decrypted JWT payload directly from context.
 
-Default schema (flat structure):
-```typescript
+```json
 {
-  username: string;   // non-empty, min 8 chars
-  credential: string; // non-empty, min 8 chars
+  "userId": "123",
+  "roles": [
+    { "id": "1", "identifier": "admin", "priority": 0 }
+  ],
+  "clientId": "optional-client-id",
+  "provider": "optional-provider",
+  "email": "user@example.com"
 }
 ```
 
-**Response 200:**
+### GET /certs (JWKS Issuer Only)
+
+**Authentication:** None (intentionally public)
 
-Uses `payload.signUp.response.schema` if provided, otherwise `AnyObjectSchema`.
+Returns the JSON Web Key Set for external verifiers.
 
 ```json
 {
-  "id": "user-id",
-  "username": "newuser123"
+  "keys": [
+    {
+      "kty": "EC",
+      "kid": "my-key-id-1",
+      "use": "sig",
+      "alg": "ES256",
+      "crv": "P-256",
+      "x": "...",
+      "y": "..."
+    }
+  ]
 }
 ```
 
-**Example:**
-```typescript
-const response = await fetch('/auth/sign-up', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    username: 'newuser123',
-    credential: 'secure-password',
-  }),
-});
+**Cache headers:** `Cache-Control: public, max-age=3600, stale-while-revalidate=86400`
 
-const user = await response.json();
-```
+## Auth Entity Column Helpers
 
+Ignis provides column helper functions that return pre-configured Drizzle column objects for common auth-related database tables. These functions are designed to be spread into `pgTable()` definitions, giving you standardized columns for User, Role, Permission, and PolicyDefinition entities without manually defining each column.
 
-### POST /auth/change-password
+All helpers that accept an `opts` parameter support `{ idType: 'string' | 'number' }` to control whether foreign key columns use `text` (for UUIDs) or `integer` (for serial IDs). The default is `'number'`.
 
-**Authentication:** Always requires JWT (`Authentication.STRATEGY_JWT`)
+### extraUserColumns
 
-**Request Body:**
+**Import:** `import { extraUserColumns } from '@venizia/ignis';`
 
-Uses `ChangePasswordRequestSchema` by default, or a custom schema via `payload.changePassword.request.schema`.
+**Signature:** `extraUserColumns(opts?: { idType: 'string' | 'number' })`
 
-Default schema:
-```typescript
-{
-  scheme: string;        // e.g., 'basic'
-  oldCredential: string; // non-empty, min 8 chars
-  newCredential: string; // non-empty, min 8 chars
-  userId: string | number;
-}
-```
+| Column | DB Column | Type | Nullable | Default | Description |
+|--------|-----------|------|----------|---------|-------------|
+| `realm` | `realm` | `text` | Yes | `''` | Multi-tenancy realm identifier |
+| `status` | `status` | `text` | No | `UserStatuses.UNKNOWN` | User lifecycle status |
+| `type` | `type` | `text` | No | `UserTypes.SYSTEM` | User type (`SYSTEM` or `LINKED`) |
+| `activatedAt` | `activated_at` | `timestamp (tz)` | Yes | `null` | When the user was activated |
+| `lastLoginAt` | `last_login_at` | `timestamp (tz)` | Yes | `null` | Last login timestamp |
+| `parentId` | `parent_id` | `text` or `integer` | Yes | `null` | Parent user ID (type depends on `idType`) |
 
-**Response 200:**
+### extraRoleColumns
 
-Uses `payload.changePassword.response.schema` if provided, otherwise `AnyObjectSchema`.
+**Import:** `import { extraRoleColumns } from '@venizia/ignis';`
 
-```json
-{
-  "success": true
-}
-```
+**Signature:** `extraRoleColumns()`
+
+| Column | DB Column | Type | Nullable | Default | Description |
+|--------|-----------|------|----------|---------|-------------|
+| `identifier` | `identifier` | `text` (unique) | No | -- | Unique role identifier (e.g., `'admin'`, `'editor'`) |
+| `name` | `name` | `text` | No | -- | Human-readable role name |
+| `description` | `description` | `text` | Yes | `null` | Optional role description |
+| `priority` | `priority` | `integer` | No | -- | Role priority (lower = higher priority) |
+| `status` | `status` | `text` | No | `RoleStatuses.ACTIVATED` | Role lifecycle status |
+
+### extraPermissionColumns
+
+**Import:** `import { extraPermissionColumns } from '@venizia/ignis';`
+
+**Signature:** `extraPermissionColumns(opts?: { idType: 'string' | 'number' })`
+
+| Column | DB Column | Type | Nullable | Default | Description |
+|--------|-----------|------|----------|---------|-------------|
+| `code` | `code` | `text` (unique) | No | -- | Unique permission code |
+| `name` | `name` | `text` | No | -- | Permission display name |
+| `subject` | `subject` | `text` | No | -- | Permission subject (e.g., `'User'`, `'Order'`) |
+| `action` | `action` | `text` | No | -- | Permitted action (e.g., `'read'`, `'write'`) |
+| `scope` | `scope` | `text` | No | -- | Permission scope |
+| `parentId` | `parent_id` | `text` or `integer` | Yes | `null` | Parent permission ID (type depends on `idType`) |
+
+### extraPolicyDefinitionColumns
+
+**Import:** `import { extraPolicyDefinitionColumns } from '@venizia/ignis';`
+
+**Signature:** `extraPolicyDefinitionColumns(opts?: { idType: 'string' | 'number' })`
+
+Provides columns for Casbin-style policy definitions that map subjects (users/roles) to targets (resources/permissions).
+
+| Column | DB Column | Type | Nullable | Default | Description |
+|--------|-----------|------|----------|---------|-------------|
+| `variant` | `variant` | `text` | No | -- | Policy variant (e.g., `'p'` for policy, `'g'` for grouping) |
+| `subjectType` | `subject_type` | `text` | No | -- | Type of subject (e.g., `'user'`, `'role'`) |
+| `targetType` | `target_type` | `text` | No | -- | Type of target (e.g., `'permission'`, `'role'`) |
+| `action` | `action` | `text` | Yes | `null` | Policy action |
+| `effect` | `effect` | `text` | Yes | `null` | Policy effect (e.g., `'allow'`, `'deny'`) |
+| `domain` | `domain` | `text` | Yes | `null` | Policy domain for multi-tenancy |
+| `subjectId` | `subject_id` | `text` or `integer` | No | -- | Subject ID (type depends on `idType`) |
+| `targetId` | `target_id` | `text` or `integer` | No | -- | Target ID (type depends on `idType`) |
+
+### Usage Example
 
-**Example:**
 ```typescript
-const response = await fetch('/auth/change-password', {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-    'Authorization': `Bearer ${token}`,
-  },
-  body: JSON.stringify({
-    scheme: 'basic',
-    oldCredential: 'old-password',
-    newCredential: 'new-secure-password',
-    userId: '123',
-  }),
+import { pgTable, serial, text } from 'drizzle-orm/pg-core';
+import {
+  extraUserColumns,
+  extraRoleColumns,
+  extraPermissionColumns,
+  extraPolicyDefinitionColumns,
+} from '@venizia/ignis';
+import { withSerialId, withTimestamps } from '@venizia/ignis';
+
+// User table
+export const users = pgTable('users', {
+  ...withSerialId(),
+  ...withTimestamps(),
+  ...extraUserColumns(),
+  username: text('username').unique().notNull(),
+  passwordHash: text('password_hash').notNull(),
+  email: text('email').unique(),
 });
 
-const result = await response.json();
-```
+// Role table
+export const roles = pgTable('roles', {
+  ...withSerialId(),
+  ...withTimestamps(),
+  ...extraRoleColumns(),
+});
 
+// Permission table
+export const permissions = pgTable('permissions', {
+  ...withSerialId(),
+  ...withTimestamps(),
+  ...extraPermissionColumns(),
+});
 
-### GET /auth/who-am-i
+// Policy definition table (Casbin-style policies)
+export const policyDefinitions = pgTable('policy_definitions', {
+  ...withSerialId(),
+  ...withTimestamps(),
+  ...extraPolicyDefinitionColumns(),
+});
 
-**Authentication:** Always requires JWT (`Authentication.STRATEGY_JWT`)
+// With UUID-based IDs
+export const uuidUsers = pgTable('users', {
+  ...withUuidId(),
+  ...withTimestamps(),
+  ...extraUserColumns({ idType: 'string' }),
+  username: text('username').unique().notNull(),
+});
 
-**Request Body:** None
+export const uuidPolicies = pgTable('policy_definitions', {
+  ...withUuidId(),
+  ...withTimestamps(),
+  ...extraPolicyDefinitionColumns({ idType: 'string' }),
+});
+```
 
-**Response 200:**
+### Context Variables
 
-Uses the `JWTTokenPayloadSchema` Zod schema. Returns the current user's decrypted JWT payload directly from context:
+The auth middleware sets several variables on the Hono `Context` object during request processing. These are declared via a `ContextVariableMap` module augmentation and can be accessed with `c.get()` / `c.set()`.
 
-```json
-{
-  "userId": "123",
-  "roles": [
-    { "id": "1", "identifier": "admin", "priority": 0 }
-  ],
-  "clientId": "optional-client-id",
-  "provider": "optional-provider",
-  "email": "user@example.com"
-}
+| Constant | Key String | Type | Description |
+|----------|-----------|------|-------------|
+| `Authentication.CURRENT_USER` | `'auth.current.user'` | `IAuthUser` | The authenticated user payload, set after successful authentication |
+| `Authentication.AUDIT_USER_ID` | `'audit.user.id'` | `IdType` | The authenticated user's ID, extracted from the user payload |
+| `Authentication.SKIP_AUTHENTICATION` | `'authentication.skip'` | `boolean` | Set to `true` in a preceding middleware to bypass authentication for the current request |
+| `Authorization.RULES` | `'authorization.rules'` | `unknown` | Authorization rules resolved for the current request |
+| `Authorization.SKIP_AUTHORIZATION` | `'authorization.skip'` | `boolean` | Set to `true` to bypass authorization checks for the current request |
+
+**Reading context variables in a handler:**
+
+```typescript
+import { Authentication, Authorization } from '@venizia/ignis';
+
+// Inside a route handler
+const currentUser = c.get(Authentication.CURRENT_USER);
+const userId = c.get(Authentication.AUDIT_USER_ID);
+const skipAuth = c.get(Authentication.SKIP_AUTHENTICATION);
+const authzRules = c.get(Authorization.RULES);
 ```
 
-**Example:**
+**Skipping auth dynamically from middleware:**
+
 ```typescript
-const response = await fetch('/auth/who-am-i', {
-  method: 'GET',
-  headers: {
-    'Authorization': `Bearer ${token}`,
-  },
-});
+import { Authentication, Authorization } from '@venizia/ignis';
+import { createMiddleware } from 'hono/factory';
 
-const user = await response.json();
-console.log('Current user:', user);
+const apiKeyMiddleware = createMiddleware(async (c, next) => {
+  if (c.req.header('X-API-Key') === process.env.INTERNAL_API_KEY) {
+    c.set(Authentication.SKIP_AUTHENTICATION, true);
+    c.set(Authorization.SKIP_AUTHORIZATION, true);
+  }
+  return next();
+});
 ```
 
 ## See Also