@venizia/ignis-docs 0.2.0 → 0.2.1-1

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

@@ -1,8 +1,31 @@
-# Authentication -- Error Reference
+---
+title: Authentication Errors
+description: Every error the Authentication component throws, organized by source, with cause and fix
+difficulty: intermediate
+---
+
+# Authentication Errors
 
-> Complete error messages and troubleshooting for the authentication module. See [Setup & Configuration](./) for initial setup.
+Every error message the Authentication component and its services throw, with cause and fix. See the [Overview](./) for initial setup.
 
-## Error Flow Overview
+## 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 - 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
@@ -10,512 +33,170 @@ flowchart LR
     MW --> SKIP{"Skip auth?"}
     SKIP -->|"Yes"| PASS["Pass through"]
     SKIP -->|"No"| EXTRACT["Extract credentials"]
-    EXTRACT -->|"Missing header"| E401A["401 Missing header"]
-    EXTRACT -->|"Wrong scheme"| E401B["401 Invalid scheme"]
-    EXTRACT -->|"Bad format"| E401C["401 Invalid format"]
-    EXTRACT -->|"OK"| VERIFY["Verify token"]
-    VERIFY -->|"Expired/invalid"| E401D["401 Invalid token"]
+    EXTRACT -->|"Missing/wrong/malformed"| E401["401"]
+    EXTRACT -->|"OK"| VERIFY["Verify token / credentials"]
+    VERIFY -->|"Invalid/expired"| E401
     VERIFY -->|"Valid"| USER["Set CURRENT_USER"]
     USER --> NEXT["Next middleware"]
 
