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

package/fesm/services/permission.service.js

@@ -0,0 +1,1010 @@
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+import { Inject, Injectable, Logger, Scope } from '@nestjs/common';
+import { In, IsNull } from 'typeorm';
+import { PermissionAction } from '../dtos/permission.dto';
+import { Action } from '../entities/action.entity';
+import { UserIamPermissionWithCompany } from '../entities/permission-with-company.entity';
+import { RoleWithCompany } from '../entities/role-with-company.entity';
+import { Role } from '../entities/role.entity';
+import { IamEntityType, IamPermissionType, UserIamPermission } from '../entities/user-iam-permission.entity';
+import { ActionType } from '../enums/action-type.enum';
+import { IAMPermissionMode } from '../enums/permission-type.enum';
+import { PermissionEvaluatorHelper } from '../helpers/permission-evaluator.helper';
+import { IAMConfigService } from './iam-config.service';
+import { IAMDataSourceProvider } from './iam-datasource.provider';
+import { PermissionCacheService } from './permission-cache.service';
+export class PermissionService {
+    // ==================== Repository Getters ====================
+    async getPermissionRepository() {
+        const enableCompanyFeature = this.iamConfigService.isCompanyFeatureEnabled();
+        const entity = enableCompanyFeature ? UserIamPermissionWithCompany : UserIamPermission;
+        return this.dataSourceProvider.getRepository(entity);
+    }
+    async getActionRepository() {
+        return this.dataSourceProvider.getRepository(Action);
+    }
+    async getRoleRepository() {
+        const enableCompanyFeature = this.iamConfigService.isCompanyFeatureEnabled();
+        const entity = enableCompanyFeature ? RoleWithCompany : Role;
+        return this.dataSourceProvider.getRepository(entity);
+    }
+    // ==================== User-Action Permissions ====================
+    async assignUserActions(dto) {
+        const permissionRepo = await this.getPermissionRepository();
+        const enableCompanyFeature = this.iamConfigService.isCompanyFeatureEnabled();
+        const branchId = dto.branchId ?? null;
+        const companyId = dto.companyId ?? null;
+        // Separate items into add and remove batches
+        const itemsToAdd = dto.items.filter((item)=>item.action === PermissionAction.ADD);
+        const itemsToRemove = dto.items.filter((item)=>item.action === PermissionAction.REMOVE);
+        let added = 0;
+        let removed = 0;
+        // Batch add: Find existing permissions in one query
+        if (itemsToAdd.length > 0) {
+            const actionIdsToAdd = itemsToAdd.map((item)=>item.id);
+            const whereFind = {
+                permissionType: IamPermissionType.USER_ACTION,
+                sourceType: IamEntityType.USER,
+                sourceId: dto.userId,
+                targetType: IamEntityType.ACTION,
+                targetId: In(actionIdsToAdd)
+            };
+            if (enableCompanyFeature) {
+                if (companyId) whereFind.companyId = companyId;
+                if (branchId) whereFind.branchId = branchId;
+            }
+            const existingPermissions = await permissionRepo.find({
+                where: whereFind,
+                select: [
+                    'targetId'
+                ]
+            });
+            const existingActionIds = new Set(existingPermissions.map((p)=>p.targetId));
+            const newPermissions = itemsToAdd.filter((item)=>!existingActionIds.has(item.id)).map((item)=>({
+                    permissionType: IamPermissionType.USER_ACTION,
+                    sourceType: IamEntityType.USER,
+                    sourceId: dto.userId,
+                    targetType: IamEntityType.ACTION,
+                    targetId: item.id,
+                    userId: dto.userId,
+                    companyId: enableCompanyFeature ? companyId : null,
+                    branchId: enableCompanyFeature ? branchId : null
+                }));
+            if (newPermissions.length > 0) {
+                await permissionRepo.save(newPermissions);
+                added = newPermissions.length;
+            }
+        }
+        // Batch remove: Delete all at once using IN clause
+        if (itemsToRemove.length > 0) {
+            const actionIdsToRemove = itemsToRemove.map((item)=>item.id);
+            const whereDelete = {
+                permissionType: IamPermissionType.USER_ACTION,
+                sourceType: IamEntityType.USER,
+                sourceId: dto.userId,
+                targetType: IamEntityType.ACTION,
+                targetId: In(actionIdsToRemove)
+            };
+            if (enableCompanyFeature) {
+                if (companyId) whereDelete.companyId = companyId;
+                if (branchId) whereDelete.branchId = branchId;
+            }
+            const result = await permissionRepo.delete(whereDelete);
+            removed = result.affected || 0;
+        }
+        // Invalidate permission cache for this user
+        await this.invalidateUserPermissionCache(dto.userId, branchId, companyId);
+        return {
+            success: true,
+            added,
+            removed,
+            message: `Successfully processed ${dto.items.length} items: ${added} added, ${removed} removed`
+        };
+    }
+    async getUserActions(userId, branchId, companyId) {
+        const permissionRepo = await this.getPermissionRepository();
+        const actionRepo = await this.getActionRepository();
+        const enableCompanyFeature = this.iamConfigService.isCompanyFeatureEnabled();
+        const where = {
+            permissionType: IamPermissionType.USER_ACTION,
+            sourceType: IamEntityType.USER,
+            sourceId: userId
+        };
+        // When company feature enabled:
+        // - companyId provided → Filter by that company (optional additional filter)
+        // - branchId provided → Filter by that branch (branch-specific actions)
+        // - branchId not provided → Filter by IS NULL (company-wide actions)
+        if (enableCompanyFeature) {
+            if (companyId) {
+                // Filter by companyId if provided
+                where.companyId = companyId;
+            }
+            if (branchId) {
+                // Branch-specific actions only
+                where.branchId = branchId;
+            } else {
+                // Company-wide actions only (branchId IS NULL)
+                where.branchId = null;
+            }
+        }
+        const permissions = await permissionRepo.find({
+            where
+        });
+        if (permissions.length === 0) {
+            return [];
+        }
+        const actionIds = permissions.map((p)=>p.targetId);
+        const actionWhere = {
+            id: In(actionIds)
+        };
+        const actions = await actionRepo.find({
+            where: actionWhere
+        });
+        const actionMap = new Map(actions.map((a)=>[
+                a.id,
+                a
+            ]));
+        return permissions.filter((p)=>actionMap.has(p.targetId)).map((p)=>{
+            const action = actionMap.get(p.targetId);
+            return {
+                id: p.id,
+                userId: p.userId,
+                actionId: action.id,
+                actionCode: action.code ?? '',
+                actionName: action.name,
+                branchId: ('branchId' in p ? p.branchId : null) ?? null,
+                createdAt: p.createdAt
+            };
+        });
+    }
+    // ==================== Role-Action Permissions ====================
+    async assignRoleActions(dto) {
+        const permissionRepo = await this.getPermissionRepository();
+        const enableCompanyFeature = this.iamConfigService.isCompanyFeatureEnabled();
+        // Fetch role companyId if company feature is enabled
+        let roleCompanyId = null;
+        if (enableCompanyFeature) {
+            const roleRepo = await this.getRoleRepository();
+            const role = await roleRepo.findOne({
+                where: {
+                    id: dto.roleId
+                },
+                select: [
+                    'id',
+                    'companyId'
+                ]
+            });
+            roleCompanyId = role?.companyId ?? null;
+        }
+        // Separate items into add and remove batches
+        const itemsToAdd = dto.items.filter((item)=>item.action === PermissionAction.ADD);
+        const itemsToRemove = dto.items.filter((item)=>item.action === PermissionAction.REMOVE);
+        let added = 0;
+        let removed = 0;
+        // Batch add: Find existing permissions in one query
+        if (itemsToAdd.length > 0) {
+            const actionIdsToAdd = itemsToAdd.map((item)=>item.id);
+            const existingPermissions = await permissionRepo.find({
+                where: {
+                    permissionType: IamPermissionType.ROLE_ACTION,
+                    sourceType: IamEntityType.ROLE,
+                    sourceId: dto.roleId,
+                    targetType: IamEntityType.ACTION,
+                    targetId: In(actionIdsToAdd)
+                },
+                select: [
+                    'targetId'
+                ]
+            });
+            const existingActionIds = new Set(existingPermissions.map((p)=>p.targetId));
+            const newPermissions = itemsToAdd.filter((item)=>!existingActionIds.has(item.id)).map((item)=>({
+                    permissionType: IamPermissionType.ROLE_ACTION,
+                    sourceType: IamEntityType.ROLE,
+                    sourceId: dto.roleId,
+                    targetType: IamEntityType.ACTION,
+                    targetId: item.id,
+                    userId: null,
+                    companyId: enableCompanyFeature ? roleCompanyId : null,
+                    branchId: null
+                }));
+            if (newPermissions.length > 0) {
+                await permissionRepo.save(newPermissions);
+                added = newPermissions.length;
+            }
+        }
+        // Batch remove: Delete all at once using IN clause
+        if (itemsToRemove.length > 0) {
+            const actionIdsToRemove = itemsToRemove.map((item)=>item.id);
+            const result = await permissionRepo.delete({
+                permissionType: IamPermissionType.ROLE_ACTION,
+                sourceType: IamEntityType.ROLE,
+                sourceId: dto.roleId,
+                targetType: IamEntityType.ACTION,
+                targetId: In(actionIdsToRemove)
+            });
+            removed = result.affected || 0;
+        }
+        // Invalidate cache for all users with this role
+        const affectedUsers = await this.invalidateRoleMembersCache(dto.roleId);
+        return {
+            success: true,
+            added,
+            removed,
+            message: `Successfully processed ${dto.items.length} items: ${added} added, ${removed} removed. Invalidated cache for ${affectedUsers} users.`
+        };
+    }
+    async getRoleActions(roleId) {
+        const permissionRepo = await this.getPermissionRepository();
+        const actionRepo = await this.getActionRepository();
+        const permissions = await permissionRepo.find({
+            where: {
+                permissionType: IamPermissionType.ROLE_ACTION,
+                sourceType: IamEntityType.ROLE,
+                sourceId: roleId
+            }
+        });
+        if (permissions.length === 0) {
+            return [];
+        }
+        const actionIds = permissions.map((p)=>p.targetId);
+        const actionWhere = {
+            id: In(actionIds)
+        };
+        const actions = await actionRepo.find({
+            where: actionWhere
+        });
+        const actionMap = new Map(actions.map((a)=>[
+                a.id,
+                a
+            ]));
+        return permissions.filter((p)=>actionMap.has(p.targetId)).map((p)=>{
+            const action = actionMap.get(p.targetId);
+            return {
+                id: p.id,
+                roleId: p.sourceId,
+                actionId: action.id,
+                actionCode: action.code ?? '',
+                actionName: action.name,
+                createdAt: p.createdAt
+            };
+        });
+    }
+    // ==================== Company-Action Permissions (Whitelist) ====================
+    /**
+   * Assign or remove actions to/from a company (whitelist)
+   * This controls which actions are available to a company
+   */ async assignCompanyActions(dto) {
+        const permissionRepo = await this.getPermissionRepository();
+        const dataSource = permissionRepo.manager.connection;
+        const itemsToAdd = dto.items.filter((item)=>item.action === PermissionAction.ADD);
+        const itemsToRemove = dto.items.filter((item)=>item.action === PermissionAction.REMOVE);
+        let added = 0;
+        let removed = 0;
+        let removedRoleActions = 0;
+        let removedUserActions = 0;
+        await dataSource.transaction(async (manager)=>{
+            const transactionalPermissionRepo = manager.getRepository(permissionRepo.target);
+            if (itemsToAdd.length > 0) {
+                added = await this.addCompanyActions(transactionalPermissionRepo, dto.companyId, itemsToAdd.map((item)=>item.id));
+            }
+            if (itemsToRemove.length > 0) {
+                const actionIdsToRemove = itemsToRemove.map((item)=>item.id);
+                const cascadeResult = await this.removeCompanyActionsWithCascade(manager, dto.companyId, actionIdsToRemove);
+                removed = cascadeResult.removedCompanyActions;
+                removedRoleActions = cascadeResult.removedRoleActions;
+                removedUserActions = cascadeResult.removedUserActions;
+            }
+        });
+        const affectedCacheEntries = await this.invalidateCompanyMembersCache(dto.companyId);
+        const cascadeInfo = removedRoleActions > 0 || removedUserActions > 0 ? ` Cascaded removal: ${removedRoleActions} role permissions, ${removedUserActions} user permissions.` : '';
+        return {
+            success: true,
+            added,
+            removed,
+            message: `Successfully processed ${dto.items.length} items: ${added} added, ${removed} removed.${cascadeInfo} Invalidated ${affectedCacheEntries} cache entries.`
+        };
+    }
+    async addCompanyActions(permissionRepo, companyId, actionIds) {
+        const existingPermissions = await permissionRepo.find({
+            where: {
+                permissionType: IamPermissionType.COMPANY_ACTION,
+                sourceType: IamEntityType.COMPANY,
+                sourceId: companyId,
+                targetType: IamEntityType.ACTION,
+                targetId: In(actionIds)
+            },
+            select: [
+                'targetId'
+            ]
+        });
+        const existingActionIds = new Set(existingPermissions.map((p)=>p.targetId));
+        const newActionIds = actionIds.filter((id)=>!existingActionIds.has(id));
+        if (newActionIds.length === 0) {
+            return 0;
+        }
+        const newPermissions = newActionIds.map((actionId)=>permissionRepo.create({
+                permissionType: IamPermissionType.COMPANY_ACTION,
+                sourceType: IamEntityType.COMPANY,
+                sourceId: companyId,
+                targetType: IamEntityType.ACTION,
+                targetId: actionId,
+                userId: null
+            }));
+        await permissionRepo.save(newPermissions);
+        return newPermissions.length;
+    }
+    async removeCompanyActionsWithCascade(manager, companyId, actionIds) {
+        const permissionEntity = this.iamConfigService.isCompanyFeatureEnabled() ? UserIamPermissionWithCompany : UserIamPermission;
+        const permissionRepo = manager.getRepository(permissionEntity);
+        const companyResult = await permissionRepo.delete({
+            permissionType: IamPermissionType.COMPANY_ACTION,
+            sourceType: IamEntityType.COMPANY,
+            sourceId: companyId,
+            targetType: IamEntityType.ACTION,
+            targetId: In(actionIds)
+        });
+        const roleEntity = this.iamConfigService.isCompanyFeatureEnabled() ? RoleWithCompany : Role;
+        const roleRepo = manager.getRepository(roleEntity);
+        const companyRoles = await roleRepo.find({
+            where: {
+                companyId,
+                deletedAt: IsNull()
+            },
+            select: [
+                'id'
+            ]
+        });
+        let removedRoleActions = 0;
+        let removedUserActions = 0;
+        if (companyRoles.length > 0) {
+            const roleIds = companyRoles.map((role)=>role.id);
+            const roleResult = await permissionRepo.delete({
+                permissionType: IamPermissionType.ROLE_ACTION,
+                sourceType: IamEntityType.ROLE,
+                sourceId: In(roleIds),
+                targetType: IamEntityType.ACTION,
+                targetId: In(actionIds)
+            });
+            removedRoleActions = roleResult.affected || 0;
+        }
+        if (this.iamConfigService.isCompanyFeatureEnabled()) {
+            const userResult = await permissionRepo.delete({
+                permissionType: IamPermissionType.USER_ACTION,
+                companyId,
+                targetType: IamEntityType.ACTION,
+                targetId: In(actionIds)
+            });
+            removedUserActions = userResult.affected || 0;
+        }
+        if (removedRoleActions > 0 || removedUserActions > 0) {
+            this.logger.log(`Cascade deleted for company ${companyId}: ${removedRoleActions} role actions, ${removedUserActions} user actions`);
+        }
+        return {
+            removedCompanyActions: companyResult.affected || 0,
+            removedRoleActions,
+            removedUserActions
+        };
+    }
+    /**
+   * Get all actions assigned to a company (whitelist)
+   */ async getCompanyActions(companyId) {
+        const permissionRepo = await this.getPermissionRepository();
+        const actionRepo = await this.getActionRepository();
+        const permissions = await permissionRepo.find({
+            where: {
+                permissionType: IamPermissionType.COMPANY_ACTION,
+                sourceType: IamEntityType.COMPANY,
+                sourceId: companyId
+            }
+        });
+        if (permissions.length === 0) {
+            return [];
+        }
+        const actionIds = permissions.map((p)=>p.targetId);
+        const actions = await actionRepo.find({
+            where: {
+                id: In(actionIds)
+            }
+        });
+        const actionMap = new Map(actions.map((a)=>[
+                a.id,
+                a
+            ]));
+        return permissions.filter((p)=>actionMap.has(p.targetId)).map((p)=>{
+            const action = actionMap.get(p.targetId);
+            return {
+                id: p.id,
+                companyId: companyId,
+                actionId: action.id,
+                actionCode: action.code ?? '',
+                actionName: action.name,
+                createdAt: p.createdAt
+            };
+        });
+    }
+    /**
+   * Get action IDs whitelisted for a company
+   * Used internally to filter actions
+   */ async getCompanyActionIds(companyId) {
+        const permissionRepo = await this.getPermissionRepository();
+        const permissions = await permissionRepo.find({
+            where: {
+                permissionType: IamPermissionType.COMPANY_ACTION,
+                sourceType: IamEntityType.COMPANY,
+                sourceId: companyId
+            },
+            select: [
+                'targetId'
+            ]
+        });
+        return permissions.map((p)=>p.targetId);
+    }
+    // ==================== User-Role Permissions ====================
+    /**
+   * Assign user to roles (branch-scoped)
+   * User roles are now branch-specific when company feature is enabled.
+   */ async assignUserRoles(dto) {
+        const permissionRepo = await this.getPermissionRepository();
+        const enableCompanyFeature = this.iamConfigService.isCompanyFeatureEnabled();
+        const branchId = dto.branchId ?? null;
+        const companyId = dto.companyId ?? null;
+        // Separate items into add and remove batches
+        const itemsToAdd = dto.items.filter((item)=>item.action === PermissionAction.ADD);
+        const itemsToRemove = dto.items.filter((item)=>item.action === PermissionAction.REMOVE);
+        let added = 0;
+        let removed = 0;
+        // Batch add: Find existing permissions in one query
+        if (itemsToAdd.length > 0) {
+            const roleIdsToAdd = itemsToAdd.map((item)=>item.id);
+            const whereFind = {
+                permissionType: IamPermissionType.USER_ROLE,
+                sourceType: IamEntityType.USER,
+                sourceId: dto.userId,
+                targetType: IamEntityType.ROLE,
+                targetId: In(roleIdsToAdd)
+            };
+            if (enableCompanyFeature) {
+                if (companyId) whereFind.companyId = companyId;
+                if (branchId) whereFind.branchId = branchId;
+            }
+            const existingPermissions = await permissionRepo.find({
+                where: whereFind,
+                select: [
+                    'targetId'
+                ]
+            });
+            const existingRoleIds = new Set(existingPermissions.map((p)=>p.targetId));
+            const newPermissions = itemsToAdd.filter((item)=>!existingRoleIds.has(item.id)).map((item)=>({
+                    permissionType: IamPermissionType.USER_ROLE,
+                    sourceType: IamEntityType.USER,
+                    sourceId: dto.userId,
+                    targetType: IamEntityType.ROLE,
+                    targetId: item.id,
+                    userId: dto.userId,
+                    companyId: enableCompanyFeature ? companyId : null,
+                    branchId: enableCompanyFeature ? branchId : null
+                }));
+            if (newPermissions.length > 0) {
+                await permissionRepo.save(newPermissions);
+                added = newPermissions.length;
+            }
+        }
+        // Batch remove: Delete all at once using IN clause
+        if (itemsToRemove.length > 0) {
+            const roleIdsToRemove = itemsToRemove.map((item)=>item.id);
+            const whereDelete = {
+                permissionType: IamPermissionType.USER_ROLE,
+                sourceType: IamEntityType.USER,
+                sourceId: dto.userId,
+                targetType: IamEntityType.ROLE,
+                targetId: In(roleIdsToRemove)
+            };
+            if (enableCompanyFeature) {
+                if (companyId) whereDelete.companyId = companyId;
+                if (branchId) whereDelete.branchId = branchId;
+            }
+            const result = await permissionRepo.delete(whereDelete);
+            removed = result.affected || 0;
+        }
+        // Invalidate permission cache for this user
+        await this.invalidateUserPermissionCache(dto.userId, branchId, companyId);
+        return {
+            success: true,
+            added,
+            removed,
+            message: `Successfully processed ${dto.items.length} items: ${added} added, ${removed} removed`
+        };
+    }
+    /**
+   * Get user's roles (branch-scoped)
+   * Returns roles assigned to user, filtered by companyId and branchId if provided.
+   */ async getUserRoles(userId, branchId, companyId) {
+        const permissionRepo = await this.getPermissionRepository();
+        const roleRepo = await this.getRoleRepository();
+        const enableCompanyFeature = this.iamConfigService.isCompanyFeatureEnabled();
+        // Build where clause with optional companyId and branchId filter
+        // When company feature enabled:
+        // - companyId provided → Filter by that company (optional additional filter)
+        // - branchId provided → Filter by that branch (branch-specific roles)
+        // - branchId not provided → Filter by IS NULL (company-wide roles)
+        const where = {
+            permissionType: IamPermissionType.USER_ROLE,
+            sourceType: IamEntityType.USER,
+            sourceId: userId
+        };
+        if (enableCompanyFeature) {
+            if (companyId) {
+                // Filter by companyId if provided
+                where.companyId = companyId;
+            }
+            if (branchId) {
+                // Branch-specific roles only
+                where.branchId = branchId;
+            } else {
+                // Company-wide roles only (branchId IS NULL)
+                where.branchId = null;
+            }
+        }
+        const permissions = await permissionRepo.find({
+            where
+        });
+        if (permissions.length === 0) {
+            return [];
+        }
+        const roleIds = permissions.map((p)=>p.targetId);
+        const roleWhere = {
+            id: In(roleIds)
+        };
+        const roles = await roleRepo.find({
+            where: roleWhere
+        });
+        const roleMap = new Map(roles.map((r)=>[
+                r.id,
+                r
+            ]));
+        return permissions.filter((p)=>roleMap.has(p.targetId)).map((p)=>{
+            const role = roleMap.get(p.targetId);
+            const permissionEntity = p;
+            return {
+                id: p.id,
+                userId: p.userId,
+                roleId: role.id,
+                roleName: role.name,
+                branchId: enableCompanyFeature ? permissionEntity.branchId ?? null : null,
+                createdAt: p.createdAt
+            };
+        });
+    }
+    // ==================== My Permissions ====================
+    /**
+   * Get user's effective permissions (cache-first approach)
+   * 1. Check cache for existing permissions
+   * 2. If cached, apply parentCodes filter and return
+   * 3. If not cached, fetch from DB, cache, and return
+   *
+   * Cache is invalidated when:
+   * - User's direct actions change (assignUserActions)
+   * - User's roles change (assignUserRoles)
+   * - Role's actions change (assignRoleActions) - affects all users with that role
+   * - Company's actions change (assignCompanyActions) - affects all users in that company
+   *
+   * @param userId - User ID
+   * @param branchId - Branch ID (null = only company-wide, value = company-wide + branch-specific)
+   * @param companyId - Company ID (for role filtering and company action whitelist)
+   * @param parentCodes - Optional parent action codes to filter by (only affects frontend actions)
+   */ async getMyPermissions(userId, branchId, companyId, parentCodes) {
+        const enableCompanyFeature = this.iamConfigService.isCompanyFeatureEnabled();
+        const cacheOptions = {
+            userId,
+            companyId,
+            branchId,
+            enableCompanyFeature
+        };
+        // Step 1: Check cache first
+        const cachedData = await this.permissionCacheService.getMyPermissions(cacheOptions);
+        if (cachedData) {
+            // Cache hit - use cached data (even if empty)
+            return this.buildResponseFromCache(cachedData, parentCodes);
+        }
+        // Step 2: Cache miss - fetch from DB and cache (even if empty)
+        const freshData = await this.fetchAndCachePermissions(userId, branchId, companyId);
+        // Step 3: Apply parentCodes filter and return
+        return this.buildResponseFromCache(freshData, parentCodes);
+    }
+    /**
+   * Build response from cached data, applying optional parentCodes filter
+   * Uses cached action code → ID mapping to avoid DB query
+   */ async buildResponseFromCache(cachedData, parentCodes) {
+        let frontendActions = cachedData.frontendActions;
+        // Apply parentCodes filter if provided
+        if (parentCodes?.length) {
+            const parentIds = await this.getParentIdsByCodesWithCache(parentCodes);
+            if (parentIds.size > 0) {
+                frontendActions = frontendActions.filter((a)=>a.parentId && parentIds.has(a.parentId));
+            } else {
+                frontendActions = [];
+            }
+        }
+        return {
+            frontendActions: frontendActions.map((a)=>({
+                    id: a.id,
+                    code: a.code,
+                    name: a.name,
+                    description: a.description
+                })),
+            cachedEndpoints: cachedData.backendCodes.length
+        };
+    }
+    /**
+   * Get parent IDs by codes, using cache first
+   */ async getParentIdsByCodesWithCache(codes) {
+        // Try cache first
+        const cachedMap = await this.permissionCacheService.getActionIdsByCodes(codes);
+        if (cachedMap) {
+            return new Set(Object.values(cachedMap));
+        }
+        // Cache miss - fetch from DB and cache
+        const actionRepo = await this.getActionRepository();
+        const allActions = await actionRepo.find({
+            select: [
+                'id',
+                'code'
+            ]
+        });
+        // Build full code → ID map and cache it
+        const fullMap = {};
+        for (const action of allActions){
+            if (action.code) {
+                fullMap[action.code] = action.id;
+            }
+        }
+        await this.permissionCacheService.setActionCodeMap(fullMap);
+        // Return only requested codes
+        return new Set(codes.map((code)=>fullMap[code]).filter(Boolean));
+    }
+    /**
+   * Fetch permissions from DB and cache them
+   * Always returns a valid cache data structure (may be empty)
+   * Empty permissions are also cached to avoid repeated DB hits
+   */ async fetchAndCachePermissions(userId, branchId, companyId) {
+        const enableCompanyFeature = this.iamConfigService.isCompanyFeatureEnabled();
+        const permissionMode = this.iamConfigService.getPermissionMode();
+        const cacheOptions = {
+            userId,
+            companyId,
+            branchId,
+            enableCompanyFeature
+        };
+        // Empty cache data for users with no permissions
+        const emptyData = {
+            frontendActions: [],
+            backendCodes: []
+        };
+        const allActionIds = new Set();
+        // Collect action IDs based on permission mode
+        if (permissionMode === IAMPermissionMode.RBAC || permissionMode === IAMPermissionMode.FULL) {
+            const userRoleIds = await this.getUserRoleIds(userId, branchId, companyId);
+            if (userRoleIds.length > 0) {
+                const roleActionIds = await this.getRoleActionIds(userRoleIds);
+                roleActionIds.forEach((id)=>allActionIds.add(id));
+            }
+        }
+        if (permissionMode === IAMPermissionMode.DIRECT || permissionMode === IAMPermissionMode.FULL) {
+            const userActionIds = await this.getUserActionIds(userId, branchId, companyId);
+            userActionIds.forEach((id)=>allActionIds.add(id));
+        }
+        if (allActionIds.size === 0) {
+            // Cache empty result to avoid repeated DB hits
+            await this.permissionCacheService.setMyPermissions(cacheOptions, emptyData);
+            return emptyData;
+        }
+        // Filter by company whitelist
+        if (enableCompanyFeature && companyId) {
+            const companyActionIds = await this.getCompanyActionIds(companyId);
+            if (companyActionIds.length > 0) {
+                const allowedActionIds = new Set(companyActionIds);
+                for (const actionId of allActionIds){
+                    if (!allowedActionIds.has(actionId)) {
+                        allActionIds.delete(actionId);
+                    }
+                }
+            }
+        }
+        if (allActionIds.size === 0) {
+            // Cache empty result to avoid repeated DB hits
+            await this.permissionCacheService.setMyPermissions(cacheOptions, emptyData);
+            return emptyData;
+        }
+        // Fetch actions from DB
+        const actionRepo = await this.getActionRepository();
+        const actions = await actionRepo.find({
+            where: {
+                id: In(Array.from(allActionIds))
+            }
+        });
+        // Separate by type
+        const backendActions = actions.filter((a)=>a.actionType === ActionType.BACKEND || a.actionType === ActionType.BOTH);
+        const frontendActions = actions.filter((a)=>a.actionType === ActionType.FRONTEND || a.actionType === ActionType.BOTH);
+        const backendCodes = backendActions.map((a)=>a.code).filter((c)=>!!c);
+        // Build cache data (includes parentId for filtering)
+        const cacheData = {
+            frontendActions: frontendActions.map((a)=>({
+                    id: a.id,
+                    code: a.code ?? '',
+                    name: a.name,
+                    description: a.description,
+                    parentId: a.parentId
+                })),
+            backendCodes
+        };
+        // Cache both: full permissions and backend codes for PermissionGuard
+        await Promise.all([
+            this.permissionCacheService.setMyPermissions(cacheOptions, cacheData),
+            this.permissionCacheService.setPermissions(cacheOptions, backendCodes)
+        ]);
+        return cacheData;
+    }
+    // ==================== Helper Methods ====================
+    /**
+   * Get role IDs assigned to a user
+   * Merges company-wide roles (branchId=null) with branch-specific roles (branchId=value)
+   *
+   * @param userId - User ID
+   * @param branchId - Branch ID (if null or not provided, only company-wide roles returned)
+   * @param companyId - Company ID for filtering roles (security)
+   * @returns Array of unique role IDs
+   */ async getUserRoleIds(userId, branchId, companyId) {
+        const permissionRepo = await this.getPermissionRepository();
+        const enableCompanyFeature = this.iamConfigService.isCompanyFeatureEnabled();
+        if (!enableCompanyFeature) {
+            // Simple case: no company feature, get all user roles
+            const permissions = await permissionRepo.find({
+                where: {
+                    permissionType: IamPermissionType.USER_ROLE,
+                    sourceType: IamEntityType.USER,
+                    sourceId: userId
+                }
+            });
+            return permissions.map((p)=>p.targetId);
+        }
+        // Company feature enabled: merge company-wide + branch-specific roles
+        const roleIds = new Set();
+        // Step 1: Get company-wide roles (branchId = null)
+        const companyWidePermissions = await permissionRepo.find({
+            where: {
+                permissionType: IamPermissionType.USER_ROLE,
+                sourceType: IamEntityType.USER,
+                sourceId: userId,
+                branchId: IsNull(),
+                companyId: companyId
+            }
+        });
+        companyWidePermissions.forEach((p)=>roleIds.add(p.targetId));
+        // Step 2: Get branch-specific roles (branchId = value) if branchId provided
+        if (branchId) {
+            const branchPermissions = await permissionRepo.find({
+                where: {
+                    permissionType: IamPermissionType.USER_ROLE,
+                    sourceType: IamEntityType.USER,
+                    sourceId: userId,
+                    branchId,
+                    companyId: companyId
+                }
+            });
+            branchPermissions.forEach((p)=>roleIds.add(p.targetId));
+        }
+        return Array.from(roleIds);
+    }
+    async getRoleActionIds(roleIds) {
+        const permissionRepo = await this.getPermissionRepository();
+        const permissions = await permissionRepo.find({
+            where: {
+                permissionType: IamPermissionType.ROLE_ACTION,
+                sourceType: IamEntityType.ROLE,
+                sourceId: In(roleIds)
+            }
+        });
+        return permissions.map((p)=>p.targetId);
+    }
+    /**
+   * Get action IDs directly assigned to a user
+   * Merges company-wide actions (branchId=null) with branch-specific actions (branchId=value)
+   *
+   * @param userId - User ID
+   * @param branchId - Branch ID (if null or not provided, only company-wide actions returned)
+   * @param companyId - Company ID for filtering actions (security)
+   * @returns Array of unique action IDs
+   */ async getUserActionIds(userId, branchId, companyId) {
+        const permissionRepo = await this.getPermissionRepository();
+        const enableCompanyFeature = this.iamConfigService.isCompanyFeatureEnabled();
+        if (!enableCompanyFeature) {
+            // Simple case: no company feature, get all user actions
+            const permissions = await permissionRepo.find({
+                where: {
+                    permissionType: IamPermissionType.USER_ACTION,
+                    sourceType: IamEntityType.USER,
+                    sourceId: userId
+                }
+            });
+            return permissions.map((p)=>p.targetId);
+        }
+        // Company feature enabled: merge company-wide + branch-specific actions
+        const actionIds = new Set();
+        // Step 1: Get company-wide actions (branchId = null, companyId = current)
+        const companyWideWhere = {
+            permissionType: IamPermissionType.USER_ACTION,
+            sourceType: IamEntityType.USER,
+            sourceId: userId,
+            branchId: IsNull()
+        };
+        if (companyId) {
+            companyWideWhere.companyId = companyId;
+        }
+        const companyWidePermissions = await permissionRepo.find({
+            where: companyWideWhere
+        });
+        companyWidePermissions.forEach((p)=>actionIds.add(p.targetId));
+        // Step 2: Get branch-specific actions (branchId = value, companyId = current) if branchId provided
+        if (branchId) {
+            const branchWhere = {
+                permissionType: IamPermissionType.USER_ACTION,
+                sourceType: IamEntityType.USER,
+                sourceId: userId,
+                branchId
+            };
+            if (companyId) {
+                branchWhere.companyId = companyId;
+            }
+            const branchPermissions = await permissionRepo.find({
+                where: branchWhere
+            });
+            branchPermissions.forEach((p)=>actionIds.add(p.targetId));
+        }
+        return Array.from(actionIds);
+    }
+    /**
+   * Invalidate permission cache for a user
+   * Delegates to PermissionCacheService
+   */ async invalidateUserPermissionCache(userId, branchId, companyId) {
+        // Wrap branchId in array if provided, otherwise invalidate null branch only
+        const branchIds = branchId !== undefined ? [
+            branchId
+        ] : [
+            null
+        ];
+        await this.permissionCacheService.invalidateUser(userId, companyId, branchIds);
+    }
+    /**
+   * Invalidate permission cache for all users with a specific role
+   * Called when role-action permissions are modified
+   * Invalidates ALL branches for affected users
+   *
+   * @param roleId - Role ID
+   * @returns Number of users whose cache was invalidated
+   */ async invalidateRoleMembersCache(roleId) {
+        const permissionRepo = await this.getPermissionRepository();
+        const roleRepo = await this.getRoleRepository();
+        const enableCompanyFeature = this.iamConfigService.isCompanyFeatureEnabled();
+        // Find all users assigned to this role with their branch IDs
+        const userRoles = await permissionRepo.find({
+            where: {
+                permissionType: IamPermissionType.USER_ROLE,
+                sourceType: IamEntityType.USER,
+                targetType: IamEntityType.ROLE,
+                targetId: roleId
+            }
+        });
+        // Get unique user IDs
+        const userIds = [
+            ...new Set(userRoles.map((ur)=>ur.sourceId))
+        ];
+        if (userIds.length === 0) {
+            return 0;
+        }
+        // Get company ID from role (if company feature enabled)
+        const role = await roleRepo.findOne({
+            where: {
+                id: roleId
+            }
+        });
+        const companyId = role?.companyId || null;
+        // Get all branch IDs for these users (to invalidate all their cached branches)
+        let branchIds = [
+            null
+        ];
+        if (enableCompanyFeature && companyId) {
+            const userBranches = await permissionRepo.createQueryBuilder('p').select('DISTINCT p.branch_id', 'branchId').where('p.user_id IN (:...userIds)', {
+                userIds
+            }).andWhere('p.company_id = :companyId', {
+                companyId
+            }).getRawMany();
+            branchIds = [
+                ...new Set(userBranches.map((p)=>p.branchId))
+            ];
+        }
+        // Invalidate cache for all users with all their branches
+        return await this.permissionCacheService.invalidateRole(roleId, userIds, companyId, branchIds);
+    }
+    /**
+   * Invalidate permission cache for all users in a company
+   * Called when company-action permissions are modified
+   * Finds all users with permissions in this company and invalidates their caches for ALL branches
+   *
+   * @param companyId - Company ID
+   * @returns Number of cache entries invalidated
+   */ async invalidateCompanyMembersCache(companyId) {
+        if (!this.iamConfigService.isCompanyFeatureEnabled()) {
+            return 0;
+        }
+        const permissionRepo = await this.getPermissionRepository();
+        // Find all unique user IDs and branch IDs that have permissions in this company
+        const userPermissions = await permissionRepo.createQueryBuilder('p').select('DISTINCT p.user_id', 'userId').addSelect('p.branch_id', 'branchId').where('p.company_id = :companyId', {
+            companyId
+        }).andWhere('p.user_id IS NOT NULL').getRawMany();
+        const userIds = [
+            ...new Set(userPermissions.map((p)=>p.userId).filter(Boolean))
+        ];
+        const branchIds = [
+            ...new Set(userPermissions.map((p)=>p.branchId))
+        ]; // includes null
+        if (userIds.length === 0) {
+            return 0;
+        }
+        return await this.permissionCacheService.invalidateUsers(userIds, companyId, branchIds);
+    }
+    // NOTE: @Inject() required for bundled code - type metadata may be lost during esbuild
+    constructor(permissionEvaluator, permissionCacheService, iamConfigService, dataSourceProvider){
+        _define_property(this, "permissionEvaluator", void 0);
+        _define_property(this, "permissionCacheService", void 0);
+        _define_property(this, "iamConfigService", void 0);
+        _define_property(this, "dataSourceProvider", void 0);
+        _define_property(this, "logger", void 0);
+        this.permissionEvaluator = permissionEvaluator;
+        this.permissionCacheService = permissionCacheService;
+        this.iamConfigService = iamConfigService;
+        this.dataSourceProvider = dataSourceProvider;
+        this.logger = new Logger(PermissionService.name);
+    }
+}
+PermissionService = _ts_decorate([
+    Injectable({
+        scope: Scope.REQUEST
+    }),
+    _ts_param(0, Inject(PermissionEvaluatorHelper)),
+    _ts_param(1, Inject(PermissionCacheService)),
+    _ts_param(2, Inject(IAMConfigService)),
+    _ts_param(3, Inject(IAMDataSourceProvider)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof PermissionEvaluatorHelper === "undefined" ? Object : PermissionEvaluatorHelper,
+        typeof PermissionCacheService === "undefined" ? Object : PermissionCacheService,
+        typeof IAMConfigService === "undefined" ? Object : IAMConfigService,
+        typeof IAMDataSourceProvider === "undefined" ? Object : IAMDataSourceProvider
+    ])
+], PermissionService);