@venizia/ignis-docs 0.0.8 → 0.2.0

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

@@ -432,8 +432,10 @@ extraPermissionColumns(opts?: { idType: 'string' | 'number' })
 | `code` | `text` (unique) | -- | Unique permission code |
 | `name` | `text` | -- | Permission name |
 | `subject` | `text` | -- | Permission subject (e.g., `'User'`, `'Order'`) |
+| `method` | `text` | -- | HTTP method (e.g., `'GET'`, `'POST'`) |
 | `action` | `text` | -- | Permitted action (e.g., `'read'`, `'write'`) |
 | `scope` | `text` | -- | Permission scope |
+| `description` | `text` | `null` | Optional permission description |
 | `parentId` | `text` or `integer` | `null` | Parent permission ID |
 
 ### extraPolicyDefinitionColumns
@@ -695,7 +697,7 @@ flowchart TD
 
 ```mermaid
 flowchart LR
-    subgraph GENERATE["generate() — Token Creation"]
+    subgraph GENERATE["generate() - Token Creation"]
         direction TB
         P["Payload: { userId, roles, email }"]
         P --> CHECK1{"applicationSecret?"}
@@ -705,7 +707,7 @@ flowchart LR
         CHECK1 -->|"No"| PLAIN1["Use payload as-is"]
     end
 
-    subgraph VERIFY["verify() — Token Verification"]
+    subgraph VERIFY["verify() - Token Verification"]
         direction TB
         T["Verified JWT payload"]
         T --> CHECK2{"applicationSecret?"}
@@ -741,7 +743,7 @@ JWT payloads can optionally be encrypted field-by-field using AES (default `aes-
 
 ## Hono Context Extension
 
-The Authentication module extends Hono's `ContextVariableMap` to provide type-safe access to auth data. Note: `ContextVariableMap` does **not** take a generic parameter — it is a plain interface augmentation:
+The Authentication module extends Hono's `ContextVariableMap` to provide type-safe access to auth data. Note: `ContextVariableMap` does **not** take a generic parameter - it is a plain interface augmentation:
 
 ```typescript
 declare module 'hono' {
@@ -835,6 +837,8 @@ const JWTTokenPayloadSchema = z.object({
 });
 ```
 
+For the `/who-am-i` response, this schema is extended at runtime with an optional `userInformation` field (typed from `payload.getUserInformation.response.schema`, falling back to `AnyObjectSchema`) so the `withUserInformation` shape is OpenAPI-documented.
+
 ## API Endpoints
 
 The built-in auth controller is created by the `defineAuthController()` factory function and is only available when `useAuthController: true` is set in `REST_OPTIONS`.
@@ -844,11 +848,13 @@ The built-in auth controller is created by the `defineAuthController()` factory
 | `POST` | `/auth/sign-in` | No | Authenticate and receive a JWT token |
 | `POST` | `/auth/sign-up` | Configurable | Create a new user account |
 | `POST` | `/auth/change-password` | JWT | Change the authenticated user's password |
-| `GET` | `/auth/who-am-i` | JWT | Return the current user's JWT payload |
+| `POST` | `/auth/token/refresh` | JWT | Re-issue an access token using a valid JWT |
+| `GET` | `/auth/who-am-i` | JWT | Return the current user's JWT payload (optionally with attached user information) |
+| `GET` | `/auth/me` | JWT | Return the current user's information from `getUserInformation` |
 | `GET` | `/certs` | No | JWKS endpoint (JWKS Issuer mode only) |
 
 > [!NOTE]
-> The base path `/auth` is configurable via `controllerOpts.restPath`. The `/certs` path is configurable via `rest.path` in `IJWKSIssuerOptions`. The `/certs` endpoint is intentionally unauthenticated — it serves the public keys needed by external verifiers.
+> The base path `/auth` is configurable via `controllerOpts.restPath`. The `/certs` path is configurable via `rest.path` in `IJWKSIssuerOptions`. The `/certs` endpoint is intentionally unauthenticated - it serves the public keys needed by external verifiers.
 
 ### POST /auth/sign-in
 
