Ecom Permissions Module

Overview

Ecom Permissions Module for NestJS provides an easy way to manage and enforce user permissions across your application. This module is designed to integrate seamlessly with other modules and is powered by Redis for caching and storage.

Features

• Flexible permissions configuration.
• Integration with Redis for caching permissions.
• Decorators for applying permissions to routes.
• guard for handling permissions enforcement.

Installation

yarn add ecom-permission

Usage

1. Add Permissions Module to your App

Import and configure the PermissionsModule in your root module.

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { PermissionsModule } from 'ecom-permission';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    PermissionsModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (configService: ConfigService) => ({
        baseUrl: configService.get<string>('AUTH_MSG_BASE_URL'),
        secretToken: configService.get<string>('COMMUNICATION_KEY'),
        redis: {
          cacheEncryptionKey: configService.get<string>('CACHE_ENCRYPTION_KEY'),
          host: configService.get<string>('REDIS_HOST'),
          port: configService.get<number>('REDIS_PORT'),
          user: configService.get<string>('REDIS_USERNAME'),
          password: configService.get<string>('REDIS_PASSWORD'),
        },
      }),
    }),
  ],
})
export class AppModule {}

2. Use Permissions Guard in a Module

Add the PermissionsGuard as a provider in any module where permissions need to be enforced.

import { Module } from '@nestjs/common';
import { PermissionsGuard } from 'ecom-permission';
import { SomeService } from './some.service';

@Module({
  providers: [PermissionsGuard, SomeService],
})
export class SomeModule {}

3. Decorators for Permissions in Controllers

Use the @AuthPermissions decorator to enforce permissions on specific routes.

Decorator Implementation

import { ApiSingleUnauthorized } from '@app/core/decorators';
import { applyDecorators, SetMetadata, UseGuards } from '@nestjs/common';
import { ApiBearerAuth } from '@nestjs/swagger';
import { PermissionsGuard } from 'ecom-permission';
import { AuthGuard } from '../guards';

export function AuthPermissions(...permissions: string[]) {
  return applyDecorators(
    SetMetadata('permissions', permissions),
    UseGuards(AuthGuard, PermissionsGuard),
    ApiBearerAuth(),
    ApiSingleUnauthorized(),
  );
}

Usage in a Controller

import { Controller, Get } from '@nestjs/common';
import { AuthPermissions } from './auth-permissions.decorator';

@Controller('users')
export class UserController {
  @Get('list')
  // ex:USER_MANAGEMENT.MANAGE
  @AuthPermissions('SUBJECT.ACTION', 'SUBJECT.ACTION')
  findAll() {
    return 'List of users';
  }
}

### 5. **Configuration Options**

- `baseUrl`: The base URL of Auth MS for permissions API.
- `secretToken`: Token for encrypting permissions.
- Redis configuration:
  - `host`: Redis host.
  - `port`: Redis port.
  - `user`: Redis username.
  - `password`: Redis password.
  - `cacheEncryptionKey`: Key for encrypting Redis cache data.

### 6. **Permission Caching**

Permissions are cached using Redis to reduce API calls and enhance performance. Ensure the Redis configuration is correctly set in the `.env` file.

### Example `.env` Configuration

```env
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_USERNAME=default
REDIS_PASSWORD=secret
COMMUNICATION_KEY=my-encryption-key
CACHE_ENCRYPTION_KEY=my-cache-key
BASE_URL=base-url-of-auth-ms

Summary

With the Ecom Permissions Module, you can:

• Enforce granular permissions for routes.
• Cache permissions for enhanced performance.
• Use simple decorators to secure your application.

This module simplifies permission management while maintaining flexibility and security.