@flusys/nestjs-iam 6.0.1 → 6.1.0

package/fesm/controllers/my-permission.controller.spec.js

@@ -0,0 +1,52 @@
+import { buildMockUser } from '@test-utils/mocks/logged-user.mock';
+import { MyPermissionController } from './my-permission.controller';
+describe('MyPermissionController', ()=>{
+    let controller;
+    let mockPermissionService;
+    beforeEach(()=>{
+        mockPermissionService = {
+            getMyPermissions: jest.fn()
+        };
+        controller = new MyPermissionController(mockPermissionService);
+    });
+    describe('getMyPermissions', ()=>{
+        it('resolves permissions for the current user, branch, and company', async ()=>{
+            const user = buildMockUser({
+                id: 'user-1',
+                companyId: 'company-1',
+                branchId: 'branch-1'
+            });
+            const permissions = {
+                menus: [],
+                actions: [
+                    'user.create'
+                ]
+            };
+            mockPermissionService.getMyPermissions.mockResolvedValue(permissions);
+            const result = await controller.getMyPermissions({
+                parentCodes: [
+                    'user'
+                ]
+            }, user);
+            expect(mockPermissionService.getMyPermissions).toHaveBeenCalledWith('user-1', 'branch-1', 'company-1', [
+                'user'
+            ]);
+            expect(result).toEqual({
+                success: true,
+                message: 'Permissions loaded successfully',
+                messageKey: expect.any(String),
+                data: permissions
+            });
+        });
+        it('passes null for missing branch and company context', async ()=>{
+            const user = buildMockUser({
+                id: 'user-1',
+                companyId: undefined,
+                branchId: undefined
+            });
+            mockPermissionService.getMyPermissions.mockResolvedValue({});
+            await controller.getMyPermissions({}, user);
+            expect(mockPermissionService.getMyPermissions).toHaveBeenCalledWith('user-1', null, null, undefined);
+        });
+    });
+});

package/fesm/controllers/role-permission.controller.spec.js

