@venizia/ignis-docs 0.0.7 → 0.0.8-1

package/wiki/best-practices/deployment-strategies.md

@@ -668,7 +668,7 @@ Add Prometheus metrics endpoint:
 ```typescript
 // src/controllers/metrics.controller.ts
 @controller({ path: '/metrics' })
-export class MetricsController extends BaseController {
+export class MetricsController extends BaseRestController {
   @get({ configs: { path: '/' } })
   getMetrics(c: Context) {
     return c.text(`

package/wiki/best-practices/error-handling.md

@@ -119,10 +119,10 @@ export class UserService extends BaseService {
 Controllers should delegate to services and let the global error handler catch exceptions:
 
 ```typescript
-import { BaseController, controller, get, post } from '@venizia/ignis';
+import { BaseRestController, controller, get, post } from '@venizia/ignis';
 
 @controller({ path: '/users' })
-export class UserController extends BaseController {
+export class UserController extends BaseRestController {
 
   @post({ configs: RouteConfigs.CREATE_USER })
   async createUser(c: TRouteContext) {

package/wiki/best-practices/performance-optimization.md

@@ -32,7 +32,7 @@ Prevent blocking the event loop with Worker Threads:
 - Large file/data processing
 - Any synchronous task > 5ms
 
-> **Deep Dive:** See [Worker Thread Helper](../references/helpers/worker-thread/) for implementation guide.
+> **Deep Dive:** See [Worker Thread Helper](../extensions/helpers/worker-thread/) for implementation guide.
 
 ## 3. Optimize Database Queries
 
@@ -127,7 +127,7 @@ Reduce database load with caching:
 
 | Cache Type | Use Case | Implementation |
 |-----------|----------|----------------|
-| **Redis** | Distributed cache, session storage | [Redis Helper](../references/helpers/redis/) |
+| **Redis** | Distributed cache, session storage | [Redis Helper](../extensions/helpers/redis/) |
 | **In-Memory** | Single-process cache | `MemoryStorageHelper` |
 
 **Example:**
@@ -390,7 +390,7 @@ logger.log('info', MSG_ORDER_FILLED);
 - Use background flushing to avoid I/O blocking
 - HfLogger uses a lock-free ring buffer (64K entries, 16MB)
 
-> **Deep Dive:** See [Logger Helper](../references/helpers/logger/) for complete HfLogger API.
+> **Deep Dive:** See [Logger Helper](../extensions/helpers/logger/) for complete HfLogger API.
 
 ## Performance Checklist
 

package/wiki/best-practices/security-guidelines.md

@@ -68,7 +68,7 @@ const SecureRoute = {
 };
 ```
 
-> **Deep Dive:** See [Authentication Component](../references/components/authentication/) for full setup guide.
+> **Deep Dive:** See [Authentication Component](../extensions/components/authentication/) for full setup guide.
 
 **Access user in protected routes:**
 ```typescript
@@ -463,6 +463,6 @@ Before deploying to production, verify:
 
 ## See Also
 
-- [Authentication Component](../references/components/authentication/) - JWT setup and configuration
+- [Authentication Component](../extensions/components/authentication/) - JWT setup and configuration
 - [Common Pitfalls](./common-pitfalls) - Security-related mistakes to avoid
 - [Deployment Strategies](./deployment-strategies) - Secure deployment practices

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

@@ -118,7 +118,7 @@ cat .env | grep APP_ENV
 - Use `try-catch` blocks to catch and log errors
 - Check database queries with Drizzle's logging: `{ logger: true }`
 
-> **Deep Dive:** See [Logger Helper](../references/helpers/logger/) for advanced logging configuration.
+> **Deep Dive:** See [Logger Helper](../extensions/helpers/logger/) for advanced logging configuration.
 
 ## 6. Request ID Tracking
 

package/wiki/{references → extensions}/components/authentication/api.md

@@ -179,7 +179,7 @@ export const authenticate = (opts: { strategies: string[]; mode?: TAuthMode }) =
 This is the primary export for creating auth middleware. It creates an `AuthenticationProvider` instance and calls `.value()` to get the middleware factory. The provider uses `AuthenticationStrategyRegistry.getInstance()` internally to resolve strategies.
 
 > [!NOTE]
-> In `all` mode, if every strategy passes but the final user payload has no `userId`, the middleware throws a `401` with message `"Failed to identify authenticated user!"`. The `any` mode **discards errors** from each failing strategy (logs at debug level) and only throws after all strategies are exhausted.
+> In `all` mode, the **first** strategy's user payload is used as the identity source — all strategies must succeed but the first one wins for identity. If every strategy passes but the first user payload has no `userId`, the middleware throws a `401` with message `"Failed to identify authenticated user!"`. The `any` mode **discards errors** from each failing strategy (logs at debug level) and only throws after all strategies are exhausted.
 
 ## Service Class Hierarchy
 
@@ -531,7 +531,7 @@ Serves the JWKS endpoint (default path `/certs`). This endpoint is **intentional
 **File:** `packages/core/src/components/auth/authenticate/controllers/jwks/controller.ts`
 
 ```typescript
-class JWKSController extends BaseController {
+class JWKSController extends BaseRestController {
   constructor(
     @inject({
       key: BindingKeys.build({
@@ -646,43 +646,35 @@ type TPermissionCommonColumns = {
   code: NotNull<PgTextBuilderInitial<...>>;
   name: NotNull<PgTextBuilderInitial<...>>;
   subject: NotNull<PgTextBuilderInitial<...>>;
-  pType: NotNull<PgTextBuilderInitial<...>>;
   action: NotNull<PgTextBuilderInitial<...>>;
   scope: NotNull<PgTextBuilderInitial<...>>;
 };
 ```
 
-### Permission Mapping Types
+### Policy Definition Types
 
 ```typescript
-type TPermissionMappingOptions = {
+type TPolicyDefinitionOptions = {
   idType?: 'string' | 'number';
 };
 
-type TPermissionMappingCommonColumns = {
-  effect: PgTextBuilderInitial<...>;
+type TPolicyDefinitionCommonColumns = {
+  variant: ReturnType<typeof text>;
+  subjectType: ReturnType<typeof text>;
+  targetType: ReturnType<typeof text>;
+  action: ReturnType<typeof text>;
+  effect: ReturnType<typeof text>;
+  domain: ReturnType<typeof text>;
 };
 ```
 
-### User Role Types
-
-```typescript
-type TUserRoleOptions = {
-  idType?: 'string' | 'number';
-};
-
-type TUserRoleCommonColumns = ReturnType<
-  typeof generatePrincipalColumnDefs<'principal', 'string' | 'number'>
->;
-```
-
 ## Controller Factory
 
 The `defineAuthController()` function dynamically creates a controller class at runtime using decorator composition:
 
 **How it works:**
 
-1. **Class creation:** A new class is created dynamically with `class AuthController extends BaseController {}` inside the factory closure
+1. **Class creation:** A new class is created dynamically with `class AuthController extends BaseRestController {}` inside the factory closure
 2. **Decorator application:** The `@controller({ path: restPath })` decorator is applied to set the base path. The controller is created with `isStrict: true`
 3. **Service injection:** The auth service is injected via `inject({ key: serviceKey })(AuthController, undefined, 0)` after class definition -- this programmatically applies `@inject` to constructor parameter 0
    - Service key is provided via `controllerOpts.serviceKey` (required)

package/wiki/{references → extensions}/components/authentication/errors.md

@@ -209,7 +209,7 @@ The middleware that executes strategies in the configured mode.
 | Error Message | Status | Method | When |
 |---------------|--------|--------|------|
 | <code v-pre>Authentication failed. Tried strategies: {{strategies}}</code> | 401 | `executeAnyMode` | All strategies failed in `'any'` mode — each strategy threw during `authenticate()` |
-| `Failed to identify authenticated user!` | 401 | `executeAllMode` | All strategies succeeded in `'all'` mode but the final `authUser.userId` is falsy |
+| `Failed to identify authenticated user!` | 401 | `executeAllMode` | All strategies succeeded in `'all'` mode but the first strategy's `authUser.userId` is falsy |
 | <code v-pre>Invalid authentication mode &#124; mode: {{mode}}</code> | 500 | `createAuthenticateMiddleware` | `mode` is not `'any'` or `'all'` |
 
 ---

package/wiki/{references → extensions}/components/authentication/index.md

@@ -178,17 +178,14 @@ import {
   extraUserColumns,
   extraRoleColumns,
   extraPermissionColumns,
-  extraPermissionMappingColumns,
-  extraUserRoleColumns,
+  extraPolicyDefinitionColumns,
 } from '@venizia/ignis';
 
 import type {
   TPermissionOptions,
   TPermissionCommonColumns,
-  TPermissionMappingOptions,
-  TPermissionMappingCommonColumns,
-  TUserRoleOptions,
-  TUserRoleCommonColumns,
+  TPolicyDefinitionOptions,
+  TPolicyDefinitionCommonColumns,
 } from '@venizia/ignis';
 ```
 
@@ -866,13 +863,13 @@ type TAuthMode = TConstValue<typeof AuthenticationModes>;
 
 - **Guides:**
   - [Components Overview](/guides/core-concepts/components) -- Component system basics
-  - [Controllers](/guides/core-concepts/controllers) -- Protecting routes with auth
+  - [REST Controllers](/guides/core-concepts/rest-controllers) | [gRPC Controllers](/guides/core-concepts/grpc-controllers) -- Protecting routes with auth
 
 - **Components:**
   - [All Components](../index) -- Built-in components list
 
 - **Helpers:**
-  - [Crypto Helper](/references/helpers/crypto/) -- Password hashing utilities
+  - [Crypto Helper](/extensions/helpers/crypto/) -- Password hashing utilities
 
 - **References:**
   - [Middlewares](/references/base/middlewares) -- Custom authentication middleware

package/wiki/{references → extensions}/components/authentication/usage.md

@@ -350,8 +350,7 @@ import {
   extraUserColumns,
   extraRoleColumns,
   extraPermissionColumns,
-  extraPermissionMappingColumns,
-  extraUserRoleColumns,
+  extraPolicyDefinitionColumns,
 } from '@venizia/ignis';
 import { withSerialId, withTimestamps } from '@venizia/ignis';
 
@@ -379,16 +378,11 @@ export const permissions = pgTable('permissions', {
   ...extraPermissionColumns(),
 });
 
-// Permission mapping (role-to-permission or user-to-permission)
-export const permissionMappings = pgTable('permission_mappings', {
-  ...withSerialId(),
-  ...extraPermissionMappingColumns(),
-});
-
-// User-role junction table
-export const userRoles = pgTable('user_roles', {
+// Policy definition table (Casbin-style policies)
+export const policyDefinitions = pgTable('policy_definitions', {
   ...withSerialId(),
-  ...extraUserRoleColumns(),
+  ...withTimestamps(),
+  ...extraPolicyDefinitionColumns(),
 });
 ```
 
@@ -435,41 +429,31 @@ extraPermissionColumns(opts?: { idType: 'string' | 'number' })
 
 | Column | Type | Default | Description |
 |--------|------|---------|-------------|
-| `code` | `text` | -- | Unique permission code |
+| `code` | `text` (unique) | -- | Unique permission code |
 | `name` | `text` | -- | Permission name |
 | `subject` | `text` | -- | Permission subject (e.g., `'User'`, `'Order'`) |
-| `pType` | `text` | -- | Permission type (maps to DB column `p_type`) |
 | `action` | `text` | -- | Permitted action (e.g., `'read'`, `'write'`) |
 | `scope` | `text` | -- | Permission scope |
 | `parentId` | `text` or `integer` | `null` | Parent permission ID |
 
-### extraPermissionMappingColumns
-
-Returns columns for mapping permissions to users or roles.
-
-```typescript
-extraPermissionMappingColumns(opts?: { idType: 'string' | 'number' })
-```
-
-| Column | Type | Default | Description |
-|--------|------|---------|-------------|
-| `effect` | `text` | `null` | Permission effect (e.g., `'allow'`, `'deny'`) |
-| `userId` | `text` or `integer` | `null` | Associated user ID |
-| `roleId` | `text` or `integer` | `null` | Associated role ID |
-| `permissionId` | `text` or `integer` | -- | Associated permission ID (not null) |
-
-### extraUserRoleColumns
+### extraPolicyDefinitionColumns
 
-Returns columns for the user-role junction table. Includes principal columns (polymorphic type/ID fields) via `generatePrincipalColumnDefs` with a default polymorphic value of `'Role'`.
+Returns columns for Casbin-style policy definitions that map subjects (users/roles) to targets (resources/permissions).
 
 ```typescript
-extraUserRoleColumns(opts?: { idType: 'string' | 'number' })
+extraPolicyDefinitionColumns(opts?: { idType: 'string' | 'number' })
 ```
 
-| Column | Type | Default | Description |
-|--------|------|---------|-------------|
-| _(principal columns)_ | _various_ | -- | Polymorphic columns from `generatePrincipalColumnDefs` |
-| `userId` | `text` or `integer` | -- | Associated user ID (not null) |
+| Column | DB Column | Type | Nullable | Default | Description |
+|--------|-----------|------|----------|---------|-------------|
+| `variant` | `variant` | `text` | No | -- | Policy variant (e.g., `'p'` for policy, `'g'` for grouping) |
+| `subjectType` | `subject_type` | `text` | No | -- | Type of subject (e.g., `'user'`, `'role'`) |
+| `targetType` | `target_type` | `text` | No | -- | Type of target (e.g., `'permission'`, `'role'`) |
+| `action` | `action` | `text` | Yes | `null` | Policy action |
+| `effect` | `effect` | `text` | Yes | `null` | Policy effect (e.g., `'allow'`, `'deny'`) |
+| `domain` | `domain` | `text` | Yes | `null` | Policy domain for multi-tenancy |
+| `subjectId` | `subject_id` | `text` or `integer` | No | -- | Subject ID (type depends on `idType`) |
+| `targetId` | `target_id` | `text` or `integer` | No | -- | Target ID (type depends on `idType`) |
 
 ### ID Type Polymorphism
 
@@ -701,7 +685,7 @@ flowchart TD
 **`all` mode:**
 - Every strategy must pass successfully
 - If any strategy fails, the request is immediately rejected (exception propagates)
-- The last strategy's user payload is used
+- The **first** strategy's user payload is used as the identity source
 - **Use case:** Multi-factor authentication (both JWT and Basic required)
 
 > [!TIP]

package/wiki/{references → extensions}/components/authorization/api.md

@@ -51,7 +51,9 @@ flowchart TD
     Roles -->|No match| Voters{Has voters?}
     Voters -->|DENY| E403a[/403 Denied by voter/]
     Voters -->|ALLOW| Next4([next - voter allow])
-    Voters -->|ABSTAIN / none| Resolve[Resolve enforcer by name]
+    Voters -->|ABSTAIN / none| HasEnforcers{Enforcers registered?}
+    HasEnforcers -->|No| Next6([next - skip, no enforcers])
+    HasEnforcers -->|Yes| Resolve[Resolve enforcer by name]
     Resolve --> Cache{Rules cached?}
     Cache -->|Yes| Evaluate
     Cache -->|No| PType{principalType?}
@@ -91,6 +93,7 @@ classDiagram
         -configuredEnforcers: Set
         +getInstance()$ AuthorizationEnforcerRegistry
         +register(opts) this
+        +hasEnforcers() boolean
         +resolveEnforcer(opts) Promise
         +resolveOptions() IAuthorizeOptions
     }
@@ -196,6 +199,7 @@ auth/authorize/
 | **Abstract base** | `AbstractAuthRegistry<T>` shared between authentication and authorization registries |
 | **Filtered adapter pattern** | `BaseFilteredAdapter` template method pattern allows custom query backends while sharing formatting logic |
 | **IAuthorizationComparable** | Generic comparison interface for custom action/resource types beyond plain strings |
+| **No-enforcer fallback** | When no enforcers are registered, the middleware skips authorization and calls `next()` instead of throwing -- prevents hard failures during development or gradual rollout |
 
 ## Component Lifecycle
 
@@ -298,6 +302,7 @@ class AuthorizationEnforcerRegistry extends AbstractAuthRegistry<IAuthorizationE
   protected getBindingPrefix(): string;  // returns Authorization.ENFORCER
 
   register(opts: { ... }): this;
+  hasEnforcers(): boolean;
   getDefaultEnforcerName(): string;
   resolveEnforcer(opts: { name: string }): Promise<IAuthorizationEnforcer>;
   resolveOptions(): IAuthorizeOptions | undefined;
@@ -310,6 +315,7 @@ class AuthorizationEnforcerRegistry extends AbstractAuthRegistry<IAuthorizationE
 |--------|---------|-------------|
 | `getInstance()` | `AuthorizationEnforcerRegistry` | Returns the singleton instance (creates on first call) |
 | `register(opts)` | `this` | Registers enforcers with type-safe options. See below. |
+| `hasEnforcers()` | `boolean` | Returns `true` if any enforcers are registered (`descriptors.size > 0`). Used by the middleware to skip authorization when no enforcers exist. |
 | `getDefaultEnforcerName()` | `string` | Delegates to `getDefaultName()` -- returns the first registered enforcer's name |
 | `resolveEnforcer({ name })` | `Promise<IAuthorizationEnforcer>` | Resolves and auto-configures an enforcer (configure-once pattern via `configuredEnforcers` Set) |
 | `resolveOptions()` | `IAuthorizeOptions \| undefined` | Iterates all registered containers looking for `AuthorizeBindingKeys.OPTIONS` |
@@ -578,12 +584,12 @@ Called once by the registry on first use. Performs:
 1. Dynamically imports `casbin` -- throws `"casbin" is not installed` if missing
 2. Validates `options.model` -- throws `options.model is required.` if missing
 3. Resolves model via driver:
-   - `'file'` → `casbin.newModelFromFile(definition)`
-   - `'text'` → `casbin.newModelFromString(definition)`
+   - `'file'` -> `casbin.newModelFromFile(definition)`
+   - `'text'` -> `casbin.newModelFromString(definition)`
 4. Creates enforcer based on cache config:
-   - `cached.use: false` → `casbin.newEnforcer(model, adapter)`
-   - `cached.driver: 'in-memory'` → `casbin.newCachedEnforcer(model, adapter)` + periodic invalidation timer (`setInterval`)
-   - `cached.driver: 'redis'` → `casbin.newEnforcer(model, adapter)` (Redis handles caching externally)
+   - `cached.use: false` -> `casbin.newEnforcer(model, adapter)`
+   - `cached.driver: 'in-memory'` -> `casbin.newCachedEnforcer(model, adapter)` + periodic invalidation timer (`setInterval`)
+   - `cached.driver: 'redis'` -> `casbin.newEnforcer(model, adapter)` (Redis handles caching externally)
 5. Validates `expiresIn >= MIN_EXPIRES_IN` (10,000 ms) for both in-memory and redis cache drivers
 
 ### destroy()
@@ -623,7 +629,7 @@ flowchart TD
 |-------------|----------|
 | `use: false` | Load policies from adapter directly via `loadPoliciesFromAdapter()` |
 | `'in-memory'` | Load policies from adapter (periodic invalidation handles cache refresh) |
-| `'redis'` | Check Redis cache → hit: load lines into model via `loadPolicyLinesIntoModel()`; miss: load from adapter, extract lines via `extractPolicyLines()`, cache in Redis with TTL |
+| `'redis'` | Check Redis cache -> hit: load lines into model via `loadPolicyLinesIntoModel()`; miss: load from adapter, extract lines via `extractPolicyLines()`, cache in Redis with TTL |
 
 Returns the `IAuthUser` directly (Casbin evaluates policies from its internal model, not from the returned value).
 
@@ -652,7 +658,7 @@ Returns `AuthorizationDecisions.ALLOW` or `AuthorizationDecisions.DENY`.
 | `resolveModel` | `{ casbin, model }` | `Model` | Resolves casbin model from file or text via driver discriminant |
 | `validateExpiresIn` | `{ expiresIn }` | `void` | Throws if `expiresIn < MIN_EXPIRES_IN` |
 | `loadPoliciesFromAdapter` | `{ user }` | `void` | Calls `enforcer.loadFilteredPolicy({ principalType, principalValue })` |
-| `loadPoliciesWithRedisCache` | `{ user, cached }` | `void` | Redis cache flow: check cache → hit: load lines; miss: load from adapter + cache |
+| `loadPoliciesWithRedisCache` | `{ user, cached }` | `void` | Redis cache flow: check cache -> hit: load lines; miss: load from adapter + cache |
 | `extractPolicyLines` | -- | `string[]` | Extracts `p` and `g` lines from enforcer model via `getPolicy()` and `getGroupingPolicy()` |
 | `loadPolicyLinesIntoModel` | `{ lines }` | `void` | Clears model, loads lines via `Helper.loadPolicyLine()`, rebuilds role links |
 
@@ -982,7 +988,8 @@ for (voter of spec.voters) {
   // ABSTAIN → continue to next voter
 }
 
-// Step 5: Resolve enforcer
+// Step 5: Resolve enforcer (with no-enforcer fallback)
+if (!registry.hasEnforcers()) → next()  // skip if no enforcers registered
 const resolvedName = enforcerName ?? registry.getDefaultEnforcerName();
 const enforcer = await registry.resolveEnforcer({ name: resolvedName });
 
@@ -1114,10 +1121,14 @@ AuthorizationRoles.ADMIN.isEqualTo({ target: AuthorizationRoles.ADMIN });
 
 ### How Authorization Middleware is Injected
 
-The `AbstractController.getRouteConfigs()` method handles middleware injection order:
+Authorization is supported in both **REST** and **gRPC** controllers.
+
+#### REST Controllers
+
+The `AbstractRestController.buildRouteMiddlewares()` method handles middleware injection order. `getRouteConfigs()` calls `buildRouteMiddlewares()` internally:
 
 ```typescript
-getRouteConfigs<RouteConfig extends IAuthRouteConfig>(opts: { configs: RouteConfig }) {
+buildRouteMiddlewares<RouteConfig extends IAuthRouteConfig>(opts: { configs: RouteConfig }) {
   const { authenticate = {}, authorize, ...restConfig } = configs;
   const mws = [];
 
@@ -1137,13 +1148,38 @@ getRouteConfigs<RouteConfig extends IAuthRouteConfig>(opts: { configs: RouteConf
   // 3. Custom middleware (last)
   if (restConfig.middleware) { ... }
 
-  return createRoute({ ...restConfig, middleware: mws, ... });
+  return { restConfig, security, mws };
+}
+```
+
+#### gRPC Controllers
+
+The `AbstractGrpcController.buildRpcMiddlewares()` method provides symmetric middleware injection for gRPC:
+
+```typescript
+buildRpcMiddlewares(opts: { configs: IRpcMetadata }): TRpcMiddleware[] {
+  const { configs } = opts;
+  const mws = [];
+
+  // 1. Authenticate middleware (first)
+  if (configs.authenticate) { ... }
+
+  // 2. Authorize middleware (second) — same pattern as REST
+  if (configs.authorize) {
+    const specs = Array.isArray(configs.authorize) ? configs.authorize : [configs.authorize];
+    for (const spec of specs) {
+      const authzMw = authorizeFn({ spec });
+      mws.push((context, next) => authzMw(context, next));
+    }
+  }
+
+  return mws;
 }
 ```
 
 ### IAuthRouteConfig
 
-Extended route config that supports both authentication and authorization:
+Extended route config that supports both authentication and authorization (REST):
 
 ```typescript
 interface IAuthRouteConfig extends HonoRouteConfig {
@@ -1154,6 +1190,19 @@ interface IAuthRouteConfig extends HonoRouteConfig {
 
 When `authorize` is an array, each spec creates a separate middleware. All must pass for the handler to execute.
 
+### Per-Route Auth Types (CRUD Factory)
+
+```typescript
+/** Per-route authorization config: { skip: true }, single spec, or array of specs. */
+type TRouteAuthorizeConfig = { skip: true } | IAuthorizationSpec | IAuthorizationSpec[];
+
+/** Per-route auth config. Endpoint config takes precedence over controller-level config. */
+type TRouteAuthConfig = {
+  authenticate?: TRouteAuthenticateConfig;
+  authorize?: TRouteAuthorizeConfig;
+};
+```
+
 ## IAuthUser Interface
 
 The user object available during authorization. Defined in `authenticate/common/types.ts`:

package/wiki/{references → extensions}/components/authorization/errors.md

@@ -14,12 +14,13 @@ flowchart TD
     S3 -->|Match| OK2([No error - bypass])
     S3 -->|No match| S4{"Step 4: Voters"}
     S4 -->|DENY| E403a[/"403: Authorization denied by voter"/]
-    S4 -->|ALLOW/ABSTAIN| S5{"Step 5: Resolve enforcer"}
+    S4 -->|ALLOW/ABSTAIN| S5{"Step 5: Enforcers registered?"}
 
-    S5 -->|Registry empty| E500a[/"500: No items registered"/]
-    S5 -->|Name not found| E500b[/"500: Descriptor not found"/]
-    S5 -->|DI fails| E500c[/"500: Failed to resolve"/]
-    S5 -->|OK| S6{"Step 6: Build rules"}
+    S5 -->|No enforcers| OK3([No error - skip])
+    S5 -->|Yes| S5b{"Resolve enforcer"}
+    S5b -->|Name not found| E500b[/"500: Descriptor not found"/]
+    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"/]
@@ -29,7 +30,7 @@ flowchart TD
     S6 -->|OK| S7{"Step 7: Evaluate"}
 
     S7 -->|No action/resource| E500g[/"500: request.action and resource required"/]
-    S7 -->|ALLOW| OK3([Authorized])
+    S7 -->|ALLOW| OK4([Authorized])
     S7 -->|DENY| E403b[/"403: Authorization denied"/]
 ```
 
@@ -63,6 +64,9 @@ All error messages from the authorization module, organized by source:
 | <code v-pre>[AuthorizationEnforcerRegistry] Descriptor not found: {{name}}</code> | 500 | `resolveDescriptor` |
 | <code v-pre>[AuthorizationEnforcerRegistry] Failed to resolve: {{name}}</code> | 500 | `resolveDescriptor` |
 
+> [!NOTE]
+> The `[AuthorizationEnforcerRegistry] No items registered` error can only occur if `getDefaultEnforcerName()` is called directly. During normal middleware execution, the provider checks `registry.hasEnforcers()` first and skips authorization if no enforcers are registered, so this error is not thrown in the standard pipeline.
+
 ### Casbin Enforcer Errors (CasbinAuthorizationEnforcer)
 
 | Error Message | Status | Method |
@@ -198,7 +202,7 @@ AuthorizationEnforcerRegistry.getInstance().register({
 
 ### "[AuthorizationEnforcerRegistry] No items registered"
 
-**Cause:** Tried to get the default enforcer name but no enforcers are registered. This usually means `AuthorizationEnforcerRegistry.register()` was never called.
+**Cause:** Tried to get the default enforcer name but no enforcers are registered. This error can only occur if `getDefaultEnforcerName()` is called directly. During normal middleware execution, the provider checks `registry.hasEnforcers()` first and skips authorization if no enforcers are registered, so this error is not triggered in the standard pipeline.
 
 **Fix:** Register enforcers after registering the component:
 
@@ -358,6 +362,7 @@ Check middleware injection order:
 1. Verify `authorize` is set on the route config (not just `authenticate`)
 2. Verify `authenticate` is not set to `{ skip: true }` (which also skips authorization in CRUD factory)
 3. Verify the component is registered and enforcers are registered via the registry
+4. Note: if no enforcers are registered, the middleware skips authorization silently (calls `next()`) rather than throwing an error
 
 ### Rules Are Built On Every Request
 

package/wiki/{references → extensions}/components/authorization/index.md

@@ -40,10 +40,12 @@ flowchart TD
     S3 -->|No match| S4{"4. Voters?"}
     S4 -->|DENY| E403a[/403/]
     S4 -->|ALLOW| Pass4([next])
-    S4 -->|ABSTAIN| S5["5. Resolve enforcer"]
-    S5 --> S6["6. Build/cache rules"]
+    S4 -->|ABSTAIN / none| S5{"5. Enforcers registered?"}
+    S5 -->|No enforcers| Pass5([next - skip])
+    S5 -->|Yes| S5b["Resolve enforcer"]
+    S5b --> S6["6. Build/cache rules"]
     S6 --> S7{"7. Evaluate"}
-    S7 -->|ALLOW| Pass5([next])
+    S7 -->|ALLOW| Pass6([next])
     S7 -->|DENY/ABSTAIN| E403b[/403/]
 ```
 
@@ -53,13 +55,16 @@ flowchart TD
 | 2 | Get authenticated user from context | Yes -- 401 if missing |
 | 3 | Check role-based shortcuts (`alwaysAllowRoles` + `allowedRoles`) | Yes -- allow if matched |
 | 4 | Execute `voters` (per-route) | Yes -- DENY/ALLOW short-circuits |
-| 5 | Resolve enforcer (by name or default) | No |
+| 5 | Check if enforcers are registered; resolve enforcer (by name or default) | Yes -- skip all if no enforcers registered |
 | 6 | Build or retrieve cached rules | No |
 | 7 | Evaluate permission via enforcer | Yes -- 403 if denied |
 
 > [!NOTE]
 > Step 3 merges the global `alwaysAllowRoles` check and the per-route `allowedRoles` check into a single step. User roles are extracted once and checked against both lists.
 
+> [!NOTE]
+> Step 5 has a safety fallback: if no enforcers are registered in the `AuthorizationEnforcerRegistry`, the middleware skips authorization entirely and calls `next()`. This prevents hard failures when authorization is configured on routes but no enforcer has been registered yet.
+
 ### Authorization Constants
 
 | Constant | Value | Description |
@@ -645,7 +650,7 @@ interface IJWTTokenPayload extends JWTPayload, IAuthUser {
 
 ## Relationship with Authentication
 
-Authorization runs **after** authentication in the middleware chain. The `AbstractController.getRouteConfigs()` method ensures the correct ordering:
+Authorization runs **after** authentication in the middleware chain. Both REST and gRPC controllers ensure the correct ordering:
 
 ```mermaid
 flowchart LR
@@ -657,10 +662,79 @@ flowchart LR
 
 1. Authentication middleware is injected first (from `authenticate` config)
 2. Authorization middleware is injected second (from `authorize` config)
-3. Custom middleware is injected last (from `middleware` config)
+3. Custom middleware is injected last (from `middleware` config -- REST only)
 
 This means `Authentication.CURRENT_USER` is always available when the authorization middleware executes.
 
+### REST Controllers
+
+The `AbstractRestController.buildRouteMiddlewares()` method builds the middleware array from route config. The `getRouteConfigs()` method calls `buildRouteMiddlewares()` internally and wraps it into a Hono route definition:
+
+```typescript
+// In AbstractRestController
+buildRouteMiddlewares<RouteConfig extends IAuthRouteConfig>(opts: { configs: RouteConfig }) {
+  const { authenticate = {}, authorize, ...restConfig } = opts.configs;
+  const mws = [];
+
+  // 1. Authenticate middleware (first)
+  if (strategies.length > 0) {
+    mws.push(authenticateFn({ strategies, mode }));
+  }
+
+  // 2. Authorize middleware (second) — supports single or array
+  if (authorize) {
+    const specs = Array.isArray(authorize) ? authorize : [authorize];
+    for (const spec of specs) {
+      mws.push(authorizeFn({ spec }));
+    }
+  }
+
+  // 3. Custom middleware (last)
+  if (restConfig.middleware) { ... }
+
+  return { restConfig, security, mws };
+}
+```
+
+### gRPC Controllers
+
+The `AbstractGrpcController.buildRpcMiddlewares()` method provides symmetric authorization support for gRPC routes. Authorization specs are applied the same way as REST:
+
+```typescript
+// In AbstractGrpcController
+buildRpcMiddlewares(opts: { configs: IRpcMetadata }): TRpcMiddleware[] {
+  const { configs } = opts;
+  const mws = [];
+
+  // 1. Authenticate middleware
+  if (configs.authenticate) { ... }
+
+  // 2. Authorize middleware — same pattern as REST
+  if (configs.authorize) {
+    const specs = Array.isArray(configs.authorize) ? configs.authorize : [configs.authorize];
+    for (const spec of specs) {
+      const authzMw = authorizeFn({ spec });
+      mws.push((context, next) => authzMw(context, next));
+    }
+  }
+
+  return mws;
+}
+```
+
+### IAuthRouteConfig
+
+Extended route config that supports both authentication and authorization:
+
+```typescript
+interface IAuthRouteConfig extends HonoRouteConfig {
+  authenticate?: { strategies?: TAuthStrategy[]; mode?: TAuthMode };
+  authorize?: IAuthorizationSpec | IAuthorizationSpec[];
+}
+```
+
+When `authorize` is an array, each spec creates a separate middleware. All must pass for the handler to execute.
+
 ### Per-Route Configuration in CRUD Factory
 
 CRUD factory routes support both authentication and authorization configuration:
@@ -694,6 +768,19 @@ ControllerFactory.defineCrudController({
 3. Per-route `authorize` overrides controller-level `authorize`
 4. No per-route config -- inherits controller-level config
 
+### Per-Route Auth Types
+
+```typescript
+/** Per-route authorization config: { skip: true }, single spec, or array of specs. */
+type TRouteAuthorizeConfig = { skip: true } | IAuthorizationSpec | IAuthorizationSpec[];
+
+/** Per-route auth config. Endpoint config takes precedence over controller-level config. */
+type TRouteAuthConfig = {
+  authenticate?: TRouteAuthenticateConfig;
+  authorize?: TRouteAuthorizeConfig;
+};
+```
+
 ## See Also
 
 - [Usage & Examples](./usage) -- Securing routes, voters, patterns, and CRUD integration