@lenne.tech/nest-server 11.17.0 → 11.19.0

package/src/core/common/interfaces/server-options.interface.ts

@@ -53,7 +53,7 @@ export interface IAuth {
    *
    * Legacy endpoints include:
    * - GraphQL: signIn, signUp, signOut, refreshToken mutations
-   * - REST: /api/auth/* endpoints
+   * - REST: /auth/* endpoints
    *
    * These can be disabled once all users have migrated to BetterAuth (IAM).
    *
@@ -156,7 +156,7 @@ export interface IAuthLegacyEndpoints {
 
   /**
    * Whether legacy REST auth endpoints are enabled.
-   * Affects: /api/auth/sign-in, /api/auth/sign-up, etc.
+   * Affects: /auth/sign-in, /auth/sign-up, etc.
    *
    * @default true (inherits from `enabled`)
    */
@@ -1426,6 +1426,26 @@ export interface IServerOptions {
            * default = true
            */
           noteCheckedObjects?: boolean;
+
+          /**
+           * Whether to remove known secret fields as a fallback safety net.
+           * Applied after securityCheck() to catch any remaining secrets.
+           * default = true
+           *
+           * @since 11.18.0
+           */
+          removeSecretFields?: boolean;
+
+          /**
+           * List of field names to remove in the fallback secret removal.
+           * Only used when removeSecretFields is true.
+           * Note: security.secretFields (global) takes precedence over this setting if both are defined.
+           * Use this for interceptor-specific overrides, or security.secretFields for a global default.
+           * default = ['password', 'verificationToken', 'passwordResetToken', 'refreshTokens', 'tempTokens']
+           *
+           * @since 11.18.0
+           */
+          secretFields?: string[];
         };
 
     /**
@@ -1449,6 +1469,146 @@ export interface IServerOptions {
            */
           nonWhitelistedFields?: 'strip' | 'error' | false;
         };