@@ -0,0 +1,136 @@
+import { ForbiddenException } from '@nestjs/common';
+import { buildMockUser } from '@test-utils/mocks/logged-user.mock';
+import { RolePermissionController } from './role-permission.controller';
+describe('RolePermissionController', ()=>{
+    let controller;
+    let mockPermissionService;
+    let mockConfig;
+    beforeEach(()=>{
+        mockPermissionService = {
+            assignRoleActions: jest.fn(),
+            getRoleActions: jest.fn(),
+            assignUserRoles: jest.fn(),
+            getUserRoles: jest.fn()
+        };
+        mockConfig = {
+            isCompanyFeatureEnabled: jest.fn().mockReturnValue(false)
+        };
+        controller = new RolePermissionController(mockPermissionService, mockConfig);
+    });
+    describe('assignRoleActions', ()=>{
+        it('assigns actions to a role and returns the operation summary', async ()=>{
+            mockPermissionService.assignRoleActions.mockResolvedValue({
+                added: 2,
+                removed: 1,
+                total: 3
+            });
+            const result = await controller.assignRoleActions({
+                roleId: 'role-1',
+                actionIds: [
+                    'action-1',
+                    'action-2'
+                ]
+            });
+            expect(mockPermissionService.assignRoleActions).toHaveBeenCalledWith({
+                roleId: 'role-1',
+                actionIds: [
+                    'action-1',
+                    'action-2'
+                ]
+            });
+            expect(result.success).toBe(true);
+            expect(result.data).toEqual({
+                added: 2,
+                removed: 1,
+                total: 3
+            });
+        });
+    });
+    describe('getRoleActions', ()=>{
+        it('returns actions assigned to the role', async ()=>{
+            mockPermissionService.getRoleActions.mockResolvedValue([
+                {
+                    actionId: 'action-1'
+                }
+            ]);
+            const result = await controller.getRoleActions({
+                roleId: 'role-1'
+            });
+            expect(mockPermissionService.getRoleActions).toHaveBeenCalledWith('role-1');
+            expect(result.data).toEqual([
+                {
+                    actionId: 'action-1'
+                }
+            ]);
+        });
+    });
+    describe('assignUserRoles', ()=>{
+        it('assigns roles to a user when the caller has access to the target company', async ()=>{
+            mockConfig.isCompanyFeatureEnabled.mockReturnValue(true);
+            const user = buildMockUser({
+                companyId: 'company-1'
+            });
+            mockPermissionService.assignUserRoles.mockResolvedValue({
+                added: 1,
+                removed: 0,
+                total: 1
+            });
+            const result = await controller.assignUserRoles({
+                userId: 'user-2',
+                roleIds: [
+                    'role-1'
+                ],
+                companyId: 'company-1'
+            }, user);
+            expect(mockPermissionService.assignUserRoles).toHaveBeenCalledWith({
+                userId: 'user-2',
+                roleIds: [
+                    'role-1'
+                ],
+                companyId: 'company-1'
+            });
+            expect(result.data).toEqual({
+                added: 1,
+                removed: 0,
+                total: 1
+            });
+        });
+        it('rejects assignment when the caller has no access to the target company', async ()=>{
+            mockConfig.isCompanyFeatureEnabled.mockReturnValue(true);
+            const user = buildMockUser({
+                companyId: 'company-1'
+            });
+            await expect(controller.assignUserRoles({
+                userId: 'user-2',
+                roleIds: [
+                    'role-1'
+                ],
+                companyId: 'company-2'
+            }, user)).rejects.toThrow(ForbiddenException);
+            expect(mockPermissionService.assignUserRoles).not.toHaveBeenCalled();
+        });
+    });
+    describe('getUserRoles', ()=>{
+        it('returns roles assigned to the user scoped by branch and company', async ()=>{
+            const user = buildMockUser({
+                companyId: 'company-1'
+            });
+            mockPermissionService.getUserRoles.mockResolvedValue([
+                {
+                    roleId: 'role-1'
+                }
+            ]);
+            const result = await controller.getUserRoles({
+                userId: 'user-2',
+                branchId: 'branch-1',
+                companyId: 'company-1'
+            }, user);
+            expect(mockPermissionService.getUserRoles).toHaveBeenCalledWith('user-2', 'branch-1', 'company-1');
+            expect(result.data).toEqual([
+                {
+                    roleId: 'role-1'
+                }
+            ]);
+        });
+    });
+});

package/fesm/controllers/role.controller.spec.js

@@ -0,0 +1,82 @@
+import { buildMockUser } from '@test-utils/mocks/logged-user.mock';
+import { RoleController } from './role.controller';
+function buildRole(overrides = {}) {
+    return {
+        id: 'role-1',
+        name: 'Admin',
+        description: null,
+        isActive: true,
+        readOnly: false,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+        ...overrides
+    };
+}
+describe('RoleController', ()=>{
+    let controller;
+    let mockRoleService;
+    beforeEach(()=>{
+        mockRoleService = {
+            insert: jest.fn(),
+            findById: jest.fn(),
+            getAll: jest.fn(),
+            update: jest.fn(),
+            delete: jest.fn()
+        };
+        controller = new RoleController(mockRoleService);
+    });
+    it('wires the injected service onto the generated controller base', ()=>{
+        expect(controller.roleService).toBe(mockRoleService);
+        expect(controller.service).toBe(mockRoleService);
+    });
+    describe('insert', ()=>{
+        it('creates a role and returns the mapped response', async ()=>{
+            const user = buildMockUser();
+            mockRoleService.insert.mockResolvedValue(buildRole());
+            const result = await controller.insert({
+                name: 'Admin'
+            }, user);
+            expect(mockRoleService.insert).toHaveBeenCalledWith({
+                name: 'Admin'
+            }, user);
+            expect(result.success).toBe(true);
+            expect(result.data).toEqual(expect.objectContaining({
+                id: 'role-1',
+                name: 'Admin'
+            }));
+        });
+    });
+    describe('getAll', ()=>{
+        it('paginates roles and maps the response list', async ()=>{
+            mockRoleService.getAll.mockResolvedValue({
+                data: [
+                    buildRole()
+                ],
+                total: 1
+            });
+            const result = await controller.getAll({}, buildMockUser(), '');
+            expect(mockRoleService.getAll).toHaveBeenCalledWith('', {}, buildMockUser());
+            expect(result.data).toHaveLength(1);
+        });
+    });
+    describe('delete', ()=>{
+        it('delegates soft-delete to the service', async ()=>{
+            mockRoleService.delete.mockResolvedValue({
+                count: 1
+            });
+            const result = await controller.delete({
+                id: [
+                    'role-1'
+                ],
+                type: 'delete'
+            }, buildMockUser());
+            expect(mockRoleService.delete).toHaveBeenCalledWith({
+                id: [
+                    'role-1'
+                ],
+                type: 'delete'
+            }, buildMockUser());
+            expect(result.success).toBe(true);
+        });
+    });
+});

