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

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

@@ -1,91 +1,122 @@
 # Authentication -- API Reference
 
-> Architecture, service internals, strategy registry, and controller factory. See [Setup & Configuration](./) for initial setup.
+> Architecture, service hierarchy, strategy registry, JWKS controller, and controller factory. See [Setup & Configuration](./) for initial setup.
 
 ## Architecture
 
 ```
+  ┌──────────────────────────────────────────────────────────────────┐
+  │                         Application                              │
+  │                                                                  │
+  │  preConfigure()                                                  │
+  │    ├── bind JWT_OPTIONS (TJWTTokenServiceOptions)                │
+  │    │     └── standard: JWS | JWKS                                │
+  │    ├── bind BASIC_OPTIONS / REST_OPTIONS                         │
+  │    ├── this.component(AuthenticateComponent)                     │
+  │    └── AuthenticationStrategyRegistry.register() ← manual        │
+  └────────────────────────────┬─────────────────────────────────────┘
+                               │
+                               ▼
+  ┌──────────────────────────────────────────────────────────────────┐
+  │                AuthenticateComponent.binding()                    │
+  │                                                                  │
+  │  1. Read JWT_OPTIONS, BASIC_OPTIONS, REST_OPTIONS                │
+  │  2. Switch on jwtOptions.standard:                               │
+  │     ├── JWS  → defineJWSAuth()  → JWSTokenService                │
+  │     └── JWKS → defineJWKSAuth() → switch on mode:                │
+  │                 ├── issuer   → JWKSIssuerTokenService             │
+  │                 │              + JWKSController (/certs)          │
+  │                 └── verifier → JWKSVerifierTokenService           │
+  │  3. defineBasicAuth() → BasicTokenService                        │
+  │  4. defineControllers() → AuthController (factory-built)         │
+  │  5. defineOAuth2() → stub (not yet implemented)                  │
+  └────────────────────────────┬─────────────────────────────────────┘
+                               │
+         ┌─────────────────────┼──────────────────────┐
+         ▼                     ▼                      ▼
+  ┌──────────────┐   ┌────────────────┐    ┌──────────────────┐
+  │ Bearer Token │   │  BasicToken    │    │  AuthController   │
+  │ Services     │   │  Service       │    │  (factory-built)  │
+  │ (see below)  │   └───────┬────────┘    └────────┬─────────┘
+  └──────┬───────┘           │                      │
+         │                   ▼                      ▼
+         │            ┌──────────────┐    ┌──────────────────┐
+         │            │ Basic        │    │ /sign-in          │
+         │            │ Strategy     │    │ /sign-up          │
+         │            └──────────────┘    │ /change-password  │
+         │                                │ /who-am-i         │
+         ▼                                └──────────────────┘
   ┌──────────────────────────────────────────────────────────┐
-  │                     Application                          │
+  │           Bearer Token Service Hierarchy                  │
   │                                                          │
-  │  preConfigure()                                          │
-  │    ├── bind JWT_OPTIONS / BASIC_OPTIONS / REST_OPTIONS   │
-  │    ├── this.component(AuthenticateComponent)             │
-  │    └── AuthenticationStrategyRegistry.register()         │
-  └──────────────────────┬───────────────────────────────────┘
-                         │
-                         ▼
-  ┌──────────────────────────────────────────────────────────┐
-  │              AuthenticateComponent.binding()              │
-  │                                                          │
-  │  1. validateOptions() — at least one auth required       │
-  │  2. defineJWTAuth() — bind JWTTokenService               │
-  │  3. defineBasicAuth() — bind BasicTokenService           │
-  │  4. defineControllers() — defineAuthController()         │
-  │  5. defineOAuth2() — stub (not yet implemented)          │
-  └──────────────────────┬───────────────────────────────────┘
-                         │
-           ┌─────────────┼─────────────┐
-           ▼             ▼             ▼
-  ┌────────────┐ ┌──────────────┐ ┌──────────────────┐
-  │ JWTToken   │ │ BasicToken   │ │  AuthController   │
-  │ Service    │ │ Service      │ │  (factory-built)  │
-  └──────┬─────┘ └──────┬───────┘ └────────┬─────────┘
-         │              │                   │
-         ▼              ▼                   ▼
-  ┌────────────┐ ┌──────────────┐ ┌──────────────────┐
-  │ JWT        │ │ Basic        │ │ /sign-in          │
-  │ Strategy   │ │ Strategy     │ │ /sign-up          │
-  │            │ │              │ │ /change-password   │
-  └────────────┘ └──────────────┘ │ /who-am-i         │
-                                  └──────────────────┘
+  │  AbstractBearerTokenService (base)                       │
+  │    ├── extractCredentials()                              │
+  │    ├── verify() → doVerify()                             │
+  │    ├── generate() → getSigner() + getSigningKey()        │
+  │    ├── encryptPayload() / decryptPayload() (optional)    │
+  │    │                                                     │
+  │    ├── JWSTokenService (symmetric HS256)                 │
+  │    │     ├── JWSAuthenticationStrategy                   │
+  │    │     └── sign with shared secret                     │
+  │    │                                                     │
+  │    └── AbstractJWKSTokenService (lazy-init + retry)      │
+  │          ├── ensureInitialized() / initialize()          │
+  │          │                                               │
+  │          ├── JWKSIssuerTokenService (asymmetric)         │
+  │          │     ├── JWKSIssuerAuthenticationStrategy      │
+  │          │     ├── sign with private key                 │
+  │          │     ├── verify with public key                │
+  │          │     └── getJWKS() / getJWKSAsync()            │
+  │          │                                               │
+  │          └── JWKSVerifierTokenService (remote verify)    │
+  │                ├── JWKSVerifierAuthenticationStrategy    │
+  │                └── verify via createRemoteJWKSet()       │
+  └──────────────────────────────────────────────────────────┘
 ```
 
 ### Tech Stack
 
 | Technology | Purpose |
 |------------|---------|