+
+    /**
+     * Mongoose password hashing plugin - automatically hashes passwords on save/update
+     * (save, findOneAndUpdate, updateOne, updateMany).
+     * Prevents plaintext passwords even when CrudService.process() is bypassed.
+     * Already-hashed values (BCrypt pattern /^\$2[aby]\$\d+\$/) are detected and skipped
+     * to prevent double-hashing.
+     *
+     * For sentinel/lock values (e.g. '!LOCKED:REQUIRES_PASSWORD_RESET'), configure
+     * skipPatterns so they are preserved as-is and not hashed.
+     *
+     * default = true (opt-out via false)
+     *
+     * @example
+     * ```typescript
+     * // Default: hash all passwords
+     * mongoosePasswordPlugin: true,
+     *
+     * // Skip sentinel values used for account locking
+     * mongoosePasswordPlugin: { skipPatterns: ['^!LOCKED:'] },
+     *
+     * // Disable entirely
+     * mongoosePasswordPlugin: false,
+     * ```
+     *
+     * @since 11.18.0
+     */
+    mongoosePasswordPlugin?:
+      | boolean
+      | {
+          /**
+           * Regex patterns for password values that should NOT be hashed.
+           * Use this for sentinel/lock values like '!LOCKED:REQUIRES_PASSWORD_RESET'
+           * that are intentionally invalid hashes to prevent login.
+           * Patterns are matched against the raw password value.
+           *
+           * @example ['^!LOCKED:', '^\\$NOHASH\\$']
+           */
+          skipPatterns?: (string | RegExp)[];
+        };
+
+    /**
+     * Mongoose audit fields plugin - automatically sets createdBy/updatedBy fields
+     * on save/update operations.
+     * Uses RequestContext (AsyncLocalStorage) to access the current user —
+     * requires RequestContextMiddleware to be active (registered automatically by CoreModule).
+     * Only activates on schemas that have createdBy and/or updatedBy fields defined.
+     * default = true (opt-out via false)
+     *
+     * @since 11.18.0
+     */
+    mongooseAuditFieldsPlugin?: boolean;
+
+    /**
+     * Mongoose role guard plugin - prevents unauthorized users from escalating roles
+     * via save/update operations.
+     * Uses RequestContext (AsyncLocalStorage) to access the current user —
+     * requires RequestContextMiddleware to be active (registered automatically by CoreModule).
+     * System operations without a request context (e.g. migrations) are allowed through.
+     *
+     * By default, only ADMIN users can assign roles. Use allowedRoles to permit
+     * additional roles (e.g. ORGA, COMPANY_ADMIN) to assign roles to other users.
+     *
+     * default = true (opt-out via false)
+     *
+     * @example
+     * ```typescript
+     * // Default: only ADMIN can assign roles
+     * mongooseRoleGuardPlugin: true,
+     *
+     * // Allow ADMIN and custom roles to assign roles
+     * mongooseRoleGuardPlugin: { allowedRoles: ['ORGA', 'COMPANY_ADMIN'] },
+     *
+     * // Disable entirely
+     * mongooseRoleGuardPlugin: false,
+     * ```
+     *
+     * @since 11.18.0
+     */
+    mongooseRoleGuardPlugin?:
+      | boolean
+      | {
+          /**
+           * Additional roles (beyond ADMIN) that are allowed to assign roles to other users.
+           * ADMIN is always implicitly allowed — no need to include it here.
+           */
+          allowedRoles?: string[];
+        };
+
+    /**
+     * ResponseModelInterceptor - auto-converts plain objects/Mongoose documents
+     * to model instances with securityCheck() and correct constructor metadata.
+     * Ensures @Restricted field filtering and securityCheck() work even when
+     * CrudService.process() is bypassed.
+     *
+     * Model class resolution order:
+     * 1. Explicit @ResponseModel(ModelClass) decorator
+     * 2. GraphQL TypeMetadataStorage (automatic for @Query/@Mutation return types)
+     * 3. Swagger @ApiOkResponse / @ApiCreatedResponse type (automatic for REST)
+     * 4. No conversion (existing interceptors work as before)
+     *
+     * Results are cached per route handler for zero-cost subsequent lookups.
+     * default = true (opt-out via false)
+     *
+     * @since 11.18.0
+     */
+    responseModelInterceptor?:
+      | boolean
+      | {
+          /**
+           * Log a warning when auto-conversion from plain object to model occurs.
+           * Useful for identifying services that bypass CrudService.
+           * default = false
+           */
+          debug?: boolean;
+        };
+
+    /**
+     * TranslateResponseInterceptor - automatically applies _translations
+     * to response objects based on the Accept-Language header of the request.
+     * Reads @Translatable field values from _translations and overwrites
+     * the base-language field with the requested translation.
+     * Includes early bailout: skips recursive traversal when no _translations
+     * are present in the response.
+     * Ensures translations work even when CrudService.process() is bypassed.
+     * default = true (opt-out via false)
+     *
+     * @since 11.18.0
+     */
+    translateResponseInterceptor?: boolean;
+
+    /**
+     * Global list of field names that should always be removed from responses.
+     * This is a fallback safety net applied after all other security checks.
+     * Takes precedence over checkSecurityInterceptor.secretFields if both are set.
+     * default = ['password', 'verificationToken', 'passwordResetToken', 'refreshTokens', 'tempTokens']
+     *
+     * @since 11.18.0
+     */
+    secretFields?: string[];
   };
 
   /**

package/src/core/common/middleware/request-context.middleware.ts

@@ -0,0 +1,25 @@
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import { NextFunction, Request, Response } from 'express';
+
+import { IRequestContext, RequestContext } from '../services/request-context.service';
+
+/**
+ * Middleware that wraps each request in a RequestContext (AsyncLocalStorage).
+ * Uses a lazy getter for currentUser so that the user is resolved at access time,
+ * not at middleware execution time. This ensures that auth middleware that runs
+ * after this middleware still sets req.user before it's read.
+ */
+@Injectable()
+export class RequestContextMiddleware implements NestMiddleware {
+  use(req: Request, _res: Response, next: NextFunction) {
+    const context: IRequestContext = {
+      get currentUser() {
+        return (req as any).user || undefined;
+      },
+      get language() {
+        return req.headers?.['accept-language'] || undefined;
+      },
+    };
+    RequestContext.run(context, () => next());
+  }
+}

