@venizia/ignis-docs 0.2.1-0 → 0.2.1-1

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

@@ -1,7 +1,19 @@
-# Authorization -- Error Reference
+# Authorization - Error Reference
 
 > Complete error messages and troubleshooting for the authorization module. See [Setup & Configuration](./) for initial setup.
 
+## Find what you need
+
+| You want to | Go to |
+|---|---|
+| See every error message, status code, and cause in one table | [Complete Error Reference](#complete-error-reference) |
+| See which pipeline step throws which error | [Error Flow Diagram](#error-flow-diagram) |
+| Fix a specific error message you're staring at | [Troubleshooting](#troubleshooting) |
+| Debug "authorization does nothing" during rollout | [Authorization is not running](#authorization-is-not-running) |
+| Debug rules rebuilding when you expected a cache hit | [Rules are rebuilt on every request](#rules-are-rebuilt-on-every-request) |
+| Debug policies that don't seem to load | [Casbin policies not loading](#casbin-policies-not-loading) |
+| Debug a Redis cache that never hits | [Redis cache not working](#redis-cache-not-working) |
+
 ## Error Flow Diagram
 
 ```mermaid
@@ -16,7 +28,8 @@ flowchart TD
     S4 -->|DENY| E403a[/"403: Authorization denied by voter"/]
     S4 -->|ALLOW/ABSTAIN| S5{"Step 5: Enforcers registered?"}
 
-    S5 -->|No enforcers| OK3([No error - skip])
+    S5 -->|No enforcers, defaultDecision: allow| OK3([No error - allow, warning logged])
+    S5 -->|No enforcers, defaultDecision: deny or unset| E403c[/"403: no enforcer registered"/]
     S5 -->|Yes| S5b{"Resolve enforcer"}
     S5b -->|Name not found| E400b[/"400: Descriptor not found"/]
     S5b -->|DI fails| E400c[/"400: Failed to resolve"/]
@@ -35,6 +48,7 @@ flowchart TD
     style E401 fill:#f8d7da,stroke:#dc3545
     style E403a fill:#f8d7da,stroke:#dc3545
     style E403b fill:#f8d7da,stroke:#dc3545
+    style E403c fill:#f8d7da,stroke:#dc3545
     style E400b fill:#fff3cd,stroke:#ffc107
     style E400c fill:#fff3cd,stroke:#ffc107
     style E400d fill:#fff3cd,stroke:#ffc107
@@ -46,7 +60,7 @@ flowchart TD
 
 ## Complete Error Reference
 
-All error messages from the authorization module, organized by source. **Status** is what `error.statusCode` holds - most calls use `getError({ message })` with no explicit `statusCode`, which the shared `ApplicationError` defaults to **400**. Only the request-pipeline errors below (steps 2, 4, 7) set an explicit `401`/`403`.
+All error messages from the authorization module, organized by source. **Status** is what `error.statusCode` holds. Most calls use `getError({ message })` with no explicit `statusCode`, so the shared `ApplicationError` defaults it to **400**. Only the request-pipeline errors below (steps 2, 4, 7) set an explicit `401`/`403`.
 
 ### Component Errors (`AuthorizeComponent`)
 
@@ -69,7 +83,7 @@ Thrown during `binding()`, at application startup.
 | <code v-pre>[AuthorizationEnforcerRegistry] Enforcer "{{name}}" does not support cache invalidation</code> | 400 | `invalidateUserCache` / `rebuildUserCache` | The resolved enforcer doesn't implement the optional cache-management methods |
 
 > [!NOTE]
-> `[AuthorizationEnforcerRegistry] No items registered` can only surface if `getDefaultEnforcerName()` is called directly. During normal middleware execution, the provider checks `registry.hasEnforcers()` first and skips authorization when no enforcers exist - it never reaches this throw.
+> `[AuthorizationEnforcerRegistry] No items registered` can only surface if `getDefaultEnforcerName()` is called directly. During normal middleware execution, the provider checks `registry.hasEnforcers()` first and denies (or, with `defaultDecision: 'allow'`, proceeds) before ever calling `getDefaultEnforcerName()`, so it never reaches this throw.
 
 ### Authorization Provider Errors (`AuthorizationProvider` - the request pipeline)
 
@@ -79,6 +93,7 @@ The only errors in the module with an **explicit** `statusCode`.
 |---------------|--------|------|-------|
 | `Authorization failed: No authenticated user found` | 401 | 2 - User check | `Authentication.CURRENT_USER` is missing from the Hono context |
 | <code v-pre>Authorization denied by voter &#124; action: {{action}} &#124; resource: {{resource}}</code> | 403 | 4 - Voters | A voter function returned `AuthorizationDecisions.DENY` |
+| <code v-pre>Authorization failed: authorize() was declared for this route but no enforcer is registered &#124; path: {{path}}</code> | 403 | 5 - Resolve enforcer | `hasEnforcers()` is `false` and `defaultDecision` is `'deny'` (the default) or unset |
 | `Authorization failed: user.principalType is required for enforcer-based authorization` | 400 | 6 - Build rules | The authenticated user object has no `principalType` field |
 | <code v-pre>Authorization denied &#124; action: {{action}} &#124; resource: {{resource}}</code> | 403 | 7 - Evaluate | The enforcer returned `DENY`, or `ABSTAIN` and `defaultDecision` resolved to `'deny'` |
 
@@ -95,7 +110,7 @@ The only errors in the module with an **explicit** `statusCode`.
 | <code v-pre>[resolveModel] Invalid model.driver &#124; Valids: [file, text]</code> | 400 | `configure` (via `resolveModel`) | `model.driver` isn't `'file'` or `'text'` |
 
 > [!NOTE]
-> There is no `Invalid cached.driver` runtime error - `cached` is a typed discriminated union (`{ use: false } | { use: true; driver: 'redis'; ... }`), so an unsupported cache driver is a compile-time error. Caching is **Redis-only**.
+> `cached` is a typed discriminated union (`{ use: false } | { use: true; driver: 'redis'; ... }`), so an unsupported cache driver fails at compile time - there is no `Invalid cached.driver` runtime error. Caching is **Redis-only**.
 
 ### Casbin Enforcer Errors - Runtime (`buildRules` / `evaluate` / cache management)
 
@@ -108,7 +123,7 @@ The only errors in the module with an **explicit** `statusCode`.
 | `[extractUserLines] Adapter does not support loadFilteredPolicy.` | 400 | `buildRules` (via `extractUserLines`) | `options.adapter` doesn't implement casbin's `FilteredAdapter.loadFilteredPolicy` |
 | `[loadPolicyLinesIntoModel] Not configured. Call configure() first.` | 400 | `evaluate` (via `loadPolicyLinesIntoModel`) | Same root cause as the `evaluate` "Not configured" row, different call site |
 
-**Not an error** - `[CasbinAuthorizationEnforcer] Cached payload is not an array of policy lines.` is logged at `warn` level by `parseCachedPolicyLines` and never thrown up to the caller: a corrupted or legacy Redis entry is discarded and the lines are refetched from the adapter, so the request never 500s (or 400s) on cache corruption.
+**Not an error** - `[CasbinAuthorizationEnforcer] Cached payload is not an array of policy lines.` `parseCachedPolicyLines` logs this at `warn` level; it never throws up to the caller. A corrupted or legacy Redis entry is discarded, and the lines are refetched from the adapter. The request never 500s (or 400s) on cache corruption.
 
 ## Troubleshooting
 
@@ -129,7 +144,11 @@ this.component(AuthorizeComponent);
 
 ### "Authorization failed: No authenticated user found"
 
-**Cause:** The authorization middleware runs after authentication, but no user was found on the context (`Authentication.CURRENT_USER` is `undefined`). Common triggers: the route has `authorize` but no `authenticate`, authentication was skipped but authorization wasn't, or the request genuinely has no valid credentials.
+**Cause:** The authorization middleware runs after authentication, but no user was found on the context (`Authentication.CURRENT_USER` is `undefined`). Common triggers:
+
+- The route has `authorize` but no `authenticate`.
+- Authentication was skipped, but authorization wasn't.
+- The request genuinely has no valid credentials.
 
 **Fix:** Every route with `authorize` needs a matching `authenticate` config.
 
@@ -148,7 +167,7 @@ this.defineRoute({
 
 ### "Authorization failed: user.principalType is required"
 
-**Cause:** The authenticated user object has no `principalType` field. Enforcer-based authorization uses it to build the casbin subject (e.g. `User_123`).
+**Cause:** The authenticated user object has no `principalType` field. Enforcer-based authorization uses it to build the casbin subject - for example, `User_123`.
 
 **Fix:** Set `principalType` when you build the user in your authentication service or token payload.
 
@@ -167,16 +186,24 @@ return {
 
 **Cause:** A voter function explicitly returned `AuthorizationDecisions.DENY`.
 
-**Fix:** Inspect the voter named in your logs. Common causes: ownership check failed, a time-window check rejected the request, or a resource-state check (locked/archived) blocked it.
+**Fix:** Inspect the voter named in your logs. Common causes:
+
+- An ownership check failed.
+- A time-window check rejected the request.
+- A resource-state check (locked/archived) blocked it.
 
 ### "Authorization denied | action: ... | resource: ..."
 
-**Cause:** `enforcer.evaluate()` returned `DENY`, or `ABSTAIN` and it fell back to `defaultDecision`. Usually: no matching policy for the user, a matching `deny` policy, or the model doesn't cover the requested domain/resource/action combination.
+**Cause:** `enforcer.evaluate()` returned `DENY`, or `ABSTAIN` and it fell back to `defaultDecision`. Usually one of:
+
+- No matching policy for the user.
+- A matching `deny` policy.
+- The model doesn't cover the requested domain/resource/action combination.
 
 **Fix:** Work through this checklist:
 
 1. **Policies are loaded correctly** - verify the adapter returns the right rows for this user (`ScopedCasbinAdapter` reads `PolicyDefinition` filtered by `subject_type`/`subject_id`).
-2. **Subject format matches.** `normalizePayloadFn` (or the default scoped payload) must produce a subject that matches what's stored, e.g. `User_123`.
+2. **Subject format matches.** `normalizePayloadFn` (or the default scoped payload) must produce a subject that matches what's stored - for example, `User_123`.
 3. **The model covers the request.** For a custom (non-scoped) `.conf`, confirm the matcher handles the action/resource/domain shape you're sending.
 4. **Set `defaultDecision` explicitly** - don't rely on an implicit fallback:
 
@@ -247,7 +274,7 @@ options: {
 
 ### "[registerMatchers] Role definition "g2" is not declared in the Casbin model..."
 
-**Cause:** `domainMatching.roleDefinition` references a relation the model doesn't declare under `[role_definition]`. Casbin would otherwise register the function as a silent no-op, leaving wildcard domains permanently unmatched (global roles silently denied) - the enforcer throws at boot instead.
+**Cause:** `domainMatching.roleDefinition` references a relation the model doesn't declare under `[role_definition]`. Without this check, Casbin would register the function as a silent no-op, leaving wildcard domains permanently unmatched - global roles would be silently denied. The enforcer throws at boot instead.
 
 **Fix:** Point `roleDefinition` at a relation the model actually declares.
 
@@ -257,9 +284,16 @@ domainMatching: { roleDefinition: 'g', fn: CasbinDomainMatchingFunctions.KEY_MAT
 
 ### "[CasbinAuthorizationEnforcer] Matcher smoke test failed at warmup..."
 
-**Cause:** `assertMatcherCompilesSync()` runs a dummy `enforceSync()` at warmup to force casbin's lazy matcher compile. It failed - a matcher syntax error, a function referenced in the matcher that was never registered, or a request-arity mismatch (3 vs. 4 tokens).
+**Cause:** `assertMatcherCompilesSync()` runs a dummy `enforceSync()` at warmup to force casbin's lazy matcher compile. It failed for one of these reasons:
+
+- A matcher syntax error.
+- A function referenced in the matcher that was never registered.
+- A request-arity mismatch (3 vs. 4 tokens).
+
+**Fix:** Check the `[matchers]` section of your `.conf`.
 
-**Fix:** Check the `[matchers]` section of your `.conf`. If scoped, confirm `isScoped: true` is set (registers `objectMatch` + `keyMatch` automatically); if using a custom flat model, confirm every function the matcher calls is registered via `domainMatching`.
+- Scoped model: confirm `isScoped: true` is set. It registers `objectMatch` and `keyMatch` automatically.
+- Custom flat model: confirm every function the matcher calls is registered via `domainMatching`.
 
 ### "[CasbinAuthorizationEnforcer] cached.options.expiresIn must be >= 10000"
 
@@ -281,7 +315,7 @@ cached: {
 
 ### "[CasbinAuthorizationEnforcer] Not configured. Call configure() first."
 
-**Cause:** `evaluate()` (or its internal `loadPolicyLinesIntoModel()`) ran before `configure()` built the enforcer pool. This shouldn't happen through `resolveEnforcer()` (which auto-configures), but can occur if the enforcer is resolved manually from the DI container.
+**Cause:** `evaluate()` (or its internal `loadPolicyLinesIntoModel()`) ran before `configure()` built the enforcer pool. This shouldn't happen through `resolveEnforcer()`, which auto-configures. It can occur if the enforcer is resolved manually from the DI container.
 
 **Fix:** Always go through the registry, which handles configure-once automatically.
 
@@ -332,7 +366,7 @@ Check, in order:
 1. `authorize` is actually set on the route config (not just `authenticate`).
 2. `authenticate` isn't `{ skip: true }` - that skips authorization too, in both raw route configs and the CRUD factory.
 3. The component is registered AND at least one enforcer is registered via `AuthorizationEnforcerRegistry`.
-4. If no enforcers are registered, the middleware skips authorization silently (`next()`) rather than throwing - this is often the real cause of "authorization does nothing" during rollout.
+4. If no enforcers are registered, the middleware denies with a 403 naming the missing enforcer - unless `defaultDecision: 'allow'` is set, in which case it proceeds and logs a warning. A warning in your logs on every request is often the real sign of "no enforcer registered" during rollout.
 
 ### Rules are rebuilt on every request
 
@@ -354,7 +388,7 @@ Rules cache on `Authorization.RULES`, but only **within one request**:
 1. **Connection** - verify the `IRedisHelper` (`RedisSingleHelper`/`RedisClusterHelper`/`RedisSentinelHelper`) is actually connected.
 2. **`keyFn`** - must return a unique, non-empty key per user.
 3. **`expiresIn`** - must be `>= 10_000` (`MIN_EXPIRES_IN`).
-4. **Corruption is silent** - a malformed cached payload is discarded and refetched (see the Casbin runtime error table above), so a "cache never seems to hit" symptom is more likely a `keyFn` mismatch than corruption.
+4. **Corruption is silent.** A malformed cached payload is discarded and refetched (see the Casbin runtime error table above). If caching never seems to hit, suspect a `keyFn` mismatch before corruption.
 
 ## See Also
 

package/content/extensions/components/authorization/getting-started.md

@@ -0,0 +1,227 @@
+---
+title: Authorization Getting Started
+description: The mental model behind IGNIS authorization, then one grant seeded and enforced end to end
+difficulty: beginner
+---
+
+# Authorization Getting Started
+
+Every authorization question IGNIS answers - can this user do that, here - comes down to one thing: can you reach an `allow` edge by walking a graph from the user. This page builds that picture first, then seeds one real grant and watches one route go from 401 to 403 to 200.
+
+## The graph, not the rule table
+
+Forget rules for a moment. IGNIS authorization state is one graph. The nodes are four kinds of thing: `User`, `Role`, `Permission`, `Domain`. Every row in the single `PolicyDefinition` table is one edge between two nodes, and its `variant` column names what kind of edge it is - a role assignment, a domain membership, a permission grant, or one of three "inherits" edges that let one node stand in for a family of others.
+
+A request is a tuple: who is asking (`subject`), where (`domain`), on what (`resource`), to do what (`action`). Casbin decides a request by walking the graph along all four of those axes at once. If it can reach an `allow` edge on every axis, and no `deny` edge also matches, the request passes. Nothing is precomputed - the walk runs fresh on every request, over the edges that user actually holds.
+
+So what do `g`, `g2`, `g3`, `g4`, `g5` mean? Each one names the walk along one axis of that tuple - not a separate language to memorize.
+
+| Relation | Axis | What it walks |
+|---|---|---|
+| `g` | subject | User holds Role, Role inherits Role |
+| `g2` | domain (membership) | User belongs to Domain |
+| `g3` | domain (nesting) | Domain contains Domain |
+| `g4` | resource | Resource covers Resource |
+| `g5` | action | Action covers Action |
+
+`p` is not a walk - it is the edge you are trying to reach. A `p` line is a grant: an action, an effect (`allow` or `deny`), and a domain, attached to a User or a Role.
+
+That is the whole model. The rest of this page makes it concrete: real tables, one real grant, one real request.
+
+## Before you touch authorization
+
+Authorization runs after authentication and only ever reads what authentication already put on the request. It needs two things from your authenticated user: `principalType` (which node type the user is - almost always `'user'`) and a `userId`. Neither is a dedicated field on `IAuthUser`; both are plain properties your authentication layer adds to the token payload.
+
+Read the [Authentication component's entity column helpers](../authentication/usage#entity-column-helpers) before continuing. They define the `User`, `Role`, `Permission`, and `PolicyDefinition` columns this page builds on, and skipping them is the single most common reason authorization "does nothing": without `user.principalType`, the enforcer throws a 400 one step before it would even reach a 403.
+
+## The three tables
+
+Authorization reads three tables directly: `Role`, `Permission`, and `PolicyDefinition`. It never reads `User` - a request only ever carries `principalType` and `userId`, not a database row.
+
+**`Role`**, via `extraRoleColumns()`:
+
+| Column | Type | Meaning |
+|---|---|---|
+| `identifier` | text, unique | The casbin role name, for example `900_admin` |
+| `name` | text | Human-readable label |
+| `priority` | integer | Higher outranks lower; backs `AuthorizationRole` comparisons |
+| `status` | text | Role lifecycle, defaults to `RoleStatuses.ACTIVATED` |
+| `description` | text, nullable | Optional |
+
+**`Permission`**, via `extraPermissionColumns()`:
+
+| Column | Type | Meaning |
+|---|---|---|
+| `code` | text, unique | The resource string a route's `authorize.resource` matches, for example `configuration` |
+| `subject` | text | Groups permissions by resource family, for example `Order` |
+| `method` | text | For example `GET`; used by subset grants |
+| `action` | text | For example `read` |
+| `scope` | text | For example `global` |
+| `parentId` | text or integer | Optional resource nesting |
+
+**`PolicyDefinition`**, via `extraPolicyDefinitionColumns({ idType: 'string' })` - the edge table:
+
+| Column | Type | Meaning |
+|---|---|---|
+| `variant` | text | Which of the seven edge kinds this row is |
+| `subjectType`, `subjectId` | text | The edge's source node, for example `user` + a user id |
+| `targetType`, `targetId` | text | The edge's destination node |
+| `action` | text, nullable | Set only on `grant` rows |
+| `effect` | text, nullable | `allow` or `deny`, set only on `grant` rows |
+| `domain` | text, nullable | The casbin domain token - see the note below |
+| `metadata` | jsonb, nullable | Only subset ("custom") grants use it |
+
+`variant` must be one of exactly seven values, owned by `AuthorizationPolicyVariants`: `grant`, `assign_role`, `role_inherits`, `join_domain`, `domain_inherits`, `resource_inherits`, `action_inherits`. Nothing validates this column on read. A typo or a wrong value does not error - the row just never matches any query, and the grant it was meant to carry silently does not exist.
+
+`domain` has the same trap. It stores a full casbin token, `<Type>_<id>` - for example `Organization_3fa85f64-5717-4562-b3fc-2c963f66afa6` - never a bare id. Get `variant` right and `domain` wrong, and every domain-scoped check for that row still fails. The next section shows the one way to avoid both mistakes at once.
+
+## Register the component
+
+This assumes a Postgres datasource is already registered - see [DataSources](/guides/core-concepts/persistent/datasources) if it is not yet. Adjust the import path and binding key to your own datasource class name.
+
+```typescript
+import {
+  AuthorizeBindingKeys, AuthorizeComponent, AuthorizationDecisions, AuthorizationEnforcerRegistry,
+  AuthorizationEnforcerTypes, CasbinAuthorizationEnforcer, CasbinEnforcerModelDrivers,
+  ScopedCasbinAdapter, CASBIN_RBAC_DOMAIN_SCOPED_MODEL, BaseApplication, IAuthorizeOptions,
+} from '@venizia/ignis';
+import { PostgresDataSource } from './datasources/postgres.datasource';
+import { Organization, Permission, PolicyDefinition, Role } from './models/entities';
+
+export class Application extends BaseApplication {
+  preConfigure() {
+    const dataSource = this.get<PostgresDataSource>({ key: 'datasources.PostgresDataSource' });
+
+    this.bind<IAuthorizeOptions>({ key: AuthorizeBindingKeys.OPTIONS }).toValue({
+      defaultDecision: AuthorizationDecisions.DENY,
+      alwaysAllowRoles: ['999_super-admin'],
+    });
+
+    this.component(AuthorizeComponent);
+
+    const adapter = new ScopedCasbinAdapter({
+      dataSource,
+      entities: {
+        policyDefinition: { tableName: PolicyDefinition.name },
+        permission: { tableName: Permission.name },
+        principals: { user: 'user', role: Role.name },
+        domainTypes: [Organization.name],
+      },
+    });
+
+    AuthorizationEnforcerRegistry.getInstance().register({
+      container: this,
+      enforcers: [{
+        enforcer: CasbinAuthorizationEnforcer,
+        name: 'casbin',
+        type: AuthorizationEnforcerTypes.CASBIN,
+        options: {
+          model: { driver: CasbinEnforcerModelDrivers.TEXT, definition: CASBIN_RBAC_DOMAIN_SCOPED_MODEL },
+          isScoped: true,
+          adapter,
+          cached: { use: false },
+        },
+      }],
+    });
+  }
+}
+```
+
+`entities.principals.user` must equal the exact `principalType` string your authentication layer puts on the token - `'user'` here. `entities.principals.role` must equal your `Role` entity's `.name`; it builds the casbin prefix for role-scoped lines (`Role_<id>`). `cached.use: false` re-reads policy rows on every request - fine while you are getting this working. The [RBAC with domains guide](./usage#rbac-with-domains-multi-tenant) covers adding a Redis cache once it matters.
+
+## Seed exactly one grant
+
+Build every `PolicyDefinition` row through `AuthorizationPolicyBuilder`. Never write `variant` or `domain` by hand - the builder cannot produce a wrong `variant`, and its `serializeDomain` step is what turns a typed `{ type, id }` domain into the `<Type>_<id>` token from the section above.
+
+A grant needs three things to already exist: the user (from sign-up), one `Organization` row (the tenant), and one `Permission` row - say `code: 'configuration'`, `action: 'read'`. Seed those however you already seed reference data. Then seed the grant itself:
+
+```typescript
+import { randomUUID } from 'crypto';
+import { Pool } from 'pg';
+import { AuthorizationActions, AuthorizationDecisions, AuthorizationPolicyBuilder } from '@venizia/ignis';
+
+const pool = new Pool({ /* your connection */ });
+
+const grant = AuthorizationPolicyBuilder.grant({
+  subject: { type: 'user', id: userId },
+  permission: { type: 'Permission', id: permissionId },
+  action: AuthorizationActions.READ,
+  effect: AuthorizationDecisions.ALLOW,
+  domain: { type: 'Organization', id: organizationId },
+});
+
+await pool.query(
+  `INSERT INTO "PolicyDefinition"
+     (id, variant, subject_type, subject_id, target_type, target_id, action, effect, domain)
+   VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`,
+  [randomUUID(), grant.variant, grant.subjectType, grant.subjectId, grant.targetType, grant.targetId, grant.action, grant.effect, grant.domain],
+);
+```
+
+That one row is enough - no role, no role assignment. The scoped model's role, domain, resource, and action axes all fall back to a self-link when a request matches a stored value exactly, so a grant made directly to the user's own `subject` clears every axis on its own. `grant.domain` now reads `Organization_<organizationId>`, never the bare id.
+
+`examples/vert/scripts/seed-user-policies.ts` runs this same builder call for seven personas at once, some with a role assignment added and some without - read it once you need more than one grant.
+
+## Protect one route
+
+```typescript
+// Inside a controller's binding()
+const READ_CONFIGURATIONS_CONFIG = {
+  path: '/authz-example/configurations',
+  method: 'get',
+  authenticate: { strategies: [Authentication.STRATEGY_JWT] },
+  authorize: {
+    action: AuthorizationActions.READ,
+    resource: 'configuration',
+    domain: { from: 'header', key: 'x-organization-id', type: 'Organization' },
+  },
+  responses: jsonResponse({ description: 'Configurations', schema: ConfigurationsSchema }),
+} as const;
+
+this.defineRoute({
+  configs: READ_CONFIGURATIONS_CONFIG,
+  handler: context => context.json({ data: ['app.name=My App'] }),
+});
+```
+
+`domain: { from: 'header', ... }` reads the tenant id straight off a request header and turns it into the same `Organization_<id>` token the grant stores - no `domainResolver` needed yet. Now sign in as usual (see [Authentication Usage](../authentication/usage)) and call the route with three different tokens:
+
+```bash
+# No token at all
+curl -i http://localhost:3000/api/authz-example/configurations
+# -> 401: no authenticated user
+
+# A signed-in user with zero PolicyDefinition rows
+curl -i http://localhost:3000/api/authz-example/configurations \
+  -H "Authorization: Bearer $TOKEN_WITHOUT_GRANT"
+# -> 403: authenticated, but nothing to reach an allow edge
+
+# The user from the previous section, with their organization's id
+curl -i http://localhost:3000/api/authz-example/configurations \
+  -H "Authorization: Bearer $TOKEN_WITH_GRANT" \
+  -H "x-organization-id: $ORGANIZATION_ID"
+# -> 200
+```
+
+`examples/vert` runs this exact scenario for real, with real ports and real tokens: `scripts/seed-authz-test-data.ts` and `scripts/seed-user-policies.ts` seed seven personas, and `scripts/test-authorization.sh` curls all of them - cases C1, C2, and C3 are the three requests above.
+
+## What just happened
+
+The 200 request walked the [seven-step pipeline](./#how-it-works) like this:
+
+1. `Authorization.SKIP_AUTHORIZATION` was not set - continue.
+2. `Authentication.CURRENT_USER` was present, with `principalType: 'user'` - continue.
+3. No `alwaysAllowRoles` or `allowedRoles` matched - continue.
+4. No voters were registered - continue.
+5. The `casbin` enforcer resolved, the only one registered.
+6. The `x-organization-id` header resolved to `Organization_<id>`. `ScopedCasbinAdapter` read the user's own rows from `PolicyDefinition` and built one `p` line from the grant you seeded.
+7. `enforcer.evaluate()` matched that line on every axis - `g` and `g3` by self-link, since the grant names the user and the domain directly; `objectMatch` and `g5` by exact string equality on `configuration` and `read` - and returned `allow`.
+
+The 403 request stopped at the same step 7, on the same enforcer, with no line to match: that user's `PolicyDefinition` rows were empty, so the rules built in step 6 had nothing in them. The 401 request never got past step 2 - there was no user to check anything against.
+
+## Where to go next
+
+- [Usage & Examples](./usage) - securing gRPC routes, voters, role shortcuts, CRUD factory integration, and domain scoping with a global `domainResolver`
+- [API Reference](./api) - every option, binding key, and enforcer internal
+- [Error Reference](./errors) - what each error means and how to fix it
+- `examples/vert/src/controllers/authorization-example/` - the full controller these routes are drawn from

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

@@ -6,7 +6,10 @@ difficulty: advanced
 
 # Authorization
 
-`AuthorizeComponent` wires up enforcer-based route authorization - RBAC through Casbin (with an optional multi-tenant domain-scoped model), voters, and role shortcuts - evaluated by the `authorize()` middleware after authentication.
+`AuthorizeComponent` decides whether an authenticated request is allowed to proceed. It evaluates role shortcuts, custom voters, and a Casbin RBAC enforcer, in that order, through the `authorize()` middleware. The middleware runs after authentication. Casbin's optional domain-scoped model adds multi-tenant grants on top.
+
+> [!TIP]
+> New to this component? Start with [Getting Started](./getting-started) - it builds the mental model (a graph of edges, not a rule table), then seeds one grant and protects one route end to end before you read the reference material below.
 
 ## In one example
 
@@ -73,11 +76,11 @@ const DELETE_ARTICLE_CONFIG = {
 
 ## How it works
 
-- **Enforcer-based and pluggable.** `authorize({ spec })` returns Hono middleware built by `AuthorizationProvider`. It resolves an `IAuthorizationEnforcer` from `AuthorizationEnforcerRegistry` by name (default: the first registered) - swap `CasbinAuthorizationEnforcer` for a custom class without touching route configs.
-- **Runs after authentication.** The middleware reads `Authentication.CURRENT_USER` from the Hono context, so `AuthenticateComponent` must run first and the route needs an `authenticate` config alongside `authorize`.
-- **No enforcers registered = no-op.** If `AuthorizationEnforcerRegistry.hasEnforcers()` is `false`, the middleware calls `next()` and skips authorization entirely - useful during incremental rollout, dangerous if you forget to register an enforcer in production.
-- **Casbin's scoped RBAC model is the recommended engine.** `CASBIN_RBAC_DOMAIN_SCOPED_MODEL` + `isScoped: true` + `ScopedCasbinAdapter` reads one principal's role/permission/domain edges (plus the shared role/resource/action/domain hierarchy) from a single `PolicyDefinition` table, and supports multi-tenant grants scoped to `SYSTEM_WIDE`, `ANY_MEMBER`, or a specific `<Type>_<id>` domain.
-- **Per-request enforcers, cached lines.** Each Casbin evaluation borrows an isolated enforcer from an internal pool, loads that user's policy lines into it, and evaluates - the datasource query only runs on cache miss (or always, if `cached.use: false`).
+- **Enforcer-based and pluggable.** `authorize({ spec })` returns Hono middleware built by `AuthorizationProvider`, which resolves an `IAuthorizationEnforcer` from `AuthorizationEnforcerRegistry` by name (default: the first registered). Swap `CasbinAuthorizationEnforcer` for a custom class without touching route configs.
+- **Runs after authentication.** The middleware reads `Authentication.CURRENT_USER` from the Hono context. `AuthenticateComponent` must run first, and the route needs an `authenticate` config alongside `authorize`.
+- **No enforcers registered = deny, unless you opt into allow.** If `AuthorizationEnforcerRegistry.hasEnforcers()` is `false`, the middleware throws a 403 naming the missing enforcer. Set `defaultDecision: 'allow'` on `IAuthorizeOptions` to proceed instead - useful during incremental rollout - and the middleware logs a warning each time it does.
+- **Casbin's scoped RBAC model is the recommended engine.** Combine `CASBIN_RBAC_DOMAIN_SCOPED_MODEL`, `isScoped: true`, and `ScopedCasbinAdapter` to read one principal's policy edges from a single `PolicyDefinition` table. See [RBAC with domains](./usage#rbac-with-domains-multi-tenant) for multi-tenant grant scoping.
+- **Per-request enforcers, cached lines.** Each Casbin evaluation borrows an isolated enforcer from an internal pool, loads that user's policy lines into it, then evaluates. The datasource query runs only on a cache miss, or every time if `cached.use: false`.
 
 **Pipeline (7 steps, short-circuits marked)**
 
@@ -87,7 +90,7 @@ const DELETE_ARTICLE_CONFIG = {
 | 2 | Read `Authentication.CURRENT_USER` | Missing -> 401 |
 | 3 | Role shortcuts (`alwaysAllowRoles` + `allowedRoles`) | Match -> `next()` |
 | 4 | Voters (per-route) | `ALLOW`/`DENY` -> `next()` / 403 |
-| 5 | Resolve enforcer | None registered -> `next()` |
+| 5 | Resolve enforcer | None registered -> 403, or `next()` if `defaultDecision: 'allow'` |
 | 6 | Build/cache rules (+ resolve domain, if any) | - |
 | 7 | `enforcer.evaluate()` | `DENY`/`ABSTAIN`-as-deny -> 403 |
 
@@ -99,7 +102,12 @@ const DELETE_ARTICLE_CONFIG = {
 authorize: { action: AuthorizationActions.READ, resource: 'Article' }
 ```
 
-**Bypass the enforcer for trusted roles.** `alwaysAllowRoles` (global, in `IAuthorizeOptions`) or `allowedRoles` (per-route spec) skip straight to `next()` once a matching role is found.
+**Bypass the enforcer for trusted roles.** Both skip straight to `next()` once a matching role is found.
+
+| Option | Scope |
+|---|---|
+| `alwaysAllowRoles` | Global, set in `IAuthorizeOptions` |
+| `allowedRoles` | Per-route, set on the spec |
 
 ```typescript
 authorize: { action: AuthorizationActions.DELETE, resource: 'Article', allowedRoles: [AuthorizationRoles.ADMIN.identifier] }
@@ -120,7 +128,7 @@ const ownerVoter: TAuthorizationVoter = async ({ user, context }) =>
 authorize: { action: 'read', resource: 'Order', domain: { from: 'param', key: 'merchantId', type: 'Merchant' } }
 ```
 
-**Reference a model instead of a hardcoded string.** `@model({ settings: { authorize: { principal } } } })` auto-populates `Model.AUTHORIZATION_SUBJECT`.
+**Reference a model instead of a hardcoded string.** `@model({ settings: { authorize: { principal } } })` auto-populates `Model.AUTHORIZATION_SUBJECT`.
 
 ```typescript
 authorize: { action: AuthorizationActions.READ, resource: Article.AUTHORIZATION_SUBJECT }
@@ -138,10 +146,10 @@ authorize: { action: AuthorizationActions.READ, resource: Article.AUTHORIZATION_
 
 **Files:**
 
-- [`packages/core/src/components/auth/authorize/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/component.ts) - `AuthorizeComponent`
-- [`packages/core/src/components/auth/authorize/common/`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/common) - constants, binding keys, types, policy/permission builders
-- [`packages/core/src/components/auth/authorize/providers/authorization.provider.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/providers/authorization.provider.ts) - `AuthorizationProvider` (the 7-step pipeline)
-- [`packages/core/src/components/auth/authorize/enforcers/`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/enforcers) - `CasbinAuthorizationEnforcer`, `AuthorizationEnforcerRegistry`, `CASBIN_RBAC_DOMAIN_SCOPED_MODEL`
-- [`packages/core/src/components/auth/authorize/adapters/`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/adapters) - `BaseFilteredAdapter`, `ScopedCasbinAdapter`
-- [`packages/core/src/components/auth/authorize/models/authorization-role.model.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/models/authorization-role.model.ts) - `AuthorizationRole`
-- [`packages/core/src/base/metadata/persistents.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/metadata/persistents.ts) - `@model` auto-populating `AUTHORIZATION_SUBJECT` from `settings.authorize.principal`
+- [`packages/core-server/src/components/auth/authorize/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/component.ts) - `AuthorizeComponent`
+- [`packages/core-server/src/components/auth/authorize/common/`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/common) - constants, binding keys, types, policy/permission builders
+- [`packages/core-server/src/components/auth/authorize/providers/authorization.provider.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/providers/authorization.provider.ts) - `AuthorizationProvider` (the 7-step pipeline)
+- [`packages/core-server/src/components/auth/authorize/enforcers/`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/enforcers) - `CasbinAuthorizationEnforcer`, `AuthorizationEnforcerRegistry`, `CASBIN_RBAC_DOMAIN_SCOPED_MODEL`
+- [`packages/core-server/src/components/auth/authorize/adapters/`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/adapters) - `BaseFilteredAdapter`, `ScopedCasbinAdapter`
+- [`packages/core-server/src/components/auth/authorize/models/authorization-role.model.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/models/authorization-role.model.ts) - `AuthorizationRole`
+- [`packages/core-server/src/base/metadata/persistents.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/metadata/persistents.ts) - `@model` auto-populating `AUTHORIZATION_SUBJECT` from `settings.authorize.principal`