-| **`jose`** | JWT signing (`SignJWT`), verification (`jwtVerify`), and type definitions (`JWTPayload`, `JWTVerifyResult`) |
-| **`@venizia/ignis-helpers`** | `AES` utility for payload field encryption, `BaseHelper`/`BaseService` base classes, `getError` for error creation, `HTTP` result codes |
+| **`jose`** | JWT signing (`SignJWT`), verification (`jwtVerify`), JWKS (`createRemoteJWKSet`, `exportJWK`, `importPKCS8`, `importSPKI`, `importJWK`), and type definitions |
+| **`@venizia/ignis-helpers`** | `AES` utility for payload encryption, `BaseHelper`/`BaseService` base classes, `getError` for error creation, `HTTP` result codes |
 | **Hono middleware** | Route-level authentication integration via `createMiddleware` from `hono/factory` |
+| **`node:fs/promises`** | Async file reading for JWKS key files |
 | **Drizzle ORM** | Database access for user lookup (in your implementation) |
-| **lodash/isEmpty** | Used in strategy registry for name validation |
 
-## Component Private Methods
+## Component Methods
 
-The `AuthenticateComponent` uses four private methods during its `binding()` lifecycle:
+The `AuthenticateComponent` uses five methods during its `binding()` lifecycle (four private, one public):
 
 | Method | Purpose |
 |--------|---------|
-| `validateOptions(opts)` | Validates that at least one of `jwtOptions` or `basicOptions` is present. Throws if neither is provided. |
-| `defineJWTAuth(opts)` | Validates JWT secrets (rejects falsy values and `'unknown_secret'`), validates `getTokenExpiresFn`, binds `JWTTokenService` as a service. Logs debug if skipped. |
+| `defineJWSAuth(opts)` | Validates JWS secrets (rejects falsy values and `'unknown_secret'`), validates `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`. |
 | `defineBasicAuth(opts)` | Validates `verifyCredentials` callback presence, binds `BasicTokenService` as a service. Logs debug if skipped. |
 | `defineControllers(opts)` | Requires `jwtOptions` when `useAuthController: true`. Calls `defineAuthController()` factory and registers the generated controller. |
-| `defineOAuth2()` | Stub method -- not yet implemented. Called during `binding()` but performs no action. |
+| `defineOAuth2()` | **Public** stub method -- not yet implemented. Called during `binding()` but performs no action. |
 
-> [!WARNING]
-> **Security concern:** The `defineJWTAuth()` method includes the actual secret value in its error message when validation fails (e.g., <code v-pre>[defineJWTAuth] Invalid jwtSecret | Provided: {{jwtSecret}}</code>). Ensure these startup errors are never exposed to end users or logged in production without sanitization.
+> [!NOTE]
+> The component reads `TJWTTokenServiceOptions` (the discriminated union) from `AuthenticateBindingKeys.JWT_OPTIONS`, then re-binds just the inner options (`IJWSTokenServiceOptions` or `IJWKSIssuerOptions`/`IJWKSVerifierOptions`) to the appropriate binding key for the service to consume via `@inject`.
 
 ## Strategy Registry
 
-<code v-pre>AuthenticationStrategyRegistry&lt;E extends Env = Env&gt;</code> is a **singleton** that manages all registered strategies. It extends `BaseHelper`.
+`AuthenticationStrategyRegistry` is a **singleton** that manages all registered strategies. It extends `AbstractAuthRegistry<IAuthenticationStrategy>` (not generic on `Env`).
 
 ### API
 
 | Method | Signature | Returns | Description |
 |--------|-----------|---------|-------------|
 | `getInstance()` | `static` | `AuthenticationStrategyRegistry` | Returns the singleton instance (creates if not exists) |