package/src/core/common/pipes/map-and-validate.pipe.ts

@@ -244,10 +244,10 @@ async function validateWithInheritance(object: any, originalPlainValue: any): Pr
                     // Special handling for validators with arrays when 'each' option is set
                     // The 'each' property indicates validation should be applied to each array element
                     const isArrayValue = Array.isArray(propertyValue);
-                    const shouldValidateEach =
+                    const shouldValidateEachItem =
                       metadata.each === true || (metadata as any).validationOptions?.each === true;
 
-                    if (isArrayValue && shouldValidateEach) {
+                    if (isArrayValue && shouldValidateEachItem) {
                       // Validate each array element individually
                       const results: boolean[] = [];
                       for (const item of propertyValue) {

package/src/core/common/plugins/complexity.plugin.ts

@@ -1,6 +1,6 @@
 import { Plugin } from '@nestjs/apollo';
 import { GraphQLSchemaHost } from '@nestjs/graphql';
-import { ApolloServerPlugin, GraphQLRequestListener } from 'apollo-server-plugin-base';
+import type { ApolloServerPlugin, BaseContext, GraphQLRequestListener } from '@apollo/server';
 import { GraphQLError } from 'graphql';
 import { fieldExtensionsEstimator, getComplexity, simpleEstimator } from 'graphql-query-complexity';
 
@@ -13,7 +13,7 @@ export class ComplexityPlugin implements ApolloServerPlugin {
     private configService: ConfigService,
   ) {}
 
-  async requestDidStart(): Promise<GraphQLRequestListener> {
+  async requestDidStart(): Promise<GraphQLRequestListener<BaseContext>> {
     const maxComplexity: number = this.configService.getFastButReadOnly('graphQl.maxComplexity');
     const { schema } = this.gqlSchemaHost;
 

package/src/core/common/plugins/mongoose-audit-fields.plugin.ts

@@ -0,0 +1,74 @@
+import { RequestContext } from '../services/request-context.service';
+
+/**
+ * Mongoose plugin that automatically sets createdBy/updatedBy fields.
+ * Uses RequestContext (AsyncLocalStorage) to access the current user.
+ *
+ * Behavior:
+ * - No user context (system operations, seeding): fields are not set
+ * - New documents: sets createdBy (if not already set) and updatedBy
+ * - Existing documents on save: sets updatedBy
+ * - Update operations: sets updatedBy
+ *
+ * Only activates on schemas that have createdBy and/or updatedBy fields defined.
+ */
+export function mongooseAuditFieldsPlugin(schema) {
+  const hasCreatedBy = !!schema.path('createdBy');
+  const hasUpdatedBy = !!schema.path('updatedBy');
+
+  // Skip schemas without audit fields (e.g. BetterAuth sessions, third-party schemas)
+  if (!hasCreatedBy && !hasUpdatedBy) {
+    return;
+  }
+
+  // Pre-save hook
+  schema.pre('save', function () {
+    const currentUser = RequestContext.getCurrentUser();
+    if (!currentUser?.id) {
+      return;
+    }
+
+    if (hasCreatedBy && this.isNew && !this['createdBy']) {
+      this['createdBy'] = currentUser.id;
+    }
+    if (hasUpdatedBy) {
+      this['updatedBy'] = currentUser.id;
+    }
+  });
+
+  // Pre-update hooks (only needed for updatedBy)
+  if (hasUpdatedBy) {
+    const updateHook = function () {
+      const currentUser = RequestContext.getCurrentUser();
+      if (!currentUser?.id) {
+        return;
+      }
+
+      const update = this.getUpdate();
+      if (!update) {
+        return;
+      }
+
+      // Handle both flat updates and $set operator
+      update['updatedBy'] = currentUser.id;
+      if (update.$set) {
+        update.$set['updatedBy'] = currentUser.id;
+      }
+
+      // Handle upsert: set createdBy on insert via $setOnInsert
+      // Only add if createdBy is not already in the update (avoids MongoDB path conflict)
+      if (hasCreatedBy && !update['createdBy'] && !update.$set?.['createdBy']) {
+        if (!update.$setOnInsert) {
+          update.$setOnInsert = {};
+        }
+        if (!update.$setOnInsert['createdBy']) {
+          update.$setOnInsert['createdBy'] = currentUser.id;
+        }
+      }
+    };
+
+    schema.pre('findOneAndUpdate', updateHook);
+    schema.pre('updateOne', updateHook);
+    schema.pre('updateMany', updateHook);
+  }
+}

package/src/core/common/plugins/mongoose-password.plugin.ts

@@ -0,0 +1,100 @@
+import bcrypt = require('bcrypt');
+import { sha256 } from 'js-sha256';
+
+import { ConfigService } from '../services/config.service';
+
+/**
+ * Mongoose plugin that automatically hashes passwords before saving to the database.
+ * Handles save(), findOneAndUpdate(), updateOne(), and updateMany() operations.
+ *
+ * Prevents plaintext passwords from being stored even when developers bypass
+ * CrudService.process() and use direct Mongoose operations.
+ *
+ * Detects already-hashed values (BCrypt pattern) to prevent double-hashing.
+ *
+ * For sentinel/lock values (e.g. '!LOCKED:REQUIRES_PASSWORD_RESET'), configure
+ * skipPatterns in security.mongoosePasswordPlugin to preserve them as-is.
+ */
+export function mongoosePasswordPlugin(schema) {
+  // Pre-save hook
+  schema.pre('save', async function () {
+    if (!this.isModified('password') || !this['password']) {
+      return;
+    }
+    this['password'] = await hashPassword(this['password']);
+  });
+
+  // Pre-findOneAndUpdate hook
+  schema.pre('findOneAndUpdate', async function () {
+    await hashUpdatePassword(this.getUpdate());
+  });
+
+  // Pre-updateOne hook
+  schema.pre('updateOne', async function () {
+    await hashUpdatePassword(this.getUpdate());
+  });
+
+  // Pre-updateMany hook
+  schema.pre('updateMany', async function () {
+    await hashUpdatePassword(this.getUpdate());
+  });
+}
+
+export async function hashUpdatePassword(update: any) {
+  if (!update) {
+    return;
+  }
+  if (update.password) {
+    update.password = await hashPassword(update.password);
+  }
+  if (update.$set?.password) {
+    update.$set.password = await hashPassword(update.$set.password);
+  }
+}
+
+// Compiled RegExp cache (built once on first call)
+let compiledSkipPatterns: RegExp[] | null = null;
+
+/**
+ * Reset the compiled skip patterns cache.
+ * Use in test environments where ConfigService is reset between test suites.
+ */
+export function resetSkipPatternsCache(): void {
+  compiledSkipPatterns = null;
+}
+
+function getSkipPatterns(): RegExp[] {
+  if (compiledSkipPatterns !== null) {
+    return compiledSkipPatterns;
+  }
+  const pluginConfig = ConfigService.configFastButReadOnly?.security?.mongoosePasswordPlugin;
+  if (pluginConfig && typeof pluginConfig === 'object' && 'skipPatterns' in pluginConfig && pluginConfig.skipPatterns) {
+    compiledSkipPatterns = (pluginConfig.skipPatterns as (string | RegExp)[]).map((p) =>
+      p instanceof RegExp ? p : new RegExp(p),
+    );
+  } else {
+    compiledSkipPatterns = [];
+  }
+  return compiledSkipPatterns;
+}
+
+export async function hashPassword(password: string): Promise<string> {
+  // Already BCrypt-hashed → skip
+  if (/^\$2[aby]\$\d+\$/.test(password)) {
+    return password;
+  }
+
+  // Check configured skip patterns (e.g. sentinel/lock values)
+  const skipPatterns = getSkipPatterns();
+  if (skipPatterns.some((pattern) => pattern.test(password))) {
+    return password;
+  }
+
+  // SHA256 pre-hash if configured and password is not already SHA256
+  const sha256Enabled = ConfigService.configFastButReadOnly?.sha256;
+  if (sha256Enabled && !/^[a-f0-9]{64}$/i.test(password)) {
+    password = sha256(password);
+  }
+
+  return bcrypt.hash(password, 10);
+}

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();
+  }
+}