@lenne.tech/nest-server 11.15.3 → 11.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.15.3",
+  "version": "11.16.0",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -178,7 +178,7 @@
   "packageManager": "pnpm@10.29.2",
   "pnpm": {
     "overrides": {
-      "lodash": "4.17.23"
+      "qs": "6.14.2"
     },
     "onlyBuiltDependencies": [
       "bcrypt",

package/src/core/common/decorators/unified-field.decorator.ts

@@ -1,7 +1,7 @@
-import { Field, FieldOptions } from '@nestjs/graphql';
+import { Field, FieldOptions, HideField } from '@nestjs/graphql';
 import { TypeMetadataStorage } from '@nestjs/graphql/dist/schema-builder/storages/type-metadata.storage';
 import { Prop, PropOptions } from '@nestjs/mongoose';
-import { ApiProperty, ApiPropertyOptions } from '@nestjs/swagger';
+import { ApiHideProperty, ApiProperty, ApiPropertyOptions } from '@nestjs/swagger';
 import { EnumAllowedTypes } from '@nestjs/swagger/dist/interfaces/schema-object-metadata.interface';
 import { Type } from 'class-transformer';
 import {
@@ -34,9 +34,89 @@ export const nestedTypeRegistry = new Map<string, any>();
  */
 export const enumNameRegistry = new Map<any, string>();
 
+// Metadata keys for input whitelist tracking
+export const UNIFIED_FIELD_KEYS = Symbol('UNIFIED_FIELD_KEYS');
+export const EXCLUDED_FIELD_KEYS = Symbol('EXCLUDED_FIELD_KEYS');
+export const FORCE_INCLUDED_FIELD_KEYS = Symbol('FORCE_INCLUDED_FIELD_KEYS');
+
+/**
+ * Get whitelisted @UnifiedField keys for a class, respecting inheritance.
+ *
+ * Priority model (3 levels):
+ * 1. Explicit settings (exclude: true / exclude: false) — resolved by nearest class (child wins)
+ * 2. Implicit includes (@UnifiedField without exclude) — overridden by any explicit exclude: true
+ *
+ * Rules:
+ * - exclude: true → explicit exclusion, wins over implicit @UnifiedField from anywhere in chain
+ * - exclude: false → explicit re-enable, can override parent's exclude: true
+ * - @UnifiedField (no exclude) → implicit inclusion, CANNOT override parent's exclude: true
+ * - Among explicit settings, child class wins (first encountered while walking up the chain)
+ */
+export function getUnifiedFieldKeys(metatype: Function): Set<string> {
+  const cacheKey = Symbol.for('UNIFIED_FIELD_KEYS_RESOLVED');
+  const cached = Reflect.getOwnMetadata(cacheKey, metatype);
+  if (cached) return cached;
+
+  const implicitIncludes = new Set<string>();
+  const explicitExcludes = new Set<string>();
+  const explicitIncludes = new Set<string>();
+  const explicitlyResolved = new Set<string>();
+
+  // Walk from child (most specific) to parent
+  let current = metatype;
+  while (current && current !== Object && current !== Function && current.prototype) {
+    const included: string[] = Reflect.getOwnMetadata(UNIFIED_FIELD_KEYS, current.prototype) || [];
+    const excluded: string[] = Reflect.getOwnMetadata(EXCLUDED_FIELD_KEYS, current.prototype) || [];
+    const forceIncluded: string[] = Reflect.getOwnMetadata(FORCE_INCLUDED_FIELD_KEYS, current.prototype) || [];
+
+    for (const key of forceIncluded) {
+      if (!explicitlyResolved.has(key)) {
+        explicitIncludes.add(key);
+        explicitlyResolved.add(key);
+      }
+    }
+
+    for (const key of excluded) {
+      if (!explicitlyResolved.has(key)) {
+        explicitExcludes.add(key);
+        explicitlyResolved.add(key);
+      }
+    }
+
+    for (const key of included) {
+      implicitIncludes.add(key);
+    }
+
+    current = Object.getPrototypeOf(current);
+  }
+
+  // Build final set: start with implicit includes
+  const result = new Set(implicitIncludes);
+
+  // Add explicit includes (force re-enabled keys)
+  for (const key of explicitIncludes) {
+    result.add(key);
+  }
+
+  // Remove explicit excludes
+  for (const key of explicitExcludes) {
+    result.delete(key);
+  }
+
+  Reflect.defineMetadata(cacheKey, result, metatype);
+  return result;
+}
+
 export interface UnifiedFieldOptions {
   /** Description used for both Swagger & Gql */
   description?: string;
+  /**
+   * Control input whitelist behavior:
+   * - true: Exclude this property (reject via REST/GraphQL, no decorators applied)
+   * - false: Explicitly re-enable (can override parent's exclude: true)
+   * - undefined (default): Normal @UnifiedField behavior
+   */
+  exclude?: boolean;
   /** Enum for class-validator */
   enum?: { enum: EnumAllowedTypes; enumName?: string; options?: ValidationOptions };
   /** Example value for swagger api documentation */
@@ -83,6 +163,56 @@ export interface UnifiedFieldOptions {
 
 export function UnifiedField(opts: UnifiedFieldOptions = {}): PropertyDecorator {
   return (target: any, propertyKey: string | symbol) => {
+    const key = String(propertyKey);
+
+    if (opts.exclude === true) {
+      // ── EXPLICIT EXCLUSION ──
+      const excludedKeys: string[] = Reflect.getOwnMetadata(EXCLUDED_FIELD_KEYS, target) || [];
+      if (!excludedKeys.includes(key)) {
+        Reflect.defineMetadata(EXCLUDED_FIELD_KEYS, [...excludedKeys, key], target);
+      }
+      HideField()(target, propertyKey);
+      ApiHideProperty()(target, propertyKey);
+      return;
+    } else if (opts.exclude === false) {
+      // ── EXPLICIT RE-ENABLE ──
+      const forceKeys: string[] = Reflect.getOwnMetadata(FORCE_INCLUDED_FIELD_KEYS, target) || [];
+      if (!forceKeys.includes(key)) {
+        Reflect.defineMetadata(FORCE_INCLUDED_FIELD_KEYS, [...forceKeys, key], target);
+      }
+      // Fall through to register in UNIFIED_FIELD_KEYS AND apply normal decorators
+    } else {
+      // ── IMPLICIT INCLUSION ──
+      // Check if any parent has exclude: true for this key
+      let parentExcluded = false;
+      let proto = Object.getPrototypeOf(target.constructor);
+      while (proto && proto !== Object && proto !== Function && proto.prototype) {
+        const excluded: string[] = Reflect.getOwnMetadata(EXCLUDED_FIELD_KEYS, proto.prototype) || [];
+        if (excluded.includes(key)) {
+          parentExcluded = true;
+          break;
+        }
+        proto = Object.getPrototypeOf(proto);
+      }
+
+      if (parentExcluded) {
+        // Parent has exclude: true — register for tracking but skip schema decorators
+        const existingKeys: string[] = Reflect.getOwnMetadata(UNIFIED_FIELD_KEYS, target) || [];
+        if (!existingKeys.includes(key)) {
+          Reflect.defineMetadata(UNIFIED_FIELD_KEYS, [...existingKeys, key], target);
+        }
+        HideField()(target, propertyKey);
+        ApiHideProperty()(target, propertyKey);
+        return;
+      }
+    }
+
+    // Register in implicit includes (for both exclude: false and exclude: undefined without parent exclusion)
+    const existingKeys: string[] = Reflect.getOwnMetadata(UNIFIED_FIELD_KEYS, target) || [];
+    if (!existingKeys.includes(key)) {
+      Reflect.defineMetadata(UNIFIED_FIELD_KEYS, [...existingKeys, key], target);
+    }
+
     const metadataType = Reflect.getMetadata('design:type', target, propertyKey);
     const userType = opts.type;
     const isArrayField = opts.isArray === true || metadataType === Array;

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

@@ -1407,7 +1407,22 @@ export interface IServerOptions {
      * See @lenne.tech/nest-server/src/core/common/pipes/map-and-validate.pipe.ts
      * default = true
      */
-    mapAndValidatePipe?: boolean;
+    mapAndValidatePipe?:
+      | boolean
+      | {
+          /**
+           * How to handle input properties not decorated with @UnifiedField.
+           * Applies recursively to nested objects.
+           * Only applies to classes with at least one @UnifiedField.
+           *
+           * - 'strip' (default): Silently remove non-whitelisted properties
+           * - 'error': Throw BadRequestException listing the forbidden properties
+           * - false: Disable check entirely (allow all properties)
+           *
+           * @default 'strip'
+           */
+          nonWhitelistedFields?: 'strip' | 'error' | false;
+        };
   };
 
   /**

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

@@ -25,8 +25,10 @@ import {
 import { ValidationMetadata } from 'class-validator/types/metadata/ValidationMetadata';
 import { inspect } from 'util';
 
-import { nestedTypeRegistry } from '../decorators/unified-field.decorator';
+import { getUnifiedFieldKeys, nestedTypeRegistry } from '../decorators/unified-field.decorator';
 import { isBasicType } from '../helpers/input.helper';
+import { ConfigService } from '../services/config.service';
+import { ErrorCode } from '../../modules/error-code/error-codes';
 
 // Debug mode can be enabled via environment variable: DEBUG_VALIDATION=true
 const DEBUG_VALIDATION = process.env.DEBUG_VALIDATION === 'true';
@@ -615,8 +617,77 @@ async function validateWithInheritance(object: any, originalPlainValue: any): Pr
   return errors;
 }
 
+/**
+ * Recursively process non-whitelisted @UnifiedField properties.
+ *
+ * @param mode - 'strip' removes forbidden keys from plainValue in-place,
+ *               'error' collects and returns their paths.
+ * @returns Array of forbidden key paths (only relevant in 'error' mode;
+ *          empty in 'strip' mode since keys are deleted immediately).
+ */
+function processNonWhitelistedFields(
+  plainValue: Record<string, any>,
+  metatype: Function,
+  mode: 'strip' | 'error',
+  path: string = '',
+): string[] {
+  const whitelistedKeys = getUnifiedFieldKeys(metatype);
+  // Skip classes without any @UnifiedField (e.g. raw class-validator usage)
+  if (whitelistedKeys.size === 0) return [];
+
+  const forbiddenKeys: string[] = [];
+
+  for (const key of Object.keys(plainValue)) {
+    const fullPath = path ? `${path}.${key}` : key;
+
+    if (!whitelistedKeys.has(key)) {
+      if (mode === 'strip') {
+        delete plainValue[key];
+      } else {
+        forbiddenKeys.push(fullPath);
+      }
+      continue;
+    }
+
+    // Recurse into nested objects using nestedTypeRegistry
+    if (plainValue[key] && typeof plainValue[key] === 'object') {
+      let nestedType: Function | undefined;
+      let current = metatype;
+      while (current && current !== Object) {
+        nestedType = nestedTypeRegistry.get(`${current.name}.${key}`);
+        if (nestedType) break;
+        current = Object.getPrototypeOf(current);
+      }
+
+      if (nestedType) {
+        if (Array.isArray(plainValue[key])) {
+          for (let i = 0; i < plainValue[key].length; i++) {
+            const item = plainValue[key][i];
+            if (item && typeof item === 'object' && !Array.isArray(item)) {
+              forbiddenKeys.push(...processNonWhitelistedFields(item, nestedType, mode, `${fullPath}[${i}]`));
+            }
+          }
+        } else {
+          forbiddenKeys.push(...processNonWhitelistedFields(plainValue[key], nestedType, mode, fullPath));
+        }
+      }
+    }
+  }
+
+  return forbiddenKeys;
+}
+
 @Injectable()
 export class MapAndValidatePipe implements PipeTransform {
+  private readonly nonWhitelistedFieldsMode: 'strip' | 'error' | false = 'strip';
+
+  constructor() {
+    const pipeConfig = ConfigService.getFastButReadOnly('security.mapAndValidatePipe');
+    if (typeof pipeConfig === 'object' && pipeConfig?.nonWhitelistedFields !== undefined) {
+      this.nonWhitelistedFieldsMode = pipeConfig.nonWhitelistedFields;
+    }
+  }
+
   async transform(value: any, metadata: ArgumentMetadata) {
     const { metatype } = metadata;
 
@@ -667,6 +738,38 @@ export class MapAndValidatePipe implements PipeTransform {
       }
     }
 
+    // Whitelist check: handle properties not decorated with @UnifiedField
+    if (this.nonWhitelistedFieldsMode && metatype && originalPlainKeys.length > 0) {
+      const plainObj = originalPlainValue || value;
+
+      if (this.nonWhitelistedFieldsMode === 'strip') {
+        processNonWhitelistedFields(plainObj, metatype, 'strip');
+
+        if (DEBUG_VALIDATION) {
+          console.debug('Stripped non-whitelisted properties. Remaining keys:', Object.keys(plainObj));
+        }
+
+        // Re-transform after stripping so the instance matches the cleaned plain object
+        if (originalPlainValue) {
+          originalPlainKeys = Object.keys(originalPlainValue);
+          value = plainToInstance(metatype, originalPlainValue, {
+            enableImplicitConversion: false,
+            excludeExtraneousValues: false,
+            exposeDefaultValues: false,
+            exposeUnsetFields: false,
+          });
+        }
+      } else if (this.nonWhitelistedFieldsMode === 'error') {
+        const forbiddenKeys = processNonWhitelistedFields(plainObj, metatype, 'error');
+        if (forbiddenKeys.length > 0) {
+          if (DEBUG_VALIDATION) {
+            console.debug(`Forbidden non-whitelisted properties: ${forbiddenKeys.join(', ')}`);
+          }
+          throw new BadRequestException(`${ErrorCode.NON_WHITELISTED_PROPERTIES} [${forbiddenKeys.join(', ')}]`);
+        }
+      }
+    }
+
     // Validate with inheritance (checks all parent classes in the prototype chain)
     if (DEBUG_VALIDATION) {
       console.debug('Starting validation with inheritance');

package/src/core/modules/error-code/error-codes.ts

@@ -370,6 +370,15 @@ export const LtnsErrors = {
     },
   },
 
+  NON_WHITELISTED_PROPERTIES: {
+    code: 'LTNS_0303',
+    message: 'Non-whitelisted properties found',
+    translations: {
+      de: 'Die folgenden Eigenschaften sind nicht erlaubt: {{properties}}. Nur mit @UnifiedField dekorierte Eigenschaften werden akzeptiert.',
+      en: 'The following properties are not allowed: {{properties}}. Only properties decorated with @UnifiedField are accepted.',
+    },
+  },
+
   // =====================================================
   // Resource Errors (LTNS_0400-LTNS_0499)
   // =====================================================

package/src/server/modules/user/inputs/user-create.input.ts

@@ -1,7 +1,7 @@
-import { Field, InputType } from '@nestjs/graphql';
-import { IsOptional } from 'class-validator';
+import { InputType } from '@nestjs/graphql';
 
 import { Restricted } from '../../../../core/common/decorators/restricted.decorator';
+import { UnifiedField } from '../../../../core/common/decorators/unified-field.decorator';
 import { RoleEnum } from '../../../../core/common/enums/role.enum';
 import { CoreUserCreateInput } from '../../../../core/modules/user/inputs/core-user-create.input';
 
@@ -12,11 +12,10 @@ import { CoreUserCreateInput } from '../../../../core/modules/user/inputs/core-u
 @Restricted(RoleEnum.ADMIN)
 export class UserCreateInput extends CoreUserCreateInput {
   // Extend UserCreateInput here
-  @Field(() => String, {
+  @UnifiedField({
     description: 'Job Title of the user',
-    nullable: true,
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
   })
-  @IsOptional()
-  @Restricted(RoleEnum.ADMIN)
   jobTitle?: string = undefined;
 }

package/src/server/modules/user/inputs/user.input.ts

@@ -1,7 +1,7 @@
-import { Field, InputType } from '@nestjs/graphql';
-import { IsOptional } from 'class-validator';
+import { InputType } from '@nestjs/graphql';
 
 import { Restricted } from '../../../../core/common/decorators/restricted.decorator';
+import { UnifiedField } from '../../../../core/common/decorators/unified-field.decorator';
 import { RoleEnum } from '../../../../core/common/enums/role.enum';
 import { CoreUserInput } from '../../../../core/modules/user/inputs/core-user.input';
 
@@ -12,11 +12,10 @@ import { CoreUserInput } from '../../../../core/modules/user/inputs/core-user.in
 @Restricted(RoleEnum.ADMIN)
 export class UserInput extends CoreUserInput {
   // Extend UserInput here
-  @Field(() => String, {
+  @UnifiedField({
     description: 'Job Title of the user',
-    nullable: true,
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
   })
-  @IsOptional()
-  @Restricted(RoleEnum.ADMIN)
   jobTitle?: string = undefined;
 }