@venizia/ignis-docs 0.0.8-1 → 0.0.8-2

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

@@ -22,11 +22,9 @@ flowchart TD
     S5b -->|DI fails| E500c[/"500: Failed to resolve"/]
     S5b -->|OK| S6{"Step 6: Build rules"}
 
-    S6 -->|No principalType| E400a[/"400: principalType required"/]
-    S6 -->|Not initialized| E500d[/"500: Enforcer not initialized"/]
+    S6 -->|Not configured| E500d[/"500: Not configured. Call configure() first."/]
     S6 -->|No FilteredAdapter| E500e[/"500: Adapter does not support loadFilteredPolicy"/]
-    S6 -->|Bad cache driver| E500f[/"500: Invalid cached.driver"/]
-    S6 -->|Empty Redis key| E400b[/"400: Invalid cachedKey"/]
+    S6 -->|Empty Redis key| E400b[/"400: keyFn returned an empty cache key"/]
     S6 -->|OK| S7{"Step 7: Evaluate"}
 
     S7 -->|No action/resource| E500g[/"500: request.action and resource required"/]
@@ -73,22 +71,38 @@ All error messages from the authorization module, organized by source:
 |---------------|--------|--------|
 | `[CasbinAuthorizationEnforcer] "casbin" is not installed` | 500 | `configure` |
 | `[CasbinAuthorizationEnforcer] options.model is required.` | 500 | `configure` |
-| `[CasbinAuthorizationEnforcer] Enforcer not initialized. Call configure() first.` | 500 | `evaluate`, `buildRules` |
-| `[CasbinAuthorizationEnforcer] Adapter does not support loadFilteredPolicy.` | 500 | `buildRules` |
+| `[CasbinAuthorizationEnforcer] Not configured. Call configure() first.` | 500 | `evaluate`, `loadPolicyLinesIntoModel` |
+| `[extractUserLines] Adapter does not support loadFilteredPolicy.` | 500 | `buildRules` (via `extractUserLines`) |
 | `[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>[buildRules] Invalid cached.driver &#124; Valids: [in-memory, redis]</code> | 500 | `buildRules` |
-| <code v-pre>[resolveCasbinEnforcer] Invalid cached.driver &#124; Valids: [in-memory, redis]</code> | 500 | `configure` (via `resolveCasbinEnforcer`) |
+| <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
+> (`{ use: false } | { use: true, driver: 'redis', ... }`), so an invalid driver is a compile-time
+> error, not a runtime one.
 
 ### Policy Loading Errors (CasbinAuthorizationEnforcer internals)
 
 | Error Message | Status | Method |
 |---------------|--------|--------|
-| `[loadPoliciesWithRedisCache] Invalid cachedKey to start validate user authorization!` | 400 | `loadPoliciesWithRedisCache` |
-| `[loadPoliciesFromAdapter] Invalid state of enforcer` | 500 | `loadPoliciesFromAdapter` |
-| `[extractPolicyLines] Invalid state of enforcer` | 500 | `extractPolicyLines` |
-| `[loadPolicyLinesIntoModel] Enforcer not initialized. Call configure() first.` | 500 | `loadPolicyLinesIntoModel` |
+| `[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 |
+
+> 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)
+
+| Error Message | Status | Method |
+|---------------|--------|--------|
+| `[AuthorizationEnforcerRegistry] Enforcer "{{name}}" does not support cache invalidation` | 500 | `invalidateUserCache` / `rebuildUserCache` (the resolved enforcer lacks the optional method) |
 
 ## Troubleshooting
 
@@ -264,18 +278,18 @@ AuthorizationEnforcerRegistry.getInstance().register({
 });
 ```
 
-### "[CasbinAuthorizationEnforcer] Adapter does not support loadFilteredPolicy"
+### "[extractUserLines] Adapter does not support loadFilteredPolicy"
 
 **Cause:** The adapter provided to the Casbin enforcer does not implement the `loadFilteredPolicy` method from casbin's `FilteredAdapter` interface. The authorization system always uses filtered policy loading.
 
-**Fix:** Use an adapter that implements `FilteredAdapter`, such as `DrizzleCasbinAdapter` or a custom adapter extending `BaseFilteredAdapter`:
+**Fix:** Use an adapter that implements `FilteredAdapter`, such as `ScopedCasbinAdapter` or a custom adapter extending `BaseFilteredAdapter`:
 
 ```typescript