@@ -878,6 +884,42 @@ When `requireAuthenticatedSignUp: true`, requires JWT authentication. When `fals
 
 **Authentication:** Always requires JWT (`Authentication.STRATEGY_JWT`)
 
+### POST /auth/token/refresh
+
+**Authentication:** Always requires JWT (`Authentication.STRATEGY_JWT`)
+
+Re-issues an access token using the caller's currently valid JWT. There is no separate refresh token - the caller must send a valid Bearer token in the `Authorization` header.
+
+**Request Body:** None
+
+**Response 200:**
+
+Uses `payload.refreshToken.response.schema` if provided, otherwise `AnyObjectSchema`. The response shape is entirely defined by your `IAuthService.refreshToken()` implementation.
+
+**Response 501 (Not Implemented):**
+
+Returned when the bound `IAuthService` does not implement the optional `refreshToken` method.
+
+**Implementing `refreshToken` in your service:**
+
+```typescript
+export class AuthenticationService extends BaseService implements IAuthService {
+  async refreshToken(context: TContext<Env>): Promise<{ token: string }> {
+    // The current user is already verified by JWT middleware
+    const currentUser = context.get(Authentication.CURRENT_USER);
+
+    // Re-issue a new token with the same payload
+    const token = await this._tokenService.generate({ payload: currentUser });
+    return { token };
+  }
+
+  // ... signIn, signUp, changePassword ...
+}
+```
+
+> [!NOTE]
+> The framework does not enforce rotation or revocation policy. If you need to invalidate old tokens after refresh, implement that logic (e.g., a token blocklist or short expiry) inside your `refreshToken` implementation.
+
 ### GET /auth/who-am-i
 
 **Authentication:** Always requires JWT (`Authentication.STRATEGY_JWT`)
@@ -896,6 +938,57 @@ Returns the current user's decrypted JWT payload directly from context.
 }
 ```
 
+**Query Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `withUserInformation` | `true` \| `false` \| `1` \| `0` | When truthy, attaches a `userInformation` field built from `IAuthService.getUserInformation`. Defaults to `false`. |
+
+When `withUserInformation` is truthy, the response merges the `getUserInformation` result into the payload:
+
+```json
+{
+  "userId": "123",
+  "roles": [{ "id": "1", "identifier": "admin", "priority": 0 }],
+  "userInformation": { "fullName": "Ada Lovelace", "department": "R&D" }
+}
+```
+
+**Response 501 (Not Implemented):**
+
+Returned when `withUserInformation` is truthy but the bound `IAuthService` does not implement the optional `getUserInformation` method.
+
+### GET /auth/me
+
+**Authentication:** Always requires JWT (`Authentication.STRATEGY_JWT`)
+
+Returns the current user's information by delegating to `IAuthService.getUserInformation(context, {})`. Unlike `who-am-i`, the response is entirely the service result -- it is not merged with the JWT payload.
+
+**Response 200:**
+
+Uses `payload.getUserInformation.response.schema` if provided, otherwise `AnyObjectSchema`. The shape is defined by your `getUserInformation` implementation.
+
+**Response 501 (Not Implemented):**
+
+Returned when the bound `IAuthService` does not implement the optional `getUserInformation` method.
+
+**Implementing `getUserInformation` in your service:**
+
+```typescript
+export class AuthenticationService extends BaseService implements IAuthService {
+  async getUserInformation(context: TContext<Env>, _opts: AnyObject): Promise<AnyObject> {
+    // The current user is already verified by JWT middleware
+    const currentUser = context.get(Authentication.CURRENT_USER);
+    return this.userRepository.findById({ id: currentUser.userId });
+  }
+
+  // ... signIn, signUp, changePassword ...
+}
+```
+
+> [!TIP]
+> One `getUserInformation` implementation backs both routes. Use `GET /me` when you want the raw profile, or `GET /who-am-i?withUserInformation=true` when you want it merged into the principal in a single round-trip.
+
 ### GET /certs (JWKS Issuer Only)
 
 **Authentication:** None (intentionally public)
