@venizia/ignis-docs 0.2.0 → 0.2.1-1

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

@@ -1,44 +1,39 @@
-# Authorization -- Usage & Examples
+---
+title: Authorization Usage
+description: Securing REST and gRPC routes, voters, role shortcuts, CRUD factory integration, custom enforcers, and multi-tenant domain scoping
+difficulty: advanced
+---
 
-> Securing routes, voters, CRUD factory integration, custom enforcers, and comparable actions/resources. See [Setup & Configuration](./) for initial setup.
+# Authorization Usage
 
-## Securing Routes
+Task-oriented examples for the Authorization component. See the [Overview](./) for initial setup and the [API Reference](./api) for every option and class.
 
-### Imperative Route (defineRoute)
+## Find what you need
 
-Use the `authorize` field in route configs to declare authorization requirements:
+| You want to | Go to |
+|---|---|
+| Add `authorize` to a REST or gRPC route | [Securing routes](#securing-routes) |
+| Call `authorize()` outside a route config | [Using the standalone authorize() function](#using-the-standalone-authorize-function) |
+| Add custom allow/deny logic before the enforcer | [Voters](#voters) |
+| Bypass the enforcer for trusted roles | [Role-based shortcuts](#role-based-shortcuts) |
+| Wire authorization into generated CRUD routes | [CRUD factory integration](#crud-factory-integration) |
+| Skip authorization for one request at runtime | [Dynamic skip authorization](#dynamic-skip-authorization) |
+| Read the resolved user, rules, or domain in a handler | [Accessing context variables](#accessing-context-variables) |
+| Replace Casbin with your own enforcer | [Custom enforcer](#custom-enforcer) |
+| Store policies in a schema `ScopedCasbinAdapter` doesn't fit | [Custom filtered adapter](#custom-filtered-adapter) |
+| Compare roles by priority | [AuthorizationRole comparison](#authorizationrole-comparison) |
+| Reference a model instead of a hardcoded resource string | [Model-Based Resource References](#model-based-resource-references) |
+| Scope grants to a tenant (multi-tenant apps) | [RBAC with domains](#rbac-with-domains-multi-tenant) |
+
+## Securing routes
+
+**Imperative route.** Add `authorize` to `defineRoute()`'s `configs`, next to `authenticate`.
 
 ```typescript
-import {
-  BaseRestController,
-  Authentication,
-  AuthorizationActions,
-} from '@venizia/ignis';
+import { BaseRestController, Authentication, AuthorizationActions } from '@venizia/ignis';
 
 class ArticleController extends BaseRestController {
   binding() {
-    // Read requires 'read' action on 'Article' resource
-    this.defineRoute({
-      configs: {
-        path: '/',
-        method: 'get',
-        authenticate: { strategies: [Authentication.STRATEGY_JWT] },
-        authorize: {
-          action: AuthorizationActions.READ,
-          resource: 'Article',
-        },
-        responses: jsonResponse({
-          description: 'List of articles',
-          schema: z.array(ArticleSchema),
-        }),
-      },
-      handler: async (context) => {
-        const articles = await this.articleService.findAll();
-        return context.json(articles);
-      },
-    });
-
-    // Delete requires 'delete' action with conditions
     this.defineRoute({
       configs: {
         path: '/{id}',
@@ -47,74 +42,26 @@ class ArticleController extends BaseRestController {
         authorize: {
           action: AuthorizationActions.DELETE,
           resource: 'Article',
-          conditions: { ownerId: 'currentUser' },
+          conditions: { ownerId: 'currentUser' }, // available to voters/custom enforcers - the built-in Casbin enforcer ignores it
         },
-        responses: jsonResponse({
-          description: 'Deleted article',
-          schema: ArticleSchema,
-        }),
+        responses: jsonResponse({ description: 'Deleted article', schema: ArticleSchema }),
       },
-      handler: async (context) => {
+      handler: async context => {
         const { id } = context.req.valid('param');
-        const result = await this.articleService.deleteById({ id });
-        return context.json(result);
+        return context.json(await this.articleService.deleteById({ id }));
       },
     });
   }
 }
 ```
 
-### Multiple Authorization Specs
-
-Pass an array of `IAuthorizationSpec` to require **all** specs to pass. Each spec creates a separate middleware -- all must succeed for the handler to execute:
-
-```typescript
-import { Authentication, AuthorizationActions } from '@venizia/ignis';
-
-this.defineRoute({
-  configs: {
-    path: '/admin/users/{id}',
-    method: 'patch',
-    authenticate: { strategies: [Authentication.STRATEGY_JWT] },
-    authorize: [
-      { action: AuthorizationActions.UPDATE, resource: 'User' },
-      { action: AuthorizationActions.UPDATE, resource: 'Admin' },
-    ],
-    responses: jsonResponse({
-      description: 'Updated user',
-      schema: UserSchema,
-    }),
-  },
-  handler: async (context) => {
-    // Both 'update:User' AND 'update:Admin' must pass
-  },
-});
-```
-
-> [!NOTE]
-> When multiple specs are evaluated on the same route, rules are built once and cached on the context (`Authorization.RULES`). The second spec reuses the cached rules without rebuilding.
-
-### Decorator-Based Route
-
-Use the `authorize` field alongside `authenticate` in decorator configs:
+**Decorator-based route.** Same `authorize` field inside `@get`/`@post`/etc. `configs`.
 
 ```typescript
 import { controller, get, post, AuthorizationActions, AuthorizationRoles } from '@venizia/ignis';
 
 @controller({ path: '/articles' })
 class ArticleController extends BaseRestController {
-  @get({
-    configs: {
-      path: '/',
-      authenticate: { strategies: [Authentication.STRATEGY_JWT] },
-      authorize: { action: AuthorizationActions.READ, resource: 'Article' },
-      responses: jsonResponse({ description: 'Articles', schema: z.array(ArticleSchema) }),
-    },
-  })
-  async findAll(opts: { context: TRouteContext }) {
-    // Handler runs only if authorized
-  }
-
   @post({
     configs: {
       path: '/',
@@ -129,232 +76,127 @@ class ArticleController extends BaseRestController {
     },
   })
   async create(opts: { context: TRouteContext }) {
-    // Handler runs if user has 'create:Article' permission OR 'editor'/'900_admin' role
+    // Runs if the user has 'create:Article' permission OR the 'editor'/'900_admin' role
   }
 }
 ```
 
-### gRPC Route Authorization
-
-Authorization works the same way in gRPC controllers. Use the `authorize` field in RPC metadata:
+**Require multiple specs.** Pass an array - each spec becomes its own middleware, and all must pass.
 
 ```typescript
-import { AuthorizationActions, Authentication } from '@venizia/ignis';
+authorize: [
+  { action: AuthorizationActions.UPDATE, resource: 'User' },
+  { action: AuthorizationActions.UPDATE, resource: 'Admin' },
+]
+```
 
-class GreeterController extends BaseGrpcController {
-  binding() {
-    this.defineRoute({
-      configs: {
-        method: sayHello,
-        authenticate: { strategies: [Authentication.STRATEGY_JWT] },
-        authorize: {
-          action: AuthorizationActions.EXECUTE,
-          resource: 'Greeter',
-        },
-      },
-      handler: async (context) => {
-        // Handler runs only if authorized
-      },
-    });
-  }
-}
+> [!NOTE]
+> When several specs run on the same route, rules are built once per ENFORCER, via `enforcer.buildRules()`, and cached on `Authorization.RULES` - a `Map` keyed by enforcer name - for the rest of the request. A second spec on the same enforcer reuses them; a spec on a different enforcer builds its own. The cache used to be a single slot shared by every enforcer, so one enforcer's rules could answer another's check.
+
+**gRPC route.** Same `authorize` field, inside RPC metadata. `AbstractGrpcController.buildRpcMiddlewares()` injects it in the same order as REST: authenticate, then authorize.
+
+```typescript
+@unary({
+  configs: {
+    name: 'deleteUser',
+    authenticate: { strategies: ['jwt'] },
+    authorize: { action: AuthorizationActions.DELETE, resource: 'user' },
+  },
+})
+async deleteUser(opts: { request: DeleteUserRequest; context: TRouteContext }) { ... }
 ```
 
-The `AbstractGrpcController.buildRpcMiddlewares()` method injects authorization middleware in the same order as REST controllers: authenticate first, then authorize.
+See [gRPC Controllers](/guides/core-concepts/grpc-controllers) for the full decorator/`defineRoute` gRPC surface.
 
-## Using the `authorize()` Standalone Function
+## Using the standalone `authorize()` function
 
-The `authorize()` function is a convenience wrapper around `AuthorizationProvider`. It returns a Hono `MiddlewareHandler`:
+`authorize({ spec, enforcerName? })` returns a plain Hono `MiddlewareHandler`. Use it outside route configs - for example, when you wire a Hono sub-app directly.
 
 ```typescript
 import { authorize, authenticate, Authentication, AuthorizationActions } from '@venizia/ignis';
 
-// Use as Hono middleware directly
 app.delete(
   '/articles/:id',
   authenticate({ strategies: [Authentication.STRATEGY_JWT] }),
   authorize({ spec: { action: AuthorizationActions.DELETE, resource: 'Article' } }),
-  (c) => {
-    const user = c.get(Authentication.CURRENT_USER);
-    return c.json({ deleted: true });
-  },
+  c => c.json({ deleted: true }),
 );
 ```
 
-### With Specific Enforcer
-
-If multiple enforcers are registered, specify which one to use:
+**Target a specific enforcer.** Omit `enforcerName` to use the first one registered.
 
 ```typescript
 authorize({
   spec: { action: AuthorizationActions.READ, resource: 'Report' },
-  enforcerName: 'my-custom',  // defaults to first registered if omitted
+  enforcerName: 'my-custom',
 });
 ```
 
 ## Voters
 
-Voters provide custom authorization logic that runs **before** the enforcer (step 4 in the pipeline).
-
-```mermaid
-flowchart TD
-    Start([Step 4: Voters]) --> HasVoters{Has voters?}
-    HasVoters -->|No| Enforcer([Continue to enforcer])
-    HasVoters -->|Yes| V1["Call voter 1"]
-    V1 --> D1{Decision?}
-    D1 -->|DENY| E403[/403 Forbidden/]
-    D1 -->|ALLOW| Next([next - authorized])
-    D1 -->|ABSTAIN| V2["Call voter 2"]
-    V2 --> D2{Decision?}
-    D2 -->|DENY| E403
-    D2 -->|ALLOW| Next
-    D2 -->|ABSTAIN| VN["... voter N"]
-    VN -->|All ABSTAIN| Enforcer
-```
-
-Each voter returns one of three decisions:
+Voters run **before** the enforcer (pipeline step 4) and are evaluated in order - the first non-`ABSTAIN` decision wins.
 
 | Decision | Effect |
 |----------|--------|
-| `AuthorizationDecisions.ALLOW` | Immediately grants access (skips remaining voters and enforcer) |
-| `AuthorizationDecisions.DENY` | Immediately denies access (throws 403) |
-| `AuthorizationDecisions.ABSTAIN` | No opinion -- continues to next voter or enforcer |
-
-### Basic Voter Example
+| `AuthorizationDecisions.ALLOW` | Grants access immediately - skips remaining voters and the enforcer |
+| `AuthorizationDecisions.DENY` | Denies access immediately - throws 403 |
+| `AuthorizationDecisions.ABSTAIN` | No opinion - falls through to the next voter, then the enforcer |
 
 ```typescript
-import {
-  AuthorizationActions,
-  AuthorizationDecisions,
-  TAuthorizationVoter,
-} from '@venizia/ignis';
+import { AuthorizationActions, AuthorizationDecisions, TAuthorizationVoter } from '@venizia/ignis';
 
 const ownerVoter: TAuthorizationVoter = async ({ user, action, resource, context }) => {
   if (action !== AuthorizationActions.UPDATE && action !== AuthorizationActions.DELETE) {
     return AuthorizationDecisions.ABSTAIN;
   }
 
-  const articleId = context.req.param('id');
-  const article = await articleService.findById({ id: articleId });
-
+  const article = await articleService.findById({ id: context.req.param('id') });
   if (!article) {
     return AuthorizationDecisions.ABSTAIN;
   }
 
-  if (article.authorId === user.userId) {
-    return AuthorizationDecisions.ALLOW;
-  }
-
-  return AuthorizationDecisions.ABSTAIN; // Let enforcer decide
+  return article.authorId === user.userId ? AuthorizationDecisions.ALLOW : AuthorizationDecisions.ABSTAIN;
 };
-```
-
-### Using Voters in Routes
 
-```typescript
-this.defineRoute({
-  configs: {
-    path: '/{id}',
-    method: 'patch',
-    authenticate: { strategies: [Authentication.STRATEGY_JWT] },
-    authorize: {
-      action: AuthorizationActions.UPDATE,
-      resource: 'Article',
-      voters: [ownerVoter],
-    },
-    // ...
-  },
-  handler: async (context) => {
-    // Runs if: owner (voter ALLOW) OR enforcer permits
-  },
-});
-```
-
-### Multiple Voters
-
-Voters are evaluated sequentially. The first non-ABSTAIN decision wins:
-
-```typescript
 authorize: {
   action: AuthorizationActions.UPDATE,
   resource: 'Article',
-  voters: [ownerVoter, adminOverrideVoter, timeWindowVoter],
+  voters: [ownerVoter, adminOverrideVoter], // sequential; first non-ABSTAIN wins
 }
 ```
 
-**Evaluation flow:**
-1. `ownerVoter` returns `ABSTAIN` -- continue
-2. `adminOverrideVoter` returns `ALLOW` -- **access granted** (skips remaining voters and enforcer)
-
 > [!TIP]
-> Use `ABSTAIN` as the default return when a voter doesn't have a strong opinion. Only return `DENY` when you're certain the request should be blocked regardless of other checks.
+> Default to `ABSTAIN` when a voter has no strong opinion. Only return `DENY` when the request should be blocked regardless of any other check. It short-circuits everything, including a later `ALLOW` voter.
 
-## Role-Based Shortcuts
+## Role-based shortcuts
 
-### Global `alwaysAllowRoles`
-
-Roles listed in `alwaysAllowRoles` bypass **all** authorization checks globally (step 3 in the pipeline):
+**Global bypass.** Roles in `alwaysAllowRoles` (bound via `IAuthorizeOptions`) skip all authorization checks on every route.
 
 ```typescript
-import { AuthorizationRoles } from '@venizia/ignis';
-
 this.bind<IAuthorizeOptions>({ key: AuthorizeBindingKeys.OPTIONS }).toValue({
   defaultDecision: 'deny',
   alwaysAllowRoles: [AuthorizationRoles.SUPER_ADMIN.identifier, 'system'],
 });
 ```
 
-### Per-Route `allowedRoles`
-
-Roles listed in `allowedRoles` on a specific `IAuthorizationSpec` bypass the enforcer for that route only (still evaluated at step 3):
+**Per-route bypass.** Roles in a spec's `allowedRoles` skip the enforcer for that route only.
 
 ```typescript
-authorize: {
-  action: AuthorizationActions.DELETE,
-  resource: 'Article',
-  allowedRoles: [AuthorizationRoles.ADMIN.identifier, 'moderator'],
-}
+authorize: { action: AuthorizationActions.DELETE, resource: 'Article', allowedRoles: [AuthorizationRoles.ADMIN.identifier, 'moderator'] }
 ```
 
-### Role Extraction
+**Role formats accepted.** `extractUserRoles()` reads `user.roles` and normalizes every entry to a string, trying `identifier` first, then `name`, then `String(id)`.
 
-The authorization middleware extracts roles from the authenticated user's `roles` field via the `extractUserRoles()` method:
+| `user.roles` shape | Extracted as |
+|---|---|
+| `['admin', 'user']` | Used as-is |
+| `[{ id: 1, identifier: '900_admin', priority: 900 }]` | `'900_admin'` (preferred - matches `AuthorizationRole.identifier`) |
+| `[{ id: 1, name: 'admin' }]` | `'admin'` |
+| `[{ id: 1 }]` | `'1'` |
 
-```mermaid
-flowchart TD
-    Input["user.roles"] --> IsArray{Array?}
-    IsArray -->|No| Empty(["return []"])
-    IsArray -->|Yes| Map["Map each role"]
-    Map --> Type{Type?}
-    Type -->|string| AsIs["Use as-is"]
-    Type -->|object| Prio["r.identifier"]
-    Prio -->|undefined| Name["r.name"]
-    Name -->|undefined| Id["String(r.id)"]
-```
+## CRUD factory integration
 
-It supports multiple formats:
-
-```typescript
-// String array
-roles: ['admin', 'user']
-
-// Object array with identifier (preferred - matches AuthorizationRole.identifier)
-roles: [{ id: 1, identifier: '900_admin', priority: 900 }]
-
-// Object array with name fallback
-roles: [{ id: 1, name: 'admin' }]
-
-// Object array with id-only fallback
-roles: [{ id: 1 }]
-```
-
-Extraction priority: `identifier` > `name` > `String(id)`
-
-## CRUD Factory Integration
-
-### Controller-Level Authorization
-
-Apply authorization to all CRUD routes:
+**Apply to every generated route.** Set `authorize` at the controller level in `defineCrudController`.
 
 ```typescript
 import { AuthorizationActions } from '@venizia/ignis';
@@ -368,89 +210,41 @@ ControllerFactory.defineCrudController({
 });
 ```
 
-### Per-Route Overrides
-
-Override authorization per CRUD endpoint:
+**Override per endpoint.** `routes.<endpoint>.authorize` takes precedence over the controller-level spec.
 
 ```typescript
-import { AuthorizationActions, AuthorizationRoles } from '@venizia/ignis';
-
-ControllerFactory.defineCrudController({
-  entity: Article,
-  repository: { name: 'ArticleRepository' },
-  controller: { name: 'ArticleController', basePath: '/articles' },
-  authenticate: { strategies: [Authentication.STRATEGY_JWT] },
-  authorize: { action: AuthorizationActions.READ, resource: 'Article' },
-  routes: {
-    // Public read -- skip both auth
-    find: { authenticate: { skip: true } },
-    count: { authenticate: { skip: true } },
-
-    // Custom authorization for write operations
-    create: {
-      authorize: { action: AuthorizationActions.CREATE, resource: 'Article' },
-    },
-    updateById: {
-      authorize: { action: AuthorizationActions.UPDATE, resource: 'Article' },
-    },
-
-    // Skip only authorization (still requires auth)
-    findOne: { authorize: { skip: true } },
-
-    // Strict delete with custom roles
-    deleteById: {
-      authorize: {
-        action: AuthorizationActions.DELETE,
-        resource: 'Article',
-        allowedRoles: [AuthorizationRoles.ADMIN.identifier],
-      },
+routes: {
+  find: { authenticate: { skip: true } },                                   // public read - skips BOTH checks
+  count: { authorize: { skip: true } },                                     // authenticated, no authorization
+  create: { authorize: { action: AuthorizationActions.CREATE, resource: 'Article' } },
+  deleteById: {
+    authorize: {
+      action: AuthorizationActions.DELETE,
+      resource: 'Article',
+      allowedRoles: [AuthorizationRoles.ADMIN.identifier],
     },
   },
-});
-```
-
-### Priority Resolution (Factory Routes)
-
-The `resolveRouteAuthorize` function in `defineControllerRouteConfigs` resolves authorization with this priority:
-
-```mermaid
-flowchart TD
-    Route([Route config]) --> AuthSkip{"authenticate:<br/>{ skip: true }?"}
-    AuthSkip -->|Yes| NoAuth([Skip BOTH<br/>auth + authz])
-    AuthSkip -->|No| AuthzSkip{"authorize:<br/>{ skip: true }?"}
-    AuthzSkip -->|Yes| NoAuthz([Skip authz only])
-    AuthzSkip -->|No| PerRoute{"Per-route<br/>authorize spec?"}
-    PerRoute -->|Yes| UseRoute([Use per-route spec])
-    PerRoute -->|No| Controller{"Controller-level<br/>authorize?"}
-    Controller -->|Yes| UseCtrl([Use controller spec])
-    Controller -->|No| NoAuthz2([No authorization])
+}
 ```
 
-1. **`authenticate: { skip: true }`** -- skips both authentication and authorization
-2. **`authorize: { skip: true }`** -- skips authorization only
-3. **Per-route `authorize` spec** -- overrides controller-level
-4. **Controller-level `authorize`** -- default for all routes
-
-### Per-Route Auth Type
+**Priority, in order:**
 
-The per-route authorize config is typed as a discriminated union:
+1. `authenticate: { skip: true }` - skips both authentication AND authorization
+2. `authorize: { skip: true }` - skips authorization only (authentication still runs)
+3. Per-route `authorize` spec - overrides the controller-level spec
+4. No per-route config - inherits the controller-level `authorize`
 
-```typescript
-type TRouteAuthorizeConfig = { skip: true } | IAuthorizationSpec | IAuthorizationSpec[];
-```
-
-This means each route can either skip authorization entirely, provide a single spec, or provide an array of specs that all must pass.
+Per-route config is typed `TRouteAuthorizeConfig = { skip: true } | IAuthorizationSpec | IAuthorizationSpec[]`. See the [API Reference](./api#crud-factory-authorization) for the full resolver signature.
 
-## Dynamic Skip Authorization
+## Dynamic skip authorization
 
-Use `Authorization.SKIP_AUTHORIZATION` to dynamically bypass authorization in middleware (step 1 in the pipeline):
+Set `Authorization.SKIP_AUTHORIZATION` from an earlier middleware to bypass authorization for that one request (pipeline step 1). This is useful for trusted service-to-service calls.
 
 ```typescript
 import { Authorization } from '@venizia/ignis';
 import { createMiddleware } from 'hono/factory';
 
 const conditionalAuthzMiddleware = createMiddleware(async (c, next) => {
-  // Skip authorization for internal service-to-service calls
   if (c.req.header('X-Internal-Service') === 'trusted-key') {
     c.set(Authorization.SKIP_AUTHORIZATION, true);
   }
@@ -458,64 +252,38 @@ const conditionalAuthzMiddleware = createMiddleware(async (c, next) => {
 });
 ```
 
-## Rules Caching
-
-The authorization middleware caches rules on the Hono context to avoid rebuilding them on every authorization spec evaluation. This is especially useful when multiple authorization specs are applied to the same route:
-
-```typescript
-// First spec triggers buildRules() → result cached on context
-authorize: [
-  { action: AuthorizationActions.READ, resource: 'Article' },
-  { action: AuthorizationActions.READ, resource: 'Comment' },
-]
-// Second spec reuses cached rules → no rebuild
-```
-
-> [!TIP]
-> Rules caching happens per-request. Each new HTTP request starts with an empty cache. If you need to invalidate cached rules mid-request (e.g., after role change), set `context.set(Authorization.RULES, null)`.
-
-## Accessing Context Variables
-
-The authorization module provides type-safe access to auth data on the Hono context:
+## Accessing context variables
 
 ```typescript
 import { Authorization, Authentication } from '@venizia/ignis';
 
-// In a route handler or middleware
-const user = c.get(Authentication.CURRENT_USER);  // IAuthUser
-const rules = c.get(Authorization.RULES);           // unknown (type depends on enforcer)
-const isSkipped = c.get(Authorization.SKIP_AUTHORIZATION); // boolean
-const domain = c.get(Authorization.DOMAIN);         // string ("<Type>_<id>" | "SYSTEM_WIDE"), set when domain scoping is in play
+const user = c.get(Authentication.CURRENT_USER);           // IAuthUser
+const rules = c.get(Authorization.RULES);                  // unknown - shape depends on the enforcer
+const isSkipped = c.get(Authorization.SKIP_AUTHORIZATION);  // boolean
+const domain = c.get(Authorization.DOMAIN);                // "<Type>_<id>" | "SYSTEM_WIDE" - set only when domain scoping is in play
 
-// Set skip dynamically
 c.set(Authorization.SKIP_AUTHORIZATION, true);
-
-// Invalidate cached rules
-c.set(Authorization.RULES, null);
+c.set(Authorization.RULES, null); // force a rebuild later in the SAME request
 ```
 
-## Custom Enforcer
+> [!TIP]
+> Rules are cached per-request only - every new HTTP request starts with an empty cache. `c.set(Authorization.RULES, null)` only matters if you need to force a rebuild mid-request, for example after mutating the user's roles inline.
+
+## Custom enforcer
 
-Create a custom enforcer by implementing `IAuthorizationEnforcer`:
+Implement `IAuthorizationEnforcer` to replace or supplement Casbin.
 
 ```typescript
 import {
-  IAuthorizationEnforcer,
-  IAuthorizationRequest,
-  IAuthUser,
-  TAuthorizationDecision,
-  AuthorizationDecisions,
-  TContext,
+  IAuthorizationEnforcer, IAuthorizationRequest, IAuthUser, TAuthorizationDecision,
+  AuthorizationDecisions, TContext,
 } from '@venizia/ignis';
 import { BaseHelper, ValueOrPromise } from '@venizia/ignis-helpers';
 import { Env } from 'hono';
 
 type MyRules = Map<string, Set<string>>;
 
-class MyCustomEnforcer
-  extends BaseHelper
-  implements IAuthorizationEnforcer<Env, string, string, MyRules>
-{
+class MyCustomEnforcer extends BaseHelper implements IAuthorizationEnforcer<Env, string, string, MyRules> {
   name = 'my-custom';
 
   constructor() {
@@ -523,85 +291,54 @@ class MyCustomEnforcer
   }
 
   async configure(): Promise<void> {
-    // One-time initialization (called by registry on first use)
+    // One-time initialization - called by the registry on first resolveEnforcer()
   }
 
-  async buildRules(opts: {
-    user: { principalType: string } & IAuthUser;
-    context: TContext;
-  }): Promise<MyRules> {
-    const rules = new Map<string, Set<string>>();
-    // Build your rules map from DB, config, etc.
-    return rules;
+  async buildRules(opts: { user: { principalType: string } & IAuthUser; context: TContext }): Promise<MyRules> {
+    return new Map(); // build from DB, config, etc.
   }
 
-  async evaluate(opts: {
-    rules: MyRules;
-    request: IAuthorizationRequest;
-    context: TContext;
-  }): Promise<TAuthorizationDecision> {
-    const { rules, request } = opts;
-    const resourceActions = rules.get(request.resource);
-    if (resourceActions?.has(request.action)) {
-      return AuthorizationDecisions.ALLOW;
-    }
-    return AuthorizationDecisions.DENY;
+  async evaluate(opts: { rules: MyRules; request: IAuthorizationRequest; context: TContext }): Promise<TAuthorizationDecision> {
+    const actions = opts.rules.get(opts.request.resource);
+    return actions?.has(opts.request.action) ? AuthorizationDecisions.ALLOW : AuthorizationDecisions.DENY;
   }
 }
 ```
 
-Then register it via the registry:
+Register it the same way as the Casbin enforcer, with `type: AuthorizationEnforcerTypes.CUSTOM`:
 
 ```typescript
-import {
-  AuthorizationEnforcerRegistry,
-  AuthorizationEnforcerTypes,
-  AuthorizeBindingKeys,
-  AuthorizeComponent,
-  IAuthorizeOptions,
-} from '@venizia/ignis';
-
-// Step 1: Global options
-this.bind<IAuthorizeOptions>({ key: AuthorizeBindingKeys.OPTIONS }).toValue({
-  defaultDecision: 'deny',
-});
-
-// Step 2: Component
-this.component(AuthorizeComponent);
-
-// Step 3: Register custom enforcer
 AuthorizationEnforcerRegistry.getInstance().register({
   container: this,
   enforcers: [{
     enforcer: MyCustomEnforcer,
     name: 'my-custom',
     type: AuthorizationEnforcerTypes.CUSTOM,
-    options: { /* your enforcer-specific options if needed */ },
+    options: { /* your enforcer-specific options, if any */ },
   }],
 });
 ```
 
 > [!NOTE]
-> Custom enforcers can inject their options via `@inject({ key: AuthorizeBindingKeys.enforcerOptions('my-custom') })` in the constructor, just like `CasbinAuthorizationEnforcer` does.
+> A custom enforcer can inject its own options via `@inject({ key: AuthorizeBindingKeys.enforcerOptions('my-custom') })` in the constructor, exactly like `CasbinAuthorizationEnforcer` does.
+
+## Custom filtered adapter
+
+Use the ready-made [`ScopedCasbinAdapter`](./api#scopedcasbinadapter) for most apps - it reads one edge table and needs no subclassing. Write a custom adapter only when your storage model differs.
 
-## Custom Filtered Adapter
+`BaseFilteredAdapter` provides:
 
-For most apps, use the ready-made [`ScopedCasbinAdapter`](./api#scopedcasbinadapter) - it reads a single
-edge table and needs no subclassing. Write a custom adapter only when your storage model differs.
+- Datasource/connector plumbing
+- `isFiltered()`
+- The no-op write methods
+- A `loadLines` helper
 
-`BaseFilteredAdapter` is now thin: it provides the datasource/connector plumbing, the `isFiltered()`
-flag, no-op write methods, and a `loadLines` helper. A subclass implements **only** `loadFilteredPolicy`
-- query your store for ONE principal's policies and turn them into casbin lines.
+A subclass implements only `loadFilteredPolicy`: query your store for ONE principal's policies and turn them into casbin lines.
 
 ```typescript
-import {
-  BaseFilteredAdapter,
-  ICasbinPolicyFilter,
-  type ICasbinPolicySource,
-} from '@venizia/ignis';
+import { BaseFilteredAdapter, ICasbinPolicyFilter, type ICasbinPolicySource } from '@venizia/ignis';
 import type { Model } from 'casbin';
 
-// Narrow the filter if you like, or use the default ICasbinPolicyFilter ({ principal: { type, id } }).
 class MyCustomAdapter extends BaseFilteredAdapter<ICasbinPolicyFilter> {
   constructor(opts: { dataSource: ICasbinPolicySource }) {
     super({ scope: MyCustomAdapter.name, dataSource: opts.dataSource });
@@ -611,9 +348,7 @@ class MyCustomAdapter extends BaseFilteredAdapter<ICasbinPolicyFilter> {
     const { type, id } = filter.principal;
 
     // 1. Query your store for THIS principal's policies (this.connector is provided by the base).
-    // 2. Build casbin lines as plain strings, e.g.:
-    //      `p, User_${id}, Order, read, allow`
-    //      `g, User_${id}, Role_42, *`
+    // 2. Build casbin lines as plain strings, e.g. `p, User_${id}, Order, read, allow` or `g, User_${id}, Role_42, *`.
     const lines: string[] = await this.buildLinesFor({ type, id });
 
     // 3. Load them into the model with the base helper.
@@ -621,58 +356,46 @@ class MyCustomAdapter extends BaseFilteredAdapter<ICasbinPolicyFilter> {
   }
 
   private async buildLinesFor(principal: { type: string; id: unknown }): Promise<string[]> {
-    // ...your queries via this.connector...
-    return [];
+    return []; // ...your queries via this.connector...
   }
 }
 ```
 
-The base no longer ships template-method hooks (`buildDirectPolicies`/`buildGroupPolicies`/…) or line
-formatters - you own line construction. See `ScopedCasbinAdapter` for a full reference implementation
-(role closure, structural trees, soft-delete, schema-qualified SQL).
+The base has no template-method query hooks or line formatters - a subclass owns its own queries and line construction. See `ScopedCasbinAdapter` for a full reference implementation (role closure, structural trees, soft-delete, schema-qualified SQL).
 
-## AuthorizationRole Comparison
+## AuthorizationRole comparison
 
-Use `AuthorizationRole` for priority-based role comparison:
+`AuthorizationRole` gives priority-based role comparison; identifiers are `{paddedPriority}{delimiter}{name}`.
 
 ```typescript
 import { AuthorizationRole, AuthorizationRoles } from '@venizia/ignis';
 
-// Built-in roles
 AuthorizationRoles.SUPER_ADMIN.identifier;  // '999_super-admin'
-AuthorizationRoles.ADMIN.identifier;         // '900_admin'
-AuthorizationRoles.USER.identifier;          // '010_user'
+AuthorizationRoles.ADMIN.identifier;        // '900_admin'
 
-// Comparison
-AuthorizationRoles.SUPER_ADMIN.isHigherThan({ target: AuthorizationRoles.ADMIN }); // true
-AuthorizationRoles.GUEST.isLowerThan({ target: AuthorizationRoles.USER });          // true
+AuthorizationRoles.SUPER_ADMIN.isHigherThan({ target: AuthorizationRoles.ADMIN }); // true (999 > 900)
+AuthorizationRoles.GUEST.isLowerThan({ target: AuthorizationRoles.USER });         // true (1 < 10)
 
-// Custom roles
 const moderator = AuthorizationRole.build({ name: 'moderator', priority: 500 });
-moderator.identifier;  // '500_moderator'
-moderator.isHigherThan({ target: AuthorizationRoles.USER });  // true (500 > 10)
-moderator.isLowerThan({ target: AuthorizationRoles.ADMIN });  // true (500 < 900)
+moderator.identifier; // '500_moderator'
 
-// Custom delimiter
 const customRole = AuthorizationRole.build({ name: 'editor', priority: 100, delimiter: '-' });
-customRole.identifier;  // '100-editor'
+customRole.identifier; // '100-editor'
 ```
 
 ## Model-Based Resource References
 
-Instead of hardcoding resource strings, use `AUTHORIZATION_SUBJECT` from your model classes. When a model declares `authorize.principal` in `@model` settings, the decorator auto-populates `AUTHORIZATION_SUBJECT`:
+Instead of hardcoding resource strings, declare `authorize.principal` on the model - `@model` auto-populates the static `AUTHORIZATION_SUBJECT` from it.
 
 ```typescript
-import { BaseEntity, model, generateIdColumnDefs } from '@venizia/ignis';
+import { BasePostgresEntity, model, generateIdColumnDefs } from '@venizia/ignis';
 import { pgTable, text } from 'drizzle-orm/pg-core';
 
 @model({
   type: 'entity',
-  settings: {
-    authorize: { principal: 'article' },
-  },
+  settings: { authorize: { principal: 'article' } },
 })
-export class Article extends BaseEntity<typeof Article.schema> {
+export class Article extends BasePostgresEntity<typeof Article.schema> {
   static override schema = pgTable('Article', {
     ...generateIdColumnDefs({ id: { dataType: 'string' } }),
     title: text('title').notNull(),
@@ -682,79 +405,60 @@ export class Article extends BaseEntity<typeof Article.schema> {
 // Article.AUTHORIZATION_SUBJECT === 'article'
 ```
 
-Use it in route configs for type-safe, refactor-friendly resource references:
-
 ```typescript
 import { AuthorizationActions } from '@venizia/ignis';
 import { Article } from '../models/entities/article.model';
 
-// Instead of: resource: 'article'
 authorize: {
   action: AuthorizationActions.READ,
-  resource: Article.AUTHORIZATION_SUBJECT,
+  resource: Article.AUTHORIZATION_SUBJECT, // instead of the string literal 'article'
 }
 ```
 
-### Querying All Principals
-
-Use `MetadataRegistry` to retrieve all registered authorization principals at runtime:
+**Query every declared principal at runtime** - for example, to seed Casbin policies.
 
 ```typescript
 import { MetadataRegistry } from '@venizia/ignis';
 
 const registry = MetadataRegistry.getInstance();
 
-// Flat array of principal names - ideal for Casbin policy setup
-const principals = registry.getAuthorizeModelPrincipals({ format: 'array' });
+registry.getAuthorizeModelPrincipals({ format: 'array' });
 // ['article', 'user', 'configuration']
 
-// Record of model name → principal
-const principalMap = registry.getAuthorizeModelPrincipals({ format: 'record' });
+registry.getAuthorizeModelPrincipals({ format: 'record' });
 // { Article: 'article', User: 'user', Configuration: 'configuration' }
 
-// Full settings with model registry entries (framework-level)
-const settings = registry.getAuthorizeModelSettings({ format: 'array' });
+registry.getAuthorizeModelSettings({ format: 'array' });
 // [{ name: 'Article', authorize: { principal: 'article' }, entry: IModelRegistryEntry }]
 ```
 
 > [!TIP]
-> Defining `authorize.principal` on the model makes the model the single source of truth for its authorization subject. This eliminates string duplication across route configs and policy setup.
+> Declaring `authorize.principal` on the model makes it the single source of truth for the authorization subject. Route configs and policy setup no longer duplicate the string. See the [Persistent Models guide](/guides/core-concepts/persistent/models#authorization-settings) for the full `@model` settings surface.
 
-## RBAC with Domains (Multi-Tenant)
+## RBAC with domains (multi-tenant)
 
-For multi-tenant apps where a user holds roles **scoped to specific tenants** (and sometimes globally), use Casbin's [RBAC with domains](https://casbin.apache.org/docs/rbac-with-domains/) model and register a **domain matching function** via `domainMatching`. This lets the domain slot of a grouping (`g`) policy use a wildcard, so a global role is a single line (`g, user, role, *`) and role permissions stay domain-agnostic (`p, role, *, …`).
+Some apps hand out roles **scoped to a specific tenant**. A user might be `owner` in Merchant A, only `viewer` in Merchant B, and hold a global role everywhere too. Casbin's [RBAC with domains](https://casbin.apache.org/docs/rbac-with-domains/) pattern keeps that policy **linear**: `memberships + permissions`, not a `permissions x tenants` cross-product. At 30 tenants and 700 permissions, that's roughly 730 lines instead of 21,000.
 
-> [!TIP]
-> Why this matters: putting the tenant on the membership (`g`) and keeping permissions wildcard (`p.dom = "*"`) keeps a user's materialized policy count **linear** (`memberships + permissions`) instead of the `permissions × tenants` cross-product. For a user with 30 tenants and 700 permissions that is ~730 lines instead of ~21,000.
-
-There are two ways to do domain scoping:
+You have two ways to get there:
 
-- **Scoped model (recommended)** - set `isScoped: true` + use `ScopedCasbinAdapter` + the built-in
-  `CASBIN_RBAC_DOMAIN_SCOPED_MODEL`, and supply the request domain **per route** via `spec.domain` (or a
-  global `domainResolver`). The enforcer registers the matchers for you; you do not write `domainMatching`
-  or `normalizePayloadFn`.
-- **Manual flat model (lower-level)** - keep a flat `g + p` model and register `domainMatching` +
-  `normalizePayloadFn` yourself. Documented below under [The model](#the-model).
+| Approach | Setup | Matchers |
+|---|---|---|
+| **Scoped model (recommended)** | `isScoped: true` + `ScopedCasbinAdapter` + `CASBIN_RBAC_DOMAIN_SCOPED_MODEL`. Supply the domain per route via `spec.domain`, or globally via `domainResolver`. | Registered for you |
+| **Manual flat model (lower-level)** | Keep a flat `g + p` model. See [The flat model](#the-flat-model). | Register `domainMatching` and `normalizePayloadFn` yourself |
 
 ### Scoped model + per-route domain (recommended)
 
-Register the scoped enforcer (see [Setup](./#step-3-register-enforcers-via-registry)) with `isScoped: true`,
-then tell each route where to read its domain from. `IAuthorizationSpec.domain` accepts either a
-**declarative source** or a **resolver function**:
+Register the enforcer with `isScoped: true` (see the [Overview](./#in-one-example)), then tell each route where to read its domain from. `IAuthorizationSpec.domain` accepts a **declarative source** or a **resolver function**.
 
 ```typescript
 import type { IAuthorizationDomainSource, TAuthorizationDomainResolver } from '@venizia/ignis';
 
 // (a) Declarative - read the domain id from a request param/header/query/context var:
 authorize({
-  spec: {
-    action: 'read',
-    resource: 'Order',
-    domain: { from: 'param', key: 'merchantId', type: 'Merchant' }, // → "Merchant_<param>"
-  },
+  spec: { action: 'read', resource: 'Order', domain: { from: 'param', key: 'merchantId', type: 'Merchant' } }, // -> "Merchant_<param>"
 });
 
-// (b) Resolver - compute { type, id } yourself (return null → SYSTEM_WIDE):
+// (b) Resolver - compute { type, id } yourself (return null -> SYSTEM_WIDE):
 authorize({
   spec: {
     action: 'read',
@@ -767,12 +471,11 @@ authorize({
 });
 ```
 
-Precedence (see `resolveRequestDomain`): `spec.domain` (resolver → declarative) → the global
-`IAuthorizeOptions.domainResolver` → `SYSTEM_WIDE`. The resolved value is stashed on
-`Authorization.DOMAIN` and passed to the enforcer as `request.domain`. A route with no domain at all
-enforces `SYSTEM_WIDE` (super-admin scope) in scoped mode.
+- **Precedence** (`resolveRequestDomain`): `spec.domain` (resolver, then declarative) -> the global `IAuthorizeOptions.domainResolver` -> `SYSTEM_WIDE`.
+- **Where it lands.** The resolved value is stashed on `Authorization.DOMAIN` and passed to the enforcer as `request.domain`.
+- **No domain = super-admin scope.** A route with no domain source at all enforces `SYSTEM_WIDE` in scoped mode.
 
-For a **global fallback** (apply the same resolver to every route that doesn't set `spec.domain`):
+**Global fallback** - apply the same resolver to every route that doesn't set `spec.domain`:
 
 ```typescript
 this.bind<IAuthorizeOptions>({ key: AuthorizeBindingKeys.OPTIONS }).toValue({
@@ -784,7 +487,7 @@ this.bind<IAuthorizeOptions>({ key: AuthorizeBindingKeys.OPTIONS }).toValue({
 });
 ```
 
-### The model
+### The flat model
 
 ```ini
 [request_definition]
@@ -804,93 +507,81 @@ m = g(r.sub, p.sub, r.dom) && keyMatch(r.dom, p.dom) && r.obj == p.obj && r.act
 ```
 
 - `g = _, _, _` - the membership relation is **domain-aware** (subject, role, domain).
-- `g(r.sub, p.sub, r.dom)` - the registered domain matching function decides whether the request domain matches the stored membership domain (this is what makes `*` a wildcard).
-- `keyMatch(r.dom, p.dom)` - `keyMatch` is a **built-in matcher function** (no registration needed); it lets a permission with `p.dom = "*"` match any request domain.
-
-### Registering the domain matching function
+- `g(r.sub, p.sub, r.dom)` - the registered domain matching function decides whether the request domain matches the stored membership domain. This is what makes `*` a wildcard.
+- `keyMatch(r.dom, p.dom)` - a **built-in** matcher (no registration needed) that lets a permission with `p.dom = "*"` match any request domain.
 
-Pass `domainMatching` in the enforcer options. It is registered once during `configure()`:
+**Register the domain matching function.** Pass `domainMatching` in the enforcer options - it registers once during `configure()`.
 
 ```typescript
 import {
-  AuthorizationEnforcerRegistry,
-  AuthorizationEnforcerTypes,
-  CasbinAuthorizationEnforcer,
-  CasbinDomainMatchingFunctions,
-  CasbinEnforcerModelDrivers,
-  type ICasbinEnforcerOptions,
+  AuthorizationEnforcerRegistry, AuthorizationEnforcerTypes, CasbinAuthorizationEnforcer,
+  CasbinDomainMatchingFunctions, CasbinEnforcerModelDrivers, type ICasbinEnforcerOptions,
 } from '@venizia/ignis';
 
 AuthorizationEnforcerRegistry.getInstance().register({
   container: this,
-  enforcers: [
-    {
-      enforcer: CasbinAuthorizationEnforcer,
-      name: 'casbin',
-      type: AuthorizationEnforcerTypes.CASBIN,
-      options: {
-        model: { driver: CasbinEnforcerModelDrivers.TEXT, definition: CASBIN_RBAC_DOMAIN_SCOPED_MODEL },
-        adapter,
-        cached,
-        // For a domain model, normalizePayloadFn MUST always return a `domain`.
-        normalizePayloadFn: ({ user, action, resource, context }) => ({
-          subject: `User_${user.userId}`,
-          domain: `Merchant_${resolveActiveMerchant({ context })}`,
-          resource,
-          action,
-        }),
-        // Register keyMatch on the `g` role definition so wildcard domains work:
-        domainMatching: { roleDefinition: 'g', fn: CasbinDomainMatchingFunctions.KEY_MATCH },
-      } satisfies ICasbinEnforcerOptions,
-    },
-  ],
+  enforcers: [{
+    enforcer: CasbinAuthorizationEnforcer,
+    name: 'casbin',
+    type: AuthorizationEnforcerTypes.CASBIN,
+    options: {
+      model: { driver: CasbinEnforcerModelDrivers.TEXT, definition: theFlatModelConfAbove }, // your own .conf text - not a framework export
+      adapter,
+      cached,
+      // For a domain model, normalizePayloadFn MUST always return a `domain`.
+      normalizePayloadFn: ({ user, action, resource, context }) => ({
+        subject: `User_${user.userId}`,
+        domain: `Merchant_${resolveActiveMerchant({ context })}`,
+        resource,
+        action,
+      }),
+      domainMatching: { roleDefinition: 'g', fn: CasbinDomainMatchingFunctions.KEY_MATCH },
+    } satisfies ICasbinEnforcerOptions,
+  }],
 });
 ```
 
 > [!NOTE]
-> `domainMatching` is opt-in. When omitted, domains are compared as exact strings and behavior is unchanged. The enforcer calls Casbin's `addNamedDomainMatchingFunc(roleDefinition, Util.keyMatchFunc)` internally - you never call it directly.
+> `domainMatching` is opt-in. When omitted, domains are compared as exact strings and behavior is unchanged. The enforcer calls Casbin's `addNamedDomainMatchingFunc(roleDefinition, Util.keyMatchFunc)` internally - never call it directly.
 
-### Choosing the matching function
+**Choosing the matching function.** `keyMatch` is the safe default for opaque domain identifiers like `Merchant_<uuid>`. It treats only `*` as special and never splits on `/` or `:`, so it cannot accidentally match one tenant against another. Use the others only for structured path-style domains.
 
-`keyMatch` is the safe default for opaque domain identifiers like `Merchant_<uuid>`: it treats only `*` as special and never splits on `/` or `:`, so it cannot accidentally match one tenant against another. Use the others only if your domains are structured paths.
+| Function | Adds |
+|---|---|
+| `CasbinDomainMatchingFunctions.KEY_MATCH` | Nothing beyond `*` (recommended default) |
+| `CasbinDomainMatchingFunctions.KEY_MATCH_2` | URL-path `:param` segments |
+| `CasbinDomainMatchingFunctions.KEY_MATCH_3` | `{param}` segments |
+| `CasbinDomainMatchingFunctions.KEY_MATCH_4` | `{param}` segments with repeated-name equality checks |
+| `CasbinDomainMatchingFunctions.REGEX_MATCH` | Full regular-expression matching on the stored value |
 
-```typescript
-domainMatching: { roleDefinition: 'g', fn: CasbinDomainMatchingFunctions.KEY_MATCH };   // * wildcard (recommended)
-domainMatching: { roleDefinition: 'g', fn: CasbinDomainMatchingFunctions.KEY_MATCH_2 };  // /tenants/:id
-domainMatching: { roleDefinition: 'g', fn: CasbinDomainMatchingFunctions.KEY_MATCH_3 };  // /tenants/{id}
-domainMatching: { roleDefinition: 'g', fn: CasbinDomainMatchingFunctions.REGEX_MATCH };  // ^Merchant_.*$
-```
-
-### All cases - policy lines and outcomes
-
-Given the model above with `keyMatch` registered on `g`, the request is `enforceSync(subject, domain, resource, action)`:
+**Policy lines and outcomes**, using the flat model above with `keyMatch` registered on `g`. Each row calls `enforceSync(subject, domain, resource, action)`:
 
 | Case | Policy lines | Request | Outcome |
 |------|--------------|---------|---------|
-| **Scoped role** (owner/employee in a tenant) | `g, User_u, Role_owner, Merchant_A`<br/>`p, Role_owner, *, Material.find, read, allow` | `(User_u, Merchant_A, Material.find, read)` | ✅ allow |
-| **Scoped role - isolation** | (same as above) | `(User_u, Merchant_B, Material.find, read)` | ❌ deny (`g` domain doesn't match) |
-| **Multi-tenant role** | `g, User_u, Role_owner, Merchant_A`<br/>`g, User_u, Role_owner, Merchant_B`<br/>`p, Role_owner, *, Material.find, read, allow` | `(User_u, Merchant_B, Material.find, read)` | ✅ allow (one `g` line per owned tenant; **single** `p` line) |
-| **Global role** (e.g. guest/onboarding) | `g, User_u, Role_guest, *`<br/>`p, Role_guest, *, Organizer.onBoarding, create, allow` | `(User_u, Merchant_anything, Organizer.onBoarding, create)` | ✅ allow (wildcard `g` domain) |
-| **Direct user permission (scoped)** | `p, User_u, Merchant_A, Report.read, read, allow` | `(User_u, Merchant_A, Report.read, read)` | ✅ allow (reflexive `g(u,u,dom)` + `keyMatch`) |
-| **Direct user permission - isolation** | (same as above) | `(User_u, Merchant_B, Report.read, read)` | ❌ deny |
-| **Deny override** | `p, Role_x, *, Secret.read, read, deny`<br/>`p, Role_y, *, Secret.read, read, allow` | any domain where the user has both roles | ❌ deny (`!some(p.eft == deny)`) |
+| Scoped role (owner in a tenant) | `g, User_u, Role_owner, Merchant_A`<br/>`p, Role_owner, *, Material.find, read, allow` | `(User_u, Merchant_A, Material.find, read)` | allow |
+| Scoped role - isolation | (same as above) | `(User_u, Merchant_B, Material.find, read)` | deny (`g` domain doesn't match) |
+| Multi-tenant role | `g, User_u, Role_owner, Merchant_A`<br/>`g, User_u, Role_owner, Merchant_B`<br/>`p, Role_owner, *, Material.find, read, allow` | `(User_u, Merchant_B, Material.find, read)` | allow (one `g` line per tenant; a single `p` line) |
+| Global role (for example, guest/onboarding) | `g, User_u, Role_guest, *`<br/>`p, Role_guest, *, Organizer.onBoarding, create, allow` | `(User_u, Merchant_anything, Organizer.onBoarding, create)` | allow (wildcard `g` domain) |
+| Direct user permission (scoped) | `p, User_u, Merchant_A, Report.read, read, allow` | `(User_u, Merchant_A, Report.read, read)` | allow (reflexive `g(u,u,dom)` + `keyMatch`) |
+| Direct user permission - isolation | (same as above) | `(User_u, Merchant_B, Report.read, read)` | deny |
+| Deny override | `p, Role_x, *, Secret.read, read, deny`<br/>`p, Role_y, *, Secret.read, read, allow` | any domain where the user has both roles | deny (`!some(p.eft == deny)`) |
 
 > [!IMPORTANT]
-> The function is applied as `fn(requestDomain, policyDomain)` - the wildcard belongs on the **stored** side. Store only `*` or exact domain values (never `Merchant_*`) to keep isolation guaranteed.
-
-### Misconfiguration is caught early
+> The matching function is applied as `fn(requestDomain, policyDomain)` - the wildcard belongs on the **stored** side. Store only `*` or exact domain values (never `Merchant_*`) to keep tenant isolation guaranteed.
 
-If `roleDefinition` is not declared under `[role_definition]` in the model, `configure()` throws - Casbin would otherwise register the function as a silent no-op, leaving wildcard domains permanently unmatched (global roles silently denied):
+**Misconfiguration is caught early.** If `roleDefinition` is not declared under `[role_definition]` in the model, `configure()` throws at boot. Without that check, Casbin would silently register the function as a no-op, leaving wildcard domains permanently unmatched - global roles would be silently denied.
 
 ```typescript
 // model declares `g` only
 domainMatching: { roleDefinition: 'g2', fn: CasbinDomainMatchingFunctions.KEY_MATCH };
-// => throws: Role definition "g2" is not declared in the Casbin model. Declare it under
-//    [role_definition] (e.g. `g = _, _, _`) before enabling domainMatching.
+// throws: Role definition "g2" is not declared in the Casbin model. Declare it under
+// [role_definition] (e.g. `g = _, _, _`) before enabling domainMatching.
 ```
 
-## See Also
+## See also
 
-- [Setup & Configuration](./) -- Binding keys, options interfaces, and initial setup
-- [API Reference](./api) -- Architecture, enforcer internals, provider, registry, and adapters
-- [Error Reference](./errors) -- Error messages and troubleshooting
+- [Setup & Configuration](./) - binding keys, options interfaces, and initial setup
+- [API Reference](./api) - architecture, enforcer internals, provider, registry, and adapters
+- [Error Reference](./errors) - error messages and troubleshooting
+- [Persistent Models](/guides/core-concepts/persistent/models#authorization-settings) - `@model` authorization settings
+- [gRPC Controllers](/guides/core-concepts/grpc-controllers) - full gRPC decorator/route surface