@katomaran/nest-role-group

nest-role-access-kato.yaml

Basic Information

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

installation:

npm_command:

  npm install nest-role-access-kato

yarn_command:

  yarn add nest-role-access-kato

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 'nest-role-access-kato'; # 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 register the PermissionGuard globally in main.ts.

code:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { PermissionGuard } from 'nest-role-access-kato';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  # Register the PermissionGuard globally
  app.useGlobalGuards(new PermissionGuard());
  await app.listen(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 'nest-role-access-kato'; 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 'nest-role-access-kato';

  @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 nest-role-access-kato 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.