package/fesm/controllers/user-action-permission.controller.js

@@ -30,12 +30,10 @@ import { Body, Controller, Inject, Post, UseGuards } from '@nestjs/common';
 import { ApiBearerAuth, ApiBody, ApiOperation, ApiTags } from '@nestjs/swagger';
 import { PERMISSION_OPERATION_MESSAGES, USER_ACTION_PERMISSION_MESSAGES } from '../config';
 import { AssignUserActionsDto, GetUserActionsDto, PermissionOperationResultDto, UserActionResponseDto } from '../dtos/permission.dto';
-import { validateCompanyAccess } from '../helpers';
 import { IAMConfigService } from '../services/iam-config.service';
 import { PermissionService } from '../services/permission.service';
 export class UserActionPermissionController {
     async assignUserActions(dto, user) {
-        validateCompanyAccess(this.config, dto.companyId, user);
         const result = await this.permissionService.assignUserActions(dto);
         return {
             success: true,
@@ -50,7 +48,6 @@ export class UserActionPermissionController {
         };
     }
     async getUserActions(dto, user) {
-        validateCompanyAccess(this.config, dto.companyId, user);
         const actions = await this.permissionService.getUserActions(dto.userId, dto.branchId, dto.companyId);
         return {
             success: true,

package/fesm/controllers/user-action-permission.controller.spec.js

@@ -0,0 +1,64 @@
+import { buildMockUser } from '@test-utils/mocks/logged-user.mock';
+import { UserActionPermissionController } from './user-action-permission.controller';
+describe('UserActionPermissionController', ()=>{
+    let controller;
+    let mockPermissionService;
+    let mockConfig;
+    beforeEach(()=>{
+        mockPermissionService = {
+            assignUserActions: jest.fn(),
+            getUserActions: jest.fn()
+        };
+        mockConfig = {};
+        controller = new UserActionPermissionController(mockPermissionService, mockConfig);
+    });
+    describe('assignUserActions', ()=>{
+        it('assigns direct action permissions to a user', async ()=>{
+            const user = buildMockUser();
+            mockPermissionService.assignUserActions.mockResolvedValue({
+                added: 1,
+                removed: 0,
+                total: 1
+            });
+            const result = await controller.assignUserActions({
+                userId: 'user-2',
+                actionIds: [
+                    'action-1'
+                ]
+            }, user);
+            expect(mockPermissionService.assignUserActions).toHaveBeenCalledWith({
+                userId: 'user-2',
+                actionIds: [
+                    'action-1'
+                ]
+            });
+            expect(result.success).toBe(true);
+            expect(result.data).toEqual({
+                added: 1,
+                removed: 0,
+                total: 1
+            });
+        });
+    });
+    describe('getUserActions', ()=>{
+        it('returns direct action permissions for a user scoped by branch/company', async ()=>{
+            const user = buildMockUser();
+            mockPermissionService.getUserActions.mockResolvedValue([
+                {
+                    actionId: 'action-1'
+                }
+            ]);
+            const result = await controller.getUserActions({
+                userId: 'user-2',
+                branchId: 'branch-1',
+                companyId: 'company-1'
+            }, user);
+            expect(mockPermissionService.getUserActions).toHaveBeenCalledWith('user-2', 'branch-1', 'company-1');
+            expect(result.data).toEqual([
+                {
+                    actionId: 'action-1'
+                }
+            ]);
+        });
+    });
+});

package/fesm/docs/iam-swagger.config.js

@@ -39,6 +39,12 @@ export function iamSwaggerConfig(enableCompanyFeature = false, permissionMode =
                 'branchId'
             ]
         },
+        {
+            schemaName: 'ActionTreeForPermissionDto',
+            properties: [
+                'companyId'
+            ]
+        },
         // Response DTOs with branchId
         {
             schemaName: 'UserActionResponseDto',

package/fesm/docs/iam-swagger.config.spec.js

@@ -0,0 +1,95 @@
+import { iamSwaggerConfig } from './iam-swagger.config';
+import { IAMPermissionMode } from '../enums/permission-type.enum';
+describe('iamSwaggerConfig', ()=>{
+    it('should default to company disabled, FULL mode, single database', ()=>{
+        const config = iamSwaggerConfig();
+        expect(config.title).toBe('IAM API');
+        expect(config.path).toBe('api/docs/iam');
+        expect(config.bearerAuth).toBe(true);
+        // enableCompanyFeature defaults to false, so company-scoped exclusions apply
+        expect(config.excludeSchemaProperties?.length).toBeGreaterThan(0);
+        expect(config.excludeQueryParameters?.length).toBeGreaterThan(0);
+        expect(config.description).not.toContain('Multi-Tenant Mode');
+    });
+    it('should always exclude auth-related tags regardless of configuration', ()=>{
+        const config = iamSwaggerConfig(true, IAMPermissionMode.FULL);
+        expect(config.excludeTags).toEqual(expect.arrayContaining([
+            'Authentication',
+            'Users',
+            'Companies',
+            'Branches'
+        ]));
+    });
+    it('should exclude company-scoped schema properties and query params when company feature is off', ()=>{
+        const config = iamSwaggerConfig(false);
+        expect(config.excludeSchemaProperties).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                schemaName: 'AssignUserActionsDto',
+                properties: [
+                    'companyId',
+                    'branchId'
+                ]
+            })
+        ]));
+        expect(config.excludeQueryParameters).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                pathPattern: '/iam/permissions/user-actions/*',
+                method: 'get'
+            })
+        ]));
+        expect(config.excludeTags).toContain('IAM - Company Action Permissions');
+    });
+    it('should not exclude company-scoped schema properties, query params, or tags when company feature is on', ()=>{
+        const config = iamSwaggerConfig(true);
+        expect(config.excludeSchemaProperties).toEqual([]);
+        expect(config.excludeQueryParameters).toEqual([]);
+        expect(config.excludeTags).not.toContain('IAM - Company Action Permissions');
+    });
+    it('should hide DIRECT-mode tags in RBAC mode', ()=>{
+        const config = iamSwaggerConfig(false, IAMPermissionMode.RBAC);
+        expect(config.excludeTags).toContain('IAM - Permissions (Direct)');
+        expect(config.excludeTags).not.toContain('IAM - Permissions (RBAC)');
+        expect(config.excludeTags).not.toContain('IAM - Roles');
+    });
+    it('should hide RBAC-mode tags (including Roles) in DIRECT mode', ()=>{
+        const config = iamSwaggerConfig(false, IAMPermissionMode.DIRECT);
+        expect(config.excludeTags).toContain('IAM - Permissions (RBAC)');
+        expect(config.excludeTags).toContain('IAM - Roles');
+        expect(config.excludeTags).not.toContain('IAM - Permissions (Direct)');
+    });
+    it('should hide neither RBAC nor DIRECT tags in FULL mode', ()=>{
+        const config = iamSwaggerConfig(false, IAMPermissionMode.FULL);
+        expect(config.excludeTags).not.toContain('IAM - Permissions (RBAC)');
+        expect(config.excludeTags).not.toContain('IAM - Permissions (Direct)');
+        expect(config.excludeTags).not.toContain('IAM - Roles');
+    });
+    it('should mention multi-tenant mode in the description only for multi-tenant database mode', ()=>{
+        const multiTenant = iamSwaggerConfig(false, IAMPermissionMode.FULL, 'multi-tenant');
+        const single = iamSwaggerConfig(false, IAMPermissionMode.FULL, 'single');
+        expect(multiTenant.description).toContain('Multi-Tenant Mode');
+        expect(single.description).not.toContain('Multi-Tenant Mode');
+    });
+    it('should describe RBAC as active and DIRECT as disabled in the endpoints summary for RBAC mode', ()=>{
+        const config = iamSwaggerConfig(false, IAMPermissionMode.RBAC);
+        expect(config.description).toContain('**Roles**: CRUD operations');
+        expect(config.description).toContain('❌ **User-Actions**: Disabled (DIRECT mode not active)');
+    });
+    it('should describe DIRECT as active and Roles as disabled in the endpoints summary for DIRECT mode', ()=>{
+        const config = iamSwaggerConfig(false, IAMPermissionMode.DIRECT);
+        expect(config.description).toContain('✅ **User-Actions**: Direct action assignment to users');
+        expect(config.description).toContain('❌ **Roles**: Disabled (RBAC mode not active)');
+    });
+    it('should describe company features as active only when company feature is enabled', ()=>{
+        const withCompany = iamSwaggerConfig(true, IAMPermissionMode.FULL);
+        const withoutCompany = iamSwaggerConfig(false, IAMPermissionMode.FULL);
+        expect(withCompany.description).toContain('Company Features (Active)');
+        expect(withCompany.description).toContain('✅ **Company-Actions**: Whitelist actions for companies');
+        expect(withoutCompany.description).not.toContain('Company Features (Active)');
+        expect(withoutCompany.description).toContain('❌ **Company-Actions**: Disabled (company feature not enabled)');
+    });
+    it('should describe the current permission mode label correctly for each mode', ()=>{
+        expect(iamSwaggerConfig(false, IAMPermissionMode.RBAC).description).toContain('**RBAC** (Role-Based Access Control)');
+        expect(iamSwaggerConfig(false, IAMPermissionMode.DIRECT).description).toContain('**DIRECT** (Direct User Permissions)');
+        expect(iamSwaggerConfig(false, IAMPermissionMode.FULL).description).toContain('**FULL** (RBAC + Direct)');
+    });
+});