-| `getStrategyKey` | `(opts: { name: string }) => string` | `string` | Returns the binding key for a strategy: <code v-pre>authentication.strategy.{{name}}</code> |
-| `getStrategy` | `(opts: { container: Container; name: string }) => IAuthenticationStrategy` | `IAuthenticationStrategy` | Resolves a strategy instance from the container by name |
-| `register` | <code v-pre>(opts: { container: Container; strategies: Array&lt;{ name: string; strategy: TClass&lt;IAuthenticationStrategy&lt;E&gt;&gt; }&gt; }) =&gt; this</code> | `this` | Registers strategies as singletons in the container. Returns `this` for chaining. |
-| `authenticate` | `(opts: { strategies: string[]; mode?: TAuthMode }) => MiddlewareHandler` | `MiddlewareHandler` | Creates a Hono middleware that performs the auth check |
+| `register` | <code v-pre>(opts: { container: Container; strategies: Array&lt;{ name: string; strategy: TClass&lt;IAuthenticationStrategy&gt; }&gt; }) =&gt; this</code> | `this` | Registers strategies as singletons in the container. Returns `this` for chaining. |
+| `resolveStrategy` | `(opts: { name: string }) => IAuthenticationStrategy` | `IAuthenticationStrategy` | Resolves a strategy instance from the container by name |
 
 **Registration:**
 ```typescript
 AuthenticationStrategyRegistry.getInstance().register({
   container: this,
   strategies: [
-    { name: Authentication.STRATEGY_JWT, strategy: JWTAuthenticationStrategy },
+    { name: Authentication.STRATEGY_JWT, strategy: JWKSIssuerAuthenticationStrategy },
     { name: Authentication.STRATEGY_BASIC, strategy: BasicAuthenticationStrategy },
   ],
 });
@@ -95,60 +126,181 @@ AuthenticationStrategyRegistry.getInstance().register({
 > `register()` returns `this`, enabling method chaining if needed.
 
 **How it works:**
-- Strategies are stored in an internal <code v-pre>Map&lt;string, { container, strategyClass }&gt;</code> and also bound to the DI container as singletons
+- Strategies are stored in an internal map and bound to the DI container as singletons
 - Binding keys follow the pattern `authentication.strategy.{name}` (e.g., `authentication.strategy.jwt`, `authentication.strategy.basic`)
-- The `authenticate()` method returns a Hono `MiddlewareHandler` that performs the auth check
-- The standalone `authenticate()` function is a convenience wrapper around the registry singleton
-
-**Strategy binding:**
-```typescript
-// Internally, the registry binds strategies like this:
-container.bind({ key: 'authentication.strategy.jwt' })
-  .toClass(JWTAuthenticationStrategy)
-  .setScope(BindingScopes.SINGLETON);
-```
+- The standalone `authenticate()` function creates middleware via `AuthenticationProvider`, which uses the registry to resolve strategies
 
 **Middleware creation:**
 
 The `authenticate()` function returns a Hono middleware that:
-1. Checks if `Authentication.SKIP_AUTHENTICATION` is set on context -- if true, skips entirely (logs debug)
-2. Checks if `Authentication.CURRENT_USER` is already set on context -- if true, skips (already authenticated)
+1. Checks if `Authentication.SKIP_AUTHENTICATION` is set on context — if true, skips entirely (logs debug)
+2. Checks if `Authentication.CURRENT_USER` is already set on context — if true, skips (already authenticated)
 3. Reads `strategies` and `mode` from the provided options
 4. Executes strategies based on mode (`any` or `all`)
 5. On success, sets `Authentication.CURRENT_USER` and `Authentication.AUDIT_USER_ID` on context
 6. On failure, throws 401 with list of tried strategies
 
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant MW as Auth Middleware
+    participant P as AuthenticationProvider
+    participant R as StrategyRegistry
+    participant S as Strategy
+    participant SVC as TokenService
+
+    C->>MW: Request with Authorization header
+    MW->>P: authenticateFn({ strategies, mode })
+    P->>P: Check SKIP_AUTHENTICATION
+    P->>P: Check CURRENT_USER already set
+    P->>R: resolveStrategy({ name })
+    R-->>P: strategy instance
+    P->>S: authenticate(context)
+    S->>SVC: extractCredentials(context)
+    SVC-->>S: { type, token }
+    S->>SVC: verify({ type, token })
+    SVC-->>S: IJWTTokenPayload
+    S-->>P: IAuthUser
+    P->>MW: Set CURRENT_USER + AUDIT_USER_ID
+    MW->>C: Continue to handler
+```
+
 ### Standalone `authenticate()` Function
 
 ```typescript
+const authenticationProvider = new AuthenticationProvider();
+const authenticateFn = authenticationProvider.value();
+
 export const authenticate = (opts: { strategies: string[]; mode?: TAuthMode }) => {
-  return AuthenticationStrategyRegistry.getInstance().authenticate(opts);
+  return authenticateFn(opts);
 };
 ```
 
-This is the primary export for creating auth middleware. It delegates directly to the singleton registry.
+This is the primary export for creating auth middleware. It creates an `AuthenticationProvider` instance and calls `.value()` to get the middleware factory. The provider uses `AuthenticationStrategyRegistry.getInstance()` internally to resolve strategies.
 
 > [!NOTE]
-> In `all` mode, if every strategy passes but the final user payload has no `userId`, the middleware throws a `401` with message `"Failed to identify authenticated user!"`. The `any` mode collects errors from each failing strategy and only throws after all strategies are exhausted.
+> In `all` mode, if every strategy passes but the final user payload has no `userId`, the middleware throws a `401` with message `"Failed to identify authenticated user!"`. The `any` mode **discards errors** from each failing strategy (logs at debug level) and only throws after all strategies are exhausted.
+
+## Service Class Hierarchy
+
+```mermaid
+classDiagram
+    class AbstractBearerTokenService {
+        <<abstract>>
+        #aes: AES | null
+        #applicationSecret: string | null
+        +extractCredentials(context) credentials
+        +verify(opts) IJWTTokenPayload
+        +generate(opts) string
+        +encryptPayload(payload) Record
+        +decryptPayload(opts) IJWTTokenPayload
+        #doVerify(token)* IJWTTokenPayload
+        +getSigner(opts)* SignJWT
+        #getSigningKey()* Uint8Array | CryptoKey
+        #getDefaultTokenExpiresFn()* TGetTokenExpiresFn
+    }
+
+    class JWSTokenService {
+        #jwtSecret: Uint8Array
+        #options: IJWSTokenServiceOptions
+    }
+
+    class AbstractJWKSTokenService {
+        <<abstract>>
+        #initialized: boolean
+        #initPromise: Promise | null
+        +ensureInitialized()
+        #initialize()* void
+    }
+
+    class JWKSIssuerTokenService {
+        #privateKey: CryptoKey | null
+        #publicKey: CryptoKey | null
+        #jwks: object | null
+        +getJWKS() keys
+        +getJWKSAsync() keys
+    }
+
+    class JWKSVerifierTokenService {
+        #jwksVerifier: Function | null
+        +getSigner() never
+        +getSigningKey() never
+    }
+
+    AbstractBearerTokenService <|-- JWSTokenService
+    AbstractBearerTokenService <|-- AbstractJWKSTokenService
+    AbstractJWKSTokenService <|-- JWKSIssuerTokenService
+    AbstractJWKSTokenService <|-- JWKSVerifierTokenService
+```
 
