@venizia/ignis-docs 0.0.8 → 0.2.0

package/content/best-practices/troubleshooting-tips.md

@@ -1,6 +1,6 @@
 # Troubleshooting Tips
 
-Common issues and their solutions when building Ignis applications.
+Common issues and their solutions when building IGNIS applications.
 
 ## 1. Application Fails to Start
 
@@ -31,8 +31,9 @@ lsof -ti:3000 | xargs kill -9
 ```typescript
 // In application.ts config
 export const appConfigs: IApplicationConfigs = {
+  path: { base: '/api', isStrict: true },
   debug: {
-    showRoutes: process.env.NODE_ENV !== 'production',
+    shouldShowRoutes: process.env.NODE_ENV !== 'production',
   },
 };
 ```
@@ -90,8 +91,8 @@ class UserService {
     // Output: [UserService-createUser] Creating user: {...}
 
     try {
-      const user = await this.userRepo.create({ data });
-      this.logger.for('createUser').info('User created: %s', user.id);
+      const user = await this.userRepository.create({ data });
+      this.logger.for('createUser').info('User created: %s', user.data.id);
       return user;
     } catch (error) {
       this.logger.for('createUser').error('Failed: %s', error);
@@ -122,21 +123,19 @@ cat .env | grep APP_ENV
 
 ## 6. Request ID Tracking
 
-Every request in Ignis is automatically assigned a unique `requestId` for log correlation. The `RequestSpyMiddleware` logs this ID at the start and end of each request.
+Every request in IGNIS is automatically assigned a unique `requestId` for log correlation (via `RequestTrackerComponent`, which registers Hono's `requestId()` middleware plus a request-spy middleware). The spy middleware logs this ID when a request starts (`[=>]`) and finishes (`[<=]`).
 
 **Log output format:**
 ```
-[spy][abc123] START | Handling Request | forwardedIp: 192.168.1.1 | path: /api/users | method: GET
-[spy][abc123] DONE  | Handling Request | forwardedIp: 192.168.1.1 | path: /api/users | method: GET | Took: 45.2 (ms)
+[SpyMW] [abc123][192.168.1.1][=>] GET      /api/users | query: {}
+[SpyMW] [abc123][192.168.1.1][<=] GET      /api/users | Took: 45.20 (ms)
 ```
 
 **Access request ID in handlers:**
 ```typescript
-import { RequestSpyMiddleware } from '@venizia/ignis';
-
-// Inside a controller method
+// Inside a controller method - 'requestId' is the Hono request-id context variable
 async getUser(c: Context) {
-  const requestId = c.get(RequestSpyMiddleware.REQUEST_ID_KEY);
+  const requestId = c.get('requestId');
   this.logger.info('[%s] Processing user request', requestId);
   // ...
 }
@@ -148,53 +147,54 @@ async getUser(c: Context) {
 grep "abc123" logs/app.log
 
 # Extract request timing
-grep "\[spy\]\[abc123\]" logs/app.log
+grep "\[abc123\]" logs/app.log | grep "Took:"
 ```
 
 **Why this matters:**
 - Correlate logs across services in distributed systems
 - Debug specific user issues by their request ID
-- Measure request duration from START to DONE timestamps
+- Measure request duration from the `[=>]` / `[<=]` log pair
 
 ## 7. Validation Error Debugging
 
-When Zod validation fails, Ignis returns a structured error response. Understanding this format helps debug client-side issues.
+When Zod validation fails, IGNIS returns a structured error response. Understanding this format helps debug client-side issues.
 
-**Error response structure:**
+**Error response structure** (top-level `message`/`messageCode` come from the first issue; the fallback message is `ValidationError`):
 ```json
 {
   "statusCode": 422,
-  "message": "ValidationError",
+  "message": "Invalid email address",
+  "messageCode": "invalid_format",
   "requestId": "abc123",
   "details": {
+    "url": "http://localhost:3000/api/users",
+    "path": "/api/users",
     "cause": [
       {
         "path": "email",
-        "message": "Invalid email",
-        "code": "invalid_string",
-        "expected": "email",
-        "received": "string"
+        "message": "Invalid email address",
+        "code": "invalid_format"
       }
     ]
   }
 }
 ```
 
-**Common validation error codes:**
+**Common validation error codes (Zod v4):**
 
 | Code | Meaning | Example |
 |------|---------|---------|
 | `invalid_type` | Wrong data type | Expected `number`, got `string` |
-| `invalid_string` | String format invalid | Invalid email or UUID format |
+| `invalid_format` | String format invalid | Invalid email or UUID format |
 | `too_small` | Value below minimum | String shorter than min length |
 | `too_big` | Value above maximum | Number exceeds max value |
-| `invalid_enum_value` | Value not in enum | Status must be 'ACTIVE' or 'INACTIVE' |
+| `invalid_value` | Value not in enum/literal | Status must be 'ACTIVE' or 'INACTIVE' |
 | `unrecognized_keys` | Extra fields in request | Strict schema rejects unknown fields |
 
 **Debugging tips:**
 
 1. **Check the `path` field** - Shows which field failed validation
-2. **Compare `expected` vs `received`** - Identifies type mismatches
+2. **Compare `expected` vs `received`** - Present on `invalid_type` issues, identifies type mismatches
 3. **Review schema definition** - Ensure client sends correct format
 
 **Example: Debugging nested validation errors:**

package/content/extensions/components/{swagger.md → api-reference.md}

@@ -1,13 +1,16 @@
-# Swagger/OpenAPI
+# API Reference
 
 Automatic interactive API documentation generation using OpenAPI specifications, powered by Scalar or Swagger UI.
 
+> [!NOTE] Renamed from SwaggerComponent
+> Swagger UI is just one of the pluggable UI providers, so the component carries a vendor-neutral name. `SwaggerComponent`, `ISwaggerOptions`, and `SwaggerBindingKeys` remain available as deprecated aliases - existing applications keep working unchanged.
+
 ## Quick Reference
 
 | Item | Value |
 |------|-------|
 | **Package** | `@venizia/ignis` |
-| **Class** | `SwaggerComponent` |
+| **Class** | `ApiReferenceComponent` |
 | **UI Factory** | `UIProviderFactory` |
 | **Runtimes** | Both |
 
@@ -18,8 +21,8 @@ Automatic interactive API documentation generation using OpenAPI specifications,
 
 #### Import Paths
 ```typescript
-import { SwaggerComponent, SwaggerBindingKeys, UIProviderFactory } from '@venizia/ignis';
-import type { ISwaggerOptions, IUIProvider, IUIConfig, IGetProviderParams } from '@venizia/ignis';
+import { ApiReferenceComponent, ApiReferenceBindingKeys, UIProviderFactory } from '@venizia/ignis';
+import type { IApiReferenceOptions, IUIProvider, IUIConfig, IGetProviderParams } from '@venizia/ignis';
 ```
 
 ## Setup
@@ -30,10 +33,10 @@ Skip this step to use the defaults (Scalar UI at `/doc/explorer`). To customize:
 
 ```typescript
 // In your Application class's preConfigure method (src/application.ts)
-import { SwaggerBindingKeys, ISwaggerOptions } from '@venizia/ignis';
+import { ApiReferenceBindingKeys, IApiReferenceOptions } from '@venizia/ignis';
 
-this.bind<ISwaggerOptions>({
-  key: SwaggerBindingKeys.SWAGGER_OPTIONS,
+this.bind<IApiReferenceOptions>({
+  key: ApiReferenceBindingKeys.API_REFERENCE_OPTIONS,
 }).toValue({
   restOptions: {
     base: { path: '/doc' },
@@ -50,12 +53,12 @@ this.bind<ISwaggerOptions>({
 
 ```typescript
 // src/application.ts
-import { SwaggerComponent, BaseApplication, ValueOrPromise } from '@venizia/ignis';
+import { ApiReferenceComponent, BaseApplication, ValueOrPromise } from '@venizia/ignis';
 
 export class Application extends BaseApplication {
   preConfigure(): ValueOrPromise<void> {
     // ...
-    this.component(SwaggerComponent);
+    this.component(ApiReferenceComponent);
   }
 }
 ```
@@ -89,7 +92,7 @@ export class HelloController extends BaseRestController {
         },
       },
       handler: (c) => {
-        return c.json({ message: 'Hello, `Ignis`!' }, HTTP.ResultCodes.RS_2.Ok);
+        return c.json({ message: 'Hello, `IGNIS`!' }, HTTP.ResultCodes.RS_2.Ok);
       },
     });
   }
@@ -116,9 +119,9 @@ export class HelloController extends BaseRestController {
 > [!NOTE]
 > The `explorer.servers` field is auto-populated only when empty. If you provide `explorer.servers` with at least one entry, the component preserves your values. When no servers are configured, it creates a default entry from `application.getServerAddress()` plus the application base path.
 
-#### ISwaggerOptions -- Full Reference
+#### IApiReferenceOptions -- Full Reference
 ```typescript
-export interface ISwaggerOptions {
+export interface IApiReferenceOptions {
   restOptions: {
     base: { path: string };
     doc: { path: string };
@@ -183,9 +186,9 @@ This interface is exported for use when building custom tooling around the `UIPr
 
 ### Component Lifecycle
 
-The `SwaggerComponent` executes the following during `binding()`:
+The `ApiReferenceComponent` executes the following during `binding()`:
 
-1. **Resolve options** -- reads `SwaggerBindingKeys.SWAGGER_OPTIONS` from DI using `application.get()` with `isOptional: true`, falls back to `DEFAULT_SWAGGER_OPTIONS` via the `??` operator if no binding exists
+1. **Resolve options** -- reads `ApiReferenceBindingKeys.API_REFERENCE_OPTIONS` from DI using `application.get()` with `isOptional: true`, then deep-merges what it finds over `DEFAULT_API_REFERENCE_OPTIONS` group by group, so an application that overrides one path keeps the defaults for the rest
 2. **Overwrite info** -- unconditionally reads `package.json` via `application.getAppInfo()` and overwrites `explorer.info` with `{ title: appInfo.name, version: appInfo.version, description: appInfo.description, contact: appInfo.author }`
 3. **Auto-detect servers** -- if `explorer.servers` is empty or unset, creates one entry from `http://` + `application.getServerAddress()` + `configs.path.base`
 4. **Normalize paths** -- all path segments (`base.path`, `doc.path`, `ui.path`) are normalized to ensure a leading `/` is present, handling both `/path` and `path` inputs
@@ -201,7 +204,7 @@ The `SwaggerComponent` executes the following during `binding()`:
 
 | Component | Class | Role |
 |-----------|-------|------|
-| **SwaggerComponent** | `extends BaseComponent` | Orchestrates binding, overwrites OpenAPI metadata from `package.json` |
+| **ApiReferenceComponent** | `extends BaseComponent` | Orchestrates binding, overwrites OpenAPI metadata from `package.json` |
 | **UIProviderFactory** | `extends MemoryStorageHelper` (singleton) | Registry for UI providers, validates and instantiates |
 | **SwaggerUIProvider** | `implements IUIProvider` | Renders Swagger UI via `@hono/swagger-ui` |
 | **ScalarUIProvider** | `implements IUIProvider` | Renders Scalar UI via `@scalar/hono-api-reference` |
@@ -314,24 +317,30 @@ This ensures routes using `authStrategies: ['jwt']` or `authStrategies: ['basic'
 
 | Key | Constant | Type | Required | Default |
 |-----|----------|------|----------|---------|
-| `@app/swagger/options` | `SwaggerBindingKeys.SWAGGER_OPTIONS` | `ISwaggerOptions` | No | See below |
+| `@app/api-reference/options` | `ApiReferenceBindingKeys.API_REFERENCE_OPTIONS` | `IApiReferenceOptions` | No | See below |
+
+The deprecated `SwaggerBindingKeys.SWAGGER_OPTIONS` still resolves - it is an alias whose **value** is that same `'@app/api-reference/options'` string. There is no binding under the literal `'@app/swagger/options'`; binding that raw string does nothing.
 
-The `SwaggerComponent` constructor creates a default binding using the `Binding` fluent API:
+The constructor registers the default through `super()`, so the binding is in the container from the start:
 
 ```typescript
-this.bindings = {
-  [SwaggerBindingKeys.SWAGGER_OPTIONS]: Binding.bind<ISwaggerOptions>({
-    key: SwaggerBindingKeys.SWAGGER_OPTIONS,
-  }).toValue(DEFAULT_SWAGGER_OPTIONS),
-};
+super({
+  scope: ApiReferenceComponent.name,
+  initDefault: { enable: true, container: application },
+  bindings: {
+    [ApiReferenceBindingKeys.API_REFERENCE_OPTIONS]: Binding.bind<IApiReferenceOptions>({
+      key: ApiReferenceBindingKeys.API_REFERENCE_OPTIONS,
+    }).toValue(DEFAULT_API_REFERENCE_OPTIONS),
+  },
+});
 ```
 
-Note that unlike `HealthCheckComponent`, `SwaggerComponent` does not pass `initDefault: { enable: true, container: application }` to `BaseComponent`. The default bindings stored in `this.bindings` are not automatically registered into the DI container. Instead, the `binding()` method reads from the container with `isOptional: true` and falls back to `DEFAULT_SWAGGER_OPTIONS` via the `??` operator.
+`binding()` then reads the key back with `isOptional: true` and **deep-merges** whatever the application bound over the defaults, group by group (`base`, `doc`, `ui`, `explorer`) - so overriding one path does not wipe the others. The merge builds a fresh `explorer` object per application; mutating the bound one would leak this application's info into every later application in the same process.
 
 **Default value:**
 
 ```typescript
-const DEFAULT_SWAGGER_OPTIONS: ISwaggerOptions = {
+const DEFAULT_API_REFERENCE_OPTIONS: IApiReferenceOptions = {
   restOptions: {
     base: { path: '/doc' },
     doc: { path: '/openapi.json' },
@@ -349,7 +358,7 @@ const DEFAULT_SWAGGER_OPTIONS: ISwaggerOptions = {
 ```
 
 > [!NOTE]
-> The `explorer.info` values in `DEFAULT_SWAGGER_OPTIONS` are never used at runtime because `binding()` unconditionally overwrites `explorer.info` with data from `package.json`. They exist only as structural defaults.
+> The `explorer.info` values in `DEFAULT_API_REFERENCE_OPTIONS` are never used at runtime because `binding()` unconditionally overwrites `explorer.info` with data from `package.json`. They exist only as structural defaults.
 
 ### Type Definitions
 
@@ -401,8 +410,8 @@ Returns the raw OpenAPI JSON specification generated from all registered control
 **Fix:** Use a valid UI type:
 
 ```typescript
-this.bind<ISwaggerOptions>({
-  key: SwaggerBindingKeys.SWAGGER_OPTIONS,
+this.bind<IApiReferenceOptions>({
+  key: ApiReferenceBindingKeys.API_REFERENCE_OPTIONS,
 }).toValue({
   restOptions: {
     base: { path: '/doc' },
@@ -439,17 +448,17 @@ this.defineRoute({
 
 **Cause:** The `UIProviderFactory.getProvider()` was called with a type that has not been registered. This typically happens if the component binding phase failed silently.
 
-**Fix:** Ensure the `SwaggerComponent` is registered in `preConfigure()` and that no errors occur during its `binding()` phase. Check the application logs for warnings from `UIProviderFactory`.
+**Fix:** Ensure the `ApiReferenceComponent` is registered in `preConfigure()` and that no errors occur during its `binding()` phase. Check the application logs for warnings from `UIProviderFactory`.
 
 ### OpenAPI spec missing authentication schemes
 
-**Cause:** The `SwaggerComponent` auto-registers JWT and Basic security schemes. If the `AuthenticationComponent` is not registered, authenticated routes will not show auth UI in the documentation.
+**Cause:** The `ApiReferenceComponent` auto-registers JWT and Basic security schemes. If the `AuthenticationComponent` is not registered, authenticated routes will not show auth UI in the documentation.
 
-**Fix:** Register `AuthenticationComponent` before `SwaggerComponent` in `preConfigure()` to ensure auth strategies are available when the Swagger component configures security schemes.
+**Fix:** Register `AuthenticationComponent` before `ApiReferenceComponent` in `preConfigure()` to ensure auth strategies are available when the Swagger component configures security schemes.
 
 ### explorer.info values not matching custom configuration
 
-**Cause:** The `SwaggerComponent` unconditionally overwrites `explorer.info` with values from `package.json` during its `binding()` phase. Any values you set in `explorer.info` via the DI binding are discarded.
+**Cause:** The `ApiReferenceComponent` unconditionally overwrites `explorer.info` with values from `package.json` during its `binding()` phase. Any values you set in `explorer.info` via the DI binding are discarded.
 
 **Fix:** Update your project's `package.json` fields (`name`, `version`, `description`, `author`) to control what appears in the API documentation info section. The component reads these via `application.getAppInfo()`.
 

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

@@ -91,7 +91,7 @@ The `AuthenticateComponent` uses five methods during its `binding()` lifecycle (
 | Method | Purpose |
 |--------|---------|
 | `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`. |
+| `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()` | **Public** stub method -- not yet implemented. Called during `binding()` but performs no action. |
@@ -133,8 +133,8 @@ AuthenticationStrategyRegistry.getInstance().register({
 **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
@@ -179,7 +179,7 @@ export const authenticate = (opts: { strategies: string[]; mode?: TAuthMode }) =
 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, the **first** strategy's user payload is used as the identity source — all strategies must succeed but the first one wins for identity. If every strategy passes but the first 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.
+> In `all` mode, the **first** strategy's user payload is used as the identity source - all strategies must succeed but the first one wins for identity. If every strategy passes but the first 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
 
@@ -259,8 +259,8 @@ Base class for all Bearer token services. Extends `BaseService`. Generic on <cod
 |--------|-----------|-------------|
 | `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()` |
+| `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. |
@@ -421,17 +421,17 @@ constructor(
   protected options: IJWKSIssuerOptions,
 ) {
   // Calls configurePayloadEncryption({ aesAlgorithm, applicationSecret })
-  // Keys are NOT loaded here — loaded lazily via ensureInitialized()
+  // 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
+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
@@ -447,8 +447,8 @@ The `initialize()` method:
 
 | 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. |
+| `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
 
@@ -504,7 +504,7 @@ constructor(
   protected options: IJWKSVerifierOptions,
 ) {
   // Calls configurePayloadEncryption({ aesAlgorithm, applicationSecret })
-  // Remote JWKS is NOT fetched here — fetched lazily via ensureInitialized()
+  // Remote JWKS is NOT fetched here - fetched lazily via ensureInitialized()
 }
 ```
 
@@ -520,13 +520,13 @@ The `initialize()` method:
 | 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 |
+| `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.
+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`
 
@@ -689,7 +689,7 @@ function defineAuthController(opts: TDefineAuthControllerOpts): typeof AuthContr
 ```
 
 > [!NOTE]
-> The factory also exports `JWTTokenPayloadSchema`, a Zod schema used for the `/who-am-i` response validation.
+> The factory also exports `JWTTokenPayloadSchema`, a Zod schema used for the `/who-am-i` response validation. For `/who-am-i`, it is extended with an optional `userInformation` field that is populated when the request sets `?withUserInformation=true`. The same `getUserInformation` service method backs the dedicated `GET /me` route.
 
 **Service resolution:**
 

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

@@ -49,7 +49,7 @@ Thrown during `binding()` when validating options and configuring services.
 | `[defineJWSAuth] getTokenExpiresFn is required` | 400 | `defineJWSAuth` | `getTokenExpiresFn` not provided in JWS options |
 
 ::: 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.
+`applicationSecret` was previously required and validated by the component. It is now **optional** - omitting it simply disables AES payload encryption.
 :::
 
 #### `defineJWKSAuth` Errors (Issuer Mode)
@@ -104,10 +104,10 @@ Base class errors shared by `JWSTokenService`, `JWKSIssuerTokenService`, and `JW
 | 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 |
+| `[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.
+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
@@ -150,7 +150,7 @@ Errors thrown during lazy initialization (`ensureInitialized()`) and key operati
 | <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.
+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
@@ -208,7 +208,7 @@ 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()` |
+| <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'` |
 
@@ -391,7 +391,7 @@ The built-in `JWKSController` already uses `getJWKSAsync()`, so this error only
 
 **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.
+**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"
 
@@ -471,7 +471,7 @@ this.bind<TBasicTokenServiceOptions>({ key: AuthenticateBindingKeys.BASIC_OPTION
 
 ### "[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.
+**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)

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

@@ -21,9 +21,9 @@
 | **JWKSVerifierAuthenticationStrategy** | JWT verification via remote JWKS URL |
 | **BasicAuthenticationStrategy** | Basic HTTP authentication using `BasicTokenService` |
 | **AbstractBearerTokenService** | Base class for all Bearer token services (JWS, JWKS Issuer, JWKS Verifier) |
-| **JWSTokenService** | Symmetric JWT — sign, verify, optional AES encrypt/decrypt |
-| **JWKSIssuerTokenService** | Asymmetric JWT — sign with private key, verify with public key, serve JWKS endpoint |
-| **JWKSVerifierTokenService** | Asymmetric JWT — verify-only via remote JWKS URL |
+| **JWSTokenService** | Symmetric JWT - sign, verify, optional AES encrypt/decrypt |
+| **JWKSIssuerTokenService** | Asymmetric JWT - sign with private key, verify with public key, serve JWKS endpoint |
+| **JWKSVerifierTokenService** | Asymmetric JWT - verify-only via remote JWKS URL |
 | **BasicTokenService** | Extract and verify Basic auth credentials |
 | **JWKSController** | Serves `/.well-known/jwks.json`-style endpoint at `/certs` |
 | **IAuthService** | Interface for custom auth implementation (sign-in, sign-up) |
@@ -97,8 +97,8 @@ The authentication module supports two JOSE (JSON Object Signing and Encryption)
 | `JWKSKeyFormats` | `JWK` | `'jwk'` | JSON Web Key format |
 
 Each constants class also provides:
-- `SCHEME_SET: Set<string>` — set of all valid values
-- `isValid(input: string): boolean` — check if a value is recognized
+- `SCHEME_SET: Set<string>` - set of all valid values
+- `isValid(input: string): boolean` - check if a value is recognized
 
 #### Import Paths
 
@@ -244,7 +244,7 @@ this.bind<TJWTTokenServiceOptions>({ key: AuthenticateBindingKeys.JWT_OPTIONS })
   standard: JOSEStandards.JWS,
   options: {
     jwtSecret: process.env.APP_ENV_JWT_SECRET,
-    applicationSecret: process.env.APP_ENV_APPLICATION_SECRET, // Optional — enables AES payload encryption
+    applicationSecret: process.env.APP_ENV_APPLICATION_SECRET, // Optional - enables AES payload encryption
     getTokenExpiresFn: () => Number(process.env.APP_ENV_JWT_EXPIRES_IN || 86400),
   },
 });
@@ -495,7 +495,7 @@ type TJWTTokenServiceOptions =
   | { standard: typeof JOSEStandards.JWKS; options: TJWKSTokenServiceOptions };
 ```
 
-This enables clean TypeScript narrowing — once you set `standard: JOSEStandards.JWS`, the `options` field is typed as `IJWSTokenServiceOptions`; with `standard: JOSEStandards.JWKS`, it becomes `TJWKSTokenServiceOptions`.
+This enables clean TypeScript narrowing - once you set `standard: JOSEStandards.JWS`, the `options` field is typed as `IJWSTokenServiceOptions`; with `standard: JOSEStandards.JWKS`, it becomes `TJWKSTokenServiceOptions`.
 
 ### JWS Options (IJWSTokenServiceOptions)
 
@@ -759,16 +759,18 @@ interface IAuthService<
   CPRS = AnyObject,
   UIRQ = AnyObject,
   UIRS = AnyObject,
+  RTRS = AnyObject,
 > {
   signIn(context: TContext<E>, opts: SIRQ): Promise<SIRS>;
   signUp(context: TContext<E>, opts: SURQ): Promise<SURS>;
   changePassword(context: TContext<E>, opts: CPRQ): Promise<CPRS>;
   getUserInformation?(context: TContext<E>, opts: UIRQ): Promise<UIRS>;
+  refreshToken?(context: TContext<E>): Promise<RTRS>;
 }
 ```
 
 > [!NOTE]
-> `IAuthService` is generic on the Hono `Env` type as well as all request/response types. The `getUserInformation` method is optional.
+> `IAuthService` is generic on the Hono `Env` type as well as all request/response types. The `getUserInformation` and `refreshToken` methods are both optional -- the auth controller factory returns a 501 (`core.not_supported`) when an endpoint that depends on one is called but the method is not implemented.
 
 #### IJWTTokenPayload -- Full Interface
 ```typescript