@bluealba/platform-cli 1.0.1 → 1.1.0

package/docs/architecture/authorization-system.mdx

@@ -0,0 +1,886 @@
+---
+title: Authorization System
+description: Deep dive into the Blue Alba Platform authorization architecture - RBAC model, operations, roles, rules, and permission checking
+---
+
+import { Card, CardGrid, Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+
+The Blue Alba Platform implements a comprehensive **Role-Based Access Control (RBAC)** system with fine-grained permissions, conditional rules, and resource-level authorization.
+
+## Authorization Model Overview
+
+The authorization system is built on four core concepts that form a hierarchy:
+
+```
+Applications
+    ↓
+Operations (permissions)
+    ↓
+Roles (collections of operations)
+    ↓
+Rules (conditional allow/deny logic)
+    ↓
+Users & Groups (assignment targets)
+```
+
+<CardGrid stagger>
+  <Card title="Applications" icon="seti:folder">
+    Top-level boundary for authorization. Operations, roles, and rules are scoped to applications.
+  </Card>
+
+  <Card title="Operations" icon="approve-check">
+    Granular permissions representing specific actions (e.g., `users::read`, `orders::create`).
+  </Card>
+
+  <Card title="Roles" icon="seti:config">
+    Named collections of operations assigned to users and groups.
+  </Card>
+
+  <Card title="Rules" icon="seti:license">
+    Conditional logic that allows or denies access based on context.
+  </Card>
+</CardGrid>
+
+---
+
+## Applications
+
+Applications are the highest level of authorization scoping.
+
+### Application Entity
+
+```typescript
+interface Application {
+  id: number;
+  name: string;              // Unique identifier (e.g., "customer-portal")
+  displayName: string;       // Human-readable name
+  description?: string;
+  allowedByDefault: boolean; // If true, users get access by default
+  createdAt: Date;
+  createdBy: string;
+  updatedAt: Date;
+  updatedBy: string;
+}
+```
+
+---
+
+## Operations
+
+**Operations** represent the most granular level of permission in the system.
+
+### Operation Entity
+
+```typescript
+interface Operation {
+  id: number;
+  name: string;              // e.g., "users::read"
+  description?: string;      // Human-readable description
+  applicationId: number;     // Scoped to application
+  createdAt: Date;
+  createdBy: string;
+  updatedAt: Date;
+  updatedBy: string;
+}
+```
+
+### Operation Naming Conventions
+
+Operations follow a hierarchical naming pattern for consistency:
+
+```
+{domain}::{resource}::{action}[.{modifier}]
+```
+
+**Structure**
+
+- **domain**: Functional area of the system (e.g., authorization, authentication, documentation)
+- **resource**: Specific entity within the domain (e.g., role, auth-methods, impersonation)
+- **action**: Operation to perform (e.g., delete, manage, read, config)
+- **modifier (optional)**: Additional qualifier to specify scope or context
+
+**Examples**:
+
+<Tabs>
+  <TabItem label="Basic Operations">
+    ```
+    users::read         → View users
+    users::write        → Create/update users
+    users::delete       → Delete users
+    orders::read        → View orders
+    orders::create      → Create new orders
+    orders::update      → Modify existing orders
+    orders::delete      → Delete orders
+    reports::read       → View reports
+    reports::export     → Export reports to file
+    ```
+  </TabItem>
+
+  <TabItem label="Complex Operations">
+    ```
+    authorization::role::delete → Delete roles from the authorization system
+    authorization::role::manage-operations → Manage operations assigned to specific roles
+    ```
+  </TabItem>
+</Tabs>
+
+### Using Operations in Code
+
+<Tabs>
+  <TabItem label="Frontend (React)">
+    ```typescript
+    import { Authorized, useAuth } from '@bluealba/pae-ui-react-core';
+
+    function OrderManagement() {
+      const { hasAccess } = useAuth();
+
+      // Check single operation
+      const canRead = hasAccess('orders::read');
+
+      // Check if user has ALL of the operations
+      const isAdmin = hasAccess(['orders::read', 'orders::write', 'orders::delete']);
+
+      return (
+        <div>
+          {/* Declarative authorization */}
+          <Authorized operations=["orders::read"]>
+            <OrderList />
+          </Authorized>
+
+          {/* Programmatic authorization */}
+          {canRead && <ViewOrderButton />}
+          {isAdmin && <AdminPanel />}
+        </div>
+      );
+    }
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+## Roles
+
+**Roles** are named collections of operations assigned to users and groups.
+
+### Role Entity
+
+```typescript
+interface Role {
+  id: number;
+  name: string;              // e.g., "admin", "viewer", "editor"
+  description?: string;
+  applicationId: number;     // Scoped to application
+  operations: Operation[];   // Associated operations
+  createdAt: Date;
+  createdBy: string;
+  updatedAt: Date;
+  updatedBy: string;
+}
+```
+
+### Standard Role Patterns
+
+<CardGrid>
+  <Card title="Admin Role" icon="star">
+    **Full application access**
+
+    Operations:
+    - `{app}.*` (all operations for the application)
+
+    Use Case: System administrators
+  </Card>
+
+  <Card title="Viewer Role" icon="open-book">
+    **Read-only access**
+
+    Operations:
+    - `users::read`
+    - `orders::read`
+    - `reports::read`
+
+    Use Case: Users who need visibility without modification rights
+  </Card>
+
+  <Card title="Editor Role" icon="pencil">
+    **Read and write access**
+
+    Operations:
+    - `users::read`
+    - `users::write`
+    - `orders::read`
+    - `orders::write`
+
+    Use Case: Users who can create and update data
+  </Card>
+
+  <Card title="Approver Role" icon="approve-check">
+    **Specialized workflow role**
+
+    Operations:
+    - `orders::read`
+    - `orders::approve`
+    - `orders::reject`
+
+    Use Case: Users with approval authority
+  </Card>
+</CardGrid>
+
+### Role Assignment
+
+Roles can be assigned in two ways:
+
+<Tabs>
+  <TabItem label="Direct Assignment">
+    ```typescript
+    // Assign role directly to a user
+    POST /applications/:appName/rules
+    {
+      "subjectType": "user",
+      "subject": "john@acme.com",
+      "resourceType": "role",
+      "resource": "editor",
+      "denied": false,
+      "tenantId": 1
+    }
+    ```
+
+    Direct assignment creates a rule granting the role to the specific user within the given tenant.
+  </TabItem>
+
+  <TabItem label="Group Assignment">
+    ```typescript
+    // Assign role to a group
+    POST /applications/:appName/rules
+    {
+      "subjectType": "group",
+      "subject": "editors-group",
+      "resourceType": "role",
+      "resource": "editor",
+      "denied": false,
+      "tenantId": 1
+    }
+
+    // Add user to group
+    POST /_/groups/:groupId/members/:username
+    ```
+
+    All users in the group automatically receive the role's operations.
+  </TabItem>
+</Tabs>
+
+<Aside type="tip">
+  **Best Practice**: Use group-based role assignment for easier management. Instead of assigning roles to 100 users individually, assign the role to a group and manage group membership.
+</Aside>
+
+---
+
+## Rules
+
+**Rules** add conditional logic to authorization, enabling fine-grained access control.
+
+### Rule Entity
+
+```typescript
+interface Rule {
+  id: number;
+  subjectType: 'user' | 'group';     // Who the rule applies to
+  subject: string;                    // Username or group name
+  resourceType: 'operation' | 'role' | 'application';
+  resourceId: number;                 // ID of the resource
+  resourceName: string;               // Name of the resource
+  denied: boolean;                    // Allow (false) or Deny (true)
+  applicationId?: number;             // Optional application scope
+  tenantId?: number;                  // Tenant scope (null = global, applies to all tenants)
+  createdAt: Date;
+  createdBy: string;
+  updatedAt: Date;
+  updatedBy: string;
+}
+```
+
+### Tenant-Scoped Rules
+
+Rules can be scoped to a specific tenant or apply globally across all tenants:
+
+- **Tenant-scoped rules** (`tenantId` set): Apply only within the specified tenant. All rules created from the Admin UI are automatically scoped to the current tenant.
+- **Global rules** (`tenantId` is `null`): Apply across all tenants. These are typically legacy rules created before tenant scoping was introduced.
+
+<Aside type="note">
+  In the Admin UI, global rules are highlighted with a **"Global"** badge. When deleting a global rule, the UI displays a confirmation warning that the deletion will affect all tenants.
+</Aside>
+
+### Rule Types
+
+<Tabs>
+  <TabItem label="Allow Rules">
+    Grant access to a resource.
+
+    ```typescript
+    {
+      subjectType: 'user',
+      subject: 'john@acme.com',
+      resourceType: 'operation',
+      resourceName: 'orders::read',
+      denied: false  // ALLOW
+    }
+    ```
+
+    Result: User `john@acme.com` can perform `orders.read` operation.
+  </TabItem>
+
+  <TabItem label="Deny Rules">
+    Revoke access to a resource (takes precedence over allow).
+
+    ```typescript
+    {
+      subjectType: 'user',
+      subject: 'john@acme.com',
+      resourceType: 'operation',
+      resourceName: 'orders::delete',
+      denied: true  // DENY
+    }
+    ```
+
+    Result: User `john@acme.com` cannot perform `orders.delete`, even if a role grants it.
+  </TabItem>
+
+  <TabItem label="Group Rules">
+    Apply rules to all members of a group.
+
+    ```typescript
+    {
+      subjectType: 'group',
+      subject: 'admins',
+      resourceType: 'role',
+      resourceName: 'admin',
+      denied: false  // ALLOW
+    }
+    ```
+
+    Result: All users in the `admins` group receive the `admin` role.
+  </TabItem>
+
+  <TabItem label="Application Rules">
+    Grant access to entire applications.
+
+    ```typescript
+    {
+      subjectType: 'user',
+      subject: 'john@acme.com',
+      resourceType: 'application',
+      resourceName: 'customer-portal',
+      denied: false  // ALLOW
+    }
+    ```
+
+    Result: User can access the `customer-portal` application.
+  </TabItem>
+</Tabs>
+
+### Rule Evaluation Order
+
+Rules are evaluated in a specific order to determine authorization:
+
+```
+1. Check DENY rules first (explicit denials take precedence)
+   ↓
+2. If denied, return DENIED
+   ↓
+3. Check ALLOW rules
+   ↓
+4. If allowed, return ALLOWED
+   ↓
+5. Default: DENIED (fail-safe)
+```
+
+**Example**:
+
+```typescript
+// User has these rules:
+[
+  { subject: 'john', resource: 'orders::read', denied: false },  // ALLOW
+  { subject: 'john', resource: 'orders::write', denied: false }, // ALLOW
+  { subject: 'john', resource: 'orders::delete', denied: true }  // DENY
+]
+
+// Authorization checks:
+isAuthorized('john', 'orders::read')   → true  (explicit allow)
+isAuthorized('john', 'orders::write')  → true  (explicit allow)
+isAuthorized('john', 'orders::delete') → false (explicit deny)
+isAuthorized('john', 'orders::approve') → false (no rule, default deny)
+```
+
+---
+
+## Authorization Flow
+
+### High-Level Flow
+
+```
+1. User makes request
+   ↓
+2. Gateway authenticates user (JWT validation)
+   ↓
+3. Gateway extracts user's groups from JWT
+   ↓
+4. Gateway resolves tenant from request context
+   ↓
+5. Gateway queries authorization service for user's allowed resources
+   (filtered by tenant: includes tenant-specific + global rules)
+   ↓
+6. Authorization service evaluates rules and returns AllowedResources
+   ↓
+7. Gateway resolves target module from catalog
+   ↓
+8. Gateway checks if user is authorized for module + path + method
+   ↓
+9. If authorized, forward request; otherwise, return 403
+```
+
+### Allowed Resources Structure
+
+The authorization service returns a consolidated view of user permissions:
+
+```typescript
+interface AllowedResources {
+  applications: Array<{
+    id: number;
+    name: string;
+    displayName: string;
+    description: string;
+    createdAt: string;
+    createdBy: string;
+    updatedAt: string;
+    updatedBy: string;
+    operations: Array<{
+      id: number;
+      name: string;
+    }>;
+  }>;
+}
+```
+
+**Example**:
+
+```json
+{
+  "applications": [
+    {
+      "id": 1,
+      "name": "customer-portal",
+      "displayName": "Customer Portal"
+      "description": "",
+      "createdAt": "2026-01-01T12:00:00.000Z",
+      "createdBy": "service",
+      "updatedAt": "2026-01-01T12:00:00.000Z",
+      "updatedBy": "service",
+      "operations": [
+        { "id": 101, "name": "users::read" },
+        { "id": 102, "name": "users::write" },
+        { "id": 201, "name": "orders::read" },
+        { "id": 202, "name": "orders::write" }
+      ]
+    },
+    {
+      "id": 2,
+      "name": "admin-console",
+      "displayName": "Admin Console"
+      "description": "",
+      "createdAt": "2026-01-01T12:00:00.000Z",
+      "createdBy": "service",
+      "updatedAt": "2026-01-01T12:00:00.000Z",
+      "updatedBy": "service",
+      "operations": [
+        { "id": 301, "name": "admin::read" },
+        { "id": 302, "name": "admin::write" }
+      ]
+    }
+  ]
+}
+```
+
+### Authorization Check Implementation
+
+The authorization check happens in multiple locations:
+
+<Tabs>
+  <TabItem label="Gateway Level">
+    ```typescript
+    // apps/pae-nestjs-gateway-service/src/authorization/authorization.service.ts
+
+    async authorizeRequest(
+      context: ExecutionContext,
+      username: string,
+      tenantId?: number
+    ): Promise<boolean> {
+      const requestMethod = context.switchToHttp().getRequest().method;
+      const requestPath = context.switchToHttp().getRequest().url;
+
+      // 1. Get user's allowed resources (filtered by tenant)
+      const allowedResources = await this.authzService.getAuthorizedResourcesForUser(username, tenantId);
+
+      // 2. Get catalog
+      const catalog = await this.catalogService.getCatalog();
+
+      // 3. Resolve target module
+      const targetModule = this.catalogService.resolveTargetModule(catalog, requestPath);
+      if (!targetModule) {
+        return false; // No module found
+      }
+
+      // 4. Check authorization using pae-core-lib
+      const isAuthorized = paeInstance.isAuthorized(
+        targetModule,
+        catalog,
+        allowedResources,
+        requestPath,
+        requestMethod
+      );
+
+      // 5. Add authorization headers for downstream services
+      if (isAuthorized) {
+        this.addAuthzHeaders(context, allowedResources);
+      }
+
+      return isAuthorized;
+    }
+    ```
+  </TabItem>
+
+  <TabItem label="Core Authorization Logic">
+    ```typescript
+    // packages/pae-core-lib/src/authorization/isAuthorized/is-authorized.ts
+
+    export const isAuthorized = (
+      module: ModuleMetadata,
+      catalog: ModuleMetadata[],
+      allowedResources: AllowedResources,
+      requestPath?: string,
+      requestMethod: HttpMethod = 'GET'
+    ): boolean => {
+      // 1. Get module requirements (what operations are needed)
+      const moduleRequirements = getModuleRequirements(
+        module,
+        catalog,
+        requestPath,
+        requestMethod
+      );
+
+      // 2. Validate user has required operations
+      return validateRequirements(moduleRequirements, allowedResources);
+    };
+    ```
+  </TabItem>
+
+  <TabItem label="Frontend Level">
+    ```typescript
+    // React component with authorization
+
+    import { Authorized, useAuth } from '@bluealba/pae-ui-react-core';
+
+    function OrdersPage() {
+      const { hasAccess } = useAuth();
+
+      return (
+        <div>
+          <h1>Orders</h1>
+
+          {/* Declarative - component only renders if authorized */}
+          <Authorized operation={["orders::read"]}>
+            <OrdersList />
+          </Authorized>
+
+          {/* Programmatic - conditional rendering */}
+          {hasAccess('orders::create') && (
+            <Button onClick={handleCreate}>Create Order</Button>
+          )}
+
+          {/* Check for every of multiple operations */}
+          {hasAccess(['orders::approve', 'orders::admin']) && (
+            <ApprovalPanel />
+          )}
+        </div>
+      );
+    }
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+## Module-Level Authorization
+
+Modules in the catalog can specify required operations for access.
+
+### Module Authorization Configuration
+
+```typescript
+interface CatalogModule {
+  id: string;
+  name: string;
+  baseUrl: string;
+
+  authorization: {
+
+    // Authorization configuration
+    operations?: string[];     // Required operations for module access
+    isPublic?: boolean;        // If true, no authentication required
+
+    // Route-level operations
+    routes?: Array<{
+      pattern: string;         // ex.: /cache/(.*)
+      methods: string[];       // ex.: ['POST', 'PUT']
+      operations: string[];    // Override operations for specific route
+    }>;
+  }
+  
+}
+```
+
+**Example**:
+
+```typescript
+{
+  name: 'orders-service',
+  baseUrl: '/api/orders',
+  
+  authorization: {
+    operations: ['orders::read'], // Default: need orders.read to access
+
+    routes: [
+      {
+        pattern: '/api/orders',
+        methods: ['GET'],
+        operations: ['orders::read'] // Can be more specific
+      },
+      {
+        pattern: '/api/orders',
+        methods: ['POST'],
+        operations: ['orders::create', 'orders::write']
+      },
+      {
+        pattern: '/api/orders/:id',
+        methods: ['DELETE'],
+        operations: ['orders::delete', 'orders::admin']
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Authorization Service Architecture
+
+The authorization system consists of multiple services working together:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Authorization Service                         │
+│                    (NestJS microservice)                         │
+│                                                                  │
+│  ┌────────────────────────────────────────────────────────────┐ │
+│  │                    Applications API                         │ │
+│  │  POST   /applications        - Create application          │ │
+│  │  GET    /applications        - List applications           │ │
+│  │  PATCH  /applications/:applicationName    - Update application          │ │
+│  │  DELETE /applications/:applicationName    - Delete application          │ │
+│  └────────────────────────────────────────────────────────────┘ │
+│                                                                  │
+│  ┌────────────────────────────────────────────────────────────┐ │
+│  │                    Operations API                           │ │
+│  │  POST   /applications/:applicationName/operations          - Create operation            │ │
+│  │  GET    /applications/:applicationName/operations          - List operations             │ │
+│  │  PATCH  /applications/:applicationName/operations/:operationName      - Update operation            │ │
+│  │  DELETE /applications/:applicationName/operations/:operationName      - Delete operation            │ │
+│  └────────────────────────────────────────────────────────────┘ │
+│                                                                  │
+│  ┌────────────────────────────────────────────────────────────┐ │
+│  │                    Roles API                                │ │
+│  │  POST   /applications/:applicationName/roles               - Create role                 │ │
+│  │  GET    /applications/:applicationName/roles               - List roles                  │ │
+│  │  PATCH  /applications/:applicationName/roles/:roleName           - Update role                 │ │
+│  │  DELETE /applications/:applicationName/roles/:roleName           - Delete role                 │ │
+│  │  POST   /roles/:roleName/operations/:operationName  - Assign operation    │ │
+│  │  DELETE /roles/:roleName/operations/:operationName  - Remove operation    │ │
+│  └────────────────────────────────────────────────────────────┘ │
+│                                                                  │
+│  ┌────────────────────────────────────────────────────────────┐ │
+│  │                    Rules API                                │ │
+│  │  POST   /applications/:applicationName/rules               - Create rule                 │ │
+│  │  GET    /applications/:applicationName/rules               - List rules                  │ │
+│  │  PATCH  /applications/:applicationName/rules/:id           - Update rule                 │ │
+│  │  DELETE /applications/:applicationName/rules/:id           - Delete rule                 │ │
+│  └────────────────────────────────────────────────────────────┘ │
+│                                                                  │
+│  ┌────────────────────────────────────────────────────────────┐ │
+│  │              Authorization Query API                        │ │
+│  │  GET /users/:username/allowed-resources                    │ │
+│  │    → Returns AllowedResources for user                     │ │
+│  │  GET /users/:username/allowed-applications                 │ │
+│  │    → Returns applications user can access                  │ │
+│  │  GET /users/:username/allowed-operations                   │ │
+│  │    → Returns operations user can perform                   │ │
+│  └────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Database Schema
+
+The authorization system uses the following database tables:
+
+```sql
+-- Applications
+CREATE TABLE applications (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(255) UNIQUE NOT NULL,
+  display_name VARCHAR(255) NOT NULL,
+  description TEXT,
+  allowed_by_default BOOLEAN DEFAULT FALSE,
+  created_at TIMESTAMP DEFAULT NOW(),
+  created_by VARCHAR(255) NOT NULL,
+  updated_at TIMESTAMP DEFAULT NOW(),
+  updated_by VARCHAR(255) NOT NULL
+);
+
+-- Operations
+CREATE TABLE operations (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  description TEXT,
+  application_id INTEGER REFERENCES applications(id) ON DELETE CASCADE,
+  created_at TIMESTAMP DEFAULT NOW(),
+  created_by VARCHAR(255) NOT NULL,
+  updated_at TIMESTAMP DEFAULT NOW(),
+  updated_by VARCHAR(255) NOT NULL,
+  UNIQUE(application_id, name)
+);
+
+-- Roles
+CREATE TABLE roles (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  description TEXT,
+  application_id INTEGER REFERENCES applications(id) ON DELETE CASCADE,
+  created_at TIMESTAMP DEFAULT NOW(),
+  created_by VARCHAR(255) NOT NULL,
+  updated_at TIMESTAMP DEFAULT NOW(),
+  updated_by VARCHAR(255) NOT NULL,
+  UNIQUE(application_id, name)
+);
+
+-- Role-Operation assignments
+CREATE TABLE role_operations (
+  role_id INTEGER REFERENCES roles(id) ON DELETE CASCADE,
+  operation_id INTEGER REFERENCES operations(id) ON DELETE CASCADE,
+  PRIMARY KEY (role_id, operation_id)
+);
+
+-- Rules
+CREATE TABLE rules (
+  id SERIAL PRIMARY KEY,
+  subject_type VARCHAR(50) NOT NULL, -- 'user' or 'group'
+  subject VARCHAR(255) NOT NULL,     -- username or group name
+  resource_type VARCHAR(50) NOT NULL, -- 'operation', 'role', 'application'
+  resource_id INTEGER NOT NULL,
+  resource_name VARCHAR(255) NOT NULL,
+  denied BOOLEAN DEFAULT FALSE,
+  application_id INTEGER REFERENCES applications(id) ON DELETE CASCADE,
+  tenant_id INTEGER REFERENCES tenants(id) ON DELETE CASCADE, -- NULL = global (all tenants)
+  created_at TIMESTAMP DEFAULT NOW(),
+  created_by VARCHAR(255) NOT NULL,
+  updated_at TIMESTAMP DEFAULT NOW(),
+  updated_by VARCHAR(255) NOT NULL
+);
+
+-- Indexes for performance
+CREATE INDEX idx_rules_subject ON rules(subject);
+CREATE INDEX idx_rules_resource ON rules(resource_type, resource_id);
+CREATE INDEX idx_rules_tenant ON rules(tenant_id);
+CREATE INDEX idx_operations_app ON operations(application_id);
+CREATE INDEX idx_roles_app ON roles(application_id);
+```
+
+---
+
+## Performance Considerations
+
+### Caching
+
+Authorization data is cached to reduce database queries:
+
+```typescript
+// Cache user's allowed resources for 5 minutes
+const cacheKey = `authz:user:${username}:resources`;
+let allowedResources = await cache.get(cacheKey);
+
+if (!allowedResources) {
+  allowedResources = await authzService.getAllowedResources(username);
+  await cache.set(cacheKey, allowedResources, 300); // 5 minutes TTL
+}
+```
+
+### Optimization Strategies
+
+<CardGrid>
+  <Card title="Batch Queries" icon="rocket">
+    Load all rules for a user in one query instead of multiple queries
+  </Card>
+
+  <Card title="Denormalization" icon="seti:db">
+    Store flattened permission data for faster lookups
+  </Card>
+
+  <Card title="Index Optimization" icon="magnifier">
+    Database indexes on subject, resource_type, and resource_id columns
+  </Card>
+
+  <Card title="Early Termination" icon="approve-check">
+    Return immediately on first DENY rule (no need to check further)
+  </Card>
+</CardGrid>
+
+---
+
+## Security Considerations
+
+<Aside type="caution" title="Authorization Security Best Practices">
+
+**Principle of Least Privilege**:
+- Grant users only the minimum permissions needed
+- Prefer deny-by-default (explicit allow required)
+- Regularly audit and review permissions
+
+**Rule Management**:
+- DENY rules take precedence over ALLOW rules
+- Avoid wildcard operations (`*.*`) except for admins
+- Document why DENY rules exist
+
+**Context Validation**:
+- Always validate tenant context
+- Never trust client-provided authorization headers
+- Verify user still has permissions (don't rely on stale tokens)
+
+**Audit Trail**:
+- Log all authorization failures
+- Track who grants/revokes permissions
+- Monitor for unusual permission changes
+
+**Testing**:
+- Unit test authorization logic extensively
+- Test both positive and negative cases
+- Verify DENY rules work correctly
+- Test permission inheritance through groups
+
+</Aside>
+
+---
+
+## Next Steps
+
+- **[Gateway Architecture](/_/docs/architecture/gateway-architecture/)** - How gateway enforces authorization
+- **[Authentication System](/_/docs/architecture/authentication-system/)** - User authentication and JWT
+- **[Multi-Tenancy](/_/docs/architecture/multi-tenancy/)** - Tenant-scoped authorization