-## JWTTokenService
+## AbstractBearerTokenService
 
-All methods are instance methods on <code v-pre>JWTTokenService&lt;E extends Env = Env&gt;</code>, which extends `BaseService`.
+Base class for all Bearer token services. Extends `BaseService`. Generic on <code v-pre>&lt;E extends Env = Env&gt;</code>.
 
-### JWTAuthenticationStrategy
+**File:** `packages/core/src/components/auth/authenticate/services/bearer/abstract.service.ts`
 
-Extends `BaseHelper` and implements <code v-pre>IAuthenticationStrategy&lt;E&gt;</code>. Generic on <code v-pre>&lt;E extends Env = Env&gt;</code>.
+### Static Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `JWT_COMMON_FIELDS` | <code v-pre>Set&lt;'iss' \| 'sub' \| 'aud' \| 'jti' \| 'nbf' \| 'exp' \| 'iat'&gt;</code> | Standard JWT fields that are never encrypted |
+
+### Protected Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `aes` | `AES \| null` | `null` | AES utility instance, configured by `configurePayloadEncryption()` |
+| `applicationSecret` | `string \| null` | `null` | AES secret, configured by `configurePayloadEncryption()` |
+| `fieldCodecs` | <code v-pre>Map&lt;string, IPayloadFieldCodec&gt;</code> | `new Map()` | Field codec map keyed by field name, configured by `configurePayloadEncryption()` |
+
+### Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `configurePayloadEncryption` | <code v-pre>(opts: { aesAlgorithm?: AESAlgorithmType; applicationSecret?: string; fieldCodecs?: IPayloadFieldCodec[] }) =&gt; void</code> | Configures optional AES encryption and field codecs. Codecs are converted to a Map keyed by `codec.key` for O(1) lookup. |
+| `extractCredentials` | <code v-pre>(context: TContext&lt;E, string&gt;) =&gt; { type: string; token: string }</code> | Extracts Bearer token from Authorization header |
+| `verify` | <code v-pre>(opts: { type: string; token: string }) =&gt; Promise&lt;IJWTTokenPayload&gt;</code> | Template method — calls `doVerify()` |
+| `generate` | <code v-pre>(opts: { payload: IJWTTokenPayload; getTokenExpiresFn?: TGetTokenExpiresFn }) =&gt; Promise&lt;string&gt;</code> | Template method — calls `getSigner()` + `getSigningKey()` |
+| `serializeField` | <code v-pre>(opts: { key: string; value: any }) =&gt; string</code> | Serializes a single field: codec → `JSON.stringify` fallback |
+| `deserializeField` | <code v-pre>(opts: { key: string; value: string }) =&gt; any</code> | Deserializes a single field: codec → `JSON.parse` fallback |
+| `encryptPayload` | <code v-pre>(payload: IJWTTokenPayload) =&gt; Record&lt;string, any&gt;</code> | AES-encrypts non-standard JWT fields using `serializeField`. Returns payload unchanged if AES not configured. |
+| `decryptPayload` | <code v-pre>(opts: { result: JWTVerifyResult&lt;IJWTTokenPayload&gt; }) =&gt; IJWTTokenPayload</code> | Decrypts AES-encrypted fields using `deserializeField`. Returns payload unchanged if AES not configured. |
+
+### Abstract Methods (implemented by subclasses)
+
+| Method | Visibility | Signature | Description |
+|--------|------------|-----------|-------------|
+| `doVerify` | `protected` | `(token: string) => Promise<IJWTTokenPayload>` | Verify the raw JWT token and return the payload |
+| `getSigner` | **`public`** | <code v-pre>(opts: { payload: IJWTTokenPayload; getTokenExpiresFn: TGetTokenExpiresFn }) =&gt; Promise&lt;SignJWT&gt;</code> | Create a `jose.SignJWT` instance with the payload |
+| `getSigningKey` | `protected` | `() => ValueOrPromise<Uint8Array \| CryptoKey>` | Return the signing key |
+| `getDefaultTokenExpiresFn` | `protected` | `() => TGetTokenExpiresFn` | Return the default token expiry function |
+
+## JWSTokenService
+
+Symmetric JWT (HS256) token service with optional AES-encrypted payloads. Extends `AbstractBearerTokenService`.
+
+**File:** `packages/core/src/components/auth/authenticate/services/bearer/jws.service.ts`
+
+### JWSAuthenticationStrategy
+
+Extends `BaseHelper` and implements <code v-pre>IAuthenticationStrategy&lt;E&gt;</code>.
 
 ```typescript
-class JWTAuthenticationStrategy<E extends Env = Env>
+class JWSAuthenticationStrategy<E extends Env = Env>
   extends BaseHelper
   implements IAuthenticationStrategy<E>
 {
-  name = Authentication.STRATEGY_JWT; // 'jwt'
+  name = Authentication.STRATEGY_JWT;
+  standard = JOSEStandards.JWS;
 
   constructor(
-    @inject({ key: 'services.JWTTokenService' })
-    private service: JWTTokenService<E>,
+    @inject({
+      key: BindingKeys.build({
+        namespace: BindingNamespaces.SERVICE,
+        key: JWSTokenService.name,
+      }),
+    })
+    private service: JWSTokenService<E>,
   ) { ... }
 
   authenticate(context: TContext<E, string>): Promise<IAuthUser> {
@@ -158,48 +310,281 @@ class JWTAuthenticationStrategy<E extends Env = Env>
 }
 ```
 