@@ -922,7 +1015,7 @@ Returns the JSON Web Key Set for external verifiers.
 
 ## Auth Entity Column Helpers
 
-Ignis provides column helper functions that return pre-configured Drizzle column objects for common auth-related database tables. These functions are designed to be spread into `pgTable()` definitions, giving you standardized columns for User, Role, Permission, and PolicyDefinition entities without manually defining each column.
+IGNIS provides column helper functions that return pre-configured Drizzle column objects for common auth-related database tables. These functions are designed to be spread into `pgTable()` definitions, giving you standardized columns for User, Role, Permission, and PolicyDefinition entities without manually defining each column.
 
 All helpers that accept an `opts` parameter support `{ idType: 'string' | 'number' }` to control whether foreign key columns use `text` (for UUIDs) or `integer` (for serial IDs). The default is `'number'`.
 
@@ -966,8 +1059,10 @@ All helpers that accept an `opts` parameter support `{ idType: 'string' | 'numbe
 | `code` | `code` | `text` (unique) | No | -- | Unique permission code |
 | `name` | `name` | `text` | No | -- | Permission display name |
 | `subject` | `subject` | `text` | No | -- | Permission subject (e.g., `'User'`, `'Order'`) |
+| `method` | `method` | `text` | No | -- | HTTP method (e.g., `'GET'`, `'POST'`) |
 | `action` | `action` | `text` | No | -- | Permitted action (e.g., `'read'`, `'write'`) |
 | `scope` | `scope` | `text` | No | -- | Permission scope |
+| `description` | `description` | `text` | Yes | `null` | Optional permission description |
 | `parentId` | `parent_id` | `text` or `integer` | Yes | `null` | Parent permission ID (type depends on `idType`) |
 
 ### extraPolicyDefinitionColumns

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

@@ -119,8 +119,8 @@ classDiagram
 
     class BaseFilteredAdapter~TFilter~ {
         <<abstract>>
-        #dataSource: IDataSource
-        #connector: TAnyConnector
+        #dataSource: ICasbinPolicySource
+        #connector: TCasbinPolicyConnector
         +loadFilteredPolicy(model, filter)* void
         +isFiltered() boolean
         #loadLines(opts) void
@@ -421,7 +421,7 @@ interface IAuthorizationEnforcer<
 
 | Enforcer | TRules | Description |
 |----------|--------|-------------|
-| `CasbinAuthorizationEnforcer` | `ICasbinRules` | `{ user, lines }` — the user plus their resolved Casbin policy lines (loaded into a pooled enforcer at evaluate time) |
+| `CasbinAuthorizationEnforcer` | `ICasbinRules` | `{ user, lines }` - the user plus their resolved Casbin policy lines (loaded into a pooled enforcer at evaluate time) |
 | Custom | Any type | Your custom rules structure |
 
 ### Method Contracts
@@ -517,20 +517,20 @@ Injects `ICasbinEnforcerOptions` from the DI container using the binding key `Au
 
 Called once by the registry on first use. Performs:
 
-1. Dynamically imports `casbin` — throws `"casbin" is not installed` if missing.
-2. Validates `options.model` — throws `options.model is required.` if missing.
+1. Dynamically imports `casbin` - throws `"casbin" is not installed` if missing.
+2. Validates `options.model` - throws `options.model is required.` if missing.
 3. Memoizes the payload normalizer (`options.normalizePayloadFn ?? defaultScopedPayloadFn()`).
 4. If `cached.use`, validates `expiresIn >= MIN_EXPIRES_IN` (10,000 ms).
-5. Builds a **`BasePoolHelper<Enforcer>`** (`size = poolSize ?? 16`, `acquireTimeoutMs = poolAcquireTimeoutMs ?? 5000`). Each pooled enforcer is created **without an adapter** (`newEnforcer(model)` — no DB load at warmup), then `registerMatchers()` and `assertMatcherCompilesSync()` run on it.
-6. `await pool.warmup()` — pre-creates the enforcers.
+5. Builds a **`BasePoolHelper<Enforcer>`** (`size = poolSize ?? 16`, `acquireTimeoutMs = poolAcquireTimeoutMs ?? 5000`). Each pooled enforcer is created **without an adapter** (`newEnforcer(model)` - no DB load at warmup), then `registerMatchers()` and `assertMatcherCompilesSync()` run on it.
+6. `await pool.warmup()` - pre-creates the enforcers.
 
