@katomaran/nest-role-group.yaml

Basic Information

@katomaran/nest-role-group: description: | This package provides a NestJS implementation for role-based access control (RBAC) to manage user permissions effectively.

installation:

npm_command:

  npm install @katomaran/nest-role-group

yarn_command:

  yarn add @katomaran/nest-role-group

Module Import

module_import: description: Import the RoleModule in the AppModule.

code

import { Module } from '@nestjs/common';
import { MongooseModule } from '@nestjs/mongoose';
import { RoleModule } from '@katomaran/nest-role-group'; # Adjust path if necessary

@Module({
  imports: [
    MongooseModule.forRoot('your_mongo_db_connection_string'), # Connect to your MongoDB
    RoleModule,
  ],
})
export class AppModule {}

Main Guard Registration

main_guard_registration: description: > Import and configure PermissionGuard, and set up role groups and roles at application startup in main.ts.

    import { NestFactory } from '@nestjs/core';
    import { AppModule } from './app.module';
    import { PermissionGuard } from '@katomaran/nest-role-group';
    import { RoleUtilityService } from '@katomaran/nest-role-group'; # Adjust the path as needed
    async function bootstrap() {
      const app = await NestFactory.create(AppModule);
      
      # Retrieve RoleUtilityService instance
      const roleUtilityService = app.get(RoleUtilityService);

      try:
        # Initialize role groups from roleGroup.json
        await roleUtilityService.createRoleGroupsFromFile('file path to the role groups');
        console.log('Role groups created successfully');

        # Initialize roles from permission.json
        await roleUtilityService.createRolesFromFile('file path to the roles');
        console.log('Roles created successfully');
      } catch (error) {
        console.error('Error creating role groups or roles:', error);
      }

      # Register PermissionGuard globally
      app.useGlobalGuards(new PermissionGuard());

      # Start application
      await app.listen(3000);
      console.log('Application is running on http://localhost:3000');
    }
    bootstrap();

Features

features:

• Create roles and role groups from JSON files.
• Validate the structure of roles and role groups.
• Check permissions for role groups based on routes and HTTP methods.
• Automatically check permissions using decorators.

Usage

usage: import_role_utility_service: description: Import RoleUtilityService in your NestJS module. import { Module } from '@nestjs/common'; import { RoleUtilityService } from '@katomaran/nest-role-group'; import { RoleService } from './role.service'; import { RoleGroupService } from './role-group.service';

  @Module({
    providers: [RoleUtilityService, RoleService, RoleGroupService],
    exports: [RoleUtilityService],
  })
  export class RoleModule {}

Example JSON Structure

json_structure:

roles:

[
  {
    "name": "Public",
    "aliasName": "public",
    "permissions": {
      "route": "v1/users",
      "methods": ["GET", "POST"]
    }
  },
  {
    "name": "User",
    "aliasName": "user",
    "permissions": {
      "route": "v1/users/:id",
      "methods": ["PUT"]
    }
  }
]

role_groups:

[
  {
    "name": "Admin Group",
    "type": "Admin",
    "roles": ["admin", "user"]
  },
  {
    "name": "User Group",
    "type": "User",
    "roles": ["user"]
  }
]

Methods

methods: createRolesFromFile: description: Reads roles from a JSON file and creates them in the database.

  createRolesFromFile(filePath: string): Promise<void>

createRoleGroupsFromFile: description: Reads role groups from a JSON file and creates them in the database.

  createRoleGroupsFromFile(filePath: string): Promise<void>

hasPermission: description: Checks if a role group has permission for a specific route and HTTP method.

  hasPermission(roleGroupId: string, route: string, method: string): Promise<boolean>

Constants

constants: REQUIRED_KEYS: Required keys for role and role group validation. ALLOWED_METHODS: Allowed HTTP methods for permissions validation.

Error Handling

error_handling: not_found: 404 Not Found when a role group is not found. general_errors: General errors during file reading or processing.

Guards

guards: usage_permission_guard: description: | To utilize the PermissionGuard in your controllers, decorate routes with the appropriate metadata. example_code: |

  import { Controller, Get } from '@nestjs/common';
  import { Public } from '@katomaran/nest-role-group';

  @Controller('users')
  export class UserController {
    @Get()
    @Public() # Automatically checks permission for the public role
    async getUsers() {
      # Logic to get users
    }
  }

Configuration and Redis Keys

configuration:

database_connection_string: Configure MongoDB connection in MongooseModule.forRoot. json_file_paths: Specify paths to JSON files if not in the root directory. redis_keys: role_data: "role: - Stores role information, including permissions." role_group_data: "roleGroup: - Stores role group information and associated roles." permission_cache: "permissions::: - Caches permissions to reduce database calls."

Conclusion

conclusion: summary: | The @katomaran/nest-role-group package provides a robust solution for implementing role-based access control in your NestJS applications, streamlining the management of user permissions and enhancing security. additional_info: | For further customization or assistance, please refer to the package documentation or the source code.

notes:

• Adjust the database connection string and file paths as necessary in your actual implementation.
• Add additional sections, such as FAQ, License, or Contributing guidelines, if needed.