+### Protected Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `jwtSecret` | `Uint8Array` | Encoded JWT secret for `jose` signing/verification |
+| `options` | `IJWSTokenServiceOptions` | Injected options |
+
+### Constructor Behavior
+
+The constructor validates required options and throws immediately (status 500) if any are missing:
+
+```typescript
+constructor(
+  @inject({ key: AuthenticateBindingKeys.JWT_OPTIONS })
+  protected options: IJWSTokenServiceOptions,
+) {
+  // Throws '[JWSTokenService] Invalid jwtSecret' if !jwtSecret
+  // Throws '[JWSTokenService] Invalid getTokenExpiresFn' if !getTokenExpiresFn
+  // Calls configurePayloadEncryption({ aesAlgorithm, applicationSecret })
+  // Encodes jwtSecret to Uint8Array for jose
+}
+```
+
+> [!NOTE]
+> `applicationSecret` is no longer validated in the constructor. If not provided, AES encryption is simply not configured, and payloads pass through in plaintext.
+
+### Overridden Methods
+
+| Method | Behavior |
+|--------|----------|
+| `doVerify(token)` | Calls `jwtVerify(token, this.jwtSecret)`, then `this.decryptPayload()` |
+| `getSigner(opts)` | Calls `this.encryptPayload()`, then creates `SignJWT` with HS256 header |
+| `getSigningKey()` | Returns `this.jwtSecret` |
+| `getDefaultTokenExpiresFn()` | Returns `this.options.getTokenExpiresFn` |
+
+## AbstractJWKSTokenService
+
+Base class for JWKS token services (Issuer + Verifier). Extends `AbstractBearerTokenService`.
+
+**File:** `packages/core/src/components/auth/authenticate/services/bearer/jwks/abstract.service.ts`
+
+Consolidates the lazy-initialization pattern with retry-on-failure semantics. If `initialize()` rejects, `initPromise` is reset so the next call retries instead of caching the failure permanently.
+
+### Protected Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `initialized` | `boolean` | `false` | Whether the service has been initialized |
+| `initPromise` | `Promise<void> \| null` | `null` | Pending initialization promise (for concurrent callers) |
+
 ### Methods
 
 | Method | Signature | Description |
 |--------|-----------|-------------|
-| `extractCredentials` | <code v-pre>(context: TContext&lt;E, string&gt;) =&gt; { type: string; token: string }</code> | Extracts Bearer token from Authorization header |
-| `verify` | <code v-pre>(opts: { type: string; token: string }) =&gt; Promise&lt;IJWTTokenPayload&gt;</code> | Verifies JWT signature via `jose.jwtVerify()` and decrypts payload |
-| `generate` | <code v-pre>(opts: { payload: IJWTTokenPayload; getTokenExpiresFn?: TGetTokenExpiresFn }) =&gt; Promise&lt;string&gt;</code> | Encrypts payload, signs JWT with configurable expiration |
-| `getSigner` | <code v-pre>(opts: { payload: IJWTTokenPayload; getTokenExpiresFn: TGetTokenExpiresFn }) =&gt; Promise&lt;SignJWT&gt;</code> | Creates a `jose.SignJWT` instance with encrypted payload, iat, exp, nbf |
-| `encryptPayload` | <code v-pre>(payload: IJWTTokenPayload) =&gt; Record&lt;string, string&gt;</code> | AES-encrypts non-standard JWT fields (keys + values) |
-| `decryptPayload` | <code v-pre>(opts: { result: JWTVerifyResult&lt;IJWTTokenPayload&gt; }) =&gt; IJWTTokenPayload</code> | Decrypts AES-encrypted fields back to IJWTTokenPayload |
+| `ensureInitialized` | `() => Promise<void>` | Lazily initializes the service on first call. Concurrent callers share the same promise. On failure, resets `initPromise` so the next call retries. |
 
-### Static Fields
+### Abstract Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `initialize` | `() => Promise<void>` | Perform one-time async initialization (load keys, create verifier, etc.) |
+
+## JWKSIssuerTokenService
+
+Asymmetric JWT token service (issuer mode). Extends `AbstractJWKSTokenService`.
+
+**File:** `packages/core/src/components/auth/authenticate/services/bearer/jwks/issuer.service.ts`
+
+### JWKSIssuerAuthenticationStrategy
 
-- `JWT_COMMON_FIELDS`: <code v-pre>Set&lt;'iss' | 'sub' | 'aud' | 'jti' | 'nbf' | 'exp' | 'iat'&gt;</code> -- fields preserved as-is during encryption
+```typescript
+class JWKSIssuerAuthenticationStrategy<E extends Env = Env>
+  extends BaseHelper
+  implements IAuthenticationStrategy<E>
+{
+  name = Authentication.STRATEGY_JWT;
+  standard = JOSEStandards.JWKS;
+
+  constructor(
+    @inject({
+      key: BindingKeys.build({
+        namespace: BindingNamespaces.SERVICE,
+        key: JWKSIssuerTokenService.name,
+      }),
+    })
+    private service: JWKSIssuerTokenService<E>,
+  ) { ... }
+
+  authenticate(context: TContext<E, string>): Promise<IAuthUser> {
+    const token = this.service.extractCredentials(context);
+    return this.service.verify(token);
+  }
+}
+```
 
 ### Protected Fields
 
-- `aes`: `AES` -- AES utility instance initialized with the configured algorithm
-- `jwtSecret`: `Uint8Array` -- encoded JWT secret for `jose` signing/verification
-- `options`: `IJWTTokenServiceOptions` -- injected options
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `privateKey` | `CryptoKey \| Uint8Array \| null` | `null` | Private key for signing (loaded during `initialize`) |
+| `publicKey` | `CryptoKey \| Uint8Array \| null` | `null` | Public key for verification (loaded during `initialize`) |
+| `jwks` | `{ keys: JWK[] } \| null` | `null` | Cached JWKS for the `/certs` endpoint |
 
 ### Constructor Behavior
 
