@lenne.tech/nest-server 11.16.1 → 11.18.0

package/src/core/common/interceptors/translate-response.interceptor.ts

@@ -0,0 +1,104 @@
+import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
+import { GqlContextType, GqlExecutionContext } from '@nestjs/graphql';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+
+import { applyTranslationsRecursively } from '../helpers/service.helper';
+
+/**
+ * Interceptor that automatically applies translations from _translations
+ * based on the Accept-Language header of the request.
+ *
+ * This ensures translations work even when developers bypass CrudService.process()
+ * and use direct Mongoose operations.
+ *
+ * Execution order on response:
+ * 1. ResponseModelInterceptor (plain → model)
+ * 2. TranslateResponseInterceptor (applies translations) ← THIS
+ * 3. CheckSecurityInterceptor (securityCheck())
+ * 4. CheckResponseInterceptor (@Restricted fields)
+ */
+@Injectable()
+export class TranslateResponseInterceptor implements NestInterceptor {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    const language = this.getLanguage(context);
+
+    if (!language) {
+      return next.handle();
+    }
+
+    return next.handle().pipe(
+      map((data) => {
+        if (!data || typeof data !== 'object') {
+          return data;
+        }
+        this.applyTranslations(data, language);
+        return data;
+      }),
+    );
+  }
+
+  private applyTranslations(data: any, language: string): void {
+    // Early bailout: skip if no _translations anywhere in the response
+    if (!this.hasTranslations(data)) {
+      return;
+    }
+
+    if (Array.isArray(data)) {
+      for (const item of data) {
+        if (item && typeof item === 'object') {
+          applyTranslationsRecursively(item, language);
+        }
+      }
+    } else if (data.items && Array.isArray(data.items)) {
+      // Wrapper objects (e.g. { items: [...], totalCount })
+      for (const item of data.items) {
+        if (item && typeof item === 'object') {
+          applyTranslationsRecursively(item, language);
+        }
+      }
+    } else {
+      applyTranslationsRecursively(data, language);
+    }
+  }
+
+  /**
+   * Quick check if _translations exists at the top level of the response.
+   * Avoids expensive recursive traversal when no translations are present.
+   */
+  private hasTranslations(data: any): boolean {
+    if (!data || typeof data !== 'object') {
+      return false;
+    }
+    if (Array.isArray(data)) {
+      return data.length > 0 && data[0] && typeof data[0] === 'object' && '_translations' in data[0];
+    }
+    if (data.items && Array.isArray(data.items)) {
+      return (
+        data.items.length > 0 && data.items[0] && typeof data.items[0] === 'object' && '_translations' in data.items[0]
+      );
+    }
+    return '_translations' in data;
+  }
+
+  private getLanguage(context: ExecutionContext): string | null {
+    // GraphQL context
+    try {
+      if (context.getType<GqlContextType>() === 'graphql') {
+        const gqlContext = GqlExecutionContext.create(context);
+        const req = gqlContext.getContext()?.req;
+        return req?.headers?.['accept-language'] || null;
+      }
+    } catch {
+      // Not a GraphQL context
+    }
+
+    // HTTP context
+    try {
+      const req = context.switchToHttp()?.getRequest();
+      return req?.headers?.['accept-language'] || null;
+    } catch {
+      return null;
+    }
+  }
+}

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

@@ -13,6 +13,7 @@ import { CollationOptions } from 'mongodb';
 import * as SMTPTransport from 'nodemailer/lib/smtp-transport';
 
 import { Falsy } from '../types/falsy.type';
+import { IPermissions } from '../../modules/permissions/interfaces/permissions.interface';
 import { CronJobConfigWithTimeZone } from './cron-job-config-with-time-zone.interface';
 import { CronJobConfigWithUtcOffset } from './cron-job-config-with-utc-offset.interface';
 import { MailjetOptions } from './mailjet-options.interface';
@@ -1317,6 +1318,31 @@ export interface IServerOptions {
     uri: string;
   };
 
+  /**
+   * Permissions report module (development tool).
+   *
+   * When enabled, provides an interactive HTML report at /permissions
+   * showing all @Roles, @Restricted decorators, and security gaps.
+   *
+   * Follows the "presence implies enabled" pattern:
+   * - `true`: Enabled with defaults (admin-only access)
+   * - `{ role: 'S_EVERYONE' }`: Enabled with custom role for access
+   * - `{ role: false }`: Enabled without auth check
+   * - `{ enabled: false }`: Explicitly disabled
+   *
+   * @default undefined (disabled)
+   *
+   * @example
+   * ```typescript
+   * // Enable for local/development (admin-only)
+   * permissions: true,
+   *
+   * // Enable with public access (no auth needed)
+   * permissions: { role: false },
+   * ```
+   */
+  permissions?: boolean | IPermissions;
+
   /**
    * Port number of the server
    * e.g. 8080
@@ -1400,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[];
         };
 
     /**
@@ -1423,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);
+}