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

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

@@ -0,0 +1,150 @@
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+import { JwtAuthGuard, SingleResponseDto } from '@flusys/nestjs-shared';
+import { Body, Controller, Get, Inject, Param, Post, Query, UseGuards } from '@nestjs/common';
+import { ApiBearerAuth, ApiBody, ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
+import { AssignRoleActionsDto, AssignUserRolesDto, GetRoleActionsDto, GetUserRolesDto, PermissionOperationResultDto } from '../dtos/permission.dto';
+import { PermissionService } from '../services/permission.service';
+export class RolePermissionController {
+    async assignRoleActions(dto) {
+        return this.permissionService.assignRoleActions(dto);
+    }
+    async getRoleActions(roleId, query) {
+        const actions = await this.permissionService.getRoleActions(roleId);
+        return {
+            success: true,
+            message: 'Role actions retrieved successfully',
+            data: actions
+        };
+    }
+    async assignUserRoles(dto) {
+        return this.permissionService.assignUserRoles(dto);
+    }
+    async getUserRoles(userId, query) {
+        const roles = await this.permissionService.getUserRoles(userId, query.branchId, query.companyId);
+        return {
+            success: true,
+            message: 'User roles retrieved successfully',
+            data: roles
+        };
+    }
+    // NOTE: @Inject() required for bundled code - type metadata may be lost during esbuild
+    constructor(permissionService){
+        _define_property(this, "permissionService", void 0);
+        this.permissionService = permissionService;
+    }
+}
+_ts_decorate([
+    Post('role-actions/assign'),
+    ApiOperation({
+        summary: 'Assign/remove actions to/from role',
+        description: 'RBAC mode. No branch scoping.'
+    }),
+    ApiResponse({
+        status: 200,
+        type: PermissionOperationResultDto
+    }),
+    ApiBody({
+        type: AssignRoleActionsDto
+    }),
+    _ts_param(0, Body()),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof AssignRoleActionsDto === "undefined" ? Object : AssignRoleActionsDto
+    ]),
+    _ts_metadata("design:returntype", Promise)
+], RolePermissionController.prototype, "assignRoleActions", null);
+_ts_decorate([
+    Get('role-actions/:roleId'),
+    ApiOperation({
+        summary: 'Get role actions',
+        description: 'Returns actions assigned to role.'
+    }),
+    ApiResponse({
+        status: 200,
+        type: SingleResponseDto
+    }),
+    _ts_param(0, Param('roleId')),
+    _ts_param(1, Query()),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        String,
+        typeof GetRoleActionsDto === "undefined" ? Object : GetRoleActionsDto
+    ]),
+    _ts_metadata("design:returntype", Promise)
+], RolePermissionController.prototype, "getRoleActions", null);
+_ts_decorate([
+    Post('user-roles/assign'),
+    ApiOperation({
+        summary: 'Assign/remove roles to/from user',
+        description: 'RBAC mode. If company feature enabled, branchId is required.'
+    }),
+    ApiResponse({
+        status: 200,
+        type: PermissionOperationResultDto
+    }),
+    ApiBody({
+        type: AssignUserRolesDto
+    }),
+    _ts_param(0, Body()),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof AssignUserRolesDto === "undefined" ? Object : AssignUserRolesDto
+    ]),
+    _ts_metadata("design:returntype", Promise)
+], RolePermissionController.prototype, "assignUserRoles", null);
+_ts_decorate([
+    Get('user-roles/:userId'),
+    ApiOperation({
+        summary: 'Get user roles',
+        description: 'Returns roles assigned to user. Filter by companyId and branchId.'
+    }),
+    ApiResponse({
+        status: 200,
+        type: SingleResponseDto
+    }),
+    _ts_param(0, Param('userId')),
+    _ts_param(1, Query()),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        String,
+        typeof GetUserRolesDto === "undefined" ? Object : GetUserRolesDto
+    ]),
+    _ts_metadata("design:returntype", Promise)
+], RolePermissionController.prototype, "getUserRoles", null);
+RolePermissionController = _ts_decorate([
+    ApiTags('IAM - Role Permissions'),
+    Controller('iam/permissions'),
+    UseGuards(JwtAuthGuard),
+    ApiBearerAuth(),
+    _ts_param(0, Inject(PermissionService)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof PermissionService === "undefined" ? Object : PermissionService
+    ])
+], RolePermissionController);

