@flusys/nestjs-iam 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -0,0 +1,665 @@
+# IAM Package Guide
+
+> **Package:** `@flusys/nestjs-iam`
+> **Purpose:** Identity and Access Management with RBAC, ABAC, and permission logic
+> **Version:** 4.4.0 | **Updated:** 2026-01-24
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Module Configuration](#module-configuration)
+- [Core Concepts](#core-concepts)
+- [Entities](#entities)
+- [Permission Modes](#permission-modes)
+- [Permission Logic](#permission-logic)
+- [Services](#services)
+- [REST API Endpoints](#rest-api-endpoints)
+- [Multi-Tenant Support](#multi-tenant-support)
+- [Permission Guard Integration](#permission-guard-integration)
+- [Best Practices](#best-practices)
+- [API Reference](#api-reference)
+- [Package Architecture](#package-architecture)
+
+---
+
+## Overview
+
+`@flusys/nestjs-iam` provides a comprehensive Identity and Access Management system:
+
+- **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
+- **Company/Branch Scoping** - Multi-tenant permissions with three-level granularity
+- **Centralized Caching** - Automatic cache invalidation for security
+
+### Package Hierarchy
+
+```
+@flusys/nestjs-core     <- Foundation
+     |
+@flusys/nestjs-shared   <- Shared utilities
+     |
+@flusys/nestjs-auth     <- User/Company management
+     |
+@flusys/nestjs-iam      <- Permission management (THIS PACKAGE)
+```
+
+---
+
+## Installation
+
+```bash
+npm install @flusys/nestjs-iam @flusys/nestjs-shared @flusys/nestjs-core
+```
+
+---
+
+## Module Configuration
+
+### With Auth Module (Recommended)
+
+```typescript
+import { AuthModule } from '@flusys/nestjs-auth';
+import { IAMModule } from '@flusys/nestjs-iam';
+
+@Module({
+  imports: [
+    AuthModule.forRoot({
+      includeIAM: true, // Required for single-tenant mode
+      bootstrapAppConfig: {
+        databaseMode: 'single',
+        enableCompanyFeature: true,
+      },
+      config: { /* auth config */ },
+    }),
+
+    IAMModule.forRoot({
+      global: true,
+      includeController: true,
+      bootstrapAppConfig: {
+        databaseMode: 'single',
+        enableCompanyFeature: true,
+        permissionMode: 'FULL', // 'FULL' | 'RBAC' | 'DIRECT'
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+---
+
+## Core Concepts
+
+### Actions
+
+Actions represent permissions in the system:
+
+| Field | Description |
+|-------|-------------|
+| `name` | Human-readable name |
+| `code` | Unique identifier (e.g., `user.create`) |
+| `actionType` | Category: `backend`, `frontend`, or `both` |
+| `metadata` | Additional data (icon, routerLink for frontend) |
+| `parentId` | Parent action for hierarchy |
+| `serial` | Display order |
+
+### Action Types
+
+```typescript
+enum ActionType {
+  BACKEND = 'backend',   // API endpoint permissions (cached for PermissionGuard)
+  FRONTEND = 'frontend', // UI features (returned in my-permissions API)
+  BOTH = 'both',         // Both backend and frontend
+}
+```
+
+### Roles
+
+Roles are collections of actions:
+
+| Field | Description |
+|-------|-------------|
+| `name` | Human-readable name |
+| `description` | Role description |
+| `companyId` | Company scope (when company feature enabled) |
+| `isActive` | Active status |
+
+### Permission Types
+
+```typescript
+enum IamPermissionType {
+  USER_ROLE = 'user_role',       // User assigned to role
+  ROLE_ACTION = 'role_action',   // Role has action
+  USER_ACTION = 'user_action',   // User has action directly
+  COMPANY_ACTION = 'company_action', // Company action whitelist
+}
+```
+
+### Permission Resolution Order
+
+1. **Company-Action Whitelist** - Filter by company (if enabled)
+2. **UserAction (DENY)** - Explicit denials take precedence
+3. **UserAction (GRANT)** - Explicit grants
+4. **UserRole -> RoleAction** - Inherited from roles
+5. **Action Permission Logic** - Complex AND/OR rules
+
+---
+
+## Entities
+
+### ActionBase
+
+Core action fields in `action-base.entity.ts`:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `readOnly` | boolean | System-protected action |
+| `name` | varchar(255) | Action name |
+| `code` | varchar(255) | Unique code |
+| `description` | varchar(500) | Description |
+| `actionType` | enum | BACKEND, FRONTEND, BOTH |
+| `permissionLogic` | json | AND/OR rules |
+| `parentId` | uuid | Parent action ID |
+| `serial` | int | Display order |
+| `isActive` | boolean | Active status |
+| `metadata` | json | Additional data |
+
+### RoleBase
+
+Core role fields in `role-base.entity.ts`:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `readOnly` | boolean | System-protected role |
+| `name` | varchar(255) | Role name |
+| `description` | varchar(500) | Description |
+| `isActive` | boolean | Active status |
+| `serial` | int | Display order |
+| `metadata` | json | Additional data |
+
+### RoleWithCompany
+
+Extends RoleBase with:
+- `companyId` (uuid) - Company scope
+
+### PermissionBase
+
+Core permission fields in `permission-base.entity.ts`:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `permissionType` | enum | USER_ROLE, ROLE_ACTION, etc. |
+| `sourceType` | enum | USER, ROLE, COMPANY |
+| `sourceId` | uuid | Source entity ID |
+| `targetType` | enum | ROLE, ACTION |
+| `targetId` | uuid | Target entity ID |
+| `userId` | uuid | User ID (nullable) |
+| `validFrom` | timestamp | Permission valid from |
+| `validUntil` | timestamp | Permission valid until |
+| `reason` | text | Reason for permission |
+| `metadata` | json | Additional data |
+
+### UserIamPermissionWithCompany
+
+Extends PermissionBase with:
+- `companyId` (uuid) - Company scope
+- `branchId` (uuid) - Branch scope
+
+**Permission Granularity:**
+
+| Level | companyId | branchId | Use Case |
+|-------|-----------|----------|----------|
+| Global | null | null | Super admin across all companies |
+| Company-wide | set | null | Manager for ALL branches in company |
+| Branch-specific | set | set | Manager for specific branch only |
+
+---
+
+## Permission Modes
+
+Set in `bootstrapAppConfig.permissionMode`:
+
+### RBAC Mode (Role-Based)
+
+```
+User -> Role -> Action
+```
+
+Only role-based permissions. Users get permissions through assigned roles.
+
+### DIRECT Mode (Action-Based)
+
+```
+User -> Action
+```
+
+Only direct permissions. Users get actions assigned directly.
+
+### FULL Mode (Combined)
+
+```
+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
+```
+
+---
+
+## Permission Logic
+
+Complex rules using AND/OR operators:
+
+```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'
+}
+```
+
+### Example: Nested Logic
+
+```typescript
+const logic: LogicNode = {
+  id: 'root',
+  type: 'group',
+  operator: 'AND',
+  children: [
+    { id: '1', type: 'action', actionId: 'employee-action-id' },
+    {
+      id: '2',
+      type: 'group',
+      operator: 'OR',
+      children: [
+        { id: '2-1', type: 'action', actionId: 'department-head' },
+        { id: '2-2', type: 'action', actionId: 'hr-clearance' },
+      ],
+    },
+  ],
+};
+// User must have employee AND (department-head OR hr-clearance)
+```
+
+---
+
+## Services
+
+### ActionService
+
+```typescript
+import { ActionService } from '@flusys/nestjs-iam';
+
+// Create action
+await actionService.insert({
+  name: 'View Users',
+  code: 'user.view',
+  actionType: ActionType.BACKEND,
+  parentId: parentAction.id,
+});
+
+// Get hierarchical tree
+const tree = await actionService.getActionTree(user, 'search', true, false);
+
+// Get actions for permission (company-filtered)
+const actions = await actionService.getActionsForPermission(user);
+```
+
+### RoleService
+
+```typescript
+import { RoleService } from '@flusys/nestjs-iam';
+
+// Create role
+await roleService.insert({
+  name: 'Administrator',
+  description: 'Full system access',
+  companyId: 'company-id',
+});
+```
+
+### PermissionService
+
+```typescript
+import { PermissionService } from '@flusys/nestjs-iam';
+
+// Assign roles to user
+await permissionService.assignUserRoles({
+  userId: 'user-id',
+  companyId: 'company-id',
+  branchId: null, // null = ALL branches
+  items: [{ id: 'role-id', action: PermissionAction.ADD }],
+});
+
+// Assign actions directly
+await permissionService.assignUserActions({
+  userId: 'user-id',
+  companyId: 'company-id',
+  branchId: 'branch-id',
+  items: [{ id: 'action-id', action: PermissionAction.ADD }],
+});
+
+// Assign actions to role
+await permissionService.assignRoleActions({
+  roleId: 'role-id',
+  items: [{ id: 'action-id', action: PermissionAction.ADD }],
+});
+
+// Get user's permissions
+const permissions = await permissionService.getMyPermissions(
+  userId, branchId, companyId, parentCodes
+);
+```
+
+### PermissionCacheService
+
+```typescript
+import { PermissionCacheService } from '@flusys/nestjs-iam';
+
+// Set permissions
+await cacheService.setPermissions(
+  { userId, companyId, branchId, enableCompanyFeature: true },
+  ['users.read', 'users.write']
+);
+
+// Invalidate user cache
+await cacheService.invalidateUser('user-id', 'company-id', ['branch-id']);
+
+// Invalidate role members
+await cacheService.invalidateRole('role-id', userIds, 'company-id');
+```
+
+**Cache Key Format:**
+```
+permissions:user:{userId}                                        // Without company
+permissions:company:{companyId}:branch:{branchId}:user:{userId}  // With company
+```
+
+---
+
+## REST API Endpoints
+
+### Actions API
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/iam/actions/insert` | POST | Create action |
+| `/iam/actions/get-all` | POST | List actions (paginated) |
+| `/iam/actions/get/:id` | GET | Get action by ID |
+| `/iam/actions/tree` | POST | Get hierarchical tree (ALL actions) |
+| `/iam/actions/tree-for-permission` | GET | Get company-filtered actions |
+| `/iam/actions/update` | POST | Update action |
+| `/iam/actions/delete` | POST | Delete action |
+
+### Roles API
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/iam/roles/insert` | POST | Create role |
+| `/iam/roles/get-all` | POST | List roles (paginated) |
+| `/iam/roles/get/:id` | GET | Get role by ID |
+| `/iam/roles/update` | POST | Update role |
+| `/iam/roles/delete` | POST | Delete role |
+
+### 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
+}
+```
+
+---
+
+## Multi-Tenant Support
+
+### Company Feature Toggle
+
+```typescript
+// config/app.config.ts
+export const bootstrapAppConfig: IBootstrapAppConfig = {
+  databaseMode: 'single',
+  enableCompanyFeature: true, // or false
+};
+```
+
+### When `enableCompanyFeature: true`
+
+- `companyId` and `branchId` fields available in DTOs
+- Company-Action Permissions controller registered
+- Three-level permission granularity (Global, Company-wide, Branch-specific)
+- Uses `UserIamPermissionWithCompany` and `RoleWithCompany` entities
+
+### When `enableCompanyFeature: false`
+
+- Company endpoints NOT available (404)
+- `companyId`/`branchId` fields visible in Swagger but ignored
+- All permissions are global
+- Uses `UserIamPermission` and `Role` entities
+
+### Permission Merging
+
+When user logs in, `getMyPermissions` merges:
+1. Company-wide roles (branchId=null) + Branch-specific roles
+2. Actions from all merged roles
+3. Company-wide user actions + Branch-specific user actions
+
+**Result:** Complete permission set without duplicates.
+
+---
+
+## Permission Guard Integration
+
+```typescript
+import { PermissionGuard } from '@flusys/nestjs-shared/guards';
+import { RequirePermission, RequireAnyPermission } from '@flusys/nestjs-shared/decorators';
+
+@Controller('users')
+export class UserController {
+  @RequirePermission('user.view')
+  @Get()
+  getUsers() {}
+
+  @RequireAnyPermission('user.create', 'admin')
+  @Post()
+  createUser() {}
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Action Code Naming
+
+```typescript
+// Hierarchical naming for backend
+'user.view', 'user.create', 'user.delete'
+
+// UPPERCASE for frontend actions
+'MENU_USERS', 'MENU_REPORTS', 'FEATURE_EXPORT'
+```
+
+### 2. Company-wide vs Branch-specific
+
+```typescript
+// Company-wide for managers across ALL branches
+{ companyId: 'company-a', branchId: null }
+
+// Branch-specific for location-bound staff
+{ companyId: 'company-a', branchId: 'branch-x' }
+```
+
+### 3. Use Roles for Common Patterns
+
+```typescript
+// Create roles for common permission sets
+const roles = [
+  { name: 'Viewer', actions: ['*.view'] },
+  { name: 'Editor', actions: ['*.view', '*.create', '*.update'] },
+  { name: 'Admin', actions: ['*'] },
+];
+```
+
+### 4. Use Direct Actions Sparingly
+
+Direct actions should be exceptions and branch-specific overrides, not the primary permission mechanism.
+
+---
+
+## API Reference
+
+### Module
+
+```typescript
+import { IAMModule, IAMPermissionMode } from '@flusys/nestjs-iam';
+```
+
+### Services
+
+```typescript
+import {
+  ActionService,
+  RoleService,
+  PermissionService,
+  PermissionCacheService,
+  IAMConfigService,
+  IAMDataSourceProvider,
+} from '@flusys/nestjs-iam';
+```
+
+### Entities
+
+```typescript
+import {
+  Action,
+  Role,
+  RoleWithCompany,
+  UserIamPermission,
+  UserIamPermissionWithCompany,
+  getIAMEntitiesByConfig,
+} from '@flusys/nestjs-iam/entities';
+```
+
+### DTOs
+
+```typescript
+import {
+  CreateActionDto,
+  UpdateActionDto,
+  CreateRoleDto,
+  UpdateRoleDto,
+  AssignUserActionsDto,
+  AssignUserRolesDto,
+  AssignRoleActionsDto,
+  AssignCompanyActionsDto,
+  MyPermissionsResponseDto,
+  FrontendActionDto,
+} from '@flusys/nestjs-iam/dtos';
+```
+
+### Enums
+
+```typescript
+import {
+  ActionType,
+  IAMPermissionMode,
+  IamPermissionType,
+  IamEntityType,
+} from '@flusys/nestjs-iam/enums';
+```
+
+### Helpers
+
+```typescript
+import {
+  PermissionEvaluatorHelper,
+  PermissionModeHelper,
+} from '@flusys/nestjs-iam/helpers';
+```
+
+---
+
+## Package Architecture
+
+```
+nestjs-iam/src/
+├── modules/
+│   └── iam.module.ts              # Main module with dynamic config
+├── entities/
+│   ├── action-base.entity.ts      # Action base fields
+│   ├── action.entity.ts           # Action entity
+│   ├── role-base.entity.ts        # Role base fields
+│   ├── role.entity.ts             # Role (no company)
+│   ├── role-with-company.entity.ts
+│   ├── permission-base.entity.ts  # Permission base fields
+│   ├── user-iam-permission.entity.ts
+│   └── permission-with-company.entity.ts
+├── 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
+├── controllers/
+│   ├── action.controller.ts
+│   ├── role.controller.ts
+│   ├── my-permission.controller.ts
+│   ├── role-permission.controller.ts
+│   ├── user-action-permission.controller.ts
+│   └── company-action-permission.controller.ts
+├── helpers/
+│   ├── permission-evaluator.helper.ts
+│   └── permission-mode.helper.ts
+├── dtos/
+│   ├── action.dto.ts
+│   ├── role.dto.ts
+│   └── permission.dto.ts
+├── interfaces/
+│   ├── action.interface.ts
+│   ├── role.interface.ts
+│   └── iam-module-options.interface.ts
+├── enums/
+│   ├── action-type.enum.ts
+│   └── permission-type.enum.ts
+└── types/
+    └── logic-node.type.ts
+```
+
+---
+
+**Last Updated:** 2026-02-09 | **Version:** 4.4.1
+
+**Recent Changes (2026-02-09):**
+- Added explicit `@Inject()` decorators to all services for esbuild bundling compatibility
+- All services use REQUEST scope with lazy repository initialization via DataSource Provider pattern

package/cjs/config/iam.constants.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "IAM_MODULE_OPTIONS", {
+    enumerable: true,
+    get: function() {
+        return IAM_MODULE_OPTIONS;
+    }
+});
+const IAM_MODULE_OPTIONS = 'IAM_MODULE_OPTIONS';

package/cjs/config/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./iam.constants"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}