@flusys/nestjs-iam 6.0.2 → 6.1.1

package/cjs/services/permission-cache.service.spec.js

@@ -0,0 +1,699 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+const _nestjsshared = require("@flusys/nestjs-shared");
+const _repositorymock = require("@test-utils/mocks/repository.mock");
+const _actionentity = require("../entities/action.entity");
+const _rolewithcompanyentity = require("../entities/role-with-company.entity");
+const _roleentity = require("../entities/role.entity");
+const _actiontypeenum = require("../enums/action-type.enum");
+const _iamentitytypeenum = require("../enums/iam-entity-type.enum");
+const _iampermissiontypeenum = require("../enums/iam-permission-type.enum");
+const _permissiontypeenum = require("../enums/permission-type.enum");
+const _permissioncacheservice = require("./permission-cache.service");
+function buildCacheData(overrides = {}) {
+    return {
+        frontendActions: [],
+        backendCodes: [],
+        ...overrides
+    };
+}
+function buildPermissionRow(overrides = {}) {
+    const row = {
+        id: 'perm-uuid-1',
+        permissionType: _iampermissiontypeenum.IamPermissionType.USER_ACTION,
+        sourceType: _iamentitytypeenum.IamEntityType.USER,
+        sourceId: 'user-1',
+        targetType: _iamentitytypeenum.IamEntityType.ACTION,
+        targetId: 'action-1',
+        companyId: null,
+        branchId: null,
+        validFrom: null,
+        validUntil: null,
+        reason: null,
+        createdAt: new Date(),
+        ...overrides
+    };
+    row.isValid = (now = new Date())=>{
+        if (row.validFrom && now < row.validFrom) return false;
+        if (row.validUntil && now > row.validUntil) return false;
+        return true;
+    };
+    return row;
+}
+function buildAction(overrides = {}) {
+    return {
+        id: 'action-1',
+        name: 'View Users',
+        code: 'user.view',
+        description: null,
+        actionType: _actiontypeenum.ActionType.BACKEND,
+        parentId: null,
+        isActive: true,
+        ...overrides
+    };
+}
+function mockRawMany(repo, rows) {
+    const builder = {
+        select: jest.fn().mockReturnThis(),
+        addSelect: jest.fn().mockReturnThis(),
+        where: jest.fn().mockReturnThis(),
+        andWhere: jest.fn().mockReturnThis(),
+        getRawMany: jest.fn().mockResolvedValue(rows)
+    };
+    repo.createQueryBuilder.mockReturnValue(builder);
+    return builder;
+}
+describe('PermissionCacheService', ()=>{
+    let mockCacheManager;
+    let mockIamConfigService;
+    let mockPermissionRepo;
+    let mockActionRepo;
+    let mockRoleRepo;
+    let mockDataSourceProvider;
+    beforeEach(()=>{
+        mockCacheManager = {
+            get: jest.fn(),
+            set: jest.fn(),
+            del: jest.fn()
+        };
+        mockIamConfigService = {
+            isCompanyFeatureEnabled: jest.fn().mockReturnValue(false),
+            getPermissionMode: jest.fn().mockReturnValue(_permissiontypeenum.IAMPermissionMode.FULL)
+        };
+        mockPermissionRepo = (0, _repositorymock.createMockRepository)();
+        mockActionRepo = (0, _repositorymock.createMockRepository)();
+        mockRoleRepo = (0, _repositorymock.createMockRepository)();
+        mockDataSourceProvider = {
+            getRepository: jest.fn((entity)=>{
+                if (entity === _actionentity.Action) return Promise.resolve(mockActionRepo);
+                if (entity === _roleentity.Role || entity === _rolewithcompanyentity.RoleWithCompany) return Promise.resolve(mockRoleRepo);
+                return Promise.resolve(mockPermissionRepo);
+            }),
+            getDataSource: jest.fn()
+        };
+    });
+    function buildService(guardConfig) {
+        return new _permissioncacheservice.PermissionCacheService(mockCacheManager, mockIamConfigService, mockDataSourceProvider, guardConfig);
+    }
+    describe('setMyPermissions / getMyPermissions', ()=>{
+        it('stores data under the user-scoped key and tracks it', async ()=>{
+            const service = buildService();
+            mockCacheManager.get.mockResolvedValue(undefined);
+            const data = buildCacheData({
+                backendCodes: [
+                    'user.read'
+                ]
+            });
+            await service.setMyPermissions({
+                userId: 'user-1'
+            }, data);
+            const expectedKey = (0, _nestjsshared.buildPermissionCacheKey)({
+                userId: 'user-1'
+            });
+            expect(mockCacheManager.set).toHaveBeenCalledWith(expectedKey, data, expect.any(Number));
+            // no company scope -> the raw cache key itself is tracked directly in the scopes index
+            expect(mockCacheManager.set).toHaveBeenCalledWith(expect.stringContaining('permission-tracked-scopes:user:user-1'), [
+                expectedKey
+            ], expect.any(Number));
+            expect(mockCacheManager.set).not.toHaveBeenCalledWith(expect.stringContaining('permission-tracked-keys'), expect.anything(), expect.any(Number));
+        });
+        it('does not duplicate an already-tracked key', async ()=>{
+            const service = buildService();
+            const expectedKey = (0, _nestjsshared.buildPermissionCacheKey)({
+                userId: 'user-1'
+            });
+            mockCacheManager.get.mockImplementation(async (key)=>{
+                if (key.includes('permission-tracked-keys')) return [
+                    expectedKey
+                ];
+                if (key.includes('permission-tracked-scopes')) return [
+                    'none'
+                ];
+                return undefined;
+            });
+            await service.setMyPermissions({
+                userId: 'user-1'
+            }, buildCacheData());
+            const trackedKeysCalls = mockCacheManager.set.mock.calls.filter(([key])=>String(key).includes('permission-tracked-keys'));
+            expect(trackedKeysCalls).toHaveLength(0);
+        });
+        it('returns cached data on a hit', async ()=>{
+            const service = buildService();
+            const data = buildCacheData({
+                backendCodes: [
+                    'a.b'
+                ]
+            });
+            mockCacheManager.get.mockResolvedValue(data);
+            const result = await service.getMyPermissions({
+                userId: 'user-1'
+            });
+            expect(result).toBe(data);
+        });
+        it('returns null on a cache miss', async ()=>{
+            const service = buildService();
+            mockCacheManager.get.mockResolvedValue(undefined);
+            const result = await service.getMyPermissions({
+                userId: 'user-1'
+            });
+            expect(result).toBeNull();
+        });
+        it('returns null (not throw) when the cache backend errors', async ()=>{
+            const service = buildService();
+            mockCacheManager.get.mockRejectedValue(new Error('cache down'));
+            const result = await service.getMyPermissions({
+                userId: 'user-1'
+            });
+            expect(result).toBeNull();
+        });
+        it('uses the company-scoped key when guard config enables company scope', async ()=>{
+            const guardConfig = {
+                enableCompanyFeature: true
+            };
+            const service = buildService(guardConfig);
+            mockCacheManager.get.mockResolvedValue(undefined);
+            await service.setMyPermissions({
+                userId: 'user-1',
+                companyId: 'company-1'
+            }, buildCacheData());
+            const expectedKey = (0, _nestjsshared.buildPermissionCacheKey)({
+                userId: 'user-1',
+                companyId: 'company-1'
+            }, guardConfig);
+            expect(mockCacheManager.set).toHaveBeenCalledWith(expectedKey, expect.anything(), expect.any(Number));
+        });
+    });
+    describe('invalidateUser', ()=>{
+        it('invalidates only the given company scope when companyId is provided, narrowing the scopes index', async ()=>{
+            const service = buildService();
+            const trackedKeysKey = 'permission-tracked-keys:user:user-1:company:company-1';
+            mockCacheManager.get.mockImplementation(async (key)=>{
+                if (key.includes('permission-tracked-keys')) return [
+                    'tracked-key-1',
+                    'tracked-key-2'
+                ];
+                if (key.includes('permission-tracked-scopes')) return [
+                    trackedKeysKey,
+                    'other-scope'
+                ];
+                return undefined;
+            });
+            await service.invalidateUser('user-1', 'company-1');
+            expect(mockCacheManager.del).toHaveBeenCalledWith('tracked-key-1');
+            expect(mockCacheManager.del).toHaveBeenCalledWith('tracked-key-2');
+            expect(mockCacheManager.del).toHaveBeenCalledWith(expect.stringContaining('permission-tracked-keys:user:user-1:company:company-1'));
+            // the invalidated scope is dropped from the index, but the index survives since another scope remains
+            expect(mockCacheManager.set).toHaveBeenCalledWith(expect.stringContaining('permission-tracked-scopes:user:user-1'), [
+                'other-scope'
+            ], expect.any(Number));
+            expect(mockCacheManager.del).not.toHaveBeenCalledWith(expect.stringContaining('permission-tracked-scopes'));
+        });
+        it('invalidates only the requested branch keys, keeping remaining branches tracked', async ()=>{
+            // company-scoped key format only differentiates by branchId when the guard config
+            // enables the company feature — otherwise every branch maps to the same cache key.
+            const guardConfig = {
+                enableCompanyFeature: true
+            };
+            const service = buildService(guardConfig);
+            const keptKey = (0, _nestjsshared.buildPermissionCacheKey)({
+                userId: 'user-1',
+                companyId: 'company-1',
+                branchId: 'branch-keep'
+            }, guardConfig);
+            mockCacheManager.get.mockImplementation(async (key)=>{
+                if (key.includes('permission-tracked-keys')) return [
+                    keptKey,
+                    'some-other-tracked-key'
+                ];
+                return undefined;
+            });
+            // companyId given directly invokes invalidateScope (bypasses the tracked-scopes fan-out)
+            await service.invalidateUser('user-1', 'company-1', [
+                'branch-a'
+            ]);
+            // the specific branch key gets deleted
+            const deletedKeys = mockCacheManager.del.mock.calls.map(([key])=>key);
+            expect(deletedKeys).toContain((0, _nestjsshared.buildPermissionCacheKey)({
+                userId: 'user-1',
+                companyId: 'company-1',
+                branchId: 'branch-a'
+            }, guardConfig));
+            // remaining tracked keys get re-saved rather than the tracked-keys index being wiped
+            expect(mockCacheManager.set).toHaveBeenCalledWith(expect.stringContaining('permission-tracked-keys'), expect.arrayContaining([
+                keptKey,
+                'some-other-tracked-key'
+            ]), expect.any(Number));
+        });
+        it('deletes the tracked-keys index entirely when no remaining keys are left after branch filtering', async ()=>{
+            const guardConfig = {
+                enableCompanyFeature: true
+            };
+            const service = buildService(guardConfig);
+            const onlyKey = (0, _nestjsshared.buildPermissionCacheKey)({
+                userId: 'user-1',
+                companyId: 'company-1',
+                branchId: 'branch-a'
+            }, guardConfig);
+            mockCacheManager.get.mockImplementation(async (key)=>{
+                if (key.includes('permission-tracked-keys')) return [
+                    onlyKey
+                ];
+                return undefined;
+            });
+            await service.invalidateUser('user-1', 'company-1', [
+                'branch-a'
+            ]);
+            const deletedKeys = mockCacheManager.del.mock.calls.map(([key])=>key);
+            expect(deletedKeys).toContain(onlyKey);
+            expect(deletedKeys.some((k)=>String(k).includes('permission-tracked-keys'))).toBe(true);
+        });
+        it('without a companyId, invalidates every tracked scope for the user and clears the scopes index', async ()=>{
+            const service = buildService();
+            // scopes list mixes a nested tracked-keys index (company scope) with a raw cache key (untracked scope)
+            const trackedKeysKey = 'permission-tracked-keys:user:user-1:company:company-a';
+            const rawKey = 'my-permissions:user:user-1';
+            mockCacheManager.get.mockImplementation(async (key)=>{
+                if (key.includes('permission-tracked-scopes')) return [
+                    trackedKeysKey,
+                    rawKey
+                ];
+                if (key === trackedKeysKey) return [
+                    'key-company-a-1'
+                ];
+                return undefined;
+            });
+            await service.invalidateUser('user-1');
+            expect(mockCacheManager.del).toHaveBeenCalledWith('key-company-a-1');
+            expect(mockCacheManager.del).toHaveBeenCalledWith(trackedKeysKey);
+            expect(mockCacheManager.del).toHaveBeenCalledWith(rawKey);
+            expect(mockCacheManager.del).toHaveBeenCalledWith(expect.stringContaining('permission-tracked-scopes:user:user-1'));
+        });
+        it('treats a cache read error for tracked scopes as an empty list (no throw)', async ()=>{
+            const service = buildService();
+            mockCacheManager.get.mockRejectedValue(new Error('down'));
+            await expect(service.invalidateUser('user-1')).resolves.toBeUndefined();
+            expect(mockCacheManager.del).toHaveBeenCalledWith(expect.stringContaining('permission-tracked-scopes:user:user-1'));
+        });
+    });
+    describe('invalidateUsers', ()=>{
+        it('returns 0 immediately for an empty user list', async ()=>{
+            const service = buildService();
+            const result = await service.invalidateUsers([]);
+            expect(result).toBe(0);
+            expect(mockCacheManager.get).not.toHaveBeenCalled();
+        });
+        it('invalidates every user and returns the count of successful invalidations', async ()=>{
+            const service = buildService();
+            mockCacheManager.get.mockResolvedValue(undefined);
+            const result = await service.invalidateUsers([
+                'user-1',
+                'user-2',
+                'user-3'
+            ], 'company-1');
+            expect(result).toBe(3);
+        });
+        it('does not let one user failing prevent the others from being counted', async ()=>{
+            const service = buildService();
+            let callCount = 0;
+            mockCacheManager.get.mockImplementation(async ()=>{
+                callCount += 1;
+                if (callCount === 1) throw new Error('boom');
+                return undefined;
+            });
+            const result = await service.invalidateUsers([
+                'user-1',
+                'user-2'
+            ], 'company-1');
+            // invalidateUser swallows its own read errors, so both still resolve successfully
+            expect(result).toBe(2);
+        });
+    });
+    describe('getMyPermissionsResponse', ()=>{
+        it('returns the response built directly from cached data on a cache hit', async ()=>{
+            const service = buildService();
+            mockCacheManager.get.mockResolvedValue(buildCacheData({
+                frontendActions: [
+                    {
+                        id: 'action-1',
+                        code: 'user.view',
+                        name: 'View',
+                        description: null,
+                        parentId: null
+                    }
+                ],
+                backendCodes: [
+                    'user.read'
+                ]
+            }));
+            const result = await service.getMyPermissionsResponse('user-1', null, 'company-1');
+            expect(result.frontendActions).toHaveLength(1);
+            expect(result.cachedEndpoints).toBe(1);
+            expect(mockPermissionRepo.find).not.toHaveBeenCalled();
+        });
+        it('fetches from the database and caches the result on a cache miss', async ()=>{
+            const service = buildService();
+            mockCacheManager.get.mockResolvedValue(undefined);
+            mockPermissionRepo.find.mockResolvedValue([]);
+            const result = await service.getMyPermissionsResponse('user-1', null, null);
+            expect(result).toEqual({
+                frontendActions: [],
+                cachedEndpoints: 0
+            });
+            expect(mockCacheManager.set).toHaveBeenCalledWith(expect.any(String), {
+                frontendActions: [],
+                backendCodes: []
+            }, expect.any(Number));
+        });
+        it('filters frontend actions by parentCodes when provided', async ()=>{
+            const service = buildService();
+            mockCacheManager.get.mockImplementation(async (key)=>{
+                if (key.includes('permission-tracked')) return undefined;
+                return buildCacheData({
+                    frontendActions: [
+                        {
+                            id: 'child-1',
+                            code: 'user.view',
+                            name: 'View',
+                            description: null,
+                            parentId: 'parent-1'
+                        },
+                        {
+                            id: 'child-2',
+                            code: 'other.view',
+                            name: 'View 2',
+                            description: null,
+                            parentId: 'other-parent'
+                        }
+                    ],
+                    backendCodes: []
+                });
+            });
+            mockActionRepo.find.mockResolvedValue([
+                {
+                    id: 'parent-1',
+                    code: 'user'
+                }
+            ]);
+            const result = await service.getMyPermissionsResponse('user-1', null, null, [
+                'user'
+            ]);
+            expect(result.frontendActions).toHaveLength(1);
+            expect(result.frontendActions[0].id).toBe('child-1');
+        });
+        it('returns an empty frontendActions list when parentCodes resolve to no known parents', async ()=>{
+            const service = buildService();
+            mockCacheManager.get.mockImplementation(async (key)=>{
+                if (key.includes('permission-tracked')) return undefined;
+                return buildCacheData({
+                    frontendActions: [
+                        {
+                            id: 'child-1',
+                            code: 'user.view',
+                            name: 'View',
+                            description: null,
+                            parentId: 'parent-1'
+                        }
+                    ],
+                    backendCodes: []
+                });
+            });
+            mockActionRepo.find.mockResolvedValue([]);
+            const result = await service.getMyPermissionsResponse('user-1', null, null, [
+                'unknown-parent-code'
+            ]);
+            expect(result.frontendActions).toEqual([]);
+        });
+    });
+    describe('collectAllActionIds (permission-mode branching)', ()=>{
+        it('RBAC mode: collects only role-derived action ids, ignoring direct user actions', async ()=>{
+            const service = buildService();
+            mockIamConfigService.getPermissionMode.mockReturnValue(_permissiontypeenum.IAMPermissionMode.RBAC);
+            mockPermissionRepo.find.mockImplementation(async ({ where })=>{
+                if (where.permissionType === _iampermissiontypeenum.IamPermissionType.USER_ROLE) {
+                    return [
+                        buildPermissionRow({
+                            permissionType: _iampermissiontypeenum.IamPermissionType.USER_ROLE,
+                            targetId: 'role-1'
+                        })
+                    ];
+                }
+                if (where.permissionType === _iampermissiontypeenum.IamPermissionType.ROLE_ACTION) {
+                    return [
+                        buildPermissionRow({
+                            permissionType: _iampermissiontypeenum.IamPermissionType.ROLE_ACTION,
+                            targetId: 'action-role-1'
+                        })
+                    ];
+                }
+                if (where.permissionType === _iampermissiontypeenum.IamPermissionType.USER_ACTION) {
+                    throw new Error('DIRECT lookup should not run in RBAC mode');
+                }
+                return [];
+            });
+            const result = await service.collectAllActionIds('user-1', null, null);
+            expect(Array.from(result)).toEqual([
+                'action-role-1'
+            ]);
+        });
+        it('DIRECT mode: collects only directly-assigned user action ids, ignoring roles', async ()=>{
+            const service = buildService();
+            mockIamConfigService.getPermissionMode.mockReturnValue(_permissiontypeenum.IAMPermissionMode.DIRECT);
+            mockPermissionRepo.find.mockImplementation(async ({ where })=>{
+                if (where.permissionType === _iampermissiontypeenum.IamPermissionType.USER_ROLE) {
+                    throw new Error('RBAC lookup should not run in DIRECT mode');
+                }
+                if (where.permissionType === _iampermissiontypeenum.IamPermissionType.USER_ACTION) {
+                    return [
+                        buildPermissionRow({
+                            permissionType: _iampermissiontypeenum.IamPermissionType.USER_ACTION,
+                            targetId: 'action-direct-1'
+                        })
+                    ];
+                }
+                return [];
+            });
+            const result = await service.collectAllActionIds('user-1', null, null);
+            expect(Array.from(result)).toEqual([
+                'action-direct-1'
+            ]);
+        });
+        it('FULL mode: merges role-derived and direct action ids, de-duplicating overlaps', async ()=>{
+            const service = buildService();
+            mockIamConfigService.getPermissionMode.mockReturnValue(_permissiontypeenum.IAMPermissionMode.FULL);
+            mockPermissionRepo.find.mockImplementation(async ({ where })=>{
+                if (where.permissionType === _iampermissiontypeenum.IamPermissionType.USER_ROLE) {
+                    return [
+                        buildPermissionRow({
+                            permissionType: _iampermissiontypeenum.IamPermissionType.USER_ROLE,
+                            targetId: 'role-1'
+                        })
+                    ];
+                }
+                if (where.permissionType === _iampermissiontypeenum.IamPermissionType.ROLE_ACTION) {
+                    return [
+                        buildPermissionRow({
+                            permissionType: _iampermissiontypeenum.IamPermissionType.ROLE_ACTION,
+                            targetId: 'action-shared'
+                        })
+                    ];
+                }
+                if (where.permissionType === _iampermissiontypeenum.IamPermissionType.USER_ACTION) {
+                    return [
+                        buildPermissionRow({
+                            permissionType: _iampermissiontypeenum.IamPermissionType.USER_ACTION,
+                            targetId: 'action-shared'
+                        }),
+                        buildPermissionRow({
+                            permissionType: _iampermissiontypeenum.IamPermissionType.USER_ACTION,
+                            targetId: 'action-direct-only'
+                        })
+                    ];
+                }
+                return [];
+            });
+            const result = await service.collectAllActionIds('user-1', null, null);
+            expect(Array.from(result).sort()).toEqual([
+                'action-direct-only',
+                'action-shared'
+            ]);
+        });
+        it('excludes expired/not-yet-valid permission rows via isValid()', async ()=>{
+            const service = buildService();
+            mockIamConfigService.getPermissionMode.mockReturnValue(_permissiontypeenum.IAMPermissionMode.DIRECT);
+            const expired = buildPermissionRow({
+                permissionType: _iampermissiontypeenum.IamPermissionType.USER_ACTION,
+                targetId: 'action-expired',
+                validUntil: new Date('2000-01-01')
+            });
+            const active = buildPermissionRow({
+                permissionType: _iampermissiontypeenum.IamPermissionType.USER_ACTION,
+                targetId: 'action-active'
+            });
+            mockPermissionRepo.find.mockResolvedValue([
+                expired,
+                active
+            ]);
+            const result = await service.collectAllActionIds('user-1', null, null);
+            expect(Array.from(result)).toEqual([
+                'action-active'
+            ]);
+        });
+    });
+    describe('buildAndCachePermissionData (via getMyPermissionsResponse on a cache miss)', ()=>{
+        it('splits actions into frontend/backend and caches them', async ()=>{
+            const service = buildService();
+            mockIamConfigService.getPermissionMode.mockReturnValue(_permissiontypeenum.IAMPermissionMode.DIRECT);
+            mockPermissionRepo.find.mockResolvedValue([
+                buildPermissionRow({
+                    permissionType: _iampermissiontypeenum.IamPermissionType.USER_ACTION,
+                    targetId: 'action-1'
+                })
+            ]);
+            mockCacheManager.get.mockResolvedValue(undefined);
+            mockActionRepo.find.mockResolvedValue([
+                buildAction({
+                    id: 'action-1',
+                    actionType: _actiontypeenum.ActionType.BOTH,
+                    code: 'user.view'
+                })
+            ]);
+            const result = await service.getMyPermissionsResponse('user-1', null, null);
+            expect(result.cachedEndpoints).toBe(1);
+            expect(result.frontendActions).toEqual([
+                {
+                    id: 'action-1',
+                    code: 'user.view',
+                    name: 'View Users',
+                    description: null
+                }
+            ]);
+            expect(mockCacheManager.set).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
+                backendCodes: [
+                    'user.view'
+                ]
+            }), expect.any(Number));
+        });
+    });
+    describe('invalidateCompanyMembersCache', ()=>{
+        it('returns 0 without querying when the company feature is disabled', async ()=>{
+            const service = buildService();
+            const result = await service.invalidateCompanyMembersCache('company-1');
+            expect(result).toBe(0);
+            expect(mockPermissionRepo.createQueryBuilder).not.toHaveBeenCalled();
+        });
+        it('returns 0 when the company has no members with permissions', async ()=>{
+            const service = buildService();
+            mockIamConfigService.isCompanyFeatureEnabled.mockReturnValue(true);
+            mockRawMany(mockPermissionRepo, []);
+            const result = await service.invalidateCompanyMembersCache('company-1');
+            expect(result).toBe(0);
+        });
+        it('invalidates every distinct member user id for the company', async ()=>{
+            const service = buildService();
+            mockIamConfigService.isCompanyFeatureEnabled.mockReturnValue(true);
+            mockRawMany(mockPermissionRepo, [
+                {
+                    userId: 'user-1'
+                },
+                {
+                    userId: 'user-2'
+                }
+            ]);
+            mockCacheManager.get.mockResolvedValue(undefined);
+            const result = await service.invalidateCompanyMembersCache('company-1');
+            expect(result).toBe(2);
+        });
+        it('wipes every tracked cache entry per member instead of only branches with an existing permission row', async ()=>{
+            // Company-wide action changes are merged into every branch a member queries, including
+            // branches where the member holds no explicit permission row — so invalidation must not
+            // be narrowed to whatever branch_ids happen to already exist in the permission table.
+            const service = buildService();
+            mockIamConfigService.isCompanyFeatureEnabled.mockReturnValue(true);
+            mockRawMany(mockPermissionRepo, [
+                {
+                    userId: 'user-1'
+                }
+            ]);
+            const trackedKeysKey = 'permission-tracked-keys:user:user-1:company:company-1';
+            mockCacheManager.get.mockImplementation(async (key)=>{
+                if (key.includes('permission-tracked-keys')) {
+                    return [
+                        'cached-key-branch-untracked-by-any-permission-row'
+                    ];
+                }
+                return undefined;
+            });
+            const result = await service.invalidateCompanyMembersCache('company-1');
+            const deletedKeys = mockCacheManager.del.mock.calls.map(([key])=>key);
+            expect(deletedKeys).toContain('cached-key-branch-untracked-by-any-permission-row');
+            expect(deletedKeys).toContain(trackedKeysKey);
+            expect(result).toBe(1);
+        });
+    });
+    describe('invalidateRoleMembersCache', ()=>{
+        it('returns 0 when the role has no members', async ()=>{
+            const service = buildService();
+            mockPermissionRepo.find.mockResolvedValue([]);
+            const result = await service.invalidateRoleMembersCache('role-1');
+            expect(result).toBe(0);
+            expect(mockRoleRepo.findOne).not.toHaveBeenCalled();
+        });
+        it('invalidates every distinct user holding the role, scoped to the role company', async ()=>{
+            const service = buildService();
+            mockPermissionRepo.find.mockResolvedValue([
+                buildPermissionRow({
+                    sourceId: 'user-9'
+                }),
+                buildPermissionRow({
+                    id: 'perm-2',
+                    sourceId: 'user-9'
+                })
+            ]);
+            mockRoleRepo.findOne.mockResolvedValue({
+                id: 'role-1',
+                companyId: null
+            });
+            mockCacheManager.get.mockResolvedValue(undefined);
+            const result = await service.invalidateRoleMembersCache('role-1');
+            expect(mockRoleRepo.findOne).toHaveBeenCalledWith({
+                where: {
+                    id: 'role-1'
+                }
+            });
+            expect(result).toBe(1);
+        });
+        it('wipes every tracked cache entry for role members instead of only branches with an existing permission row', async ()=>{
+            // Role actions are merged into every branch a member queries, including branches
+            // where the member holds no explicit permission row — so invalidation must not be
+            // narrowed to whatever branch_ids happen to already exist in the permission table.
+            const service = buildService();
+            mockIamConfigService.isCompanyFeatureEnabled.mockReturnValue(true);
+            mockPermissionRepo.find.mockResolvedValue([
+                buildPermissionRow({
+                    sourceId: 'user-9'
+                })
+            ]);
+            mockRoleRepo.findOne.mockResolvedValue({
+                id: 'role-1',
+                companyId: 'company-1'
+            });
+            const trackedKeysKey = 'permission-tracked-keys:user:user-9:company:company-1';
+            mockCacheManager.get.mockImplementation(async (key)=>{
+                if (key.includes('permission-tracked-keys')) {
+                    return [
+                        'cached-key-branch-untracked-by-any-permission-row'
+                    ];
+                }
+                return undefined;
+            });
+            const result = await service.invalidateRoleMembersCache('role-1');
+            expect(mockPermissionRepo.createQueryBuilder).not.toHaveBeenCalled();
+            const deletedKeys = mockCacheManager.del.mock.calls.map(([key])=>key);
+            expect(deletedKeys).toContain('cached-key-branch-untracked-by-any-permission-row');
+            expect(deletedKeys).toContain(trackedKeysKey);
+            expect(result).toBe(1);
+        });
+    });
+});