package/fesm/controllers/role.controller.js

@@ -0,0 +1,48 @@
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+import { createApiController } from '@flusys/nestjs-shared/classes';
+import { Controller, Inject } from '@nestjs/common';
+import { ApiTags } from '@nestjs/swagger';
+import { CreateRoleDto, RoleResponseDto, UpdateRoleDto } from '../dtos/role.dto';
+import { RoleService } from '../services/role.service';
+export class RoleController extends createApiController(CreateRoleDto, UpdateRoleDto, RoleResponseDto, {
+    security: 'jwt'
+}) {
+    constructor(roleService){
+        super(roleService), _define_property(this, "roleService", void 0), this.roleService = roleService;
+    }
+}
+RoleController = _ts_decorate([
+    ApiTags('IAM - Roles'),
+    Controller('iam/roles'),
+    _ts_param(0, Inject(RoleService)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof RoleService === "undefined" ? Object : RoleService
+    ])
+], RoleController);

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

@@ -0,0 +1,100 @@
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+import { JwtAuthGuard, SingleResponseDto } from '@flusys/nestjs-shared';
+import { Body, Controller, Get, Inject, Param, Post, Query, UseGuards } from '@nestjs/common';
+import { ApiBearerAuth, ApiBody, ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
+import { AssignUserActionsDto, GetUserActionsDto, PermissionOperationResultDto } from '../dtos/permission.dto';
+import { PermissionService } from '../services/permission.service';
+export class UserActionPermissionController {
+    async assignUserActions(dto) {
+        return this.permissionService.assignUserActions(dto);
+    }
+    async getUserActions(userId, query) {
+        const actions = await this.permissionService.getUserActions(userId, query.branchId, query.companyId);
+        return {
+            success: true,
+            message: 'User actions retrieved successfully',
+            data: actions
+        };
+    }
+    // NOTE: @Inject() required for bundled code - type metadata may be lost during esbuild
+    constructor(permissionService){
+        _define_property(this, "permissionService", void 0);
+        this.permissionService = permissionService;
+    }
+}
+_ts_decorate([
+    Post('user-actions/assign'),
+    ApiOperation({
+        summary: 'Assign/remove actions to/from user',
+        description: 'Direct permissions. If company feature enabled, branchId is required.'
+    }),
+    ApiResponse({
+        status: 200,
+        type: PermissionOperationResultDto
+    }),
+    ApiBody({
+        type: AssignUserActionsDto
+    }),
+    _ts_param(0, Body()),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof AssignUserActionsDto === "undefined" ? Object : AssignUserActionsDto
+    ]),
+    _ts_metadata("design:returntype", Promise)
+], UserActionPermissionController.prototype, "assignUserActions", null);
+_ts_decorate([
+    Get('user-actions/:userId'),
+    ApiOperation({
+        summary: 'Get user direct actions',
+        description: 'Returns direct action permissions for user. Filter by companyId and branchId.'
+    }),
+    ApiResponse({
+        status: 200,
+        type: SingleResponseDto
+    }),
+    _ts_param(0, Param('userId')),
+    _ts_param(1, Query()),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        String,
+        typeof GetUserActionsDto === "undefined" ? Object : GetUserActionsDto
+    ]),
+    _ts_metadata("design:returntype", Promise)
+], UserActionPermissionController.prototype, "getUserActions", null);
+UserActionPermissionController = _ts_decorate([
+    ApiTags('IAM - User Action Permissions'),
+    Controller('iam/permissions'),
+    UseGuards(JwtAuthGuard),
+    ApiBearerAuth(),
+    _ts_param(0, Inject(PermissionService)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof PermissionService === "undefined" ? Object : PermissionService
+    ])
+], UserActionPermissionController);

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

