@lenne.tech/nest-server 11.16.1 → 11.18.0

package/src/core/common/plugins/mongoose-role-guard.plugin.ts

@@ -0,0 +1,150 @@
+import { Logger } from '@nestjs/common';
+
+import { RoleEnum } from '../enums/role.enum';
+import { ConfigService } from '../services/config.service';
+import { RequestContext } from '../services/request-context.service';
+
+const logger = new Logger('mongooseRoleGuardPlugin');
+
+/**
+ * Mongoose plugin that prevents unauthorized users from escalating roles.
+ * Uses RequestContext (AsyncLocalStorage) to access the current user.
+ *
+ * **When are role changes allowed?**
+ * 1. No user context (system operations, seeding, CLI scripts) → allowed
+ * 2. No currentUser on request (e.g. signUp — user not logged in) → allowed
+ * 3. User has ADMIN role → allowed
+ * 4. User has one of the configured `allowedRoles` → allowed
+ * 5. `RequestContext.runWithBypassRoleGuard()` is active → allowed
+ * 6. `CrudService.process()` with `force: true` → allowed (auto-bypasses)
+ *
+ * **When are role changes blocked?**
+ * - Logged-in non-admin user without bypass → blocked
+ * - On save (new): roles set to `[]`
+ * - On save (existing): roles reverted to original
+ * - On update: roles stripped from update object
+ *
+ * **Configuration** via `security.mongooseRoleGuardPlugin`:
+ * - `true` — Only ADMIN can assign roles (default)
+ * - `{ allowedRoles: ['ORGA', 'HR_MANAGER'] }` — Additional roles that can assign roles
+ * - `false` — Plugin disabled entirely
+ *
+ * **Bypass for authorized service code** (e.g. HR system creating users with roles):
+ * ```typescript
+ * import { RequestContext } from '@lenne.tech/nest-server';
+ *
+ * // Wrap the database operation in runWithBypassRoleGuard
+ * await RequestContext.runWithBypassRoleGuard(async () => {
+ *   await this.mainDbModel.create({ email, roles: ['EMPLOYEE'] });
+ * });
+ *
+ * // Or use CrudService.process() with force: true
+ * return this.process(
+ *   async () => this.mainDbModel.findByIdAndUpdate(id, { roles }),
+ *   { serviceOptions, force: true },
+ * );
+ * ```
+ */
+export function mongooseRoleGuardPlugin(schema) {
+  // Pre-save hook
+  schema.pre('save', function () {
+    if (!this.isModified('roles')) {
+      return;
+    }
+
+    if (isRoleChangeAllowed()) {
+      return;
+    }
+
+    // Unauthorized: prevent role escalation
+    const currentUser = RequestContext.getCurrentUser();
+    logger.debug(
+      `[nest-server] mongooseRoleGuardPlugin: Blocked role change on ${this.isNew ? 'new' : 'existing'} document by user ${currentUser?.id || 'unknown'}`,
+    );
+    if (this.isNew) {
+      this['roles'] = [];
+    } else {
+      // Revert to original value
+      this.unmarkModified('roles');
+    }
+  });
+
+  // Pre-findOneAndUpdate hook
+  schema.pre('findOneAndUpdate', function () {
+    handleUpdateRoleGuard(this.getUpdate());
+  });
+
+  // Pre-updateOne hook
+  schema.pre('updateOne', function () {
+    handleUpdateRoleGuard(this.getUpdate());
+  });
+
+  // Pre-updateMany hook
+  schema.pre('updateMany', function () {
+    handleUpdateRoleGuard(this.getUpdate());
+  });
+}
+
+/**
+ * Check if the current user is allowed to modify roles.
+ * Returns true if:
+ * - No user context (system operation)
+ * - bypassRoleGuard is active (via RequestContext.runWithBypassRoleGuard())
+ * - User has ADMIN role
+ * - User has one of the configured allowedRoles
+ */
+function isRoleChangeAllowed(): boolean {
+  const currentUser = RequestContext.getCurrentUser();
+  // No user context (system operation) → allow
+  if (!currentUser) {
+    return true;
+  }
+  // Explicit bypass (e.g. signUp with default roles, authorized service operations)
+  if (RequestContext.isBypassRoleGuard()) {
+    return true;
+  }
+  // Admin → always allow
+  if (currentUser.hasRole?.([RoleEnum.ADMIN]) || currentUser.roles?.includes(RoleEnum.ADMIN)) {
+    return true;
+  }
+
+  // Check configured allowedRoles
+  const pluginConfig = ConfigService.configFastButReadOnly?.security?.mongooseRoleGuardPlugin;
+  if (pluginConfig && typeof pluginConfig === 'object' && 'allowedRoles' in pluginConfig && pluginConfig.allowedRoles) {
+    const allowedRoles: string[] = pluginConfig.allowedRoles as string[];
+    if (currentUser.roles?.some((role: string) => allowedRoles.includes(role))) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function handleUpdateRoleGuard(update: any) {
+  if (!update) {
+    return;
+  }
+
+  const hasRolesUpdate = update.roles || update.$set?.roles || update.$push?.roles || update.$addToSet?.roles;
+  if (!hasRolesUpdate) {
+    return;
+  }
+
+  if (isRoleChangeAllowed()) {
+    return;
+  }
+
+  // Unauthorized: remove roles changes with debug log
+  const currentUser = RequestContext.getCurrentUser();
+  logger.debug(`Stripped unauthorized roles change from user ${currentUser?.id || 'unknown'}`);
+  delete update.roles;
+  if (update.$set?.roles) {
+    delete update.$set.roles;
+  }
+  if (update.$push?.roles) {
+    delete update.$push.roles;
+  }
+  if (update.$addToSet?.roles) {
+    delete update.$addToSet.roles;
+  }
+}

package/src/core/common/services/config.service.ts

@@ -74,8 +74,8 @@ export class ConfigService {
 
     // Init subject handling
     if (!isInitialized) {
-      ConfigService._configSubject$.subscribe((config) => {
-        ConfigService._frozenConfigSubject$.next(deepFreeze(cloneDeep(config)));
+      ConfigService._configSubject$.subscribe((value) => {
+        ConfigService._frozenConfigSubject$.next(deepFreeze(cloneDeep(value)));
       });
     }
 

package/src/core/common/services/model-registry.service.ts

@@ -0,0 +1,25 @@
+import { CoreModel } from '../models/core-model.model';
+
+/**
+ * Central registry mapping Mongoose model names to CoreModel classes.
+ * Populated automatically by ModuleService constructors.
+ */
+export class ModelRegistry {
+  private static models = new Map<string, new (...args: any[]) => CoreModel>();
+
+  static register(dbModelName: string, modelClass: new (...args: any[]) => CoreModel): void {
+    this.models.set(dbModelName, modelClass);
+  }
+
+  static getModelClass(dbModelName: string): (new (...args: any[]) => CoreModel) | undefined {
+    return this.models.get(dbModelName);
+  }
+
+  static getAll(): Map<string, new (...args: any[]) => CoreModel> {
+    return this.models;
+  }
+
+  static clear(): void {
+    this.models.clear();
+  }
+}

package/src/core/common/services/module.service.ts

@@ -5,10 +5,13 @@ import { ProcessType } from '../enums/process-type.enum';
 import { getStringIds, popAndMap } from '../helpers/db.helper';
 import { check } from '../helpers/input.helper';
 import { prepareInput, prepareOutput } from '../helpers/service.helper';
+import { getTranslatablePropertyKeys, updateLanguage } from '../decorators/translatable.decorator';
 import { ServiceOptions } from '../interfaces/service-options.interface';
 import { CoreModel } from '../models/core-model.model';
 import { FieldSelection } from '../types/field-selection.type';
 import { ConfigService } from './config.service';
+import { ModelRegistry } from './model-registry.service';
+import { RequestContext } from './request-context.service';
 
 /**
  * Module service class to be extended by concrete module services
@@ -40,6 +43,11 @@ export abstract class ModuleService<T extends CoreModel = any> {
     this.configService = options?.configService;
     this.mainDbModel = options?.mainDbModel;
     this.mainModelConstructor = options?.mainModelConstructor;
+
+    // Auto-register model class for ResponseModelInterceptor lookups
+    if (options?.mainModelConstructor && options?.mainDbModel?.modelName) {
+      ModelRegistry.register(options.mainDbModel.modelName, options.mainModelConstructor);
+    }
   }
 
   /**
@@ -191,7 +199,10 @@ export abstract class ModuleService<T extends CoreModel = any> {
     }
 
     // Run service function
-    let result = await serviceFunc(config);
+    // When force is enabled, bypass the Mongoose role guard plugin as well
+    let result = config.force
+      ? await RequestContext.runWithBypassRoleGuard(() => serviceFunc(config))
+      : await serviceFunc(config);
 
     // Pop and map main model
     if (config.processFieldSelection && config.fieldSelection && this.processFieldSelection) {
@@ -242,6 +253,85 @@ export abstract class ModuleService<T extends CoreModel = any> {
     return result;
   }
 
+  /**
+   * Simplified result processing for direct Mongoose queries.
+   * Handles population and output preparation without the full process() pipeline.
+   *
+   * Security (password hashing, role guard, createdBy/updatedBy, type mapping,
+   * field filtering, secret removal, translations) is handled automatically
+   * by the safety net (Mongoose plugins + interceptors).
+   *
+   * Use this when bypassing CrudService methods but still wanting
+   * population and custom prepareOutput() transformations.
+   *
+   * Note: This method does NOT perform authorization checks (checkRights).
+   * The caller is responsible for verifying permissions before calling this method.
+   *
+   * @example
+   * ```typescript
+   * // Direct Mongoose query with result processing
+   * const doc = await this.mainDbModel.findById(id).exec();
+   * return this.processResult(doc, serviceOptions);
+   *
+   * // Aggregate with result processing
+   * const results = await this.mainDbModel.aggregate(pipeline).exec();
+   * return this.processResult(results, serviceOptions);
+   * ```
+   */
+  async processResult(result: any, serviceOptions: ServiceOptions = {}): Promise<any> {
+    if (!result) {
+      return result;
+    }
+
+    // Population (if GraphQL field selection is available)
+    if (serviceOptions.fieldSelection && this.processFieldSelection) {
+      const populateOpts = serviceOptions.processFieldSelection || {};
+      const items = Array.isArray(result) ? result : [result];
+      for (const item of items) {
+        await this.processFieldSelection(item, serviceOptions.fieldSelection, populateOpts);
+      }
+    }
+
+    // Custom prepareOutput (type mapping, ObjectId conversion, custom overrides)
+    if (this.prepareOutput) {
+      result = await this.prepareOutput(result, serviceOptions);
+    }
+
+    return result;
+  }
+
+  /**
+   * Apply translation-aware input processing.
+   * Auto-detects @Translatable fields on the model and routes non-base-language
+   * values into _translations.
+   *
+   * @param input - The input data to transform
+   * @param oldDoc - The existing document from DB (needed for value comparison)
+   * @param language - Language code (defaults to RequestContext.getLanguage())
+   * @returns The transformed input with translations stored in _translations
+   *
+   * @example
+   * ```typescript
+   * // In a custom update method:
+   * const oldDoc = await this.mainDbModel.findById(id).lean();
+   * input = this.applyTranslationInput(input, oldDoc, serviceOptions.language);
+   * return this.mainDbModel.findByIdAndUpdate(id, input, { returnDocument: 'after' }).exec();
+   * ```
+   */
+  protected applyTranslationInput(input: any, oldDoc: any, language?: string): any {
+    language = language || RequestContext.getLanguage();
+    if (!language) {
+      return input;
+    }
+
+    const translatableFields = getTranslatablePropertyKeys(this.mainModelConstructor);
+    if (translatableFields.length === 0) {
+      return input;
+    }
+
+    return updateLanguage(language, input, oldDoc, translatableFields);
+  }
+
   /**
    * Prepare input before save
    */

package/src/core/common/services/request-context.service.ts

@@ -0,0 +1,69 @@
+import { AsyncLocalStorage } from 'async_hooks';
+
+export interface IRequestContext {
+  currentUser?: {
+    id: string;
+    hasRole?: (roles: string[]) => boolean;
+    roles?: string[];
+  };
+  language?: string;
+  /** When true, mongooseRoleGuardPlugin allows role changes regardless of user permissions */
+  bypassRoleGuard?: boolean;
+}
+
+/**
+ * Request-scoped context using AsyncLocalStorage.
+ * Provides access to the current user in Mongoose hooks and other
+ * places where NestJS request scope is not available.
+ */
+export class RequestContext {
+  private static storage = new AsyncLocalStorage<IRequestContext>();
+
+  static run<T>(context: IRequestContext, fn: () => T): T {
+    return this.storage.run(context, fn);
+  }
+
+  static get(): IRequestContext | undefined {
+    return this.storage.getStore();
+  }
+
+  static getCurrentUser(): IRequestContext['currentUser'] | undefined {
+    return this.storage.getStore()?.currentUser;
+  }
+
+  static getLanguage(): string | undefined {
+    return this.storage.getStore()?.language;
+  }
+
+  /**
+   * Check if the role guard bypass is active for the current context.
+   */
+  static isBypassRoleGuard(): boolean {
+    return this.storage.getStore()?.bypassRoleGuard === true;
+  }
+
+  /**
+   * Run a function with the role guard bypass enabled.
+   * The current context (user, language) is preserved; only bypassRoleGuard is added.
+   *
+   * Use this when authorized code needs to set roles on users, e.g.:
+   * - signUp with default roles
+   * - Admin panel where a non-admin role (e.g. HR_MANAGER) creates users with roles
+   * - System setup creating initial admin
+   *
+   * @example
+   * ```typescript
+   * await RequestContext.runWithBypassRoleGuard(async () => {
+   *   await this.mainDbModel.findByIdAndUpdate(userId, { roles: ['EMPLOYEE'] });
+   * });
+   * ```
+   */
+  static runWithBypassRoleGuard<T>(fn: () => T): T {
+    const currentStore = this.storage.getStore();
+    const context: IRequestContext = {
+      ...currentStore,
+      bypassRoleGuard: true,
+    };
+    return this.storage.run(context, fn);
+  }
+}

package/src/core/modules/auth/guards/auth.guard.ts

@@ -40,8 +40,8 @@ const createPassportContext =
         try {
           request.authInfo = info;
           return resolve(callback(err, user, info));
-        } catch (err) {
-          reject(err);
+        } catch (callbackError) {
+          reject(callbackError);
         }
       })(request, response, (err: any) => (err ? reject(err) : resolve(undefined))),
     );

package/src/core/modules/better-auth/core-better-auth.resolver.ts

@@ -342,9 +342,9 @@ export class CoreBetterAuthResolver {
         // 1. accessToken (JWT plugin enriched response)
         // 2. token (top-level, some BetterAuth versions)
         // 3. session.token (session-based fallback)
-        const responseAny = response as any;
+        const tokenResponse = response as any;
         const rawToken =
-          responseAny.accessToken || responseAny.token || (hasSession(response) ? response.session.token : undefined);
+          tokenResponse.accessToken || tokenResponse.token || (hasSession(response) ? response.session.token : undefined);
         const token = await this.resolveJwtToken(rawToken);
 
         return {

package/src/core/modules/permissions/INTEGRATION-CHECKLIST.md

@@ -0,0 +1,56 @@
+# Permissions Module Integration Checklist
+
+## Reference Implementation
+
+- Local: `node_modules/@lenne.tech/nest-server/src/server/` (scanned at runtime)
+- GitHub: https://github.com/lenneTech/nest-server/tree/develop/src/core/modules/permissions
+
+## Quick Setup
+
+The Permissions module requires **no files to create** in the consuming project. It only needs a configuration entry.
+
+### 1. Enable in config.env.ts
+
+Add the `permissions` property to your environment configuration:
+
+```typescript
+// config.env.ts - local/development only
+permissions: true,
+```
+
+**WHY only dev/local?** This is a development tool that exposes security metadata. It should never run in production.
+
+### 2. Verify (Optional)
+
+Start your server and navigate to:
+
+- `http://localhost:3000/permissions` - HTML dashboard
+- `http://localhost:3000/permissions/json` - Raw JSON
+
+## Configuration Options
+
+| Config                               | Access     | Description                                          |
+| ------------------------------------ | ---------- | ---------------------------------------------------- |
+| `true`                               | Admin only | Default, requires `RoleEnum.ADMIN` at `/permissions` |
+| `{ role: 'S_EVERYONE' }`             | Any role   | Custom role for access                               |
+| `{ role: false }`                    | No auth    | No authentication required                           |
+| `{ path: 'admin/permissions' }`      | Admin only | Custom endpoint path (default: `permissions`)        |
+| `{ role: false, path: 'dev/perms' }` | No auth    | Custom path + no auth                                |
+| `{ enabled: false }`                 | Disabled   | Explicitly disabled                                  |
+| `undefined`                          | Disabled   | Default (not configured)                             |
+
+## Verification Checklist
+
+- [ ] `permissions: true` added to local/dev config only
+- [ ] Server starts without errors
+- [ ] `/permissions` returns HTML dashboard (requires admin login)
+- [ ] `/permissions/json` returns JSON report
+- [ ] Production config does NOT include `permissions`
+
+## Common Mistakes
+
+| Mistake                      | Symptom                            | Fix                                                          |
+| ---------------------------- | ---------------------------------- | ------------------------------------------------------------ |
+| Enabled in production config | Security metadata exposed publicly | Only enable in `local` / `dev` environments                  |
+| Missing admin token          | 401 Unauthorized on `/permissions` | Login as admin first, or use `{ role: false }` for local dev |
+| No modules found             | Empty report                       | Ensure `src/server/modules/` exists with module directories  |

package/src/core/modules/permissions/README.md

@@ -0,0 +1,102 @@
+# Permissions Report Module
+
+A development tool that scans `src/server/modules/` for `@Roles`, `@Restricted`, and `securityCheck()` usage, then generates an interactive HTML dashboard.
+
+## Purpose
+
+Provides a real-time overview of all role-based access control configuration across your project, helping identify:
+
+- Endpoints without `@Roles` protection
+- Models without `@Restricted` class-level restrictions
+- Models missing `securityCheck()` overrides
+- Fields without role restrictions
+
+## Endpoints
+
+The base path defaults to `/permissions` but can be customized via the `path` config option.
+
+| Method | Path               | Content-Type       | Description                               |
+| ------ | ------------------ | ------------------ | ----------------------------------------- |
+| `GET`  | `/{path}`          | `text/html`        | Interactive HTML dashboard                |
+| `GET`  | `/{path}/json`     | `application/json` | JSON report with `stats` field            |
+| `GET`  | `/{path}/markdown` | `text/plain`       | Markdown report (optimized for AI agents) |
+| `POST` | `/{path}/rescan`   | `application/json` | Force a rescan (rate limited: 1 per 10s)  |
+
+## JSON Stats
+
+The JSON report includes a `stats` field with pre-calculated metrics:
+
+```json
+{
+  "stats": {
+    "totalModules": 5,
+    "totalModels": 8,
+    "totalEndpoints": 42,
+    "totalSubObjects": 3,
+    "totalWarnings": 12,
+    "endpointCoverage": 85,
+    "securityCoverage": 62,
+    "warningsByType": {
+      "NO_RESTRICTION": 3,
+      "NO_ROLES": 2,
+      "NO_SECURITY_CHECK": 3,
+      "UNRESTRICTED_FIELD": 2,
+      "UNRESTRICTED_METHOD": 2
+    }
+  }
+}
+```
+
+- **endpointCoverage**: % of methods with @Roles (own or class-level)
+- **securityCoverage**: % of models with both @Restricted AND securityCheck()
+
+## Configuration
+
+Add `permissions` to your `config.env.ts`:
+
+```typescript
+// Enable with admin-only access (default)
+permissions: true,
+
+// Enable with custom role
+permissions: { role: 'S_EVERYONE' },
+
+// Enable without authentication
+permissions: { role: false },
+
+// Custom endpoint path (e.g. /admin/permissions instead of /permissions)
+permissions: { path: 'admin/permissions' },
+
+// Explicitly disabled
+permissions: { enabled: false },
+```
+
+Follows the [Boolean Shorthand Pattern](/.claude/rules/configurable-features.md).
+
+## How It Works
+
+1. **Lazy scanning**: The first request to `/permissions` triggers a full scan using [ts-morph](https://ts-morph.com/) to parse TypeScript AST
+2. **Caching**: Results are cached in memory until a `.ts` file changes in `src/server/`
+3. **File watching**: A recursive `fs.watch` on `src/server/` invalidates the cache on changes
+4. **Inheritance resolution**: Walks `node_modules/@lenne.tech/nest-server` to resolve inherited fields from `Core*` base classes
+5. **Security gap detection**: Compares found decorators against expected patterns and reports warnings
+
+## Access Control
+
+By default, only users with `RoleEnum.ADMIN` can access the endpoints. This is applied via `Reflect.defineMetadata('roles', ...)` at module registration time, which is read by `RolesGuard`.
+
+## Architecture
+
+```
+CorePermissionsModule.forRoot(config)
+  -> CorePermissionsController (REST endpoints)
+  -> CorePermissionsService (caching, file watcher, HTML/Markdown generation)
+  -> permissions-scanner.ts (standalone AST scanning, shared with lt CLI)
+```
+
+The architecture is split into:
+
+- **`permissions-scanner.ts`** (standalone, no NestJS dependencies): All AST-based scan logic using `ts-morph`. This is the single source of truth, also used by the `lt server permissions` CLI command via dynamic import.
+- **`CorePermissionsService`**: Caching, rate limiting, file watching, HTML/Markdown generation. Delegates scanning to `scanPermissions()`.
+- **`CorePermissionsController`**: REST endpoints with dynamically configurable base path.
+- **`CorePermissionsModule`**: DynamicModule with `forRoot()`, configures role and path via `Reflect.defineMetadata`.

package/src/core/modules/permissions/core-permissions.controller.ts

@@ -0,0 +1,34 @@
+import { Controller, Get, Header, Headers, Post } from '@nestjs/common';
+
+import { CorePermissionsService } from './core-permissions.service';
+import type { PermissionsReport } from './interfaces/permissions.interface';
+
+@Controller()
+export class CorePermissionsController {
+  constructor(private readonly permissionsService: CorePermissionsService) {}
+
+  @Get()
+  @Header('Content-Type', 'text/html')
+  async getPermissionsHtml(@Headers('authorization') authHeader?: string): Promise<string> {
+    await this.permissionsService.getOrScan();
+    return this.permissionsService.generateHtml(authHeader);
+  }
+
+  @Get('json')
+  async getPermissionsJson(): Promise<PermissionsReport> {
+    return this.permissionsService.getOrScan();
+  }
+
+  @Get('markdown')
+  @Header('Content-Type', 'text/plain; charset=utf-8')
+  async getPermissionsMarkdown(): Promise<string> {
+    await this.permissionsService.getOrScan();
+    return this.permissionsService.generateMarkdown();
+  }
+
+  @Post('rescan')
+  async rescan() {
+    await this.permissionsService.scan();
+    return { message: 'Rescan completed', timestamp: new Date().toISOString() };
+  }
+}

package/src/core/modules/permissions/core-permissions.module.ts

@@ -0,0 +1,36 @@
+import { DynamicModule, Module } from '@nestjs/common';
+import { PATH_METADATA } from '@nestjs/common/constants';
+
+import { RoleEnum } from '../../common/enums/role.enum';
+
+import { CorePermissionsController } from './core-permissions.controller';
+import { CorePermissionsService } from './core-permissions.service';
+import type { IPermissions } from './interfaces/permissions.interface';
+
+@Module({})
+export class CorePermissionsModule {
+  static forRoot(config: boolean | IPermissions): DynamicModule {
+    const role = typeof config === 'object' && config.role !== undefined ? config.role : RoleEnum.ADMIN;
+
+    const path = typeof config === 'object' && config.path ? config.path : 'permissions';
+
+    // Apply role-based access control at the class level using Reflect.defineMetadata
+    // instead of the @Roles() decorator because the role value is determined at runtime
+    // from the configuration. RolesGuard reads this metadata to enforce access control.
+    if (role !== false) {
+      Reflect.defineMetadata('roles', [role], CorePermissionsController);
+    }
+
+    // Override the controller's @Controller() path with the configured path.
+    // This allows users to serve the permissions report under a custom route (e.g. 'admin/permissions')
+    // while keeping the default 'permissions' path when no custom path is specified.
+    Reflect.defineMetadata(PATH_METADATA, path, CorePermissionsController);
+
+    return {
+      controllers: [CorePermissionsController],
+      exports: [CorePermissionsService],
+      module: CorePermissionsModule,
+      providers: [{ provide: 'PERMISSIONS_PATH', useValue: path }, CorePermissionsService],
+    };
+  }
+}