@venizia/ignis-docs 0.0.7 → 0.0.8-0

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

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

@@ -10,12 +10,12 @@ Use the `authorize` field in route configs to declare authorization requirements
 
 ```typescript
 import {
-  BaseController,
+  BaseRestController,
   Authentication,
   AuthorizationActions,
 } from '@venizia/ignis';
 
-class ArticleController extends BaseController {
+class ArticleController extends BaseRestController {
   binding() {
     // Read requires 'read' action on 'Article' resource
     this.defineRoute({
@@ -102,7 +102,7 @@ Use the `authorize` field alongside `authenticate` in decorator configs:
 import { controller, get, post, AuthorizationActions, AuthorizationRoles } from '@venizia/ignis';
 
 @controller({ path: '/articles' })
-class ArticleController extends BaseController {
+class ArticleController extends BaseRestController {
   @get({
     configs: {
       path: '/',
@@ -134,6 +134,34 @@ class ArticleController extends BaseController {
 }
 ```
 
+### gRPC Route Authorization
+
+Authorization works the same way in gRPC controllers. Use the `authorize` field in RPC metadata:
+
+```typescript
+import { AuthorizationActions, Authentication } from '@venizia/ignis';
+
+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
+      },
+    });
+  }
+}
+```
+
+The `AbstractGrpcController.buildRpcMiddlewares()` method injects authorization middleware in the same order as REST controllers: authenticate first, then authorize.
+
 ## Using the `authorize()` Standalone Function
 
 The `authorize()` function is a convenience wrapper around `AuthorizationProvider`. It returns a Hono `MiddlewareHandler`:
@@ -383,7 +411,7 @@ ControllerFactory.defineCrudController({
 
 ### Priority Resolution (Factory Routes)
 
-The `defineControllerRouteConfigs` function resolves authorization with this priority:
+The `resolveRouteAuthorize` function in `defineControllerRouteConfigs` resolves authorization with this priority:
 
 ```mermaid
 flowchart TD
@@ -403,6 +431,16 @@ flowchart TD
 3. **Per-route `authorize` spec** -- overrides controller-level
 4. **Controller-level `authorize`** -- default for all routes
 
+### Per-Route Auth Type
+
+The per-route authorize config is typed as a discriminated union:
+
+```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.
+
 ## Dynamic Skip Authorization
 
 Use `Authorization.SKIP_AUTHORIZATION` to dynamically bypass authorization in middleware (step 1 in the pipeline):

package/wiki/{references → extensions}/components/health-check.md

@@ -213,10 +213,11 @@ The controller uses `this.definitions = RouteConfigs` to store route configurati
 #### Controller Source
 ```typescript
 import {
-  BaseController, IControllerOptions, TRouteContext,
-  api, jsonContent, jsonResponse, z,
+  BaseRestController, IControllerOptions, TRouteContext,
 } from '@venizia/ignis';
-import { HTTP } from '@venizia/ignis-helpers';
+import { api, jsonContent, jsonResponse } from '@venizia/ignis';
+import { z } from '@hono/zod-openapi';
+import { HTTP, ValueOrPromise } from '@venizia/ignis-helpers';
 
 const RouteConfigs = {
   ROOT: {
@@ -258,7 +259,7 @@ const RouteConfigs = {
   },
 } as const;
 
-export class HealthCheckController extends BaseController {
+export class HealthCheckController extends BaseRestController {
   constructor(opts: IControllerOptions) {
     super({ ...opts, scope: HealthCheckController.name });
     this.definitions = RouteConfigs;

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

@@ -15,6 +15,7 @@ Reusable, pluggable modules that group together related features. A component ca
 | [WebSocket](./websocket/) | Real-time communication | Bun native WebSocket, Redis Pub/Sub, heartbeat |
 | [Static Asset](./static-asset/) | File management | Upload/download files, MinIO & local filesystem support |
 | [Swagger](./swagger) | API documentation | OpenAPI generation, Swagger UI, Scalar UI |
+| [gRPC](/references/base/grpc-controllers) | gRPC transport | ConnectRPC integration, unary RPC, decorator-based |
 
 ## Creating a Component
 
@@ -81,6 +82,7 @@ Using components is a great way to organize your application's features into mod
   - [WebSocket](./websocket/) - Bun native WebSocket
   - [Static Asset](./static-asset/) - Static file serving
   - [Swagger](./swagger) - API documentation
+  - [gRPC](/references/base/grpc-controllers) - gRPC transport (ConnectRPC)
 
 - **References:**
   - [BaseComponent API](/references/base/components) - Component base class

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

@@ -211,7 +211,7 @@ The `TMailOptions` configuration determines which email transport provider is us
 
 ```typescript
 // Simple SMTP Authentication (e.g., Gmail with app password)
-this.bind<TMailOptions>({ key: MailBindingKeys.MAIL_OPTIONS }).toValue({
+this.bind<TMailOptions>({ key: MailKeys.MAIL_OPTIONS }).toValue({
   provider: 'nodemailer',
   from: 'noreply@example.com',
   fromName: 'My App',

package/wiki/{references → extensions}/components/request-tracker.md

@@ -248,7 +248,7 @@ If running without a proxy, ensure the runtime provides connection info (Bun doe
   - [All Components](./index) - Built-in components list
 
 - **Helpers:**
-  - [Logger Helper](/references/helpers/logger/) - Logging utilities
+  - [Logger Helper](/extensions/helpers/logger/) - Logging utilities
 
 - **Best Practices:**
   - [Troubleshooting Tips](/best-practices/troubleshooting-tips) - Debugging with request IDs

package/wiki/{references → extensions}/components/socket-io/api.md

@@ -630,7 +630,7 @@ Reads all binding keys from the DI container and validates required ones:
 |---------|-----------|------------------|
 | `SERVER_OPTIONS` | Optional, merged with defaults via `Object.assign()` | -- |
 | `REDIS_CONNECTION` | Must be `instanceof DefaultRedisHelper` | `"Invalid instance of redisConnection | Please init connection with RedisHelper for single redis connection or RedisClusterHelper for redis cluster mode!"` |
-| `AUTHENTICATE_HANDLER` | Must be a function (non-null) | `"Invalid authenticateFn to setup io socket server!"` |
+| `AUTHENTICATE_HANDLER` | Must be a function (non-null) | `"[DANGER][SocketIOComponent] Invalid authenticateFn to setup io socket server!"` |
 | `VALIDATE_ROOM_HANDLER` | Optional, resolved from container, `null` coerced to `undefined` | -- |
 | `CLIENT_CONNECTED_HANDLER` | Optional, resolved from container, `null` coerced to `undefined` | -- |
 
@@ -673,7 +673,7 @@ Returns a fetch handler function that routes requests:
 Registers a post-start hook that:
 
 1. Gets the HTTP server instance via `getServerInstance()`
-2. Validates the server instance exists (throws `"HTTP server not available for Node.js runtime!"` if not)
+2. Validates the server instance exists (throws `"[SocketIOComponent] HTTP server not available for Node.js runtime!"` if not)
 3. Calls `createNodeSocketIOHelper()` which creates `SocketIOServerHelper` with `runtime: RuntimeModules.NODE` and the HTTP server, then awaits `configure()`
 4. Binds the helper to `SOCKET_IO_INSTANCE`
 

package/wiki/{references → extensions}/components/socket-io/errors.md

@@ -59,6 +59,8 @@
 **Fix**: Use `RedisHelper` (single instance) or `RedisClusterHelper` (cluster mode):
 
 ```typescript
+import { SocketIOBindingKeys } from '@venizia/ignis/socket-io';
+
 // Correct -- single instance
 this.bind({ key: SocketIOBindingKeys.REDIS_CONNECTION })
   .toValue(new RedisHelper({ name: 'socket-io', host, port, password }));