@flusys/nestjs-iam 1.1.0-beta → 2.0.0

package/README.md

@@ -8,11 +8,13 @@
 - [Overview](#overview)
 - [Installation](#installation)
 - [Module Configuration](#module-configuration)
+- [Constants](#constants)
 - [Core Concepts](#core-concepts)
 - [Entities](#entities)
 - [Permission Modes](#permission-modes)
 - [Permission Logic](#permission-logic)
 - [Services](#services)
+- [Helpers](#helpers)
 - [REST API Endpoints](#rest-api-endpoints)
 - [Multi-Tenant Support](#multi-tenant-support)
 - [Permission Guard Integration](#permission-guard-integration)
@@ -28,11 +30,11 @@
 
 - **Hierarchical Actions** - Organize permissions in tree structures
 - **Action Types** - BACKEND (cached for guards), FRONTEND (returned to UI), BOTH
-- **RBAC** - Role-Based Access Control
-- **ABAC/DIRECT** - Direct user-to-action assignments
-- **Permission Logic** - Complex AND/OR rules
+- **RBAC** - Role-Based Access Control with validation
+- **DIRECT** - Direct user-to-action assignments with validation
+- **Permission Mode Validation** - Throws `BadRequestException` when using wrong mode
 - **Company/Branch Scoping** - Multi-tenant permissions with three-level granularity
-- **Centralized Caching** - Automatic cache invalidation for security
+- **Tenant-Aware Caching** - Automatic cache invalidation with multi-tenant support
 
 ### Package Hierarchy
 
@@ -89,6 +91,34 @@ import { IAMModule } from '@flusys/nestjs-iam';
 export class AppModule {}
 ```
 
+### Async Configuration
+
+```typescript
+IAMModule.forRootAsync({
+  global: true,
+  includeController: true,
+  bootstrapAppConfig: {
+    databaseMode: 'single',
+    enableCompanyFeature: true,
+    permissionMode: 'RBAC',
+  },
+  imports: [ConfigModule],
+  useFactory: (config: ConfigService) => ({
+    // IAM-specific options from config
+  }),
+  inject: [ConfigService],
+})
+```
+
+---
+
+## Constants
+
+```typescript
+// Injection Token
+export const IAM_MODULE_OPTIONS = 'IAM_MODULE_OPTIONS';
+```
+
 ---
 
 ## Core Concepts
@@ -146,10 +176,75 @@ enum IamPermissionType {
 4. **UserRole -> RoleAction** - Inherited from roles
 5. **Action Permission Logic** - Complex AND/OR rules
 
+### Permission Cascade Deletion
+
+When removing company actions via `removeCompanyActionsWithCascade()`, the `PermissionService` performs cascade deletion:
+
+```
+Company Action Removed
+        ↓
+1. Delete COMPANY_ACTION permissions
+        ↓
+2. Find all roles in the company
+        ↓
+3. Delete ROLE_ACTION permissions for those actions
+        ↓
+4. Find all users in the company
+        ↓
+5. Delete USER_ACTION permissions for those actions
+        ↓
+6. Invalidate permission cache for affected users
+```
+
 ---
 
 ## Entities
 
+### Entity Groups
+
+```typescript
+// Core entities (no company feature)
+export const IAMCoreEntities = [Action, Role, UserIamPermission];
+
+// Company-specific entities
+export const IAMCompanyEntities = [RoleWithCompany, UserIamPermissionWithCompany];
+
+// All entities
+export const IAMAllEntities = [
+  Action,
+  Role,
+  RoleWithCompany,
+  UserIamPermission,
+  UserIamPermissionWithCompany,
+];
+
+// Helper function
+export function getIAMEntitiesByConfig(
+  enableCompanyFeature: boolean,
+  permissionMode: 'FULL' | 'RBAC' | 'DIRECT' = 'FULL',
+): any[] {
+  const entities: any[] = [Action];
+
+  // Permission entity - always included
+  if (enableCompanyFeature) {
+    entities.push(UserIamPermissionWithCompany);
+  } else {
+    entities.push(UserIamPermission);
+  }
+
+  // Role entity - Only for RBAC or FULL mode (not DIRECT)
+  if (permissionMode === 'RBAC' || permissionMode === 'FULL') {
+    if (enableCompanyFeature) {
+      entities.push(RoleWithCompany);
+    } else {
+      entities.push(Role);
+    }
+  }
+
+  return entities;
+}
+```
+
 ### ActionBase
 
 Core action fields in `action-base.entity.ts`:
@@ -222,6 +317,16 @@ Extends PermissionBase with:
 
 Set in `bootstrapAppConfig.permissionMode`:
 
+### Permission Mode Enum
+
+```typescript
+enum IAMPermissionMode {
+  RBAC = 1,   // Role-Based: Action + RoleAction + UserRole
+  DIRECT = 2, // Direct User Permissions: Action + UserAction
+  FULL = 3,   // Both RBAC + Direct permissions
+}
+```
+
 ### RBAC Mode (Role-Based)
 
 ```
@@ -230,6 +335,8 @@ User -> Role -> Action
 
 Only role-based permissions. Users get permissions through assigned roles.
 
+**Note:** Calling `assignUserActions()` in RBAC mode throws `BadRequestException`.
+
 ### DIRECT Mode (Action-Based)
 
 ```
@@ -238,6 +345,8 @@ User -> Action
 
 Only direct permissions. Users get actions assigned directly.
 
+**Note:** Calling `assignUserRoles()` or `assignRoleActions()` in DIRECT mode throws `BadRequestException`.
+
 ### FULL Mode (Combined)
 
 ```
@@ -245,34 +354,25 @@ User -> Role -> Action
 User -> Action
 ```
 
-Both RBAC and direct permissions. Default mode.
-
-### PermissionModeHelper
-
-```typescript
-import { PermissionModeHelper } from '@flusys/nestjs-iam/helpers';
-
-const mode = PermissionModeHelper.fromString('RBAC');
-// Returns: IAMPermissionMode.RBAC
-```
+Both RBAC and direct permissions. Default mode. All assignment methods available.
 
 ---
 
 ## Permission Logic
 
-Complex rules using AND/OR operators:
+Complex permission rules using AND/OR operators stored in `permissionLogic` field:
 
 ```typescript
 interface LogicNode {
   id: string;
   type: 'group' | 'action';
-  operator?: 'AND' | 'OR'; // Only for type: 'group'
-  children?: LogicNode[];  // Only for type: 'group'
-  actionId?: string;       // Only for type: 'action'
+  operator?: 'AND' | 'OR';
+  children?: LogicNode[];
+  actionId?: string;
 }
 ```
 
-### Example: Nested Logic
+**Example:** User must have "employee" AND ("department-head" OR "hr-clearance")
 
 ```typescript
 const logic: LogicNode = {
@@ -292,13 +392,21 @@ const logic: LogicNode = {
     },
   ],
 };
-// User must have employee AND (department-head OR hr-clearance)
 ```
 
 ---
 
 ## Services
 
+| Service | Scope | Description |
+|---------|-------|-------------|
+| `ActionService` | REQUEST | Action CRUD, tree queries |
+| `RoleService` | REQUEST | Role CRUD (RBAC/FULL mode only) |
+| `PermissionService` | REQUEST | Permission assignments, my-permissions |
+| `PermissionCacheService` | REQUEST | Cache management |
+| `IAMConfigService` | SINGLETON | IAM configuration access |
+| `IAMDataSourceService` | REQUEST | DataSource provider for multi-tenant |
+
 ### ActionService
 
 ```typescript
@@ -335,17 +443,17 @@ await roleService.insert({
 ### PermissionService
 
 ```typescript
-import { PermissionService } from '@flusys/nestjs-iam';
+import { PermissionService, PermissionAction } from '@flusys/nestjs-iam';
 
-// Assign roles to user
+// Assign roles to user (RBAC/FULL mode only)
 await permissionService.assignUserRoles({
   userId: 'user-id',
   companyId: 'company-id',
-  branchId: null, // null = ALL branches
+  branchId: null, // null = company-wide
   items: [{ id: 'role-id', action: PermissionAction.ADD }],
 });
 
-// Assign actions directly
+// Assign actions directly (DIRECT/FULL mode only)
 await permissionService.assignUserActions({
   userId: 'user-id',
   companyId: 'company-id',
@@ -353,7 +461,7 @@ await permissionService.assignUserActions({
   items: [{ id: 'action-id', action: PermissionAction.ADD }],
 });
 
-// Assign actions to role
+// Assign actions to role (RBAC/FULL mode only)
 await permissionService.assignRoleActions({
   roleId: 'role-id',
   items: [{ id: 'action-id', action: PermissionAction.ADD }],
@@ -381,12 +489,64 @@ await cacheService.invalidateUser('user-id', 'company-id', ['branch-id']);
 
 // Invalidate role members
 await cacheService.invalidateRole('role-id', userIds, 'company-id');
+
+// Tenant-aware action code cache
+await cacheService.setActionCodeMap(codeToIdMap, tenantId);
+await cacheService.getActionIdsByCodes(['user.view'], tenantId);
+await cacheService.invalidateActionCodeCache(tenantId);
 ```
 
-**Cache Key Format:**
+**Cache Key Formats:**
 ```
 permissions:user:{userId}                                        // Without company
 permissions:company:{companyId}:branch:{branchId}:user:{userId}  // With company
+action-codes:map                                                 // Single tenant
+action-codes:tenant:{tenantId}:map                               // Multi-tenant
+```
+
+---
+
+## Helpers
+
+### PermissionModeHelper
+
+Centralizes conversion from string to enum to prevent duplication:
+
+```typescript
+import { PermissionModeHelper } from '@flusys/nestjs-iam';
+
+// Convert string to enum
+const mode = PermissionModeHelper.fromString('RBAC');
+// Returns: IAMPermissionMode.RBAC
+
+const mode = PermissionModeHelper.fromString(undefined);
+// Returns: IAMPermissionMode.FULL (default)
+
+// Convert enum to string
+const str = PermissionModeHelper.toString(IAMPermissionMode.RBAC);
+// Returns: 'RBAC'
+```
+
+**Used by:**
+- `iam.module.ts` (forRoot, forRootAsync)
+- `iam-config.service.ts` (getPermissionMode)
+- `main.ts` (Swagger setup)
+
+### validateCompanyAccess
+
+Validates user access to a company for permission operations:
+
+```typescript
+import { validateCompanyAccess } from '@flusys/nestjs-iam';
+
+// In a controller or service
+validateCompanyAccess(
+  iamConfig,
+  dto.companyId,
+  user,
+  'You do not have access to this company',
+);
+// Throws ForbiddenException if user.companyId !== dto.companyId
 ```
 
 ---
@@ -405,7 +565,7 @@ permissions:company:{companyId}:branch:{branchId}:user:{userId}  // With company
 | `/iam/actions/update` | POST | Update action |
 | `/iam/actions/delete` | POST | Delete action |
 
-### Roles API
+### Roles API (RBAC/FULL mode only)
 
 | Endpoint | Method | Description |
 |----------|--------|-------------|
@@ -417,25 +577,25 @@ permissions:company:{companyId}:branch:{branchId}:user:{userId}  // With company
 
 ### Permissions API
 
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/iam/permissions/role-actions/assign` | POST | Assign actions to role |
-| `/iam/permissions/role-actions/get` | POST | Get role actions |
-| `/iam/permissions/user-roles/assign` | POST | Assign roles to user |
-| `/iam/permissions/user-roles/get` | POST | Get user roles |
-| `/iam/permissions/user-actions/assign` | POST | Assign actions to user |
-| `/iam/permissions/user-actions/get` | POST | Get user actions |
-| `/iam/permissions/company-actions/assign` | POST | Company action whitelist |
-| `/iam/permissions/company-actions/get` | POST | Get company actions |
-| `/iam/permissions/my-permissions` | POST | Get current user's permissions |
-
-**My Permissions Response:**
-```typescript
-{
-  frontendActions: FrontendActionDto[],
-  cachedEndpoints: number
-}
-```
+| Endpoint | Method | Modes | Description |
+|----------|--------|-------|-------------|
+| `/iam/permissions/role-actions/assign` | POST | RBAC, FULL | Assign actions to role |
+| `/iam/permissions/role-actions/get` | POST | RBAC, FULL | Get role actions |
+| `/iam/permissions/user-roles/assign` | POST | RBAC, FULL | Assign roles to user |
+| `/iam/permissions/user-roles/get` | POST | RBAC, FULL | Get user roles |
+| `/iam/permissions/user-actions/assign` | POST | DIRECT, FULL | Assign actions to user |
+| `/iam/permissions/user-actions/get` | POST | DIRECT, FULL | Get user actions |
+| `/iam/permissions/company-actions/assign` | POST | All (company enabled) | Company action whitelist |
+| `/iam/permissions/company-actions/get` | POST | All (company enabled) | Get company actions |
+| `/iam/permissions/my-permissions` | POST | All | Get current user's permissions |
+
+**Controller Registration by Mode:**
+
+| Mode | Controllers |
+|------|-------------|
+| DIRECT | ActionController, MyPermissionController, UserActionPermissionController |
+| RBAC | ActionController, MyPermissionController, RoleController, RolePermissionController |
+| FULL | All controllers |
 
 ---
 
@@ -446,8 +606,9 @@ permissions:company:{companyId}:branch:{branchId}:user:{userId}  // With company
 ```typescript
 // config/app.config.ts
 export const bootstrapAppConfig: IBootstrapAppConfig = {
-  databaseMode: 'single',
-  enableCompanyFeature: true, // or false
+  databaseMode: 'single', // or 'multi-tenant'
+  enableCompanyFeature: true,
+  permissionMode: 'FULL',
 };
 ```
 
@@ -465,14 +626,28 @@ export const bootstrapAppConfig: IBootstrapAppConfig = {
 - All permissions are global
 - Uses `UserIamPermission` and `Role` entities
 
+### Multi-Tenant Database Mode
+
+When `databaseMode: 'multi-tenant'`:
+- Each tenant has isolated database/schema
+- Action code cache is tenant-aware (separate cache per tenant)
+- Uses `IAMDataSourceService` for tenant-specific connections
+
 ### Permission Merging
 
-When user logs in, `getMyPermissions` merges:
-1. Company-wide roles (branchId=null) + Branch-specific roles
+When `getMyPermissions` is called:
+
+**With branchId specified:**
+1. Company-wide roles (branchId=null) + Branch-specific roles for that branch
 2. Actions from all merged roles
-3. Company-wide user actions + Branch-specific user actions
+3. Company-wide user actions + Branch-specific user actions for that branch
+
+**Without branchId (null):**
+1. ALL roles for the user in the company (any branch)
+2. Actions from all roles
+3. ALL user actions for the company (any branch)
 
-**Result:** Complete permission set without duplicates.
+**Result:** Complete permission set without duplicates, filtered by company whitelist.
 
 ---
 
@@ -537,73 +712,62 @@ Direct actions should be exceptions and branch-specific overrides, not the prima
 
 ## API Reference
 
-### Module
+### Exports
 
 ```typescript
-import { IAMModule, IAMPermissionMode } from '@flusys/nestjs-iam';
-```
+// Config
+export { IAM_MODULE_OPTIONS } from './config';
 
-### Services
+// Modules
+export { IAMModule } from './modules';
 
-```typescript
-import {
-  ActionService,
-  RoleService,
-  PermissionService,
-  PermissionCacheService,
-  IAMConfigService,
-  IAMDataSourceProvider,
-} from '@flusys/nestjs-iam';
-```
+// Entities
+export { Action } from './entities/action.entity';
+export { ActionBase } from './entities/action-base.entity';
+export { Role } from './entities/role.entity';
+export { RoleBase } from './entities/role-base.entity';
+export { RoleWithCompany } from './entities/role-with-company.entity';
+export { PermissionBase } from './entities/permission-base.entity';
+export { UserIamPermission } from './entities/user-iam-permission.entity';
+export { UserIamPermissionWithCompany } from './entities/permission-with-company.entity';
+export { IAMCoreEntities, IAMCompanyEntities, IAMAllEntities, getIAMEntitiesByConfig } from './entities';
 
-### Entities
+// Services
+export { ActionService } from './services/action.service';
+export { RoleService } from './services/role.service';
+export { PermissionService } from './services/permission.service';
+export { PermissionCacheService } from './services/permission-cache.service';
+export { IAMConfigService } from './services/iam-config.service';
+export { IAMDataSourceService } from './services/iam-datasource.service';
 
-```typescript
-import {
-  Action,
-  Role,
-  RoleWithCompany,
-  UserIamPermission,
-  UserIamPermissionWithCompany,
-  getIAMEntitiesByConfig,
-} from '@flusys/nestjs-iam/entities';
-```
+// Helpers
+export { PermissionModeHelper } from './helpers/permission-mode.helper';
+export { validateCompanyAccess } from './helpers/company-access.helper';
 
-### DTOs
+// Enums
+export { ActionType } from './enums/action-type.enum';
+export { IAMPermissionMode } from './enums/permission-type.enum';
 
-```typescript
-import {
-  CreateActionDto,
-  UpdateActionDto,
-  CreateRoleDto,
-  UpdateRoleDto,
-  AssignUserActionsDto,
-  AssignUserRolesDto,
-  AssignRoleActionsDto,
-  AssignCompanyActionsDto,
-  MyPermissionsResponseDto,
-  FrontendActionDto,
-} from '@flusys/nestjs-iam/dtos';
-```
-
-### Enums
+// Types
+export { LogicNode } from './types/logic-node.type';
 
-```typescript
-import {
-  ActionType,
-  IAMPermissionMode,
-  IamPermissionType,
-  IamEntityType,
-} from '@flusys/nestjs-iam/enums';
+// DTOs
+export * from './dtos';
+
+// Interfaces
+export * from './interfaces';
+
+// Swagger Config
+export { iamSwaggerConfig } from './docs';
 ```
 
-### Helpers
+### Module Static Methods
 
 ```typescript
-import {
-  PermissionEvaluatorHelper,
-  PermissionModeHelper,
-} from '@flusys/nestjs-iam/helpers';
+// Configure module
+IAMModule.forRoot(options?: IAMModuleOptions): DynamicModule
+IAMModule.forRootAsync(options: IAMModuleAsyncOptions): DynamicModule
+IAMModule.forFeature(options?: IAMModuleOptions): DynamicModule
 ```
 
 ---
@@ -612,6 +776,9 @@ import {
 
 ```
 nestjs-iam/src/
+├── config/
+│   ├── iam.constants.ts           # IAM_MODULE_OPTIONS token
+│   └── index.ts
 ├── modules/
 │   └── iam.module.ts              # Main module with dynamic config
 ├── entities/
@@ -622,14 +789,15 @@ nestjs-iam/src/
 │   ├── role-with-company.entity.ts
 │   ├── permission-base.entity.ts  # Permission base fields
 │   ├── user-iam-permission.entity.ts
-│   └── permission-with-company.entity.ts
+│   ├── permission-with-company.entity.ts
+│   └── index.ts                   # Entity groups & getIAMEntitiesByConfig
 ├── services/
 │   ├── action.service.ts          # Action CRUD
 │   ├── role.service.ts            # Role CRUD
 │   ├── permission.service.ts      # Permission management
 │   ├── permission-cache.service.ts # Cache management
 │   ├── iam-config.service.ts      # Configuration
-│   └── iam-datasource.provider.ts # DataSource provider
+│   └── iam-datasource.service.ts  # DataSource provider
 ├── controllers/
 │   ├── action.controller.ts
 │   ├── role.controller.ts
@@ -638,8 +806,8 @@ nestjs-iam/src/
 │   ├── user-action-permission.controller.ts
 │   └── company-action-permission.controller.ts
 ├── helpers/
-│   ├── permission-evaluator.helper.ts
-│   └── permission-mode.helper.ts
+│   ├── company-access.helper.ts   # Company access validation
+│   └── permission-mode.helper.ts  # String to enum conversion
 ├── dtos/
 │   ├── action.dto.ts
 │   ├── role.dto.ts
@@ -647,15 +815,17 @@ nestjs-iam/src/
 ├── interfaces/
 │   ├── action.interface.ts
 │   ├── role.interface.ts
-│   ├── iam-module-options.interface.ts
-│   └── iam-module-async-options.interface.ts
+│   └── iam-module-options.interface.ts
 ├── enums/
 │   ├── action-type.enum.ts
 │   └── permission-type.enum.ts
-└── types/
-    └── logic-node.type.ts
+├── types/
+│   └── logic-node.type.ts
+├── docs/
+│   └── iam-swagger.config.ts
+└── index.ts
 ```
 
 ---
 
-**Last Updated:** 2026-02-16
+**Last Updated:** 2026-02-21

package/cjs/controllers/action.controller.js

@@ -42,7 +42,50 @@ function _ts_param(paramIndex, decorator) {
     };
 }
 let ActionController = class ActionController extends (0, _nestjsshared.createApiController)(_actiondto.CreateActionDto, _actiondto.UpdateActionDto, _actiondto.ActionResponseDto, {
-    security: 'jwt'
+    security: {
+        insert: {
+            level: 'permission',
+            permissions: [
+                _nestjsshared.ACTION_PERMISSIONS.CREATE
+            ]
+        },
+        insertMany: {
+            level: 'permission',
+            permissions: [
+                _nestjsshared.ACTION_PERMISSIONS.CREATE
+            ]
+        },
+        getById: {
+            level: 'permission',
+            permissions: [
+                _nestjsshared.ACTION_PERMISSIONS.READ
+            ]
+        },
+        getAll: {
+            level: 'permission',
+            permissions: [
+                _nestjsshared.ACTION_PERMISSIONS.READ
+            ]
+        },
+        update: {
+            level: 'permission',
+            permissions: [
+                _nestjsshared.ACTION_PERMISSIONS.UPDATE
+            ]
+        },
+        updateMany: {
+            level: 'permission',
+            permissions: [
+                _nestjsshared.ACTION_PERMISSIONS.UPDATE
+            ]
+        },
+        delete: {
+            level: 'permission',
+            permissions: [
+                _nestjsshared.ACTION_PERMISSIONS.DELETE
+            ]
+        }
+    }
 }) {
     async getActionsForPermission(user) {
         const actions = await this.actionService.getActionsForPermission(user);
@@ -65,7 +108,7 @@ let ActionController = class ActionController extends (0, _nestjsshared.createAp
     }
 };
 _ts_decorate([
-    (0, _common.Get)('tree-for-permission'),
+    (0, _common.Post)('tree-for-permission'),
     (0, _common.UseGuards)(_guards.JwtAuthGuard),
     (0, _swagger.ApiBearerAuth)(),
     (0, _swagger.ApiOperation)({