-`registerMatchers()` — when `isScoped`, registers `keyMatch` as the domain matching func on `g`, adds `objectMatch` as a function, and registers it as the matching func on the resource relation (`g4`). When `domainMatching` is set (non-scoped), registers the chosen `Util.*Func` on the named role definition. Always finishes with `buildRoleLinks()`.
+`registerMatchers()` - when `isScoped`, registers `keyMatch` as the domain matching func on `g`, adds `objectMatch` as a function, and registers it as the matching func on the resource relation (`g4`). When `domainMatching` is set (non-scoped), registers the chosen `Util.*Func` on the named role definition. Always finishes with `buildRoleLinks()`.
 
-`assertMatcherCompilesSync()` — a boot-time smoke test: forces casbin's lazy matcher compile by running one dummy `enforceSync` (4 args when scoped/`normalizePayloadFn`, else 3), so a malformed matcher, an unregistered function, or an arity mismatch fails at warmup instead of on the first real request.
+`assertMatcherCompilesSync()` - a boot-time smoke test: forces casbin's lazy matcher compile by running one dummy `enforceSync` (4 args when scoped/`normalizePayloadFn`, else 3), so a malformed matcher, an unregistered function, or an arity mismatch fails at warmup instead of on the first real request.
 
 ### destroy()
 
-`this.pool?.destroy()` — drains and disposes the pooled enforcers.
+`this.pool?.destroy()` - drains and disposes the pooled enforcers.
 
 ### buildRules()
 
@@ -551,7 +551,7 @@ flowchart TD
 
 - **`extractUserLines(user)`** builds a fresh, **isolated** enforcer *with the adapter*, calls
   `adapter.loadFilteredPolicy({ principal: { type, id } })`, then `extractLinesFrom()` serializes every
-  p-type and g-type rule back into lines. This throwaway enforcer never serves a request — that is the
+  p-type and g-type rule back into lines. This throwaway enforcer never serves a request - that is the
   anti-poisoning guarantee.
 - **`fetchLinesWithRedisCache`** returns cached lines on hit (Redis owns expiry via `PX`). On miss it
   dedups concurrent misses through `pendingLineFetches` (single-flight), extracts once, and writes the
@@ -631,7 +631,7 @@ await opts.enforcer.buildRoleLinks();
 ## BaseFilteredAdapter
 
 Thin read-only base for casbin `FilteredAdapter`s backed by a datasource. It owns the boilerplate
-every filtered adapter repeats — datasource/connector plumbing, the `isFiltered() === true` flag, the
+every filtered adapter repeats - datasource/connector plumbing, the `isFiltered() === true` flag, the
 no-op write methods, and a `loadLines` helper. A subclass implements only `loadFilteredPolicy`: query
 the store for ONE principal's policies and turn them into casbin lines.
 
