@flusys/nestjs-iam 6.0.1 → 6.1.0

package/cjs/services/iam-datasource.service.spec.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+const _modules = require("@flusys/nestjs-shared/modules");
+const _actionentity = require("../entities/action.entity");
+const _useriampermissionentity = require("../entities/user-iam-permission.entity");
+const _permissionwithcompanyentity = require("../entities/permission-with-company.entity");
+const _roleentity = require("../entities/role.entity");
+const _rolewithcompanyentity = require("../entities/role-with-company.entity");
+const _iamdatasourceservice = require("./iam-datasource.service");
+describe('IAMDataSourceService', ()=>{
+    let mockConfigService;
+    beforeEach(()=>{
+        mockConfigService = {
+            isCompanyFeatureEnabled: jest.fn().mockReturnValue(false),
+            getPermissionMode: jest.fn(),
+            getOptions: jest.fn().mockReturnValue({
+                global: false,
+                includeController: false
+            })
+        };
+    });
+    function buildService(request) {
+        return new _iamdatasourceservice.IAMDataSourceService(mockConfigService, request);
+    }
+    describe('getEnableCompanyFeatureForTenant', ()=>{
+        it('uses the tenant override when defined (true)', ()=>{
+            const service = buildService();
+            mockConfigService.isCompanyFeatureEnabled.mockReturnValue(false);
+            expect(service.getEnableCompanyFeatureForTenant({
+                enableCompanyFeature: true
+            })).toBe(true);
+        });
+        it('uses the tenant override when defined (false)', ()=>{
+            const service = buildService();
+            mockConfigService.isCompanyFeatureEnabled.mockReturnValue(true);
+            expect(service.getEnableCompanyFeatureForTenant({
+                enableCompanyFeature: false
+            })).toBe(false);
+        });
+        it('falls back to the config service when the tenant has no override', ()=>{
+            const service = buildService();
+            mockConfigService.isCompanyFeatureEnabled.mockReturnValue(true);
+            expect(service.getEnableCompanyFeatureForTenant({})).toBe(true);
+        });
+        it('falls back to the config service when no tenant is provided', ()=>{
+            const service = buildService();
+            mockConfigService.isCompanyFeatureEnabled.mockReturnValue(true);
+            expect(service.getEnableCompanyFeatureForTenant(undefined)).toBe(true);
+        });
+    });
+    describe('getEnableCompanyFeatureForCurrentTenant', ()=>{
+        it('falls back to the config service when there is no current request/tenant', ()=>{
+            const service = buildService();
+            mockConfigService.isCompanyFeatureEnabled.mockReturnValue(true);
+            expect(service.getEnableCompanyFeatureForCurrentTenant()).toBe(true);
+        });
+    });
+    describe('getIAMEntities', ()=>{
+        it('returns Action + non-company permission + role entities for RBAC mode', async ()=>{
+            mockConfigService.isCompanyFeatureEnabled.mockReturnValue(false);
+            mockConfigService.getPermissionMode.mockReturnValue(1); // RBAC
+            const service = buildService();
+            const entities = await service.getIAMEntities();
+            expect(entities).toContain(_actionentity.Action);
+            expect(entities).toContain(_useriampermissionentity.UserIamPermission);
+            expect(entities).toContain(_roleentity.Role);
+            expect(entities).not.toContain(_permissionwithcompanyentity.UserIamPermissionWithCompany);
+            expect(entities).not.toContain(_rolewithcompanyentity.RoleWithCompany);
+        });
+        it('returns company-scoped entities when company feature is enabled', async ()=>{
+            mockConfigService.isCompanyFeatureEnabled.mockReturnValue(true);
+            mockConfigService.getPermissionMode.mockReturnValue(3); // FULL
+            const service = buildService();
+            const entities = await service.getIAMEntities();
+            expect(entities).toContain(_actionentity.Action);
+            expect(entities).toContain(_permissionwithcompanyentity.UserIamPermissionWithCompany);
+            expect(entities).toContain(_rolewithcompanyentity.RoleWithCompany);
+            expect(entities).not.toContain(_useriampermissionentity.UserIamPermission);
+            expect(entities).not.toContain(_roleentity.Role);
+        });
+        it('excludes role entities entirely in DIRECT mode', async ()=>{
+            mockConfigService.isCompanyFeatureEnabled.mockReturnValue(false);
+            mockConfigService.getPermissionMode.mockReturnValue(2); // DIRECT
+            const service = buildService();
+            const entities = await service.getIAMEntities();
+            expect(entities).toEqual([
+                _actionentity.Action,
+                _useriampermissionentity.UserIamPermission
+            ]);
+        });
+    });
+    describe('createDataSourceFromConfig', ()=>{
+        it('resolves IAM entities and delegates to the parent with them', async ()=>{
+            mockConfigService.isCompanyFeatureEnabled.mockReturnValue(false);
+            mockConfigService.getPermissionMode.mockReturnValue(1); // RBAC
+            const service = buildService();
+            const fakeDataSource = {
+                isInitialized: true
+            };
+            const parentSpy = jest.spyOn(_modules.MultiTenantDataSourceService.prototype, 'createDataSourceFromConfig').mockResolvedValue(fakeDataSource);
+            const config = {
+                type: 'mysql',
+                host: 'localhost'
+            };
+            const result = await service.createDataSourceFromConfig(config);
+            expect(result).toBe(fakeDataSource);
+            expect(parentSpy).toHaveBeenCalledWith(config, [
+                _actionentity.Action,
+                _useriampermissionentity.UserIamPermission,
+                _roleentity.Role
+            ]);
+            parentSpy.mockRestore();
+        });
+    });
+});

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