package/fesm/dtos/action.dto.js

@@ -199,6 +199,20 @@ _ts_decorate([
     }),
     _ts_metadata("design:type", Array)
 ], ActionTreeDto.prototype, "children", void 0);
+export class ActionTreeForPermissionDto {
+    constructor(){
+        _define_property(this, "companyId", void 0);
+    }
+}
+_ts_decorate([
+    ApiProperty({
+        description: 'Company to scope the action whitelist to. Defaults to the current user session company when omitted.',
+        required: false
+    }),
+    IsUUID(),
+    IsOptional(),
+    _ts_metadata("design:type", String)
+], ActionTreeForPermissionDto.prototype, "companyId", void 0);
 export class ActionTreeQueryDto {
     constructor(){
         _define_property(this, "search", void 0);

package/fesm/entities/index.spec.js

@@ -0,0 +1,52 @@
+import { getIAMEntitiesByConfig } from './index';
+import { Action } from './action.entity';
+import { Role } from './role.entity';
+import { RoleWithCompany } from './role-with-company.entity';
+import { UserIamPermission } from './user-iam-permission.entity';
+import { UserIamPermissionWithCompany } from './permission-with-company.entity';
+describe('getIAMEntitiesByConfig', ()=>{
+    it('should always include Action', ()=>{
+        expect(getIAMEntitiesByConfig(false)).toContain(Action);
+        expect(getIAMEntitiesByConfig(true)).toContain(Action);
+    });
+    it('should default permissionMode to FULL and include Role + UserIamPermission when company feature is off', ()=>{
+        const entities = getIAMEntitiesByConfig(false);
+        expect(entities).toEqual(expect.arrayContaining([
+            Action,
+            UserIamPermission,
+            Role
+        ]));
+        expect(entities).not.toContain(RoleWithCompany);
+        expect(entities).not.toContain(UserIamPermissionWithCompany);
+    });
+    it('should use the company-scoped permission entity when enableCompanyFeature is true', ()=>{
+        const entities = getIAMEntitiesByConfig(true, 'FULL');
+        expect(entities).toContain(UserIamPermissionWithCompany);
+        expect(entities).not.toContain(UserIamPermission);
+    });
+    it('should use the company-scoped role entity when enableCompanyFeature is true', ()=>{
+        const entities = getIAMEntitiesByConfig(true, 'RBAC');
+        expect(entities).toContain(RoleWithCompany);
+        expect(entities).not.toContain(Role);
+    });
+    it('should include Role for RBAC mode', ()=>{
+        expect(getIAMEntitiesByConfig(false, 'RBAC')).toContain(Role);
+    });
+    it('should include Role for FULL mode', ()=>{
+        expect(getIAMEntitiesByConfig(false, 'FULL')).toContain(Role);
+    });
+    it('should exclude Role entirely for DIRECT mode', ()=>{
+        const entities = getIAMEntitiesByConfig(false, 'DIRECT');
+        expect(entities).not.toContain(Role);
+        expect(entities).not.toContain(RoleWithCompany);
+        expect(entities).toEqual(expect.arrayContaining([
+            Action,
+            UserIamPermission
+        ]));
+    });
+    it('should exclude the company-scoped Role for DIRECT mode even with company feature enabled', ()=>{
+        const entities = getIAMEntitiesByConfig(true, 'DIRECT');
+        expect(entities).not.toContain(RoleWithCompany);
+        expect(entities).toContain(UserIamPermissionWithCompany);
+    });
+});

package/fesm/helpers/company-access.helper.spec.js

@@ -0,0 +1,64 @@
+import { ForbiddenException } from '@nestjs/common';
+import { AUTH_MESSAGES } from '@flusys/nestjs-shared/constants';
+import { buildMockUser } from '@test-utils/mocks/logged-user.mock';
+import { validateCompanyAccess } from './company-access.helper';
+describe('validateCompanyAccess', ()=>{
+    function buildConfig(isCompanyFeatureEnabled) {
+        return {
+            isCompanyFeatureEnabled: jest.fn().mockReturnValue(isCompanyFeatureEnabled)
+        };
+    }
+    it('does not throw when company feature is disabled', ()=>{
+        const config = buildConfig(false);
+        const user = buildMockUser({
+            companyId: 'company-uuid-1'
+        });
+        expect(()=>validateCompanyAccess(config, 'company-uuid-2', user)).not.toThrow();
+    });
+    it('does not throw when companyId is undefined', ()=>{
+        const config = buildConfig(true);
+        const user = buildMockUser({
+            companyId: 'company-uuid-1'
+        });
+        expect(()=>validateCompanyAccess(config, undefined, user)).not.toThrow();
+    });
+    it('does not throw when the companyId matches the user company', ()=>{
+        const config = buildConfig(true);
+        const user = buildMockUser({
+            companyId: 'company-uuid-1'
+        });
+        expect(()=>validateCompanyAccess(config, 'company-uuid-1', user)).not.toThrow();
+    });
+    it('throws ForbiddenException with default message/key when the company does not match', ()=>{
+        const config = buildConfig(true);
+        const user = buildMockUser({
+            companyId: 'company-uuid-1'
+        });
+        try {
+            validateCompanyAccess(config, 'company-uuid-2', user);
+            fail('expected validateCompanyAccess to throw');
+        } catch (error) {
+            expect(error).toBeInstanceOf(ForbiddenException);
+            expect(error.getResponse()).toEqual(expect.objectContaining({
+                message: 'You do not have access to this company',
+                messageKey: AUTH_MESSAGES.COMPANY_NO_ACCESS
+            }));
+        }
+    });
+    it('throws with a custom message and messageKey when provided', ()=>{
+        const config = buildConfig(true);
+        const user = buildMockUser({
+            companyId: 'company-uuid-1'
+        });
+        try {
+            validateCompanyAccess(config, 'company-uuid-2', user, 'Custom message', 'custom.message.key');
+            fail('expected validateCompanyAccess to throw');
+        } catch (error) {
+            expect(error).toBeInstanceOf(ForbiddenException);
+            expect(error.getResponse()).toEqual(expect.objectContaining({
+                message: 'Custom message',
+                messageKey: 'custom.message.key'
+            }));
+        }
+    });
+});

package/fesm/helpers/permission-mode.helper.spec.js

@@ -0,0 +1,50 @@
+import { IAMPermissionMode } from '../enums/permission-type.enum';
+import { PermissionModeHelper } from './permission-mode.helper';
+describe('PermissionModeHelper', ()=>{
+    describe('fromString', ()=>{
+        it('converts "RBAC" to IAMPermissionMode.RBAC', ()=>{
+            expect(PermissionModeHelper.fromString('RBAC')).toBe(IAMPermissionMode.RBAC);
+        });
+        it('converts "DIRECT" to IAMPermissionMode.DIRECT', ()=>{
+            expect(PermissionModeHelper.fromString('DIRECT')).toBe(IAMPermissionMode.DIRECT);
+        });
+        it('converts "FULL" to IAMPermissionMode.FULL', ()=>{
+            expect(PermissionModeHelper.fromString('FULL')).toBe(IAMPermissionMode.FULL);
+        });
+        it('defaults to FULL when the string is undefined', ()=>{
+            expect(PermissionModeHelper.fromString(undefined)).toBe(IAMPermissionMode.FULL);
+        });
+        it('defaults to FULL when the string is empty', ()=>{
+            expect(PermissionModeHelper.fromString('')).toBe(IAMPermissionMode.FULL);
+        });
+        it('defaults to FULL when the string is not a known mode', ()=>{
+            expect(PermissionModeHelper.fromString('INVALID_MODE')).toBe(IAMPermissionMode.FULL);
+        });
+        it('is case-sensitive and falls back to FULL for lowercase input', ()=>{
+            expect(PermissionModeHelper.fromString('rbac')).toBe(IAMPermissionMode.FULL);
+        });
+    });
+    describe('toString', ()=>{
+        it('converts IAMPermissionMode.RBAC to "RBAC"', ()=>{
+            expect(PermissionModeHelper.toString(IAMPermissionMode.RBAC)).toBe('RBAC');
+        });
+        it('converts IAMPermissionMode.DIRECT to "DIRECT"', ()=>{
+            expect(PermissionModeHelper.toString(IAMPermissionMode.DIRECT)).toBe('DIRECT');
+        });
+        it('converts IAMPermissionMode.FULL to "FULL"', ()=>{
+            expect(PermissionModeHelper.toString(IAMPermissionMode.FULL)).toBe('FULL');
+        });
+    });
+    describe('round trip', ()=>{
+        it('fromString(toString(mode)) returns the original mode for every enum value', ()=>{
+            const modes = [
+                IAMPermissionMode.RBAC,
+                IAMPermissionMode.DIRECT,
+                IAMPermissionMode.FULL
+            ];
+            for (const mode of modes){
+                expect(PermissionModeHelper.fromString(PermissionModeHelper.toString(mode))).toBe(mode);
+            }
+        });
+    });
+});