@@ -642,10 +642,10 @@ abstract class BaseFilteredAdapter<TFilter = ICasbinPolicyFilter>
   extends BaseHelper
   implements FilteredAdapter
 {
-  protected readonly dataSource: IDataSource;
-  protected get connector(): TAnyConnector;
+  protected readonly dataSource: ICasbinPolicySource;
+  protected get connector(): TCasbinPolicyConnector;
 
-  constructor(opts: { scope: string; dataSource: IDataSource });
+  constructor(opts: { scope: string; dataSource: ICasbinPolicySource });
 
   // Subclasses implement ONLY this:
   abstract loadFilteredPolicy(model: Model, filter: TFilter): Promise<void>;
@@ -680,9 +680,29 @@ interface ICasbinPolicyFilter {
 }
 ```
 
+### ICasbinPolicySource
+
+The minimal contract `BaseFilteredAdapter` depends on for its `dataSource` -- **not** the framework's
+general `IDataSource` interface. Any drizzle-backed datasource (e.g. `BasePostgresDataSource`) satisfies
+it structurally; the adapter only ever needs the connector to run policy queries.
+
+```typescript
+interface ICasbinPolicySource {
+  connector: TCasbinPolicyConnector;
+}
+
+type TCasbinPolicyConnector = ReturnType<
+  typeof drizzle<Record<string, AnyType>, NodePgClient>
+>;
+```
+
+> [!NOTE]
+> Components that only need query execution depend on this minimal local contract rather than a
+> connector class -- keeps the casbin adapters decoupled from the full datasource surface.
+
 ### loadLines()
 
-The base's only orchestration helper — subclasses call it from `loadFilteredPolicy` after assembling
+The base's only orchestration helper - subclasses call it from `loadFilteredPolicy` after assembling
 their casbin lines:
 
 ```typescript
@@ -694,14 +714,14 @@ protected async loadLines(opts: { model: Model; lines: string[] }): Promise<void
 }
 ```
 
-There are no template-method query hooks or shared line formatters on the base — a subclass owns its
+There are no template-method query hooks or shared line formatters on the base - a subclass owns its
 own queries and line construction (see `ScopedCasbinAdapter` below for the reference implementation).
 
 ## ScopedCasbinAdapter
 
 The generic, read-only `FilteredAdapter` for the scoped RBAC model. It reads **one principal's edges**
 plus the **shared structural hierarchy** from a single `PolicyDefinition` edge table (joined to
-`Permission` for codes) and emits casbin lines. No subclassing — configure it with `IScopedCasbinEntities`.
+`Permission` for codes) and emits casbin lines. No subclassing - configure it with `IScopedCasbinEntities`.
 
 ### Class
 
@@ -709,7 +729,7 @@ plus the **shared structural hierarchy** from a single `PolicyDefinition` edge t
 class ScopedCasbinAdapter extends BaseFilteredAdapter<IScopedCasbinPolicyFilter> {
   protected readonly entities: IScopedCasbinEntities;
 
-  constructor(opts: { dataSource: IDataSource; entities: IScopedCasbinEntities });
+  constructor(opts: { dataSource: ICasbinPolicySource; entities: IScopedCasbinEntities });
 
   async loadFilteredPolicy(model: Model, filter: IScopedCasbinPolicyFilter): Promise<void>;
 
@@ -750,7 +770,7 @@ interface IScopedCasbinPolicyFilter {
 }
 ```
 
-### loadFilteredPolicy() — two waves
+### loadFilteredPolicy() - two waves
 
 ```mermaid
 flowchart TD
@@ -761,8 +781,8 @@ flowchart TD
     W2 --> Load["loadLines(model, all lines)"]
 ```
 