-The constructor validates all three required options and throws immediately (status 500) if any are missing:
+```typescript
+constructor(
+  @inject({ key: AuthenticateBindingKeys.JWKS_OPTIONS })
+  protected options: IJWKSIssuerOptions,
+) {
+  // Calls configurePayloadEncryption({ aesAlgorithm, applicationSecret })
+  // Keys are NOT loaded here — loaded lazily via ensureInitialized()
+}
+```
+
+### Initialization Flow
+
+The `initialize()` method:
+1. **Resolves key content** — reads from file (`readFile` from `node:fs/promises`) or uses inline text, based on `keys.driver`
+2. **Parses key material** — imports keys using `importPKCS8`/`importSPKI` (PEM format) or `importJWK` (JWK format), based on `keys.format`
+3. **Exports public JWK** — calls `exportJWK()` and adds `kid`, `alg`, `use: 'sig'` metadata
+4. **Caches JWKS** — stores `{ keys: [publicJWK] }` for the `/certs` endpoint
+5. **Sets `initialized = true`**
+
+### Overridden Methods
+
+| Method | Behavior |
+|--------|----------|
+| `doVerify(token)` | Calls `ensureInitialized()`, then `jwtVerify(token, this.publicKey!)`, then `this.decryptPayload()` |
+| `getSigner(opts)` | Calls `ensureInitialized()`, then `this.encryptPayload()`, then creates `SignJWT` with algorithm + kid header |
+| `getSigningKey()` | Returns `this.privateKey` |
+| `getDefaultTokenExpiresFn()` | Returns `this.options.getTokenExpiresFn` |
+
+### JWKS Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getJWKS` | `() => { keys: JWK[] }` | Synchronous — returns cached JWKS. Throws if not yet initialized. |
+| `getJWKSAsync` | `() => Promise<{ keys: JWK[] }>` | Async — calls `ensureInitialized()` first, then returns JWKS. |
+
+### Internal Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `resolveKeyContent` | `(opts: { keys }) => Promise<{ priv: string; pub: string }>` | Reads key content from file or returns inline text |
+| `parseKeyMaterial` | `(opts: { raw, algorithm, keys }) => Promise<{ priv, pub }>` | Imports keys using `jose` based on format (PEM or JWK) |
+
+## JWKSVerifierTokenService
+
+Asymmetric JWT token service (verifier mode). Extends `AbstractJWKSTokenService`.
+
+**File:** `packages/core/src/components/auth/authenticate/services/bearer/jwks/verifier.service.ts`
+
+### JWKSVerifierAuthenticationStrategy
+
+```typescript
+class JWKSVerifierAuthenticationStrategy<E extends Env = Env>
+  extends BaseHelper
+  implements IAuthenticationStrategy<E>
+{
+  name = Authentication.STRATEGY_JWT;
+  standard = JOSEStandards.JWKS;
+
+  constructor(
+    @inject({
+      key: BindingKeys.build({
+        namespace: BindingNamespaces.SERVICE,
+        key: JWKSVerifierTokenService.name,
+      }),
+    })
+    private service: JWKSVerifierTokenService<E>,
+  ) { ... }
+
+  authenticate(context: TContext<E, string>): Promise<IAuthUser> {
+    const token = this.service.extractCredentials(context);
+    return this.service.verify(token);
+  }
+}
+```
+
+### Protected Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `jwksVerifier` | `ReturnType<typeof createRemoteJWKSet> \| null` | `null` | Remote JWKS verifier function |
+
+### Constructor Behavior
 
 ```typescript
 constructor(
-  @inject({ key: AuthenticateBindingKeys.JWT_OPTIONS })
-  protected options: IJWTTokenServiceOptions,
+  @inject({ key: AuthenticateBindingKeys.JWKS_OPTIONS })
+  protected options: IJWKSVerifierOptions,
 ) {
-  // Throws '[JWTTokenService] Invalid jwtSecret' if !jwtSecret
-  // Throws '[JWTTokenService] Invalid applicationSecret' if !applicationSecret
-  // Throws '[JWTTokenService] Invalid getTokenExpiresFn' if !getTokenExpiresFn
-  // Initializes AES with configured algorithm (default 'aes-256-cbc')
-  // Encodes jwtSecret to Uint8Array for jose
+  // Calls configurePayloadEncryption({ aesAlgorithm, applicationSecret })
+  // Remote JWKS is NOT fetched here — fetched lazily via ensureInitialized()
+}
+```
+
+### Initialization Flow
+
+The `initialize()` method:
+1. Creates a `createRemoteJWKSet()` from the configured `jwksUrl`
+2. Configures `cacheMaxAge` (default 12h) and `cooldownDuration` (default 30s)
+3. Sets `initialized = true`
+
+### Overridden Methods
+
+| Method | Behavior |
+|--------|----------|
+| `doVerify(token)` | Calls `ensureInitialized()`, then `jwtVerify(token, this.jwksVerifier!)`, then `this.decryptPayload()` |
+| `getSigner(opts)` | Throws — verifier mode cannot sign tokens |
+| `getSigningKey()` | Throws — verifier mode cannot sign tokens |
+| `getDefaultTokenExpiresFn()` | Throws — verifier mode has no token expiry |
+
+## JWKSController
+
+Serves the JWKS endpoint (default path `/certs`). This endpoint is **intentionally unauthenticated** — it serves the public keys needed by external verifiers.
+
+**File:** `packages/core/src/components/auth/authenticate/controllers/jwks/controller.ts`
+
+```typescript
+class JWKSController extends BaseController {
+  constructor(
+    @inject({
+      key: BindingKeys.build({
+        namespace: BindingNamespaces.SERVICE,
+        key: JWKSIssuerTokenService.name,
+      }),
+    })
+    private jwksService: JWKSIssuerTokenService,
+  ) {
+    super({ scope: JWKSController.name, path: '/certs', isStrict: true });
+  }
+
+  override binding(): ValueOrPromise<void> {
+    this.defineRoute({
+      configs: RouteConfigs.GET_JWKS_CERTS,
+      handler: async context => {
+        const jwks = await this.jwksService.getJWKSAsync();
+        context.header('Cache-Control', 'public, max-age=3600, stale-while-revalidate=86400');
+        return context.json(jwks, HTTP.ResultCodes.RS_2.Ok);
+      },
+    });
+  }
+}
+```
+
+**Response format:**
+```json
+{
+  "keys": [
+    {
+      "kty": "EC",
+      "kid": "my-key-id-1",
+      "use": "sig",
+      "alg": "ES256",
+      "crv": "P-256",
+      "x": "...",
+      "y": "..."
+    }
+  ]
 }
 ```
 