-import { DrizzleCasbinAdapter } from '@venizia/ignis';
+import { ScopedCasbinAdapter } from '@venizia/ignis';
 
-const adapter = new DrizzleCasbinAdapter({
+const adapter = new ScopedCasbinAdapter({
   dataSource,
-  entities: { ... },
+  entities: { /* IScopedCasbinEntities */ },
 });
 ```
 
@@ -297,9 +311,9 @@ cached: {
 },
 ```
 
-### "[CasbinAuthorizationEnforcer] Enforcer not initialized"
+### "[CasbinAuthorizationEnforcer] Not configured. Call configure() first."
 
-**Cause:** The Casbin enforcer's `evaluate()`, `buildRules()`, or internal methods were called before `configure()`. This should not happen when using `resolveEnforcer()` (which auto-configures), but can occur if the enforcer is resolved manually via the DI container.
+**Cause:** The Casbin enforcer's `evaluate()` (or `loadPolicyLinesIntoModel()`) was called before `configure()` built the enforcer pool. This should not happen when using `resolveEnforcer()` (which auto-configures), but can occur if the enforcer is resolved manually via the DI container.
 
 **Fix:** Always resolve enforcers through the registry's `resolveEnforcer()` method, which handles configure-once automatically:
 
@@ -323,36 +337,31 @@ keyFn: ({ user }) => {
 },
 ```
 
-### "[loadPoliciesFromAdapter] Invalid state of enforcer"
-
-**Cause:** `loadPoliciesFromAdapter()` was called but the internal casbin enforcer is null. This is an internal state error.
-
-**Fix:** This should not occur in normal usage. If it does, ensure `configure()` completed successfully before any policy loading operations.
+### "[CasbinAuthorizationEnforcer] Not configured. Call configure() first."
 
-### "[extractPolicyLines] Invalid state of enforcer"
+**Cause:** `evaluate()` or `loadPolicyLinesIntoModel()` ran before the enforcer pool was built.
 
-**Cause:** `extractPolicyLines()` was called but the internal casbin enforcer is null. This method is called during Redis cache miss flow.
+**Fix:** Ensure `configure()` completed successfully (the registry calls it on first use) before any
+evaluation. The enforcer pool is created in `configure()`.
 
-**Fix:** Same as above -- ensure `configure()` completed before policy operations.
+### "[CasbinAuthorizationEnforcer] keyFn returned an empty cache key."
 
-### "[loadPolicyLinesIntoModel] Enforcer not initialized"
+**Cause:** The Redis `cached.options.keyFn` returned an empty string for a user.
 
-**Cause:** `loadPolicyLinesIntoModel()` was called but the internal casbin enforcer is null. This method is called during Redis cache hit flow to load cached lines.
+**Fix:** Return a stable, non-empty key (commonly derived from `user.principalType` + `user.userId`):
 
-**Fix:** Same as above -- ensure `configure()` completed before policy operations.
+```typescript
+keyFn: ({ user }) => `authz:policies:${user.principalType}:${user.userId}`,
+```
 
-### Invalid driver errors
+### "[resolveModel] Invalid model.driver | Valids: [file, text]"
 
-**Messages:**
-- `[buildRules] Invalid cached.driver | Valids: [in-memory, redis]`
-- `[resolveCasbinEnforcer] Invalid cached.driver | Valids: [in-memory, redis]`
-- `[resolveModel] Invalid model.driver | Valids: [file, text]`
+**Cause:** An unsupported `model.driver` string was passed.
 
-**Cause:** An unsupported driver string was passed in the options.
+**Fix:** Use `CasbinEnforcerModelDrivers.FILE` (`'file'`) or `CasbinEnforcerModelDrivers.TEXT` (`'text'`).
 
-**Fix:** Use one of the valid values:
-- Cache drivers: `CasbinEnforcerCachedDrivers.IN_MEMORY` (`'in-memory'`) or `CasbinEnforcerCachedDrivers.REDIS` (`'redis'`)
-- Model drivers: `CasbinEnforcerModelDrivers.FILE` (`'file'`) or `CasbinEnforcerModelDrivers.TEXT` (`'text'`)
+> 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
 
@@ -373,10 +382,10 @@ Check that rules are being cached correctly. The middleware caches on `Authoriza
 
 ### Casbin Policies Not Loading
 
-1. **Check adapter entities** -- ensure `tableName` and `principalType` match your database schema
-2. **Check variant column** -- policy rows must have `variant = 'policy'` (`CasbinRuleVariants.POLICY`), role assignments must have `variant = 'group'` (`CasbinRuleVariants.GROUP`)
-3. **Check subject/target types** -- the SQL queries filter by `subject_type` and `target_type`
-4. **Check the model file** -- ensure your `.conf` file matches the policy format (e.g., domain-aware vs simple)
+1. **Check adapter entities** -- ensure `IScopedCasbinEntities` (`policyDefinition`/`permission` table names + `schemaName`, `principals`, `domainTypes`) match your database schema
+2. **Check the variant column** -- `PolicyDefinition.variant` must use the `AuthorizationPolicyVariants.*.action` values: `grant`, `assign_role`, `join_domain`, `role_inherits`, `resource_inherits`, `action_inherits`, `domain_inherits`
+3. **Check subject/target types** -- the SQL queries filter by `subject_type`/`target_type` against `principals` and `domainTypes`
+4. **Check the model** -- for scoped RBAC, use `CASBIN_RBAC_DOMAIN_SCOPED_MODEL` with `isScoped: true`
 
 ### Redis Cache Not Working
 

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

@@ -20,10 +20,8 @@
 | **AuthorizationProvider** | IProvider producing the `authorize()` middleware factory |
 | **authorize** | Standalone function wrapping `AuthorizationProvider.value()` |
 | **AuthorizationRole** | Value object for role identity with priority-based comparison |
-| **BaseFilteredAdapter** | Abstract casbin `FilteredAdapter` with template method pattern for query hooks |
-| **DrizzleCasbinAdapter** | Drizzle-based read-only `FilteredAdapter` using raw SQL queries |
-| **StringAuthorizationAction** | `IAuthorizationComparable` implementation for string actions (includes `WILDCARD = '*'`) |
-| **StringAuthorizationResource** | `IAuthorizationComparable` implementation for string resources |
+| **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 |
 | **AbstractAuthRegistry** | Shared base class for authentication strategy registry and authorization enforcer registry |
 
 ### Authorization Flow (7 Steps)
@@ -72,6 +70,7 @@ flowchart TD
 | `Authorization.RULES` | `'authorization.rules'` | Context key for cached rules |
 | `Authorization.SKIP_AUTHORIZATION` | `'authorization.skip'` | Context key to dynamically skip authorization |
 | `Authorization.ENFORCER` | `'authorization.enforcer'` | Binding key prefix for enforcers |
+| `Authorization.DOMAIN` | `'authorization.domain'` | Context key for the resolved request domain scope (set by the provider when domain scoping is in play) |
 
 ### Authorization Actions
 
@@ -125,21 +124,72 @@ flowchart TD
 
 | Constant | Value | Description |
 |----------|-------|-------------|
-| `CasbinEnforcerCachedDrivers.IN_MEMORY` | `'in-memory'` | In-memory cache with periodic invalidation |
-| `CasbinEnforcerCachedDrivers.REDIS` | `'redis'` | Redis-backed cache with TTL |
+| `CasbinEnforcerCachedDrivers.REDIS` | `'redis'` | Redis-backed per-user line cache with TTL (the only cache driver) |
 
 `CasbinEnforcerCachedDrivers.SCHEME_SET` contains all valid drivers. `CasbinEnforcerCachedDrivers.isValid(input)` checks membership.
 
-### Casbin Rule Variants
+> The in-memory cache driver was removed. Caching is **Redis-only**: set `cached` to
+> `{ use: true, driver: 'redis', options: { connection, expiresIn, keyFn } }`, or `{ use: false }`
+> to disable caching (every request rebuilds the user's policy from the datasource).
+
+### Casbin Domain Matching Functions
+
+Built-in Casbin matching functions selectable for `ICasbinEnforcerOptions.domainMatching.fn`. Each value maps 1:1 to a Casbin `Util.*Func` export and is applied to the **domain slot** of a role definition (e.g. `g`).
 
 | Constant | Value | Description |
 |----------|-------|-------------|
-| `CasbinRuleVariants.POLICY` | `'policy'` | Database variant column value for permission rules |
-| `CasbinRuleVariants.GROUP` | `'group'` | Database variant column value for role assignments |
-| `CasbinRuleVariants.P` | `'p'` | Casbin line prefix for policy rules |
-| `CasbinRuleVariants.G` | `'g'` | Casbin line prefix for grouping rules |
+| `CasbinDomainMatchingFunctions.KEY_MATCH` | `'keyMatch'` | `*` is the only wildcard; exact compare otherwise. Recommended for `Merchant_<uuid>`-style domains |
+| `CasbinDomainMatchingFunctions.KEY_MATCH_2` | `'keyMatch2'` | Adds URL-path `:param` segment matching |
+| `CasbinDomainMatchingFunctions.KEY_MATCH_3` | `'keyMatch3'` | Adds `{param}` segment matching |
+| `CasbinDomainMatchingFunctions.KEY_MATCH_4` | `'keyMatch4'` | `{param}` with repeated-name equality checks |
+| `CasbinDomainMatchingFunctions.REGEX_MATCH` | `'regexMatch'` | Treats the stored/policy value as a full regular expression |
+
+`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.
+
+### Casbin Rule Variants
+
+`CasbinRuleVariants` holds **only the Casbin line prefixes** declared by the model, numbered in
+request-tuple order (`sub → dom → obj → act`):
+
+| Constant | Value | Relation |
+|----------|-------|----------|
+| `CasbinRuleVariants.P` | `'p'` | Permission policy line |
+| `CasbinRuleVariants.G` | `'g'` | Role membership + role inheritance (the `sub` axis) |
+| `CasbinRuleVariants.G2` | `'g2'` | User→domain membership (the `dom` axis) |
+| `CasbinRuleVariants.G3` | `'g3'` | Domain hierarchy (the `dom` axis) |
+| `CasbinRuleVariants.G4` | `'g4'` | Resource hierarchy (the `obj` axis, via `objectMatch`) |
+| `CasbinRuleVariants.G5` | `'g5'` | Action hierarchy (the `act` axis) |
+
+### Authorization Policy Variants
+
+The DB `variant` discriminator (the kind of "edge" stored in `PolicyDefinition`) lives on
+`AuthorizationPolicyVariants`. Each entry carries `action` (the DB value) and `rule` (the Casbin prefix
+the adapter emits for that edge):
+
+| Variant | `action` (DB) | `rule` | Meaning |
+|---------|---------------|--------|---------|
+| `GRANT` | `'grant'` | `p` | Give a permission to a User or Role |
+| `ASSIGN_ROLE` | `'assign_role'` | `g` | Give a User a Role (optionally domain-scoped) |
+| `ROLE_INHERITS` | `'role_inherits'` | `g` | Role inherits another Role |
+| `JOIN_DOMAIN` | `'join_domain'` | `g2` | User is a member of a Domain |
+| `DOMAIN_INHERITS` | `'domain_inherits'` | `g3` | Domain nested under a parent Domain |
+| `RESOURCE_INHERITS` | `'resource_inherits'` | `g4` | Resource nested under a broader Resource |
+| `ACTION_INHERITS` | `'action_inherits'` | `g5` | Action implied by a broader Action |
 
-`CasbinRuleVariants.SCHEME_SET` contains `POLICY` and `GROUP` (the DB variants). `CasbinRuleVariants.isValid(input)` checks membership against the DB variants.
+`AuthorizationPolicyVariants.isValidAction(input)` / `isValidRule(input)` check membership;
+`ACTION_SCHEME_SET` / `RULE_SCHEME_SET` hold the sets.
+
+### Authorization Domain Scopes
+
+Sentinel domain values used on `grant` rows:
+
+| Constant | Value | Meaning |
+|----------|-------|---------|
+| `AuthorizationDomainScopes.ANY_MEMBER` | `'ANY_MEMBER'` | Applies in every domain the subject joined (checked via `g2`) |
+| `AuthorizationDomainScopes.SYSTEM_WIDE` | `'SYSTEM_WIDE'` | Applies system-wide, bypassing membership (super-admin) |
 
 > [!NOTE]
 > All constant classes follow the same pattern: static readonly values + `SCHEME_SET: Set<string>` + `isValid(input): boolean`. Each class also has a companion type alias generated via `TConstValue<typeof ClassName>` (e.g., `TAuthorizationAction`, `TAuthorizationDecision`, `TCasbinRuleVariant`).
@@ -174,22 +224,26 @@ import {
 
   // Adapters
   BaseFilteredAdapter,
-  DrizzleCasbinAdapter,
+  ScopedCasbinAdapter,
+
+  // Scoped RBAC model
+  CASBIN_RBAC_DOMAIN_SCOPED_MODEL,
 
   // Models
   AuthorizationRole,
-  StringAuthorizationAction,
-  StringAuthorizationResource,
 
   // Constants
   Authorization,
   AuthorizationActions,
   AuthorizationDecisions,
+  AuthorizationDomainScopes,
+  AuthorizationPolicyVariants,
   AuthorizationRoles,
   AuthorizationEnforcerTypes,
   CasbinEnforcerModelDrivers,
   CasbinEnforcerCachedDrivers,
   CasbinRuleVariants,
+  CasbinDomainMatchingFunctions,
 
   // Binding keys
   AuthorizeBindingKeys,
@@ -203,19 +257,15 @@ import type {
   IAuthorizationSpec,
   IAuthorizationRequest,
   IAuthorizationRole,
-  IAuthorizationComparable,
 
   // Casbin options
   ICasbinEnforcerOptions,
-  ICasbinEnforcerCachedMemory,
   ICasbinEnforcerCachedRedis,
 
   // Adapter types
-  IBaseFilteredAdapterEntities,
   ICasbinPolicyFilter,
-  TBasePolicyRow,
-  IDrizzleCasbinEntities,
-  IDrizzleCasbinAdapterOptions,
+  IScopedCasbinEntities,
+  IScopedCasbinPolicyFilter,
 
   // Function & utility types
   TAuthorizeFn,
@@ -230,6 +280,7 @@ import type {
   TCasbinEnforcerCachedDriver,
   TCasbinEnforcerModelDriver,
   TCasbinRuleVariant,
+  TCasbinDomainMatchingFunction,
 } from '@venizia/ignis';
 ```
 
@@ -290,18 +341,20 @@ import {
   AuthorizationEnforcerTypes,
   CasbinAuthorizationEnforcer,
   CasbinEnforcerModelDrivers,
-  DrizzleCasbinAdapter,
+  ScopedCasbinAdapter,
+  CASBIN_RBAC_DOMAIN_SCOPED_MODEL,
 } from '@venizia/ignis';
-import path from 'node:path';
 
-// Create adapter (Drizzle example)
-const adapter = new DrizzleCasbinAdapter({
+// 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,
   entities: {
-    permission: { tableName: 'Permission', principalType: 'Permission' },
-    role: { tableName: 'Role', principalType: 'Role' },
-    policyDefinition: { tableName: 'PolicyDefinition', principalType: 'PolicyDefinition' },
-    domain: { principalType: 'Organization' },
+    policyDefinition: { tableName: 'PolicyDefinition', schemaName: 'identity' },
+    permission: { tableName: 'Permission', schemaName: 'identity' },
+    principals: { user: 'User', role: 'Role' },   // casbin name prefixes
+    domainTypes: ['Merchant', 'Organizer'],         // domain types you scope on
+    softDelete: { use: true, columnName: 'deleted_at' },
   },
 });
 
@@ -313,9 +366,10 @@ AuthorizationEnforcerRegistry.getInstance().register({
     type: AuthorizationEnforcerTypes.CASBIN,
     options: {
       model: {
-        driver: CasbinEnforcerModelDrivers.FILE,
-        definition: path.resolve(__dirname, './security/rbac_with_domains_deny.conf'),
+        driver: CasbinEnforcerModelDrivers.TEXT,
+        definition: CASBIN_RBAC_DOMAIN_SCOPED_MODEL,
       },
+      isScoped: true,           // 4-token (sub, dom, obj, act); auto-registers keyMatch + objectMatch
       adapter,
       cached: {
         use: true,
@@ -323,15 +377,12 @@ AuthorizationEnforcerRegistry.getInstance().register({
         options: {
           connection: redisHelper,
           expiresIn: 5 * 60 * 1000, // 5 minutes
-          keyFn: ({ user }) => `authz:policies:${user.userId}`,
+          keyFn: ({ user }) => `authz:policies:${user.principalType}:${user.userId}`,
         },
       },
-      normalizePayloadFn: ({ user, action, resource }) => ({
-        subject: `user_${user.userId}`,
-        domain: `Organization_${user.organizationId}`,
-        resource,
-        action,
-      }),
+      // poolSize / poolAcquireTimeoutMs are optional (defaults 16 / 5000ms).
+      // 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).
     },
   }],
 });
@@ -361,7 +412,8 @@ import {
   AuthorizationEnforcerTypes,
   CasbinAuthorizationEnforcer,
   CasbinEnforcerModelDrivers,
-  DrizzleCasbinAdapter,
+  ScopedCasbinAdapter,
+  CASBIN_RBAC_DOMAIN_SCOPED_MODEL,
   BaseApplication,
   IAuthorizeOptions,
 } from '@venizia/ignis';
@@ -378,7 +430,7 @@ export class Application extends BaseApplication {
     this.component(AuthorizeComponent);
 
     // Step 3: Register enforcer(s) with co-located options
-    const adapter = new DrizzleCasbinAdapter({ dataSource, entities: { ... } });
+    const adapter = new ScopedCasbinAdapter({ dataSource, entities: { /* IScopedCasbinEntities */ } });
 
     AuthorizationEnforcerRegistry.getInstance().register({
       container: this,
@@ -388,9 +440,10 @@ export class Application extends BaseApplication {
         type: AuthorizationEnforcerTypes.CASBIN,
         options: {
           model: {
-            driver: CasbinEnforcerModelDrivers.FILE,
-            definition: path.resolve(__dirname, './security/rbac_model.conf'),
+            driver: CasbinEnforcerModelDrivers.TEXT,
+            definition: CASBIN_RBAC_DOMAIN_SCOPED_MODEL,
           },
+          isScoped: true,
           adapter,
           cached: { use: false },
         },
@@ -416,11 +469,14 @@ Global authorization settings. Bound to the container before registering `Author
 |--------|------|---------|-------------|
 | `defaultDecision` | `TAuthorizationDecision` | -- | **Required.** Decision when enforcer returns `ABSTAIN` (`'allow'`, `'deny'`, or `'abstain'`) |
 | `alwaysAllowRoles` | `string[]` | `[]` | Roles that bypass all authorization checks (global) |
+| `domainResolver` | `TAuthorizationDomainResolver` | -- | Fallback domain resolver used when a route's `spec.domain` is not set. Returns `{ type, id }` or `null` (→ `SYSTEM_WIDE`) |
 
 ```typescript
 interface IAuthorizeOptions {
   defaultDecision: TAuthorizationDecision;
   alwaysAllowRoles?: string[];
+  /** Fallback domain resolver used when a route's spec has no `domain`. */
+  domainResolver?: TAuthorizationDomainResolver;
 }
 ```
 
@@ -430,10 +486,14 @@ Casbin-specific options, provided per-enforcer via `AuthorizationEnforcerRegistr
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `model` | `{ driver, definition }` | -- | **Required.** Casbin model definition (file path or inline text) |
-| `cached` | `{ use: false } \| { use: true, driver, options }` | -- | **Required.** Caching configuration |
-| `adapter` | `Adapter` | -- | Casbin adapter instance (e.g., `DrizzleCasbinAdapter`) |
-| `normalizePayloadFn` | `(opts) => { subject, resource, action, domain? }` | -- | Normalize subject/resource/action before evaluation |
+| `model` | `{ driver, definition }` | -- | **Required.** Casbin model definition (file path or inline text). For scoped RBAC, use `CASBIN_RBAC_DOMAIN_SCOPED_MODEL` |
+| `cached` | `{ use: false } \| { use: true, driver: 'redis', options }` | -- | **Required.** Caching configuration (Redis-only) |
+| `adapter` | `Adapter` | -- | Casbin adapter instance (e.g., `ScopedCasbinAdapter`) |
+| `isScoped` | `boolean` | `false` | Enable the scoped model: 4-token `(sub, dom, obj, act)` requests; auto-registers `keyMatch` on `g` + `objectMatch` on the resource relation |
+| `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 |
 
 ```typescript
 interface ICasbinEnforcerOptions<
@@ -448,15 +508,17 @@ interface ICasbinEnforcerOptions<
 
   cached:
     | { use: false }
-    | { use: true; driver: 'in-memory'; options: { expiresIn: number } }
-    | { use: true; driver: 'redis'; options: {
-        connection: DefaultRedisHelper;
-        expiresIn: number;
-        keyFn: (opts: { user: { principalType: string } & IAuthUser }) => ValueOrPromise<string>;
-      } };
+    | (ICasbinEnforcerCachedRedis & { use: true });
 
   adapter?: TAdapter;
 
+  // Enable the scoped RBAC model (4-token requests + auto-registered matchers).
+  isScoped?: boolean;
+
+  // Per-request enforcer pool (concurrency-safe; fail-closed on error).
+  poolSize?: number;             // default 16
+  poolAcquireTimeoutMs?: number; // default 5000
+
   normalizePayloadFn?(opts: {
     user: IAuthUser;
     action: TAction;
@@ -468,6 +530,13 @@ interface ICasbinEnforcerOptions<
     action: string;
     domain?: string;
   };
+
+  // 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.
+  domainMatching?: {
+    roleDefinition: string; // e.g. 'g'
+    fn: TCasbinDomainMatchingFunction;
+  };
 }
 ```
 
@@ -476,25 +545,19 @@ interface ICasbinEnforcerOptions<
 
 #### Cache Configuration Types
 
-The `cached` field is a discriminated union:
+The `cached` field is a discriminated union. **Caching is Redis-only** (the in-memory driver was removed):
 
 ```typescript
-// No caching
+// No caching — every request rebuilds the user's policy from the datasource.
 interface { use: false }
 
-// In-memory cache (CachedEnforcer with periodic invalidation timer)
-interface ICasbinEnforcerCachedMemory {
-  driver: 'in-memory';
-  options: { expiresIn: number };
-}
-
-// Redis cache (store/retrieve policy lines from Redis)
+// Redis cache (store/retrieve the user's policy lines from Redis, TTL via PX).
 interface ICasbinEnforcerCachedRedis {
   driver: 'redis';
   options: {
     connection: DefaultRedisHelper;
     expiresIn: number;
-    keyFn: (opts: { user: { principalType: string } & IAuthUser }) => ValueOrPromise<string>;
+    keyFn: (opts: { user: IAuthorizationUser }) => ValueOrPromise<string>;
   };
 }
 ```
@@ -519,9 +582,6 @@ interface IAuthorizationSpec<E extends Env = Env, TAction = string, TResource =
 }
 ```
 
-> [!NOTE]
-> `TAction` and `TResource` default to `string` but can accept `IAuthorizationComparable` implementations (e.g., `StringAuthorizationAction`) for custom comparison logic.
-
 ### TAuthorizationConditions
 
 Key-value conditions for attribute-based access control. Values are compared with strict equality (`===`).
@@ -598,6 +658,7 @@ declare module 'hono' {
     // Authorization
     [Authorization.RULES]: unknown;
     [Authorization.SKIP_AUTHORIZATION]: boolean;
+    [Authorization.DOMAIN]: string;
   }
 }
 ```
@@ -608,6 +669,7 @@ declare module 'hono' {
 |-----|----------|------|-------------|
 | `'authorization.rules'` | `Authorization.RULES` | `unknown` | Cached rules built by the enforcer. Type depends on enforcer implementation. |
 | `'authorization.skip'` | `Authorization.SKIP_AUTHORIZATION` | `boolean` | Set to `true` to dynamically skip authorization for this request. |
+| `'authorization.domain'` | `Authorization.DOMAIN` | `string` | Resolved request domain scope (`"<Type>_<id>"` or `SYSTEM_WIDE`); set by the provider when `spec.domain` or a global `domainResolver` is in play, and read by the enforcer. |
 
 ### Authentication Variables Used by Authorization