-1. **Wave 1 (parallel):** the principal's own edges — role assignments (`g`), domain memberships
-   (`g2`), direct grants (`p`) — plus the shared structural trees (`role_inherits` → `g`,
+1. **Wave 1 (parallel):** the principal's own edges - role assignments (`g`), domain memberships
+   (`g2`), direct grants (`p`) - plus the shared structural trees (`role_inherits` → `g`,
    `domain_inherits` → `g3`, `resource_inherits` → `g4`, `action_inherits` → `g5`).
 2. **Role closure:** `expandRoleClosure` does a cycle-safe BFS over the `role_inherits` (`g`) edges to
    collect the assigned roles + all transitive parents.
@@ -898,7 +918,7 @@ Supports these formats:
 // String array
 roles: ['admin', 'user']
 
-// Object array with identifier (preferred — matches AuthorizationRole.identifier)
+// Object array with identifier (preferred - matches AuthorizationRole.identifier)
 roles: [{ id: 1, identifier: '900_admin', priority: 900 }]
 
 // Object array with name fallback
@@ -999,7 +1019,7 @@ buildRouteMiddlewares<RouteConfig extends IAuthRouteConfig>(opts: { configs: Rou
     mws.push(authenticateFn({ strategies, mode }));
   }
 
-  // 2. Authorize middleware (second) — supports single or array
+  // 2. Authorize middleware (second) - supports single or array
   if (authorize) {
     const specs = Array.isArray(authorize) ? authorize : [authorize];
     for (const spec of specs) {
@@ -1026,7 +1046,7 @@ buildRpcMiddlewares(opts: { configs: IRpcMetadata }): TRpcMiddleware[] {
   // 1. Authenticate middleware (first)
   if (configs.authenticate) { ... }
 
-  // 2. Authorize middleware (second) — same pattern as REST
+  // 2. Authorize middleware (second) - same pattern as REST
   if (configs.authorize) {
     const specs = Array.isArray(configs.authorize) ? configs.authorize : [configs.authorize];
     for (const spec of specs) {

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

@@ -76,13 +76,13 @@ All error messages from the authorization module, organized by source:
 | `[CasbinAuthorizationEnforcer] request.action and request.resource are required.` | 500 | `evaluate` |
 | `[CasbinAuthorizationEnforcer] keyFn returned an empty cache key.` | 400 | `buildRules`/cache management (via `resolveCacheKey`) |
 | <code v-pre>[CasbinAuthorizationEnforcer] cached.options.expiresIn must be >= 10000 (ms) &#124; Received: {{value}}</code> | 500 | `configure` (via `validateExpiresIn`) |
-| <code v-pre>[CasbinAuthorizationEnforcer] Matcher smoke test failed at warmup — ...</code> | 500 | `configure` (via `assertMatcherCompilesSync`) |
+| <code v-pre>[CasbinAuthorizationEnforcer] Matcher smoke test failed at warmup - ...</code> | 500 | `configure` (via `assertMatcherCompilesSync`) |
 | <code v-pre>[resolveDomainMatchingFn] Unsupported func: {{name}} &#124; Valids: [...]</code> | 500 | `configure` (via `registerMatchers`) |
 | <code v-pre>[registerMatchers] Role definition "{{name}}" is not declared in the Casbin model. ...</code> | 500 | `configure` (via `registerMatchers`, only when `domainMatching` is set) |
 | <code v-pre>[resolveModel] Invalid model.driver &#124; Valids: [file, text]</code> | 500 | `configure` (via `resolveModel`) |
 | `[CasbinAuthorizationEnforcer] Cache management requires the redis cache driver, but caching is disabled.` | 500 | `invalidateUserCache`/`rebuildUserCache` (via `requireRedisCache`) |
 
-> The `Invalid cached.driver` errors were removed — `cached` is now a typed union
+> The `Invalid cached.driver` errors were removed - `cached` is now a typed union
 > (`{ use: false } | { use: true, driver: 'redis', ... }`), so an invalid driver is a compile-time
 > error, not a runtime one.
 
@@ -93,9 +93,9 @@ All error messages from the authorization module, organized by source:
 | `[CasbinAuthorizationEnforcer] keyFn returned an empty cache key.` | 400 | `resolveCacheKey` (read + cache-management paths) |
 | `[extractUserLines] Adapter does not support loadFilteredPolicy.` | 500 | `extractUserLines` |
 | `[loadPolicyLinesIntoModel] Not configured. Call configure() first.` | 500 | `loadPolicyLinesIntoModel` |
-| `[CasbinAuthorizationEnforcer] Cached payload is not an array of policy lines.` | — (logged, not thrown) | `parseCachedPolicyLines` — corrupt entry is discarded + refetched |
+| `[CasbinAuthorizationEnforcer] Cached payload is not an array of policy lines.` | - (logged, not thrown) | `parseCachedPolicyLines` - corrupt entry is discarded + refetched |
 
-> A corrupted Redis cache entry does **not** raise an error — it is logged and discarded, and the
+> A corrupted Redis cache entry does **not** raise an error - it is logged and discarded, and the
 > lines are refetched from the adapter (the request never 500s on cache corruption).
 
 ### Registry Errors (AuthorizationEnforcerRegistry)
@@ -360,7 +360,7 @@ keyFn: ({ user }) => `authz:policies:${user.principalType}:${user.userId}`,
 
 **Fix:** Use `CasbinEnforcerModelDrivers.FILE` (`'file'`) or `CasbinEnforcerModelDrivers.TEXT` (`'text'`).
 
-> There is no longer an `Invalid cached.driver` runtime error — `cached` is a typed union, so an
+> There is no longer an `Invalid cached.driver` runtime error - `cached` is a typed union, so an
 > unsupported cache driver is caught at compile time. Caching is **Redis-only**.
 
 ## Common Patterns
@@ -389,7 +389,7 @@ Check that rules are being cached correctly. The middleware caches on `Authoriza
 
 ### Redis Cache Not Working
 
-1. **Check Redis connection** -- verify `DefaultRedisHelper` is properly connected
+1. **Check Redis connection** -- verify the `AbstractRedisHelper` subclass (`RedisSingleHelper`, `RedisClusterHelper`, or `RedisSentinelHelper`) is properly connected
 2. **Check keyFn** -- ensure it returns a unique, non-empty key per user
 3. **Check expiresIn** -- must be >= 10,000 ms (`MIN_EXPIRES_IN`)
 4. **Verify cache hit** -- check logs for `"Loaded CACHED Policies"` vs `"Loaded ADAPTER + CACHED Policies"`

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

@@ -21,7 +21,7 @@
 | **authorize** | Standalone function wrapping `AuthorizationProvider.value()` |
 | **AuthorizationRole** | Value object for role identity with priority-based comparison |
 | **BaseFilteredAdapter** | Thin abstract casbin `FilteredAdapter` (datasource plumbing + `loadLines`); subclasses implement only `loadFilteredPolicy` |
-| **ScopedCasbinAdapter** | Generic read-only `FilteredAdapter` for the scoped RBAC model — reads one principal's edges + the shared hierarchy from a single `PolicyDefinition` table |
+| **ScopedCasbinAdapter** | Generic read-only `FilteredAdapter` for the scoped RBAC model - reads one principal's edges + the shared hierarchy from a single `PolicyDefinition` table |
 | **AbstractAuthRegistry** | Shared base class for authentication strategy registry and authorization enforcer registry |
 
 ### Authorization Flow (7 Steps)
@@ -147,7 +147,7 @@ Built-in Casbin matching functions selectable for `ICasbinEnforcerOptions.domain
 `CasbinDomainMatchingFunctions.SCHEME_SET` contains all valid values. `CasbinDomainMatchingFunctions.isValid(input)` checks membership. Companion type: `TCasbinDomainMatchingFunction`.
 
 > [!IMPORTANT]
-> The function is applied as `fn(requestDomain, policyDomain)` — the wildcard must live on the **stored/policy** side. With `keyMatch`: `keyMatch("Merchant_X", "*") === true`, `keyMatch("Merchant_X", "Merchant_X") === true`, `keyMatch("Merchant_X", "Merchant_Y") === false`. Store only `*` or exact domain values (never partial patterns like `Merchant_*`) to keep tenant isolation guaranteed.
+> The function is applied as `fn(requestDomain, policyDomain)` - the wildcard must live on the **stored/policy** side. With `keyMatch`: `keyMatch("Merchant_X", "*") === true`, `keyMatch("Merchant_X", "Merchant_X") === true`, `keyMatch("Merchant_X", "Merchant_Y") === false`. Store only `*` or exact domain values (never partial patterns like `Merchant_*`) to keep tenant isolation guaranteed.
 
 ### Casbin Rule Variants
 
@@ -264,6 +264,7 @@ import type {
 
   // Adapter types
   ICasbinPolicyFilter,
+  ICasbinPolicySource,
   IScopedCasbinEntities,
   IScopedCasbinPolicyFilter,
 
@@ -345,7 +346,7 @@ import {
   CASBIN_RBAC_DOMAIN_SCOPED_MODEL,
 } from '@venizia/ignis';
 
-// The generic scoped adapter — reads one principal's edges + the shared hierarchy from a single
+// The generic scoped adapter - reads one principal's edges + the shared hierarchy from a single
 // PolicyDefinition edge table. No subclassing; configure it with IScopedCasbinEntities.
 const adapter = new ScopedCasbinAdapter({
   dataSource,
@@ -381,7 +382,7 @@ AuthorizationEnforcerRegistry.getInstance().register({
         },
       },
       // poolSize / poolAcquireTimeoutMs are optional (defaults 16 / 5000ms).
-      // In scoped mode you do NOT pass domainMatching or normalizePayloadFn — the request domain
+      // In scoped mode you do NOT pass domainMatching or normalizePayloadFn - the request domain
       // is supplied by the provider's domain resolver (see "Domain scoping" in usage.md).
     },
   }],
@@ -493,7 +494,7 @@ Casbin-specific options, provided per-enforcer via `AuthorizationEnforcerRegistr
 | `poolSize` | `number` | `16` | Number of pooled enforcers (each request enforces on its own) |
 | `poolAcquireTimeoutMs` | `number` | `5000` | Max ms to wait for a free pooled enforcer before failing closed |
 | `normalizePayloadFn` | `(opts) => { subject, resource, action, domain? }` | -- | (Non-scoped/custom) normalize subject/resource/action before evaluation |
-| `domainMatching` | `{ roleDefinition: string; fn: TCasbinDomainMatchingFunction }` | -- | (Non-scoped) opt-in domain matching function on a role definition. **Not needed when `isScoped: true`** — the scoped model registers its matchers automatically |
+| `domainMatching` | `{ roleDefinition: string; fn: TCasbinDomainMatchingFunction }` | -- | (Non-scoped) opt-in domain matching function on a role definition. **Not needed when `isScoped: true`** - the scoped model registers its matchers automatically |
 
 ```typescript
 interface ICasbinEnforcerOptions<
@@ -532,7 +533,7 @@ interface ICasbinEnforcerOptions<
   };
 
   // Non-scoped only. Registers a Casbin domain matching function on the named role definition.
-  // When isScoped is true, the scoped model registers its own matchers — do not set this.
+  // When isScoped is true, the scoped model registers its own matchers - do not set this.
   domainMatching?: {
     roleDefinition: string; // e.g. 'g'
     fn: TCasbinDomainMatchingFunction;
@@ -548,14 +549,14 @@ interface ICasbinEnforcerOptions<
 The `cached` field is a discriminated union. **Caching is Redis-only** (the in-memory driver was removed):
 
 ```typescript
-// No caching — every request rebuilds the user's policy from the datasource.
+// No caching - every request rebuilds the user's policy from the datasource.
 interface { use: false }
 
 // Redis cache (store/retrieve the user's policy lines from Redis, TTL via PX).
 interface ICasbinEnforcerCachedRedis {
   driver: 'redis';
   options: {
-    connection: DefaultRedisHelper;
+    connection: IRedisHelper;
     expiresIn: number;
     keyFn: (opts: { user: IAuthorizationUser }) => ValueOrPromise<string>;
   };
@@ -743,7 +744,7 @@ buildRouteMiddlewares<RouteConfig extends IAuthRouteConfig>(opts: { configs: Rou
     mws.push(authenticateFn({ strategies, mode }));
   }
 
-  // 2. Authorize middleware (second) — supports single or array
+  // 2. Authorize middleware (second) - supports single or array
   if (authorize) {
     const specs = Array.isArray(authorize) ? authorize : [authorize];
     for (const spec of specs) {
@@ -771,7 +772,7 @@ buildRpcMiddlewares(opts: { configs: IRpcMetadata }): TRpcMiddleware[] {
   // 1. Authenticate middleware
   if (configs.authenticate) { ... }
 
-  // 2. Authorize middleware — same pattern as REST
+  // 2. Authorize middleware - same pattern as REST
   if (configs.authorize) {
     const specs = Array.isArray(configs.authorize) ? configs.authorize : [configs.authorize];
     for (const spec of specs) {