+**Cache headers:** `Cache-Control: public, max-age=3600, stale-while-revalidate=86400`
+
+> [!NOTE]
+> The `/certs` path is configurable via `rest.path` in `IJWKSIssuerOptions`. The component applies the `@controller` decorator dynamically with the configured path.
+
 ## BasicTokenService
 
 All methods are instance methods on <code v-pre>BasicTokenService&lt;E extends Env = Env&gt;</code>, which extends `BaseService`.
 
+**File:** `packages/core/src/components/auth/authenticate/services/basic/service.ts`
+
 ### BasicAuthenticationStrategy
 
 Extends `BaseHelper` and implements <code v-pre>IAuthenticationStrategy&lt;E&gt;</code>. Generic on <code v-pre>&lt;E extends Env = Env&gt;</code>.
@@ -209,10 +594,15 @@ class BasicAuthenticationStrategy<E extends Env = Env>
   extends BaseHelper
   implements IAuthenticationStrategy<E>
 {
-  name = Authentication.STRATEGY_BASIC; // 'basic'
+  name = Authentication.STRATEGY_BASIC;
 
   constructor(
-    @inject({ key: 'services.BasicTokenService' })
+    @inject({
+      key: BindingKeys.build({
+        namespace: BindingNamespaces.SERVICE,
+        key: BasicTokenService.name,
+      }),
+    })
     private service: BasicTokenService<E>,
   ) { ... }
 
@@ -230,16 +620,12 @@ class BasicAuthenticationStrategy<E extends Env = Env>
 | `extractCredentials` | <code v-pre>(context: TContext&lt;E, string&gt;) =&gt; { username: string; password: string }</code> | Decodes Base64 <code v-pre>Authorization: Basic &lt;base64&gt;</code> header |
 | `verify` | <code v-pre>(opts: { credentials: { username: string; password: string }; context: TContext&lt;E, string&gt; }) =&gt; Promise&lt;IAuthUser&gt;</code> | Calls user-provided `verifyCredentials` callback |
 
-### Private Fields
-
-- `verifyCredentials` -- the callback function extracted from injected options
-
 ### Constructor Behavior
 
 ```typescript
 constructor(
   @inject({ key: AuthenticateBindingKeys.BASIC_OPTIONS })
-  protected options: IBasicTokenServiceOptions<E>,
+  protected options: TBasicTokenServiceOptions<E>,
 ) {
   // Throws '[BasicTokenService] Invalid verifyCredentials function' if !options?.verifyCredentials
 }
@@ -299,7 +685,7 @@ The `defineAuthController()` function dynamically creates a controller class at
 1. **Class creation:** A new class is created dynamically with `class AuthController extends BaseController {}` inside the factory closure
 2. **Decorator application:** The `@controller({ path: restPath })` decorator is applied to set the base path. The controller is created with `isStrict: true`
 3. **Service injection:** The auth service is injected via `inject({ key: serviceKey })(AuthController, undefined, 0)` after class definition -- this programmatically applies `@inject` to constructor parameter 0
-   - Default service key: `'services.AuthenticationService'`
+   - Service key is provided via `controllerOpts.serviceKey` (required)
    - Service must implement `IAuthService` interface
 4. **Route definition:** Routes are defined in the controller's `binding()` method using `this.defineRoute()`
 5. **Schema customization:** Custom Zod schemas can be provided per endpoint via the `payload` option. Defaults to built-in schemas when not provided, with `AnyObjectSchema` as the response fallback.
@@ -313,111 +699,6 @@ function defineAuthController(opts: TDefineAuthControllerOpts): typeof AuthContr
 > [!NOTE]
 > The factory also exports `JWTTokenPayloadSchema`, a Zod schema used for the `/who-am-i` response validation.
 
-**Internal route binding:**
-
-```typescript
-// Inside the factory-generated controller
-binding(): void {
-  // /sign-in -- no auth, delegates to service.signIn()
-  this.defineRoute({
-    configs: {
-      path: '/sign-in',
-      method: 'post',
-      request: {
-        body: jsonContent({
-          description: 'Sign-in request body',
-          required: true,
-          schema: payload?.signIn?.request?.schema ?? SignInRequestSchema,
-        }),
-      },
-      responses: jsonResponse({
-        schema: payload?.signIn?.request?.schema ?? AnyObjectSchema,
-        description: 'Success Response',
-      }),
-    },
-    handler: async (context) => {
-      const body = await context.req.json();
-      const rs = await this.service.signIn(context, body);
-      return context.json(rs, HTTP.ResultCodes.RS_2.Ok);
-    },
-  });
-
-  // /sign-up -- conditionally requires JWT auth
-  this.defineRoute({
-    configs: {
-      path: '/sign-up',
-      method: 'post',
-      authenticate: {
-        strategies: !requireAuthenticatedSignUp ? [] : [Authentication.STRATEGY_JWT],
-      },
-      request: {
-        body: jsonContent({
-          description: 'Sign-up request body',
-          required: true,
-          schema: payload?.signUp?.request?.schema ?? SignUpRequestSchema,
-        }),
-      },
-      responses: jsonResponse({
-        schema: payload?.signUp?.response?.schema ?? AnyObjectSchema,
-        description: 'Success Response',
-      }),
-    },
-    handler: async (context) => {
-      const body = await context.req.json();
-      const rs = await this.service.signUp(context, body);
-      return context.json(rs, HTTP.ResultCodes.RS_2.Ok);
-    },
-  });
-
-  // /change-password -- always requires JWT auth
-  this.defineRoute({
-    configs: {
-      path: '/change-password',
-      method: 'post',
-      authenticate: { strategies: [Authentication.STRATEGY_JWT] },
-      request: {
-        body: jsonContent({
-          description: 'Change password request body',
-          required: true,
-          schema: payload?.changePassword?.request?.schema ?? ChangePasswordRequestSchema,
-        }),
-      },
-      responses: jsonResponse({
-        schema: payload?.changePassword?.response?.schema ?? AnyObjectSchema,
-        description: 'Success Response',
-      }),
-    },
-    handler: async (context) => {
-      const body = await context.req.json();
-      const rs = await this.service.changePassword(context, body);
-      return context.json(rs, HTTP.ResultCodes.RS_2.Ok);
-    },
-  });
-
-  // /who-am-i -- always requires JWT, returns current user from context
-  this.defineRoute({
-    configs: {
-      path: '/who-am-i',
-      method: 'get',
-      authenticate: { strategies: [Authentication.STRATEGY_JWT] },
-      responses: {
-        [HTTP.ResultCodes.RS_2.Ok]: jsonContent({
-          description: 'Success Response',
-          schema: JWTTokenPayloadSchema,
-        }),
-      },
-    },
-    handler: (context) => {
-      const currentUser = context.get(Authentication.CURRENT_USER as never) as IJWTTokenPayload;
-      return context.json(currentUser, HTTP.ResultCodes.RS_2.Ok);
-    },
-  });
-}
-```
-
-> [!TIP]
-> If the default request/response schemas do not fit your needs, provide custom Zod schemas through the `payload` option in `controllerOpts`. This allows full control over validation while keeping the built-in routing.
-
 **Service resolution:**
 
 The factory applies `@inject` programmatically to constructor parameter 0:
@@ -437,6 +718,45 @@ constructor(
 
 If the service is not bound, the component will throw: `"[AuthController] Failed to init auth controller | Invalid injectable authentication service!"`
 
+## File Structure
+
+```
+packages/core/src/components/auth/authenticate/
+├── common/
+│   ├── codecs.ts             # AuthenticationFieldCodecs (ROLES_CODEC, build() factory)
+│   ├── constants.ts          # AuthenticateStrategy, JOSEStandards, JWKSModes, JWKSKeyDrivers, JWKSKeyFormats, Authentication, AuthenticationTokenTypes, AuthenticationModes
+│   ├── keys.ts               # AuthenticateBindingKeys (REST_OPTIONS, JWT_OPTIONS, JWKS_OPTIONS, BASIC_OPTIONS)
+│   ├── types.ts              # All option interfaces, discriminated unions, IAuthUser, IJWTTokenPayload, IPayloadFieldCodec, IAuthService
+│   └── index.ts              # Barrel export
+├── controllers/
+│   ├── factory.ts            # defineAuthController() factory + JWTTokenPayloadSchema
+│   └── jwks/
+│       ├── controller.ts     # JWKSController (serves /certs endpoint)
+│       └── definitions.ts    # Route config for GET /certs
+├── middlewares/
+│   └── authenticate.middleware.ts  # Standalone authenticate() convenience function
+├── providers/
+│   └── authentication.provider.ts  # AuthenticationProvider (IProvider pattern, creates middleware)
+├── services/
+│   ├── basic/
+│   │   └── service.ts        # BasicTokenService
+│   ├── bearer/
+│   │   ├── abstract.service.ts   # AbstractBearerTokenService (shared logic)
+│   │   ├── jws.service.ts        # JWSTokenService (symmetric HS256)
+│   │   └── jwks/
+│   │       ├── abstract.service.ts   # AbstractJWKSTokenService (lazy-init)
+│   │       ├── issuer.service.ts     # JWKSIssuerTokenService
+│   │       └── verifier.service.ts   # JWKSVerifierTokenService
+│   └── index.ts              # Barrel export
+├── strategies/
+│   ├── basic.strategy.ts     # BasicAuthenticationStrategy
+│   ├── jws.strategy.ts       # JWSAuthenticationStrategy
+│   ├── jwks.strategy.ts      # JWKSIssuerAuthenticationStrategy + JWKSVerifierAuthenticationStrategy
+│   ├── strategy-registry.ts  # AuthenticationStrategyRegistry singleton
+│   └── index.ts              # Barrel export
+└── component.ts              # AuthenticateComponent
+```
+
 ## See Also
 
 - [Setup & Configuration](./) -- Binding keys, options interfaces, and initial setup