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

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

@@ -0,0 +1,202 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "iamSwaggerConfig", {
+    enumerable: true,
+    get: function() {
+        return iamSwaggerConfig;
+    }
+});
+const _permissiontypeenum = require("../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'
+];
+function iamSwaggerConfig(enableCompanyFeature = false, permissionMode = _permissiontypeenum.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 === _permissiontypeenum.IAMPermissionMode.RBAC) {
+        // RBAC only - hide direct user action endpoints
+        excludeTags.push('IAM - Permissions (Direct)');
+    } else if (permissionMode === _permissiontypeenum.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 === _permissiontypeenum.IAMPermissionMode.RBAC ? '**RBAC** (Role-Based Access Control)' : permissionMode === _permissiontypeenum.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 === _permissiontypeenum.IAMPermissionMode.RBAC || permissionMode === _permissiontypeenum.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 === _permissiontypeenum.IAMPermissionMode.DIRECT || permissionMode === _permissiontypeenum.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 === _permissiontypeenum.IAMPermissionMode.RBAC || permissionMode === _permissiontypeenum.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 === _permissiontypeenum.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 === _permissiontypeenum.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 === _permissiontypeenum.IAMPermissionMode.RBAC || permissionMode === _permissiontypeenum.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 === _permissiontypeenum.IAMPermissionMode.DIRECT || permissionMode === _permissiontypeenum.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 === _permissiontypeenum.IAMPermissionMode.RBAC || permissionMode === _permissiontypeenum.IAMPermissionMode.FULL ? `
+3. **Role Design**: Create roles for common permission patterns` : ''}${permissionMode === _permissiontypeenum.IAMPermissionMode.DIRECT || permissionMode === _permissiontypeenum.IAMPermissionMode.FULL ? `
+${permissionMode === _permissiontypeenum.IAMPermissionMode.FULL ? '4' : '3'}. **Direct Actions**: Use sparingly for exceptions` : ''}${enableCompanyFeature ? `
+${permissionMode === _permissiontypeenum.IAMPermissionMode.FULL ? '5' : '4'}. **Company Whitelisting**: Set up action whitelist before assigning permissions
+${permissionMode === _permissiontypeenum.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/cjs/docs/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./iam-swagger.config"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}

package/cjs/dtos/action.dto.js

@@ -0,0 +1,347 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get ActionQueryDto () {
+        return ActionQueryDto;
+    },
+    get ActionResponseDto () {
+        return ActionResponseDto;
+    },
+    get ActionTreeDto () {
+        return ActionTreeDto;
+    },
+    get ActionTreeQueryDto () {
+        return ActionTreeQueryDto;
+    },
+    get CreateActionDto () {
+        return CreateActionDto;
+    },
+    get UpdateActionDto () {
+        return UpdateActionDto;
+    }
+});
+const _swagger = require("@nestjs/swagger");
+const _classvalidator = require("class-validator");
+const _enums = require("../enums");
+const _types = require("../types");
+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);
+}
+let CreateActionDto = class CreateActionDto {
+    constructor(){
+        _define_property(this, "name", void 0);
+        _define_property(this, "description", void 0);
+        _define_property(this, "code", void 0);
+        _define_property(this, "actionType", void 0);
+        _define_property(this, "permissionLogic", void 0);
+        _define_property(this, "parentId", void 0);
+        _define_property(this, "serial", void 0);
+        _define_property(this, "isActive", void 0);
+        _define_property(this, "metadata", void 0);
+    }
+};
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        description: 'Action name',
+        example: 'View Users'
+    }),
+    (0, _classvalidator.IsString)(),
+    (0, _classvalidator.IsNotEmpty)(),
+    (0, _classvalidator.MaxLength)(255),
+    _ts_metadata("design:type", String)
+], CreateActionDto.prototype, "name", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        description: 'Action description',
+        example: 'Permission to view user list',
+        required: false
+    }),
+    (0, _classvalidator.IsString)(),
+    (0, _classvalidator.IsOptional)(),
+    (0, _classvalidator.MaxLength)(500),
+    _ts_metadata("design:type", String)
+], CreateActionDto.prototype, "description", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        description: 'Unique code for programmatic reference',
+        example: 'user.view',
+        required: false
+    }),
+    (0, _classvalidator.IsString)(),
+    (0, _classvalidator.IsOptional)(),
+    (0, _classvalidator.MaxLength)(255),
+    _ts_metadata("design:type", String)
+], CreateActionDto.prototype, "code", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        description: 'Action type (backend for API endpoints, frontend for UI features)',
+        enum: _enums.ActionType,
+        example: _enums.ActionType.BACKEND,
+        default: _enums.ActionType.BACKEND,
+        required: false
+    }),
+    (0, _classvalidator.IsEnum)(_enums.ActionType),
+    (0, _classvalidator.IsOptional)(),
+    _ts_metadata("design:type", typeof _enums.ActionType === "undefined" ? Object : _enums.ActionType)
+], CreateActionDto.prototype, "actionType", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        description: 'Permission logic (AND/OR rules)',
+        required: false
+    }),
+    (0, _classvalidator.IsOptional)(),
+    _ts_metadata("design:type", typeof _types.LogicNode === "undefined" ? Object : _types.LogicNode)
+], CreateActionDto.prototype, "permissionLogic", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        description: 'Parent action ID for hierarchy',
+        example: '123e4567-e89b-12d3-a456-426614174000',
+        required: false
+    }),
+    (0, _classvalidator.IsUUID)(),
+    (0, _classvalidator.IsOptional)(),
+    _ts_metadata("design:type", String)
+], CreateActionDto.prototype, "parentId", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        description: 'Display order',
+        required: false
+    }),
+    (0, _classvalidator.IsInt)(),
+    (0, _classvalidator.IsOptional)(),
+    _ts_metadata("design:type", Number)
+], CreateActionDto.prototype, "serial", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        description: 'Active status',
+        default: true,
+        required: false
+    }),
+    (0, _classvalidator.IsBoolean)(),
+    (0, _classvalidator.IsOptional)(),
+    _ts_metadata("design:type", Boolean)
+], CreateActionDto.prototype, "isActive", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        description: 'Additional metadata',
+        required: false
+    }),
+    (0, _classvalidator.IsOptional)(),
+    _ts_metadata("design:type", typeof Record === "undefined" ? Object : Record)
+], CreateActionDto.prototype, "metadata", void 0);
+let UpdateActionDto = class UpdateActionDto extends (0, _swagger.PartialType)(CreateActionDto) {
+    constructor(...args){
+        super(...args), _define_property(this, "id", void 0);
+    }
+};
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        description: 'Action ID',
+        example: '123e4567-e89b-12d3-a456-426614174000'
+    }),
+    (0, _classvalidator.IsUUID)(),
+    (0, _classvalidator.IsNotEmpty)(),
+    _ts_metadata("design:type", String)
+], UpdateActionDto.prototype, "id", void 0);
+let ActionResponseDto = class ActionResponseDto {
+    constructor(){
+        _define_property(this, "id", void 0);
+        _define_property(this, "readOnly", void 0);
+        _define_property(this, "name", void 0);
+        _define_property(this, "description", void 0);
+        _define_property(this, "code", void 0);
+        _define_property(this, "actionType", void 0);
+        _define_property(this, "permissionLogic", void 0);
+        _define_property(this, "parentId", void 0);
+        _define_property(this, "serial", void 0);
+        _define_property(this, "isActive", void 0);
+        _define_property(this, "metadata", void 0);
+        _define_property(this, "createdAt", void 0);
+        _define_property(this, "updatedAt", void 0);
+        _define_property(this, "deletedAt", void 0);
+        _define_property(this, "createdById", void 0);
+        _define_property(this, "updatedById", void 0);
+        _define_property(this, "deletedById", void 0);
+    }
+};
+_ts_decorate([
+    (0, _swagger.ApiProperty)(),
+    _ts_metadata("design:type", String)
+], ActionResponseDto.prototype, "id", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)(),
+    _ts_metadata("design:type", Boolean)
+], ActionResponseDto.prototype, "readOnly", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)(),
+    _ts_metadata("design:type", String)
+], ActionResponseDto.prototype, "name", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)(),
+    _ts_metadata("design:type", Object)
+], ActionResponseDto.prototype, "description", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)(),
+    _ts_metadata("design:type", Object)
+], ActionResponseDto.prototype, "code", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        enum: _enums.ActionType
+    }),
+    _ts_metadata("design:type", typeof _enums.ActionType === "undefined" ? Object : _enums.ActionType)
+], ActionResponseDto.prototype, "actionType", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)(),
+    _ts_metadata("design:type", Object)
+], ActionResponseDto.prototype, "permissionLogic", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)(),
+    _ts_metadata("design:type", Object)
+], ActionResponseDto.prototype, "parentId", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)(),
+    _ts_metadata("design:type", Object)
+], ActionResponseDto.prototype, "serial", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)(),
+    _ts_metadata("design:type", Boolean)
+], ActionResponseDto.prototype, "isActive", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        required: false
+    }),
+    _ts_metadata("design:type", Object)
+], ActionResponseDto.prototype, "metadata", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)(),
+    _ts_metadata("design:type", typeof Date === "undefined" ? Object : Date)
+], ActionResponseDto.prototype, "createdAt", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)(),
+    _ts_metadata("design:type", typeof Date === "undefined" ? Object : Date)
+], ActionResponseDto.prototype, "updatedAt", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        required: false
+    }),
+    _ts_metadata("design:type", Object)
+], ActionResponseDto.prototype, "deletedAt", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        required: false
+    }),
+    _ts_metadata("design:type", Object)
+], ActionResponseDto.prototype, "createdById", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        required: false
+    }),
+    _ts_metadata("design:type", Object)
+], ActionResponseDto.prototype, "updatedById", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        required: false
+    }),
+    _ts_metadata("design:type", Object)
+], ActionResponseDto.prototype, "deletedById", void 0);
+let ActionTreeDto = class ActionTreeDto extends ActionResponseDto {
+    constructor(...args){
+        super(...args), _define_property(this, "children", void 0);
+    }
+};
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        type: ()=>[
+                ActionTreeDto
+            ]
+    }),
+    _ts_metadata("design:type", Array)
+], ActionTreeDto.prototype, "children", void 0);
+let ActionQueryDto = class ActionQueryDto {
+    constructor(){
+        _define_property(this, "isActive", void 0);
+        _define_property(this, "parentId", void 0);
+    }
+};
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        description: 'Filter by active status',
+        required: false
+    }),
+    (0, _classvalidator.IsBoolean)(),
+    (0, _classvalidator.IsOptional)(),
+    _ts_metadata("design:type", Boolean)
+], ActionQueryDto.prototype, "isActive", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        description: 'Filter by parent ID',
+        required: false
+    }),
+    (0, _classvalidator.IsUUID)(),
+    (0, _classvalidator.IsOptional)(),
+    _ts_metadata("design:type", String)
+], ActionQueryDto.prototype, "parentId", void 0);
+let ActionTreeQueryDto = class ActionTreeQueryDto {
+    constructor(){
+        _define_property(this, "search", void 0);
+        _define_property(this, "isActive", void 0);
+        _define_property(this, "withDeleted", void 0);
+    }
+};
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        description: 'Search by name or code',
+        example: 'user',
+        required: false
+    }),
+    (0, _classvalidator.IsString)(),
+    (0, _classvalidator.IsOptional)(),
+    _ts_metadata("design:type", String)
+], ActionTreeQueryDto.prototype, "search", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        description: 'Filter by active status',
+        example: true,
+        required: false
+    }),
+    (0, _classvalidator.IsBoolean)(),
+    (0, _classvalidator.IsOptional)(),
+    _ts_metadata("design:type", Boolean)
+], ActionTreeQueryDto.prototype, "isActive", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)({
+        description: 'Include deleted actions',
+        default: false,
+        required: false
+    }),
+    (0, _classvalidator.IsBoolean)(),
+    (0, _classvalidator.IsOptional)(),
+    _ts_metadata("design:type", Boolean)
+], ActionTreeQueryDto.prototype, "withDeleted", void 0);

package/cjs/dtos/index.js

@@ -0,0 +1,21 @@
+// Core DTOs
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./action.dto"), exports);
+_export_star(require("./role.dto"), exports);
+_export_star(require("./permission.dto"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}