@@ -0,0 +1,192 @@
+import { IAMPermissionMode } from '../enums/permission-type.enum';
+/** Auth-related tags that should always be excluded from IAM API docs */ const AUTH_RELATED_TAGS = [
+    'Authentication',
+    'Users',
+    'Companies',
+    'Branches',
+    'User Permissions',
+    'Company Selection'
+];
+export function iamSwaggerConfig(enableCompanyFeature = false, permissionMode = IAMPermissionMode.FULL) {
+    const excludeSchemaProperties = enableCompanyFeature ? [] : [
+        // DTOs with companyId and branchId
+        {
+            schemaName: 'AssignUserActionsDto',
+            properties: [
+                'companyId',
+                'branchId'
+            ]
+        },
+        {
+            schemaName: 'AssignUserRolesDto',
+            properties: [
+                'companyId',
+                'branchId'
+            ]
+        },
+        {
+            schemaName: 'GetUserActionsDto',
+            properties: [
+                'companyId',
+                'branchId'
+            ]
+        },
+        {
+            schemaName: 'GetUserRolesDto',
+            properties: [
+                'companyId',
+                'branchId'
+            ]
+        },
+        // Response DTOs with branchId
+        {
+            schemaName: 'UserActionResponseDto',
+            properties: [
+                'branchId'
+            ]
+        },
+        {
+            schemaName: 'UserRoleResponseDto',
+            properties: [
+                'branchId'
+            ]
+        },
+        // Company-related DTOs (entire schemas hidden via tag exclusion, but just in case)
+        {
+            schemaName: 'AssignCompanyActionsDto',
+            properties: [
+                'companyId'
+            ]
+        },
+        {
+            schemaName: 'CompanyActionResponseDto',
+            properties: [
+                'companyId'
+            ]
+        }
+    ];
+    // Hide query parameters for GET endpoints when company feature is disabled
+    const excludeQueryParameters = enableCompanyFeature ? [] : [
+        {
+            pathPattern: '/iam/permissions/user-actions/*',
+            method: 'get',
+            parameters: [
+                'companyId',
+                'branchId'
+            ]
+        },
+        {
+            pathPattern: '/iam/permissions/user-roles/*',
+            method: 'get',
+            parameters: [
+                'companyId',
+                'branchId'
+            ]
+        }
+    ];
+    // Build exclude tags list: always exclude Auth tags + conditionally exclude based on permission mode
+    const excludeTags = [
+        ...AUTH_RELATED_TAGS
+    ];
+    // Hide company-related IAM endpoints when company feature is disabled
+    if (!enableCompanyFeature) {
+        excludeTags.push('IAM - Company Action Permissions');
+    }
+    // Conditionally exclude endpoints based on permission mode
+    if (permissionMode === IAMPermissionMode.RBAC) {
+        // RBAC only - hide direct user action endpoints
+        excludeTags.push('IAM - Permissions (Direct)');
+    } else if (permissionMode === IAMPermissionMode.DIRECT) {
+        // Direct only - hide RBAC endpoints
+        excludeTags.push('IAM - Permissions (RBAC)');
+        excludeTags.push('IAM - Roles'); // Roles are only used in RBAC
+    }
+    return {
+        title: 'IAM API',
+        description: `
+## Identity & Access Management API
+
+Advanced permission system with flexible modes: RBAC, Direct Permissions, or both.
+
+### Current Configuration
+- **Permission Mode**: ${permissionMode === IAMPermissionMode.RBAC ? '**RBAC** (Role-Based Access Control)' : permissionMode === IAMPermissionMode.DIRECT ? '**DIRECT** (Direct User Permissions)' : '**FULL** (RBAC + Direct)'}${enableCompanyFeature ? '\n- **Company Feature**: Enabled (Multi-tenant with company/branch scoping)' : '\n- **Company Feature**: Disabled'}
+
+### Features Based on Mode
+
+${permissionMode === IAMPermissionMode.RBAC || permissionMode === IAMPermissionMode.FULL ? `#### RBAC Features (Active)
+- **Roles**: Create company-scoped roles${enableCompanyFeature ? ' (auto-filtered by user company)' : ''}
+- **Role-Actions**: Assign actions to roles
+- **User-Roles**: Assign roles to users${enableCompanyFeature ? ' at branch level' : ''}
+` : ''}${permissionMode === IAMPermissionMode.DIRECT || permissionMode === IAMPermissionMode.FULL ? `#### Direct Permission Features (Active)
+- **User-Actions**: Direct action assignment to users${enableCompanyFeature ? ' at branch level' : ''}
+` : ''}${enableCompanyFeature ? `#### Company Features (Active)
+- **Company-Action Whitelist**: Control which actions are available per company
+- **Branch-Based Scoping**: Permissions scoped to specific branches
+- **Auto-Filtering**: Roles automatically filtered by user's company
+- **Action Tree Filtering**: Available actions filtered by company whitelist
+` : ''}
+### Core Concepts
+
+#### Actions
+Represent permissions in the system. Can be hierarchical.
+
+**Action Types:**
+- \`menu\` - Menu visibility (actions with type='menu' are used as menus)
+- \`endpoint\` - API endpoint access
+- \`frontend\` - Frontend feature toggles
+${permissionMode === IAMPermissionMode.RBAC || permissionMode === IAMPermissionMode.FULL ? `
+#### Roles
+Collections of actions that can be assigned to users.${enableCompanyFeature ? ' Scoped to companies.' : ' Global across the system.'}
+` : ''}${enableCompanyFeature ? `
+#### Company-Action Whitelist
+Controls which actions are available to a company. Users/roles can only use whitelisted actions.
+
+**Flow:**
+1. Admin assigns actions to company (whitelist)
+2. Only whitelisted actions appear in permission assignment UIs
+3. Users/roles cannot be assigned non-whitelisted actions
+` : ''}
+### Permission Resolution
+
+${permissionMode === IAMPermissionMode.FULL ? `1. **Company-Action Whitelist** - Filter by company (if enabled)
+2. **UserAction (DENY)** - Explicit denials take precedence
+3. **UserAction (GRANT)** - Direct user grants
+4. **UserRole → RoleAction** - Inherited from assigned roles
+5. **Action Permission Logic** - Complex AND/OR rules` : permissionMode === IAMPermissionMode.RBAC ? `1. **Company-Action Whitelist** - Filter by company (if enabled)
+2. **UserRole → RoleAction** - Actions inherited from roles
+3. **Action Permission Logic** - Complex AND/OR rules` : `1. **Company-Action Whitelist** - Filter by company (if enabled)
+2. **UserAction (DENY)** - Explicit denials take precedence
+3. **UserAction (GRANT)** - Direct user grants
+4. **Action Permission Logic** - Complex AND/OR rules`}
+
+### API Endpoints Summary
+
+#### Available Endpoints
+- ✅ **Actions**: CRUD operations, tree view${enableCompanyFeature ? ', filtered tree for permissions' : ''}${permissionMode === IAMPermissionMode.RBAC || permissionMode === IAMPermissionMode.FULL ? `
+- ✅ **Roles**: CRUD operations${enableCompanyFeature ? ' (auto-filtered by company)' : ''}
+- ✅ **Role-Actions**: Assign actions to roles, get role actions
+- ✅ **User-Roles**: Assign roles to users, get user roles` : `
+- ❌ **Roles**: Disabled (RBAC mode not active)`}${permissionMode === IAMPermissionMode.DIRECT || permissionMode === IAMPermissionMode.FULL ? `
+- ✅ **User-Actions**: Direct action assignment to users` : `
+- ❌ **User-Actions**: Disabled (DIRECT mode not active)`}${enableCompanyFeature ? `
+- ✅ **Company-Actions**: Whitelist actions for companies` : `
+- ❌ **Company-Actions**: Disabled (company feature not enabled)`}
+- ✅ **My Permissions**: Get current user's complete permissions (includes menu-type actions)
+
+### Best Practices
+
+1. **Action Codes**: Use meaningful codes like \`user.create\`, \`order.view\`
+2. **Hierarchical Actions**: Group related actions (use parentId for hierarchy)${permissionMode === IAMPermissionMode.RBAC || permissionMode === IAMPermissionMode.FULL ? `
+3. **Role Design**: Create roles for common permission patterns` : ''}${permissionMode === IAMPermissionMode.DIRECT || permissionMode === IAMPermissionMode.FULL ? `
+${permissionMode === IAMPermissionMode.FULL ? '4' : '3'}. **Direct Actions**: Use sparingly for exceptions` : ''}${enableCompanyFeature ? `
+${permissionMode === IAMPermissionMode.FULL ? '5' : '4'}. **Company Whitelisting**: Set up action whitelist before assigning permissions
+${permissionMode === IAMPermissionMode.FULL ? '6' : '5'}. **Branch Scoping**: Use branches for location-based access control` : ''}
+  `,
+        version: '1.0',
+        path: 'api/docs/iam',
+        bearerAuth: true,
+        excludeSchemaProperties,
+        excludeTags,
+        excludeQueryParameters
+    };
+}

package/fesm/docs/index.js

@@ -0,0 +1 @@
+export * from './iam-swagger.config';