@@ -2,12 +2,24 @@
 Object.defineProperty(exports, "__esModule", {
     value: true
 });
-Object.defineProperty(exports, "PermissionCacheService", {
-    enumerable: true,
-    get: function() {
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get MY_PERMISSIONS_CACHE_PREFIX () {
+        return MY_PERMISSIONS_CACHE_PREFIX;
+    },
+    get PermissionCacheKeyOptions () {
+        return _nestjsshared.PermissionCacheKeyOptions;
+    },
+    get PermissionCacheService () {
         return PermissionCacheService;
     }
 });
+const _config = require("@flusys/nestjs-core/config");
 const _nestjsshared = require("@flusys/nestjs-shared");
 const _common = require("@nestjs/common");
 function _define_property(obj, key, value) {
@@ -37,84 +49,118 @@ function _ts_param(paramIndex, decorator) {
         decorator(target, key, paramIndex);
     };
 }
+const MY_PERMISSIONS_CACHE_PREFIX = _nestjsshared.PERMISSIONS_CACHE_PREFIX;
+const NO_COMPANY_SCOPE = 'none';
 let PermissionCacheService = class PermissionCacheService {
     // Cache Key Generation
-    generateCacheKey(options) {
-        return this.buildCacheKey(this.CACHE_PREFIX, options);
+    parseDurationMs(duration) {
+        const unitMs = {
+            ms: 1,
+            s: 1000,
+            m: 60000,
+            h: 3600000,
+            d: 86400000,
+            w: 604800000
+        };
+        const match = /^(\d+)\s*(ms|s|m|h|d|w)?$/i.exec(duration.trim());
+        if (!match) {
+            return unitMs.h; // fallback: 1 hour
+        }
+        const unit = (match[2] || 'ms').toLowerCase();
+        return Number(match[1]) * unitMs[unit];
     }
-    generateMyPermissionsCacheKey(options) {
-        return this.buildCacheKey(this.MY_PERMISSIONS_PREFIX, options);
+    buildCacheKey(options) {
+        return (0, _nestjsshared.buildPermissionCacheKey)(options, this.guardConfig);
     }
-    buildCacheKey(prefix, options) {
-        const { userId, companyId, branchId, enableCompanyFeature } = options;
-        if (enableCompanyFeature && companyId) {
-            return `${prefix}:company:${companyId}:branch:${branchId || 'null'}:user:${userId}`;
-        }
-        return `${prefix}:user:${userId}`;
+    scopeToken(companyId) {
+        return companyId || NO_COMPANY_SCOPE;
     }
-    // Cache Operations
-    async setPermissions(options, permissions) {
-        const key = this.generateCacheKey(options);
-        await this.cacheManager.set(key, permissions, this.TTL);
+    buildTrackedKeysKey(userId, companyId) {
+        return `${this.TRACKED_KEYS_PREFIX}:user:${userId}:company:${this.scopeToken(companyId)}`;
     }
-    // My-Permissions Cache Operations
+    buildTrackedScopesKey(userId) {
+        return `${this.TRACKED_SCOPES_PREFIX}:user:${userId}`;
+    }
+    // Cache Operations
     async setMyPermissions(options, data) {
-        const key = this.generateMyPermissionsCacheKey(options);
+        const key = this.buildCacheKey(options);
         await this.cacheManager.set(key, data, this.TTL);
+        await this.trackKey(options.userId, key, options.companyId);
     }
     async getMyPermissions(options) {
         try {
-            const key = this.generateMyPermissionsCacheKey(options);
+            const key = this.buildCacheKey(options);
             const result = await this.cacheManager.get(key);
             return result || null;
         } catch  {
             return null;
         }
     }
-    // Action Code Cache Operations (tenant-aware for multi-tenant mode)
-    /** Generate tenant-aware cache key for action codes */ generateActionCodeCacheKey(tenantId) {
-        if (tenantId) {
-            return `${this.ACTION_CODE_PREFIX}:tenant:${tenantId}:map`;
-        }
-        return `${this.ACTION_CODE_PREFIX}:map`;
-    }
-    async setActionCodeMap(codeToIdMap, tenantId) {
-        const key = this.generateActionCodeCacheKey(tenantId);
-        await this.cacheManager.set(key, codeToIdMap, this.ACTION_CODE_TTL);
-    }
-    async getActionIdsByCodes(codes, tenantId) {
+    async trackKey(userId, key, companyId) {
         try {
-            const key = this.generateActionCodeCacheKey(tenantId);
-            const fullMap = await this.cacheManager.get(key);
-            if (!fullMap) {
-                return null;
+            const trackedKeysKey = this.buildTrackedKeysKey(userId, companyId);
+            const keys = await this.cacheManager.get(trackedKeysKey) || [];
+            if (!keys.includes(key)) {
+                keys.push(key);
+                await this.cacheManager.set(trackedKeysKey, keys, this.TTL);
             }
-            const result = {};
-            for (const code of codes){
-                if (fullMap[code]) {
-                    result[code] = fullMap[code];
-                }
+            const scopesKey = this.buildTrackedScopesKey(userId);
+            const scopes = await this.cacheManager.get(scopesKey) || [];
+            const scope = this.scopeToken(companyId);
+            if (!scopes.includes(scope)) {
+                scopes.push(scope);
+                await this.cacheManager.set(scopesKey, scopes, this.TTL);
             }
-            return Object.keys(result).length > 0 ? result : null;
         } catch  {
-            return null;
+        // tracking is best-effort; a missed entry only widens invalidation, never narrows it
         }
     }
     // Cache Invalidation
     async invalidateUser(userId, companyId, branchIds) {
-        const keysToDelete = [
-            `${this.CACHE_PREFIX}:user:${userId}`,
-            `${this.MY_PERMISSIONS_PREFIX}:user:${userId}`
-        ];
         if (companyId) {
-            const branches = branchIds?.length ? branchIds : [
-                null
-            ];
-            for (const branchId of branches){
-                keysToDelete.push(`${this.CACHE_PREFIX}:company:${companyId}:branch:${branchId || 'null'}:user:${userId}`, `${this.MY_PERMISSIONS_PREFIX}:company:${companyId}:branch:${branchId || 'null'}:user:${userId}`);
+            await this.invalidateScope(userId, companyId, branchIds);
+            return;
+        }
+        // No company scope given: clear every company/branch scope tracked for this user
+        const scopesKey = this.buildTrackedScopesKey(userId);
+        let scopes = [];
+        try {
+            scopes = await this.cacheManager.get(scopesKey) || [];
+        } catch  {
+            scopes = [];
+        }
+        await Promise.all(scopes.map((scope)=>this.invalidateScope(userId, scope === NO_COMPANY_SCOPE ? null : scope, branchIds)));
+        await this.cacheManager.del(scopesKey);
+    }
+    async invalidateScope(userId, companyId, branchIds) {
+        const keysToDelete = new Set();
+        const trackedKeysKey = this.buildTrackedKeysKey(userId, companyId);
+        let trackedKeys = [];
+        try {
+            trackedKeys = await this.cacheManager.get(trackedKeysKey) || [];
+        } catch  {
+            trackedKeys = [];
+        }
+        if (!branchIds?.length) {
+            trackedKeys.forEach((key)=>keysToDelete.add(key));
+            keysToDelete.add(trackedKeysKey);
+        } else {
+            // Branch scope given: only invalidate those branches, keep the rest tracked
+            branchIds.forEach((branchId)=>keysToDelete.add(this.buildCacheKey({
+                    userId,
+                    companyId,
+                    branchId
+                })));
+            const remainingKeys = trackedKeys.filter((key)=>!keysToDelete.has(key));
+            if (remainingKeys.length) {
+                await this.cacheManager.set(trackedKeysKey, remainingKeys, this.TTL);
+            } else {
+                keysToDelete.add(trackedKeysKey);
             }
         }
-        await Promise.all(keysToDelete.map((key)=>this.cacheManager.del(key)));
+        await Promise.all([
+            ...keysToDelete
+        ].map((key)=>this.cacheManager.del(key)));
     }
     async invalidateUsers(userIds, companyId, branchIds) {
         if (userIds.length === 0) {
@@ -123,39 +169,19 @@ let PermissionCacheService = class PermissionCacheService {
         const results = await Promise.allSettled(userIds.map((userId)=>this.invalidateUser(userId, companyId, branchIds)));
         return results.filter((r)=>r.status === 'fulfilled').length;
     }
-    async invalidateRole(_roleId, userIds, companyId, branchIds) {
-        if (userIds.length === 0) {
-            return 0;
-        }
-        return await this.invalidateUsers(userIds, companyId, branchIds);
-    }
-    constructor(cacheManager){
+    constructor(cacheManager, guardConfig){
         _define_property(this, "cacheManager", void 0);
-        _define_property(this, "TTL", void 0); // 1 hour
-        _define_property(this, "ACTION_CODE_TTL", void 0); // 2 hours for action codes (less frequent changes)
-        _define_property(this, "CACHE_PREFIX", void 0);
-        _define_property(this, "MY_PERMISSIONS_PREFIX", void 0);
-        _define_property(this, "ACTION_CODE_PREFIX", void 0);
+        _define_property(this, "guardConfig", void 0);
+        _define_property(this, "TRACKED_KEYS_PREFIX", void 0);
+        _define_property(this, "TRACKED_SCOPES_PREFIX", void 0);
+        _define_property(this, "TTL", void 0);
         this.cacheManager = cacheManager;
-        this.TTL = 3600000;
-        this.ACTION_CODE_TTL = 7200000;
-        this.CACHE_PREFIX = 'permissions';
-        this.MY_PERMISSIONS_PREFIX = 'my-permissions';
-        this.ACTION_CODE_PREFIX = 'action-codes';
+        this.guardConfig = guardConfig;
+        this.TRACKED_KEYS_PREFIX = 'permission-tracked-keys';
+        this.TRACKED_SCOPES_PREFIX = 'permission-tracked-scopes';
+        this.TTL = this.parseDurationMs(_config.envConfig.getJwtConfig().refreshExpiration);
     }
 };
-_ts_decorate([
-    (0, _nestjsshared.LogAction)({
-        action: 'permissionCache.setPermissions',
-        module: 'iam'
-    }),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", [
-        typeof PermissionCacheKeyOptions === "undefined" ? Object : PermissionCacheKeyOptions,
-        Array
-    ]),
-    _ts_metadata("design:returntype", Promise)
-], PermissionCacheService.prototype, "setPermissions", null);
 _ts_decorate([
     (0, _nestjsshared.LogAction)({
         action: 'permissionCache.setMyPermissions',
@@ -163,23 +189,11 @@ _ts_decorate([
     }),
     _ts_metadata("design:type", Function),
     _ts_metadata("design:paramtypes", [
-        typeof PermissionCacheKeyOptions === "undefined" ? Object : PermissionCacheKeyOptions,
+        typeof _nestjsshared.PermissionCacheKeyOptions === "undefined" ? Object : _nestjsshared.PermissionCacheKeyOptions,
         typeof CachedMyPermissions === "undefined" ? Object : CachedMyPermissions
     ]),
     _ts_metadata("design:returntype", Promise)
 ], PermissionCacheService.prototype, "setMyPermissions", null);
-_ts_decorate([
-    (0, _nestjsshared.LogAction)({
-        action: 'permissionCache.setActionCodeMap',
-        module: 'iam'
-    }),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", [
-        typeof Record === "undefined" ? Object : Record,
-        String
-    ]),
-    _ts_metadata("design:returntype", Promise)
-], PermissionCacheService.prototype, "setActionCodeMap", null);
 _ts_decorate([
     (0, _nestjsshared.LogAction)({
         action: 'permissionCache.invalidateUser',
@@ -206,25 +220,14 @@ _ts_decorate([
     ]),
     _ts_metadata("design:returntype", Promise)
 ], PermissionCacheService.prototype, "invalidateUsers", null);
-_ts_decorate([
-    (0, _nestjsshared.LogAction)({
-        action: 'permissionCache.invalidateRole',
-        module: 'iam'
-    }),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", [
-        String,
-        Array,
-        Object,
-        Array
-    ]),
-    _ts_metadata("design:returntype", Promise)
-], PermissionCacheService.prototype, "invalidateRole", null);
 PermissionCacheService = _ts_decorate([
     (0, _common.Injectable)(),
     _ts_param(0, (0, _common.Inject)('CACHE_INSTANCE')),
+    _ts_param(1, (0, _common.Optional)()),
+    _ts_param(1, (0, _common.Inject)(_nestjsshared.PERMISSION_GUARD_CONFIG)),
     _ts_metadata("design:type", Function),
     _ts_metadata("design:paramtypes", [
-        typeof _nestjsshared.HybridCache === "undefined" ? Object : _nestjsshared.HybridCache
+        typeof _nestjsshared.HybridCache === "undefined" ? Object : _nestjsshared.HybridCache,
+        typeof _nestjsshared.PermissionGuardConfig === "undefined" ? Object : _nestjsshared.PermissionGuardConfig
     ])
 ], PermissionCacheService);

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

@@ -0,0 +1,252 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+const _nestjsshared = require("@flusys/nestjs-shared");
+const _permissioncacheservice = require("./permission-cache.service");
+function buildCacheData(overrides = {}) {
+    return {
+        frontendActions: [],
+        backendCodes: [],
+        ...overrides
+    };
+}
+describe('PermissionCacheService', ()=>{
+    let mockCacheManager;
+    beforeEach(()=>{
+        mockCacheManager = {
+            get: jest.fn(),
+            set: jest.fn(),
+            del: jest.fn()
+        };
+    });
+    function buildService(guardConfig) {
+        return new _permissioncacheservice.PermissionCacheService(mockCacheManager, 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));
+            // tracked keys + tracked scopes get written too
+            expect(mockCacheManager.set).toHaveBeenCalledWith(expect.stringContaining('permission-tracked-keys:user:user-1'), [
+                expectedKey
+            ], expect.any(Number));
+            expect(mockCacheManager.set).toHaveBeenCalledWith(expect.stringContaining('permission-tracked-scopes:user:user-1'), [
+                'none'
+            ], 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', async ()=>{
+            const service = buildService();
+            mockCacheManager.get.mockImplementation(async (key)=>{
+                if (key.includes('permission-tracked-keys')) return [
+                    'tracked-key-1',
+                    'tracked-key-2'
+                ];
+                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'));
+            // no company scope given -> tracked-scopes key should not be touched in this branch
+            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();
+            mockCacheManager.get.mockImplementation(async (key)=>{
+                if (key.includes('permission-tracked-scopes')) return [
+                    'none',
+                    'company-a'
+                ];
+                if (key.includes('company:none')) return [
+                    'key-none-1'
+                ];
+                if (key.includes('company:company-a')) return [
+                    'key-company-a-1'
+                ];
+                return undefined;
+            });
+            await service.invalidateUser('user-1');
+            expect(mockCacheManager.del).toHaveBeenCalledWith('key-none-1');
+            expect(mockCacheManager.del).toHaveBeenCalledWith('key-company-a-1');
+            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);
+        });
+    });
+});