@smartsoft001/nestjs 1.1.91 → 2.60.0

package/.eslintrc.json

@@ -0,0 +1,30 @@
+{
+  "extends": ["../../../.eslintrc.json"],
+  "ignorePatterns": ["!**/*"],
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.json"],
+      "parser": "jsonc-eslint-parser",
+      "rules": {
+        "@nx/dependency-checks": [
+          "error",
+          {
+            "ignoredFiles": ["{projectRoot}/eslint.config.{js,cjs,mjs}"]
+          }
+        ]
+      }
+    }
+  ]
+}

package/README.md

@@ -1,7 +1,348 @@
-# shared-nestjs
+# 📦 @smartsoft001/nestjs npm downloads
 
-This library was generated with [Nx](https://nx.dev).
+![npm](https://img.shields.io/npm/v/@smartsoft001/nestjs) ![downloads](https://img.shields.io/npm/dm/@smartsoft001/nestjs)
 
-## Running unit tests
+## 🚀 Usage
 
-Run `ng test shared-nestjs` to execute the unit tests via [Jest](https://jestjs.io).
+```bash
+npm install @smartsoft001/nestjs
+```
+
+## ⚙️ Configuration
+
+The library uses the `SharedConfig` class for authentication and permissions configuration:
+
+### Token Configuration
+
+| Field                            | Type     | Description                              |
+| -------------------------------- | -------- | ---------------------------------------- |
+| `tokenConfig.secretOrPrivateKey` | `string` | Secret or private key for signing tokens |
+| `tokenConfig.expiredIn`          | `number` | Token expiration time in seconds         |
+
+### Permissions Configuration
+
+| Field                | Type            | Description                               |
+| -------------------- | --------------- | ----------------------------------------- |
+| `permissions.create` | `Array<string>` | List of permissions for create operations |
+| `permissions.read`   | `Array<string>` | List of permissions for read operations   |
+| `permissions.update` | `Array<string>` | List of permissions for update operations |
+| `permissions.delete` | `Array<string>` | List of permissions for delete operations |
+| `permissions.[key]`  | `Array<string>` | Any additional custom permissions         |
+
+## Types
+
+```typescript
+export type PermissionType = 'create' | 'read' | 'update' | 'delete' | string;
+```
+
+# Modules
+
+## SharedModule
+
+The `SharedModule` is a dynamic NestJS module that provides shared configuration and services across the application. It offers two static methods for configuration: `forFeature()` and `forRoot()`.
+
+---
+
+### forFeature() Method
+
+The `forFeature()` method configures the module's core functionalities:
+
+```typescript
+static forFeature(config: SharedConfig): DynamicModule
+```
+
+#### Parameters:
+
+- `config`: An object of type `SharedConfig` containing the module's configuration.
+
+#### Returns:
+
+A `DynamicModule` object with the following elements:
+
+- Providers: `SharedConfig`, `JwtStrategy`, `PermissionService`
+- Exports: `SharedConfig`, `PermissionService`, `JwtStrategy`
+
+#### Example Usage:
+
+```typescript
+import { SharedModule, SharedConfig } from '@smartsoft001/nestjs';
+
+@Module({
+  imports: [
+    SharedModule.forFeature({
+      tokenConfig: {
+        secretOrPrivateKey: 'secret_key',
+        expiredIn: 3600,
+      },
+      permissions: {
+        create: ['admin'],
+        read: ['user', 'admin'],
+        update: ['admin'],
+        delete: ['admin'],
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+---
+
+### forRoot() Method
+
+The `forRoot()` method extends the `forFeature()` configuration by adding database settings:
+
+```typescript
+static forRoot(config: SharedConfig & {
+  db: {
+    host: string;
+    port: number;
+    database: string;
+    username?: string;
+    password?: string;
+  };
+}): DynamicModule
+```
+
+#### Parameters:
+
+- `config`: An extended `SharedConfig` object that includes additional database settings.
+
+#### Returns:
+
+A `DynamicModule` object that imports and exports the `forFeature()` configuration.
+
+#### Example Usage:
+
+```typescript
+import { SharedModule, SharedConfig } from '@smartsoft001/nestjs';
+
+@Module({
+  imports: [
+    SharedModule.forRoot({
+      tokenConfig: {
+        secretOrPrivateKey: 'secret_key',
+        expiredIn: 3600,
+      },
+      permissions: {
+        create: ['admin'],
+        read: ['user', 'admin'],
+        update: ['admin'],
+        delete: ['admin'],
+      },
+      db: {
+        host: 'localhost',
+        port: 5432,
+        database: 'my_database',
+        username: 'user',
+        password: 'password',
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+---
+
+### Summary
+
+The `SharedModule` provides flexible configuration for various use cases, enabling easy sharing of authorization, permissions, and database settings across the entire NestJS application.
+
+# Decorators
+
+## @User Decorator
+
+The `@User` decorator is a custom parameter decorator in NestJS that simplifies retrieving the user object from an HTTP request.
+
+### Functionality
+
+The `@User` decorator performs the following actions:
+
+- Extracts the request object (`req`) from the execution context.
+- Returns the `req.user` value, which typically contains information about the authenticated user.
+
+### Usage
+
+The `@User` decorator can be used in NestJS controllers to easily access user data:
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+
+import { IUser } from '@smartsoft001/users';
+
+import { User } from './user.decorator';
+
+@Controller('profile')
+export class ProfileController {
+  @Get()
+  getProfile(@User() user: IUser) {
+    return user;
+  }
+}
+```
+
+# Auth
+
+After registering the authentication module, you can use `JwtStrategy` and `PermissionService` as follows:
+
+---
+
+## Using JwtStrategy
+
+`JwtStrategy` is automatically used by `AuthGuard('jwt')`. You don't need to call it directly. Instead, use it indirectly via the `@UseGuards()` decorator:
+
+```typescript
+import { Controller, Get, UseGuards } from '@nestjs/common';
+import { AuthGuard } from '@nestjs/passport';
+
+@Controller('secure')
+@UseGuards(AuthGuard('jwt'))
+export class SecureController {
+  @Get()
+  getSecureData() {
+    return 'This is protected content';
+  }
+}
+```
+
+---
+
+## Using PermissionService
+
+`PermissionService` can be injected into controllers or services and used directly. Here are the main usage patterns:
+
+### 1. **Injecting the Service**
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { PermissionService } from './permission.service';
+
+@Injectable()
+export class SomeService {
+  constructor(private permissionService: PermissionService) {}
+
+  // ...
+}
+```
+
+---
+
+### 2. **Validating Permissions**
+
+```typescript
+import { User } from './user.decorator';
+
+@Get('admin-panel')
+adminPanel(@User() user) {
+  this.permissionService.valid('admin-panel', user);
+  return 'Admin Panel';
+}
+```
+
+---
+
+### 3. **Handling Errors**
+
+```typescript
+try {
+  this.permissionService.valid('some-action', user);
+  // Perform the protected action
+} catch (error) {
+  if (error instanceof DomainForbiddenError) {
+    // Handle lack of permissions
+  }
+  throw error;
+}
+```
+
+---
+
+### 4. **Using in a Custom Guard**
+
+```typescript
+import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
+import { PermissionService } from './permission.service';
+
+@Injectable()
+export class CustomPermissionGuard implements CanActivate {
+  constructor(private permissionService: PermissionService) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const request = context.switchToHttp().getRequest();
+    const user = request.user;
+    const requiredPermission = 'some-permission';
+
+    try {
+      this.permissionService.valid(requiredPermission, user);
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+}
+```
+
+---
+
+### 5. **Checking Multiple Permissions**
+
+```typescript
+multipleChecks(@User() user) {
+  this.permissionService.valid('permission1', user);
+  this.permissionService.valid('permission2', user);
+  // If both checks pass, perform the action
+}
+```
+
+---
+
+### Notes
+
+- `PermissionService` throws a `DomainForbiddenError` if the required permissions are missing. Always be prepared to handle this exception or let it be caught by a global exception filter.
+
+# Filters
+
+## AppExceptionFilter Overview
+
+The `AppExceptionFilter` class implements the `ExceptionFilter` interface and is used for handling exceptions in a NestJS application.
+
+### Functionality
+
+The filter intercepts all exceptions and processes them as follows:
+
+- For `HttpException`, it uses the original HTTP status and message.
+- For `DomainValidationError`, it sets a 400 (Bad Request) status.
+- For `DomainForbiddenError`, it sets a 403 (Forbidden) status.
+- For all other exceptions, it sets a 500 (Internal Server Error) status.
+
+### Logging
+
+The filter logs exception details (stack trace or message) using `Logger.error()`.
+
+### Response
+
+The filter returns an HTTP response with the appropriate status code and optionally a JSON object containing error details.
+
+### Usage
+
+To use this filter globally in a NestJS application, register it in the main module:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { APP_FILTER } from '@nestjs/core';
+
+import { AppExceptionFilter } from '@smartsoft001/nestjs';
+
+@Module({
+  providers: [
+    {
+      provide: APP_FILTER,
+      useClass: AppExceptionFilter,
+    },
+  ],
+})
+export class AppModule {}
+```
+
+This filter ensures consistent error handling throughout the application, mapping different exception types to appropriate HTTP status codes and formatting responses accordingly.

package/jest.config.ts

@@ -0,0 +1,10 @@
+export default {
+  displayName: 'nestjs',
+  preset: '../../../jest.preset.js',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.[tj]s$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.spec.json' }],
+  },
+  moduleFileExtensions: ['ts', 'js', 'html'],
+  coverageDirectory: '../../../coverage/packages/shared/nestjs',
+};

package/package.json

@@ -1,50 +1,16 @@
 {
   "name": "@smartsoft001/nestjs",
-  "version": "1.1.91",
-  "description": "Utils to nestjs",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/emiljuchnikowski/smartsoft.git"
-  },
-  "keywords": [
-    "smartsoft",
-    "oauth",
-    "nestjs"
-  ],
-  "author": "Emil Juchnikowski",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/emiljuchnikowski/smartsoft/issues"
-  },
-  "homepage": "https://github.com/emiljuchnikowski/smartsoft#readme",
-  "dependencies": {
-    "@angular/common": "16.1.3",
-    "@angular/core": "16.1.3",
-    "@angular/platform-browser-dynamic": "16.1.3",
-    "@nestjs/axios": "3.0.0",
-    "@nestjs/common": "^10.0.5",
-    "@nestjs/passport": "^10.0.0",
-    "@nestjs/terminus": "^10.0.1",
-    "@nestjs/typeorm": "^10.0.0",
-    "flatted": "^3.2.4",
-    "guid-typescript": "1.0.9",
-    "lodash": "^4.17.20",
-    "md5": "2.3.0",
-    "mongodb": "5.6.0",
-    "passport-jwt": "4.0.0",
-    "reflect-metadata": "0.1.13",
-    "rxjs": "7.8.1"
-  },
-  "peerDependencies": {
-    "@smartsoft001/crud-shell-dtos": "1.1.91",
-    "@smartsoft001/domain-core": "1.1.91",
-    "@smartsoft001/models": "1.1.91",
-    "@smartsoft001/mongo": "1.1.91",
-    "@smartsoft001/users": "1.1.91",
-    "@smartsoft001/utils": "1.1.91",
-    "util": "0.12.5",
-    "tslib": "2.5.3"
-  },
+  "version": "2.60.0",
+  "type": "commonjs",
   "main": "./src/index.js",
-  "types": "./src/index.d.ts"
+  "types": "./src/index.d.ts",
+  "dependencies": {
+    "tslib": "^2.3.0",
+    "passport-jwt": "^4.0.1",
+    "@nestjs/passport": "^11.0.5",
+    "@nestjs/common": "^11.0.7",
+    "@nestjs/testing": "^11.0.7",
+    "@smartsoft001/domain-core": "2.60.0",
+    "@smartsoft001/users": "2.60.0"
+  }
 }

package/project.json

@@ -0,0 +1,37 @@
+{
+  "name": "nestjs",
+  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/shared/nestjs/src",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/packages/shared/nestjs",
+        "main": "packages/shared/nestjs/src/index.ts",
+        "tsConfig": "packages/shared/nestjs/tsconfig.lib.json",
+        "assets": ["packages/shared/nestjs/*.md"]
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint"
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
+      "options": {
+        "jestConfig": "packages/shared/nestjs/jest.config.ts"
+      }
+    },
+    "deploy": {
+      "executor": "ngx-deploy-npm:deploy",
+      "options": {
+        "access": "public",
+        "distFolderPath": "dist/packages/shared/nestjs"
+      },
+      "dependsOn": ["build"]
+    }
+  }
+}

package/src/{index.d.ts → index.ts}

@@ -1,5 +1,5 @@
-export * from "./lib/filters";
-export * from './lib/decorators';
-export * from './lib/shared.module';
 export * from './lib/shared.config';
+export * from './lib/shared.module';
+export * from './lib/filters';
+export * from './lib/decorators';
 export * from './lib/auth';

package/src/lib/auth/{index.d.ts → index.ts}

@@ -1 +1,2 @@
+export * from './jwt.strategy';
 export * from './permission.service';

package/src/lib/auth/jwt.strategy.ts

@@ -0,0 +1,24 @@
+import { Injectable } from '@nestjs/common';
+import { PassportStrategy } from '@nestjs/passport';
+import { ExtractJwt, Strategy } from 'passport-jwt';
+
+import { SharedConfig } from '../shared.config';
+
+@Injectable()
+export class JwtStrategy extends PassportStrategy(Strategy) {
+  constructor(private config: SharedConfig) {
+    super({
+      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+      ignoreExpiration: false,
+      secretOrKey: config.tokenConfig?.secretOrPrivateKey as string,
+    });
+  }
+
+  async validate(payload: any) {
+    return {
+      ...payload,
+      permissions: payload.permissions,
+      username: payload.sub,
+    };
+  }
+}

package/src/lib/auth/permission.service.spec.ts

@@ -0,0 +1,61 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { DomainForbiddenError } from '@smartsoft001/domain-core';
+import { IUser } from '@smartsoft001/users';
+
+import { PermissionService } from './permission.service';
+import { SharedConfig } from '../shared.config';
+
+describe('shared-nestjs: PermissionService', () => {
+  let service: PermissionService;
+  let config: SharedConfig;
+
+  beforeEach(async () => {
+    config = {
+      permissions: {
+        create: ['admin', 'editor'],
+        read: ['admin', 'editor', 'viewer'],
+        update: ['admin', 'editor'],
+        delete: ['admin'],
+      },
+    };
+
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        PermissionService,
+        { provide: SharedConfig, useValue: config },
+      ],
+    }).compile();
+
+    service = module.get<PermissionService>(PermissionService);
+  });
+
+  it('should be defined', () => {
+    expect(service).toBeDefined();
+  });
+
+  it('should allow access if user has the required permission', () => {
+    const user: IUser = { username: 'testuser', permissions: ['admin'] };
+    expect(() => service.valid('create', user)).not.toThrow();
+  });
+
+  it('should throw DomainForbiddenError if user does not have the required permission', () => {
+    const user: IUser = { username: 'testuser', permissions: ['viewer'] };
+    expect(() => service.valid('create', user)).toThrow(DomainForbiddenError);
+  });
+
+  it('should not throw if permissions config is not defined', () => {
+    config.permissions = undefined;
+    const user: IUser = { username: 'testuser', permissions: ['admin'] };
+    expect(() => service.valid('create', user)).not.toThrow();
+  });
+
+  it('should not throw if permission type config is not defined', () => {
+    const user: IUser = { username: 'testuser', permissions: ['admin'] };
+    expect(() => service.valid('nonexistent', user)).not.toThrow();
+  });
+
+  it('should throw DomainForbiddenError if user permissions are not defined', () => {
+    const user: IUser = { username: 'testuser', permissions: [] };
+    expect(() => service.valid('create', user)).toThrow(DomainForbiddenError);
+  });
+});

package/src/lib/auth/permission.service.ts

@@ -0,0 +1,34 @@
+import { Injectable } from '@nestjs/common';
+import { DomainForbiddenError } from '@smartsoft001/domain-core';
+import { IUser } from '@smartsoft001/users';
+
+import { PermissionType, SharedConfig } from '../shared.config';
+
+/**
+ * Service to handle permission validation for users.
+ *
+ * @class PermissionService
+ */
+@Injectable()
+export class PermissionService {
+  constructor(private config: SharedConfig) {}
+
+  /**
+   * Validates if the user has the required permissions for a given type.
+   * @param {PermissionType} type - The type of permission to validate.
+   * @param {IUser} user - The user object containing permissions.
+   * @throws {DomainForbiddenError} If the user does not have the required permissions.
+   */
+  valid(type: PermissionType, user: IUser): void {
+    if (!this.config.permissions) return;
+
+    const typeConfig = this.config.permissions[type];
+
+    if (!typeConfig) return;
+
+    if (!user.permissions) throw new DomainForbiddenError(`Context forbidden`);
+
+    if (!typeConfig.some((tc) => user.permissions.some((up) => tc === up)))
+      throw new DomainForbiddenError(`Context forbidden`);
+  }
+}

package/src/lib/decorators/user/user.decorator.ts

@@ -0,0 +1,26 @@
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+
+/**
+ * Custom decorator to extract the user object from the request.
+ *
+ * @example
+ * ```ts
+ * import { Controller, Get } from '@nestjs/common';
+ *
+ * import { IUser } from '@smartsoft001/users';
+ *
+ * import { User } from './user.decorator';
+ *
+ * @Controller('profile')
+ * export class ProfileController {
+ *   @Get()
+ *   getProfile(@User() user: IUser) {
+ *     return user;
+ *   }
+ * }
+ * ```
+ */
+export const User = createParamDecorator((_, context: ExecutionContext) => {
+  const [req] = context.getArgs();
+  return req.user;
+});