-    style E401A fill:#f8d7da,stroke:#dc3545
-    style E401B fill:#f8d7da,stroke:#dc3545
-    style E401C fill:#f8d7da,stroke:#dc3545
-    style E401D fill:#f8d7da,stroke:#dc3545
+    style E401 fill:#f8d7da,stroke:#dc3545
     style PASS fill:#d4edda,stroke:#28a745
     style NEXT fill:#d4edda,stroke:#28a745
 ```
 
-## Complete Error Reference
+## AuthenticateComponent (startup)
 
-All error messages from the authentication module, organized by source.
+Thrown during `binding()` while validating options and wiring services.
 
----
+| Message | Status | Cause | Fix |
+|---------|--------|-------|-----|
+| `[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 - `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` |
+| `[defineJWKSAuth] kid is required for issuer mode` | 400 | `kid` (Key ID) not provided | Provide a unique `kid` string |
+| `[defineJWKSAuth] getTokenExpiresFn is required for issuer mode` | 400 | `getTokenExpiresFn` missing | Provide a token-expiry function |
+| `[defineJWKSAuth] jwksUrl is required for verifier mode` | 400 | Verifier mode missing `jwksUrl` | Provide the issuer's `/certs` URL |
+| `[defineJWKSAuth] Invalid JWKS mode: {mode}` | 400 | `mode` is not `'issuer'` or `'verifier'` | Use `JWKSModes.ISSUER` or `JWKSModes.VERIFIER` |
+| `[defineBasicAuth] verifyCredentials function is required` | 400 | `BASIC_OPTIONS` bound without a `verifyCredentials` callback | Provide the callback - see [Setup](./#common-tasks) |
+| `[defineControllers] Auth controller requires jwtOptions to be configured` | 400 | `useAuthController: true` but no `jwtOptions` bound | Bind `JWT_OPTIONS` before enabling the auth controller |
 
-### Component Errors (`AuthenticateComponent`)
+> [!NOTE]
+> `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.
 
-Thrown during `binding()` when validating options and configuring services.
+## Bearer token services (runtime)
 
-| Error Message | Status | Method | When |
-|---------------|--------|--------|------|
-| `[AuthenticateComponent] At least one of jwtOptions or basicOptions must be provided` | 400 | `binding` | Neither `JWT_OPTIONS` nor `BASIC_OPTIONS` bound in DI container |
-| <code v-pre>[AuthenticateComponent] Unknown JOSE standard: {{standard}}</code> | 400 | `binding` | `jwtOptions.standard` is not `'JWS'` or `'JWKS'` |
+Shared by `JWSTokenService`, `JWKSIssuerTokenService`, and `JWKSVerifierTokenService` via `AbstractBearerTokenService`.
 
-#### `defineJWSAuth` Errors
+| Message | Status | Method | Cause | Fix |
+|---------|--------|--------|-------|-----|
+| `Unauthorized user! Missing authorization header` | 401 | `extractCredentials` | No `Authorization` header | Send `Authorization: Bearer <token>` |
+| `Unauthorized user! Invalid schema of request token!` | 401 | `extractCredentials` | Header doesn't start with `Bearer` | Use the `Bearer` scheme |
+| `Authorization header value is invalid format. It must follow the pattern: 'Bearer xx.yy.zz' ...` | 401 | `extractCredentials` | Header doesn't split into exactly 2 parts | Check for extra whitespace or a malformed token |
+| `[verify] Invalid request token!` | 401 | `verify` | Token value is empty | Ensure the token half of the header isn't blank |
+| `[verify] Invalid or expired token` | 401 | `verify` | `doVerify()` threw - expired, malformed, or bad signature | Check application logs for the real cause (see below) |
+| `[generate] Invalid token payload!` | 401 | `generate` | Payload is null/undefined | Pass a non-null `IJWTTokenPayload` |
+| `[generate] Failed to generate token` | 500 | `generate` | Signing failed (key/algorithm issue) | Check application logs for the real cause |
 
-| Error Message | Status | Method | When |
-|---------------|--------|--------|------|
-| <code v-pre>[defineJWSAuth] Invalid jwtSecret &#124; Provided: {{jwtSecret}}</code> | 400 | `defineJWSAuth` | `jwtSecret` is falsy or equals `'unknown_secret'` |
-| `[defineJWSAuth] getTokenExpiresFn is required` | 400 | `defineJWSAuth` | `getTokenExpiresFn` not provided in JWS options |
+> [!TIP]
+> Errors are sanitized on the wire. `verify()` and `generate()` never leak the original `error.message` to the client. The full error is logged at `error` level - run `grep "Failed to verify token" logs/application.log` to find it.
 
-::: info applicationSecret is no longer validated
-`applicationSecret` was previously required and validated by the component. It is now **optional** - omitting it simply disables AES payload encryption.
-:::
+## JWSTokenService (constructor)
 
-#### `defineJWKSAuth` Errors (Issuer Mode)
+| Message | Status | Cause | Fix |
+|---------|--------|-------|-----|
+| `[JWSTokenService] Invalid jwtSecret` | 500 | `jwtSecret` falsy in injected options | Fix the `JWT_OPTIONS` binding |
+| `[JWSTokenService] Invalid getTokenExpiresFn` | 500 | `getTokenExpiresFn` falsy in injected options | Fix the `JWT_OPTIONS` binding |
+| `[getSigningKey] Invalid jwtSecret!` | 400 | `jwtSecret` Uint8Array is null | Should not happen after constructor validation - report if seen |
 
-| Error Message | Status | Method | When |
-|---------------|--------|--------|------|
-| `[defineJWKSAuth] keys.private and keys.public are required for issuer mode` | 400 | `defineJWKSAuth` | `keys.private` or `keys.public` missing |
-| <code v-pre>[defineJWKSAuth] keys.format is required and must be one of: pem, jwk</code> | 400 | `defineJWKSAuth` | `keys.format` missing or not in `JWKSKeyFormats.SCHEME_SET` |
-| `[defineJWKSAuth] kid is required for issuer mode` | 400 | `defineJWKSAuth` | `kid` (Key ID) not provided |
-| `[defineJWKSAuth] getTokenExpiresFn is required for issuer mode` | 400 | `defineJWKSAuth` | `getTokenExpiresFn` not provided |
+## JWKSIssuerTokenService (init + runtime)
 
-#### `defineJWKSAuth` Errors (Verifier Mode)
+| Message | Status | Method | Cause | Fix |
+|---------|--------|--------|-------|-----|
+| `[JWKSIssuerTokenService] Unknown key driver: {driver}` | 500 | `resolveKeyContent` | `keys.driver` not `'text'` or `'file'` | Use `JWKSKeyDrivers.TEXT` or `.FILE` |
+| `[JWKSIssuerTokenService] Invalid raw.priv key!` | 500 | `parseKeyMaterial` | Resolved private key content is empty | Check the file path or inline string |
+| `[JWKSIssuerTokenService] Invalid raw.pub key!` | 500 | `parseKeyMaterial` | Resolved public key content is empty | Check the file path or inline string |
+| `[JWKSIssuerTokenService] Invalid JWK key material` | 500 | `parseKeyMaterial` | JWK JSON parse or `importJWK()` failed | Validate the JWK is well-formed JSON (see below) |
+| `[JWKSIssuerTokenService] Unknown key format: {format}` | 500 | `parseKeyMaterial` | `keys.format` not `'pem'` or `'jwk'` | Use `JWKSKeyFormats.PEM` or `.JWK` |
+| `[getSigningKey] Invalid privateKey!` | 400 | `getSigningKey` | Private key null - init incomplete or failed | Ensure `initialize()` succeeded; check logs |
+| `[JWKSIssuerTokenService] JWKS not initialized yet. Call getJWKSAsync() instead.` | 500 | `getJWKS` | Sync `getJWKS()` called before lazy init completed | Use `await getJWKSAsync()` instead |
 
-| Error Message | Status | Method | When |
-|---------------|--------|--------|------|
-| `[defineJWKSAuth] jwksUrl is required for verifier mode` | 400 | `defineJWKSAuth` | `jwksUrl` not provided for verifier mode |
+> [!WARNING]
+> File read errors are not wrapped. With `JWKSKeyDrivers.FILE`, `readFile()` errors (`ENOENT`, `EACCES`, ...) surface as raw Node.js filesystem errors during initialization - they are not caught and re-thrown as `getError()`.
 
-#### `defineJWKSAuth` Errors (General)
+## JWKSVerifierTokenService (runtime)
 
-| Error Message | Status | Method | When |
-|---------------|--------|--------|------|
-| <code v-pre>[defineJWKSAuth] Invalid JWKS mode: {{mode}}</code> | 400 | `defineJWKSAuth` | `mode` is not `'issuer'` or `'verifier'` |
+| Message | Status | Method | Cause |
+|---------|--------|--------|-------|
+| `[JWKSVerifierTokenService] Verifier mode cannot sign tokens` | 500 | `getSigner` | `generate()` called on a verify-only service |
+| `[JWKSVerifierTokenService] Verifier mode cannot sign tokens` | 500 | `getSigningKey` | Signing key accessed on a verify-only service |
+| `[JWKSVerifierTokenService] Verifier mode has no token expiry` | 500 | `getDefaultTokenExpiresFn` | Token expiry accessed on a verify-only service |
 
-#### `defineBasicAuth` Errors
-
-| Error Message | Status | Method | When |
-|---------------|--------|--------|------|
-| `[defineBasicAuth] verifyCredentials function is required` | 400 | `defineBasicAuth` | `BASIC_OPTIONS` bound without a `verifyCredentials` callback |
-
-#### `defineControllers` Errors
-
-| Error Message | Status | Method | When |
-|---------------|--------|--------|------|
-| `[defineControllers] Auth controller requires jwtOptions to be configured` | 400 | `defineControllers` | `useAuthController: true` but no `jwtOptions` provided |
-
----
+**Fix:** token generation must happen on the **issuer** service. If one application needs both signing and verification, use `JWKSModes.ISSUER` everywhere - an issuer can both sign and verify.
 
-### Bearer Token Service Errors (`AbstractBearerTokenService`)
-
-Base class errors shared by `JWSTokenService`, `JWKSIssuerTokenService`, and `JWKSVerifierTokenService`.
-
-#### `extractCredentials` Errors
-
-| Error Message | Status | Method | When |
-|---------------|--------|--------|------|
-| `Unauthorized user! Missing authorization header` | 401 | `extractCredentials` | Request has no `Authorization` header |
-| `Unauthorized user! Invalid schema of request token!` | 401 | `extractCredentials` | `Authorization` header doesn't start with `Bearer` |
-| <code v-pre>Authorization header value is invalid format. It must follow the pattern: 'Bearer xx.yy.zz' where xx.yy.zz is a valid JWT token.</code> | 401 | `extractCredentials` | `Authorization` header doesn't have exactly 2 parts (type + token) |
-
-#### `verify` Errors
-
-| Error Message | Status | Method | When |
-|---------------|--------|--------|------|
-| `[verify] Invalid request token!` | 401 | `verify` | Token value is empty/falsy |
-| `[verify] Invalid or expired token` | 401 | `verify` | `doVerify()` threw - token is expired, malformed, or signature invalid |
-
-::: tip Sanitized error messages
-The `verify()` and `generate()` methods use **sanitized error messages** - they do NOT include the original `error.message` in the thrown error. The full error is logged at `error` level for debugging but not exposed to clients.
-:::
-
-#### `generate` Errors
-
-| Error Message | Status | Method | When |
-|---------------|--------|--------|------|
-| `[generate] Invalid token payload!` | 401 | `generate` | Payload is null/undefined |
-| `[generate] Failed to generate token` | 500 | `generate` | Signing failed (key issue, algorithm mismatch, etc.) |
-
----
-
-### JWS Token Service Errors (`JWSTokenService`)
-
-Constructor validation errors thrown during DI resolution.
-
-| Error Message | Status | Method | When |
-|---------------|--------|--------|------|
-| `[JWSTokenService] Invalid jwtSecret` | 500 | `constructor` | `jwtSecret` is falsy in injected `IJWSTokenServiceOptions` |
-| `[JWSTokenService] Invalid getTokenExpiresFn` | 500 | `constructor` | `getTokenExpiresFn` is falsy in injected options |
-| `[getSigningKey] Invalid jwtSecret!` | 400 | `getSigningKey` | `jwtSecret` Uint8Array is null (should not happen after constructor validation) |
-
-::: info applicationSecret no longer validated
-`JWSTokenService` no longer validates `applicationSecret` in its constructor. If not provided, AES payload encryption is simply disabled.
-:::
-
----
-
-### JWKS Issuer Token Service Errors (`JWKSIssuerTokenService`)
-
-Errors thrown during lazy initialization (`ensureInitialized()`) and key operations.
-
-#### Initialization Errors
-
-| Error Message | Status | Method | When |
-|---------------|--------|--------|------|
-| <code v-pre>[JWKSIssuerTokenService] Unknown key driver: {{driver}}</code> | 500 | `resolveKeyContent` | `keys.driver` is not `'text'` or `'file'` |
-| `[JWKSIssuerTokenService] Invalid raw.priv key!` | 500 | `parseKeyMaterial` | Resolved private key content is empty |
-| `[JWKSIssuerTokenService] Invalid raw.pub key!` | 500 | `parseKeyMaterial` | Resolved public key content is empty |
-| `[JWKSIssuerTokenService] Invalid JWK key material` | 500 | `parseKeyMaterial` | JWK JSON parsing or `importJWK()` failed (PEM format works, JWK content is invalid) |
-| <code v-pre>[JWKSIssuerTokenService] Unknown key format: {{format}}</code> | 500 | `parseKeyMaterial` | `keys.format` is not `'pem'` or `'jwk'` |
-
-::: warning File read errors
-When using `JWKSKeyDrivers.FILE`, file read errors from `readFile()` propagate as Node.js filesystem errors (e.g., `ENOENT`, `EACCES`). These are **not** wrapped - the raw error surfaces during initialization.
-:::
-
-#### Runtime Errors
-
-| Error Message | Status | Method | When |
-|---------------|--------|--------|------|
-| `[getSigningKey] Invalid privateKey!` | 400 | `getSigningKey` | Private key is null (initialization incomplete or failed) |
-| `[JWKSIssuerTokenService] JWKS not initialized yet. Call getJWKSAsync() instead.` | 500 | `getJWKS` | Sync `getJWKS()` called before lazy init completed |
-
----
-
-### JWKS Verifier Token Service Errors (`JWKSVerifierTokenService`)
-
-| Error Message | Status | Method | When |
-|---------------|--------|--------|------|
-| `[JWKSVerifierTokenService] Verifier mode cannot sign tokens` | 500 | `getSigner` | Attempt to call `generate()` on a verify-only service |
-| `[JWKSVerifierTokenService] Verifier mode cannot sign tokens` | 500 | `getSigningKey` | Attempt to access signing key on a verify-only service |
-| `[JWKSVerifierTokenService] Verifier mode has no token expiry` | 500 | `getDefaultTokenExpiresFn` | Attempt to access token expiry on a verify-only service |
-
-::: tip Verifier mode is read-only
-`JWKSVerifierTokenService` **cannot** generate tokens. Calling `generate()` throws because both `getSigner()` and `getSigningKey()` throw. Only `verify()` and `extractCredentials()` are functional.
-:::
-
----
+## BasicTokenService (runtime)
 
-### Basic Token Service Errors (`BasicTokenService`)
+| Message | Status | Method | Cause | Fix |
+|---------|--------|--------|-------|-----|
+| `[BasicTokenService] Invalid verifyCredentials function` | 500 | `constructor` | `verifyCredentials` missing from injected options | Provide the callback in `BASIC_OPTIONS` |
+| `Unauthorized! Missing authorization header` | 401 | `extractCredentials` | No `Authorization` header | Send `Authorization: Basic <base64>` |
+| `Unauthorized! Invalid authorization schema, expected Basic` | 401 | `extractCredentials` | Header doesn't start with `Basic` | Use the `Basic` scheme |
+| `Unauthorized! Invalid authorization header format` | 401 | `extractCredentials` | Header doesn't split into exactly 2 parts | Check the header value |
+| `Unauthorized! Invalid base64 credentials format` | 401 | `extractCredentials` | Base64 decode failed, or no `:` separator, or empty username | Verify the client encodes `username:password` correctly |
+| `Unauthorized! Invalid username or password` | 401 | `verify` | `verifyCredentials` callback returned `null` | Expected on wrong credentials - check your callback's lookup logic if unexpected |
 
-| Error Message | Status | Method | When |
-|---------------|--------|--------|------|
-| `[BasicTokenService] Invalid verifyCredentials function` | 500 | `constructor` | `verifyCredentials` not provided in injected `TBasicTokenServiceOptions` |
-| `Unauthorized! Missing authorization header` | 401 | `extractCredentials` | Request has no `Authorization` header |
-| `Unauthorized! Invalid authorization schema, expected Basic` | 401 | `extractCredentials` | `Authorization` header doesn't start with `Basic` |
-| `Unauthorized! Invalid authorization header format` | 401 | `extractCredentials` | Header doesn't have exactly 2 parts (`Basic` + base64 value) |
-| `Unauthorized! Invalid base64 credentials format` | 401 | `extractCredentials` | Base64 decoding failed, no colon separator, or empty username |
-| `Unauthorized! Invalid username or password` | 401 | `verify` | `verifyCredentials` callback returned null/falsy |
-
----
-
-### Strategy Registry Errors (`AuthenticationStrategyRegistry`)
+## AuthenticationStrategyRegistry (startup + runtime)
 
 Inherited from `AbstractAuthRegistry`.
 
-| Error Message | Status | Method | When |
-|---------------|--------|--------|------|
-| <code v-pre>[getKey] Invalid name &#124; name: {{name}}</code> | 400 | `getKey` | Strategy name is empty or falsy |
-| <code v-pre>[AuthenticationStrategyRegistry] No items registered</code> | 400 | `getDefaultName` | No strategies have been registered |
-| <code v-pre>[AuthenticationStrategyRegistry] Descriptor not found: {{name}}</code> | 400 | `resolveDescriptor` | Strategy with given name is not registered |
-| <code v-pre>[AuthenticationStrategyRegistry] Failed to resolve: {{name}}</code> | 400 | `resolveDescriptor` | Strategy registered but DI container returned null |
-
----
-
-### Authentication Provider Errors (`AuthenticationProvider`)
-
-The middleware that executes strategies in the configured mode.
-
-| Error Message | Status | Method | When |
-|---------------|--------|--------|------|
-| <code v-pre>Authentication failed. Tried strategies: {{strategies}}</code> | 401 | `executeAnyMode` | All strategies failed in `'any'` mode - each strategy threw during `authenticate()` |
-| `Failed to identify authenticated user!` | 401 | `executeAllMode` | All strategies succeeded in `'all'` mode but the first strategy's `authUser.userId` is falsy |
-| <code v-pre>Invalid authentication mode &#124; mode: {{mode}}</code> | 500 | `createAuthenticateMiddleware` | `mode` is not `'any'` or `'all'` |
-
----
-
-### Auth Controller Factory Errors
-
-| Error Message | Status | Method | When |
-|---------------|--------|--------|------|
-| `[AuthController] Failed to init auth controller \| Invalid injectable authentication service!` | 400 | `constructor` | DI could not resolve the authentication service (service key not bound) |
-
----
+| Message | Status | Method | Cause | Fix |
+|---------|--------|--------|-------|-----|
+| `[getKey] Invalid name \| name: {name}` | 400 | `getKey` | Strategy name empty or falsy | Pass a non-empty strategy name |
+| `[AuthenticationStrategyRegistry] No items registered` | 400 | `getDefaultName` | No strategies registered yet | Register at least one strategy |
+| `[AuthenticationStrategyRegistry] Descriptor not found: {name}` | 400 | `resolveDescriptor` | Route references a strategy name that was never registered | Register it after the component - see below |
+| `[AuthenticationStrategyRegistry] Failed to resolve: {name}` | 400 | `resolveDescriptor` | Strategy registered but the container returned null | Check the strategy's own constructor dependencies |
 
-## Troubleshooting
-
-### "[AuthenticateComponent] At least one of jwtOptions or basicOptions must be provided"
-
-**Cause:** The component requires at least one authentication method. Neither `JWT_OPTIONS` nor `BASIC_OPTIONS` was bound before calling `this.component(AuthenticateComponent)`.
-
-**Fix:** Bind at least one set of options before registering the component:
+**Fix for "Descriptor not found":** strategies are **not** auto-registered by `AuthenticateComponent`.
 
 ```typescript
-// Option A: JWS (symmetric JWT)
-this.bind<TJWTTokenServiceOptions>({ key: AuthenticateBindingKeys.JWT_OPTIONS }).toValue({
-  standard: JOSEStandards.JWS,
-  options: {
-    jwtSecret: env.get('JWT_SECRET'),
-    getTokenExpiresFn: () => 86_400,
-  },
-});
-
-// Option B: JWKS Issuer (asymmetric JWT)
-this.bind<TJWTTokenServiceOptions>({ key: AuthenticateBindingKeys.JWT_OPTIONS }).toValue({
-  standard: JOSEStandards.JWKS,
-  options: {
-    mode: JWKSModes.ISSUER,
-    algorithm: 'RS256',
-    kid: 'my-key-1',
-    keys: { driver: JWKSKeyDrivers.FILE, format: JWKSKeyFormats.PEM, private: './keys/private.pem', public: './keys/public.pem' },
-    getTokenExpiresFn: () => 86_400,
-  },
-});
-
-// Then register the component
 this.component(AuthenticateComponent);
-```
-
-### "[defineJWSAuth] Invalid jwtSecret"
-
-**Cause:** `jwtSecret` is missing, empty, or set to the default placeholder `'unknown_secret'`. The component validates this during `defineJWSAuth()`.
-
-**Fix:** Set a strong, unique JWT secret:
-
-```bash
-# .env
-JWT_SECRET=your-strong-jwt-secret-at-least-32-chars
-```
-
-```typescript
-this.bind<TJWTTokenServiceOptions>({ key: AuthenticateBindingKeys.JWT_OPTIONS }).toValue({
-  standard: JOSEStandards.JWS,
-  options: {
-    jwtSecret: env.get('JWT_SECRET'),
-    getTokenExpiresFn: () => 86_400,
-  },
-});
-```
-
-### "[defineJWSAuth] getTokenExpiresFn is required"
-
-**Cause:** `getTokenExpiresFn` was not provided in the JWS options.
-
-**Fix:** Include a function that returns the token expiry time in seconds:
-
-```typescript
-options: {
-  jwtSecret: env.get('JWT_SECRET'),
-  getTokenExpiresFn: () => Number(env.get('JWT_EXPIRES_IN') || 86_400),
-}
-```
-
-### "[defineJWKSAuth] keys.private and keys.public are required for issuer mode"
-
-**Cause:** JWKS issuer mode requires both a private key (for signing) and a public key (for the `/certs` JWKS endpoint). One or both were not provided.
 
-**Fix:** Provide both keys in the options:
-
-```typescript
-options: {
-  mode: JWKSModes.ISSUER,
-  algorithm: 'RS256',
-  kid: 'my-key-1',
-  keys: {
-    driver: JWKSKeyDrivers.FILE,
-    format: JWKSKeyFormats.PEM,
-    private: './keys/private.pem',
-    public: './keys/public.pem',
-  },
-  getTokenExpiresFn: () => 86_400,
-}
-```
-
-### "[defineJWKSAuth] keys.format is required and must be one of: pem, jwk"
-
-**Cause:** `keys.format` is missing or invalid. The component validates against `JWKSKeyFormats.SCHEME_SET` (values are lowercase: `'pem'`, `'jwk'`).
-
-**Fix:** Use one of the supported formats:
-
-```typescript
-keys: {
-  driver: JWKSKeyDrivers.FILE,
-  format: JWKSKeyFormats.PEM,  // or JWKSKeyFormats.JWK
-  private: './keys/private.pem',
-  public: './keys/public.pem',
-}
-```
-
-### "[defineJWKSAuth] kid is required for issuer mode"
-
-**Cause:** The Key ID (`kid`) is required for the issuer to include in the JWKS and JWT headers. It allows verifiers to identify which key was used to sign a token.
-
-**Fix:** Provide a unique key identifier:
-
-```typescript
-options: {
-  mode: JWKSModes.ISSUER,
-  kid: 'my-service-key-2024',
-  // ...
-}
-```
-
-### "[defineJWKSAuth] jwksUrl is required for verifier mode"
-
-**Cause:** JWKS verifier mode needs the URL of the issuer's `/certs` endpoint to fetch the public key set.
-
-**Fix:** Provide the JWKS endpoint URL:
-
-```typescript
-this.bind<TJWTTokenServiceOptions>({ key: AuthenticateBindingKeys.JWT_OPTIONS }).toValue({
-  standard: JOSEStandards.JWKS,
-  options: {
-    mode: JWKSModes.VERIFIER,
-    jwksUrl: 'https://auth-service.example.com/certs',
-  },
-});
-```
-
-### "[JWKSIssuerTokenService] Invalid JWK key material"
-
-**Cause:** When using `JWKSKeyFormats.JWK`, the private or public key content failed to parse as valid JSON, or `importJWK()` rejected it. The full error is logged at `error` level.
-
-**Fix:** Ensure your JWK keys are valid JSON objects:
-
-```json
-{
-  "kty": "RSA",
-  "n": "...",
-  "e": "AQAB",
-  "d": "...",
-  "alg": "RS256",
-  "use": "sig"
-}
-```
-
-If stored as files, ensure the file contains valid JSON (not PEM). If stored as text (`JWKSKeyDrivers.TEXT`), ensure the string is parseable JSON.
-
-### "[JWKSIssuerTokenService] JWKS not initialized yet. Call getJWKSAsync() instead."
-
-**Cause:** `getJWKS()` (synchronous) was called before the lazy initialization completed. The issuer loads keys asynchronously on first use.
-
-**Fix:** Use the async variant:
-
-```typescript
-const jwks = await issuerService.getJWKSAsync();
-```
-
-The built-in `JWKSController` already uses `getJWKSAsync()`, so this error only occurs if you call `getJWKS()` directly in custom code.
-
-### "[JWKSVerifierTokenService] Verifier mode cannot sign tokens"
-
-**Cause:** `generate()` was called on a `JWKSVerifierTokenService`. The verifier mode only has access to public keys (via the remote JWKS URL) and cannot sign tokens.
-
-**Fix:** Token generation should only happen on the **issuer** service. If you need both signing and verification in the same application, use `JWKSModes.ISSUER` - the issuer can both sign and verify.
-
-### "Authentication failed. Tried strategies: jwt, jwks"
-
-**Cause:** All configured strategies failed in `'any'` mode. Each strategy attempted to authenticate the request and threw.
-
-**Fix:** Verify the client is sending the correct `Authorization` header:
-- For Bearer (JWS/JWKS): `Authorization: Bearer <token>`
-- For Basic: `Authorization: Basic <base64(username:password)>`
-
-Common causes:
-- Token expired
-- Token signed with a different key
-- Wrong strategy name in route config (e.g., `'jwt'` when using JWKS)
-- Strategy not registered (see below)
-
-### "[AuthenticationStrategyRegistry] Descriptor not found: jwt"
-
-**Cause:** A route references strategy name `'jwt'` but no strategy with that name has been registered in the `AuthenticationStrategyRegistry`.
-
-**Fix:** Strategies are **not auto-registered** by `AuthenticateComponent`. You must manually register them after the component:
-
-```typescript
-// In preConfigure() or after component registration
-this.component(AuthenticateComponent);
-
-// Manual strategy registration
 AuthenticationStrategyRegistry.getInstance().register({
   container: this,
-  strategies: [
-    { strategy: JWSAuthenticationStrategy, name: 'jwt' },
-  ],
+  strategies: [{ name: Authentication.STRATEGY_JWT, strategy: JWSAuthenticationStrategy }],
 });
 ```
 
-See [Usage & Examples](./usage#strategy-registration) for the full registration flow.
+## AuthenticationProvider (runtime)
+
+The middleware that executes strategies in the configured mode.
+
+| Message | Status | Method | Cause |
+|---------|--------|--------|-------|
+| `Authentication failed. Tried strategies: {strategies}` | 401 | `executeAnyMode` | Every strategy failed in `'any'` 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'` |
 
-### "[AuthController] Failed to init auth controller | Invalid injectable authentication service!"
+**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.
 
-**Cause:** The auth controller factory could not resolve the authentication service from DI. The service key (configured via `controllerOpts.serviceKey`) is not bound.
+## Auth controller factory
 
-**Fix:** Register your `AuthenticationService` before registering the component:
+| Message | Status | Method | Cause | Fix |
+|---------|--------|--------|-------|-----|
+| `[AuthController] Failed to init auth controller \| Invalid injectable authentication service!` | 400 | `constructor` | DI could not resolve the service at `controllerOpts.serviceKey` | Register your service before the component |
 
 ```typescript
-// 1. Register your auth service
 this.service(AuthenticationService);
 
-// 2. Configure REST options with matching service key
 this.bind<TAuthenticationRestOptions>({ key: AuthenticateBindingKeys.REST_OPTIONS }).toValue({
   useAuthController: true,
-  controllerOpts: {
-    restPath: '/auth',
-    serviceKey: 'services.AuthenticationService',
-  },
+  controllerOpts: { restPath: '/auth', serviceKey: 'services.AuthenticationService' },
 });
 
-// 3. Register component
 this.component(AuthenticateComponent);
 ```
 
-### "[defineBasicAuth] verifyCredentials function is required"
-
-**Cause:** `BASIC_OPTIONS` was bound but without a `verifyCredentials` callback.
-
-**Fix:** Provide a `verifyCredentials` function:
-
-```typescript
-this.bind<TBasicTokenServiceOptions>({ key: AuthenticateBindingKeys.BASIC_OPTIONS }).toValue({
-  verifyCredentials: async ({ credentials, context }) => {
-    const user = await userRepo.findByUsername(credentials.username);
-    if (user && await bcrypt.compare(credentials.password, user.passwordHash)) {
-      return { userId: user.id };
-    }
-    return null;
-  },
-});
-```
-
-### "[verify] Invalid or expired token"
-
-**Cause:** Token verification failed. This is a sanitized error - the original error (expired, wrong signature, malformed) is logged internally but not exposed to clients.
-
-**Fix:** Check the application logs for the full error. Common causes:
-- Token has expired (check `exp` claim)
-- Token signed with a different secret/key
-- Token was tampered with
-- Algorithm mismatch between signing and verification
-
-```bash
-# Look for the full error in logs
-grep "Failed to verify token" logs/application.log
-```
-
----
-
-## Error Categories
+## Error categories
 
 ```mermaid
 flowchart TB
-    subgraph S400["Startup Errors (400)"]
-        direction TB
-        A1["Missing options"]
-        A2["Invalid secrets"]
-        A3["Missing functions"]
-        A4["JWKS key validation"]
-        A5["Mode validation"]
-        A6["DI resolution"]
+    subgraph S400["Startup (400)"]
+        A1["Missing options / secrets / functions"]
+        A2["JWKS key + format validation"]
+        A3["Mode validation"]
+        A4["DI resolution"]
     end
-
-    subgraph S401["Runtime Errors (401)"]
-        direction TB
-        B1["Missing header"]
-        B2["Wrong scheme"]
-        B3["Invalid format"]
-        B4["Token verification"]
-        B5["Credential verification"]
-        B6["Strategy exhaustion"]
+    subgraph S401["Runtime (401)"]
+        B1["Missing/wrong/malformed header"]
+        B2["Token or credential verification"]
+        B3["Strategy exhaustion"]
     end
-
-    subgraph S500["Structural Errors (500)"]
-        direction TB
+    subgraph S500["Structural (500)"]
         C1["Unsupported operation"]
         C2["Uninitialized state"]
-        C3["Key/file I/O errors"]
-        C4["Invalid auth mode"]
+        C3["Key/file I/O"]
     end
 
     style S400 fill:#fff3cd,stroke:#ffc107
@@ -523,52 +204,8 @@ flowchart TB
     style S500 fill:#d1ecf1,stroke:#0dcaf0
 ```
 
-### Startup Errors (400)
-
-These errors prevent the application from starting. They occur during component binding or DI resolution. The component uses `getError()` without an explicit status code, which defaults to **400**.
-
-| Category | Errors | When |
-|----------|--------|------|
-| Missing options | `At least one of jwtOptions or basicOptions` | No auth options bound |
-| Invalid secrets | `Invalid jwtSecret` | JWS secret missing or placeholder |
-| Missing functions | `getTokenExpiresFn is required` | No expiry function |
-| JWKS key validation | `keys.private and keys.public are required` | Missing key material |
-| JWKS format validation | `keys.format is required` | Invalid key format |
-| Mode validation | `Unknown JOSE standard`, `Invalid JWKS mode` | Invalid discriminated union value |
-| DI resolution | `Invalid injectable authentication service` | Service not registered |
-
-::: info Why 400 and not 500?
-The `AuthenticateComponent` and `AbstractAuthRegistry` use `getError({ message })` without specifying `statusCode`. The `getError()` helper defaults to `statusCode: 400`. Service-level initialization errors (file I/O, key parsing) explicitly set `statusCode: 500`.
-:::
-
-### Runtime Errors (401)
-
-These errors occur during request processing and return `401 Unauthorized` to clients.
-
-| Category | Errors | When |
-|----------|--------|------|
-| Missing header | `Missing authorization header` | No `Authorization` header |
-| Wrong scheme | `Invalid schema of request token` | Header uses wrong auth type |
-| Invalid format | `Invalid authorization header format` | Malformed header value |
-| Token verification | `Invalid or expired token` | JWT verification failed |
-| Credential verification | `Invalid username or password` | Basic auth credentials rejected |
-| Strategy exhaustion | `Authentication failed. Tried strategies:` | All strategies failed |
-
-### Structural Errors (500)
-
-These errors indicate programming mistakes, I/O failures, or misconfiguration that should be fixed in code.
-
-| Category | Errors | When |
-|----------|--------|------|
-| Unsupported operation | `Verifier mode cannot sign tokens` | Wrong service used for signing |
-| Uninitialized state | `JWKS not initialized yet` | Sync access before async init |
-| Key/file I/O errors | `Unknown key driver`, `Invalid raw.priv key`, `Invalid JWK key material` | JWKS key loading/parsing failed |
-| Invalid mode | `Invalid authentication mode` | Unknown mode passed to provider |
-
----
-
-## See Also
+## See also
 
-- [Setup & Configuration](./) -- Binding keys, options interfaces, and initial setup
-- [Usage & Examples](./usage) -- Securing routes, auth flows, and API endpoints
-- [API Reference](./api) -- Architecture, service internals, and strategy registry
+- [Overview](./) - initial setup and binding keys
+- [Usage & Examples](./usage) - securing routes, auth flows, and API endpoints
+- [API Reference](./api) - architecture, service internals, and strategy registry