@lenne.tech/nest-server 11.34.0 → 11.34.1

package/migration-guides/11.34.0-to-11.34.1.md

@@ -0,0 +1,132 @@
+# Migration Guide: 11.34.0 → 11.34.1
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None in signatures. One **client-visible text** change: validation error messages are now rendered the way class-validator itself renders them (§1, §2) |
+| **Bugfixes** | A custom `message` in `ValidationOptions` is no longer ignored (§1). Default messages no longer reach API clients with raw placeholders such as `$constraint1` (§2) |
+| **Migration Effort** | Nothing to configure. Read §1 and §2 if any test — or any frontend — asserts on exact validation error strings. Read §3 before you put `$value` in a custom message |
+
+`MapAndValidatePipe` re-implements class-validator's validation executor, so it also has to render
+error messages the way that executor does. It did neither: it built every message from the
+constraint's `defaultMessage()` alone, and substituted only `$property`.
+
+---
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server@11.34.1
+pnpm run build
+pnpm test
+```
+
+No configuration change is required, and no source change is required in a typical project.
+
+**Vendor-mode projects: this release ADDS a file, so the sync is atomic.**
+`src/core/common/pipes/map-and-validate.pipe.ts` now imports the new
+`src/core/common/helpers/validation-message.helper.ts`. Taking the pipe without the helper does not
+fail a rights check or a test — it fails the build. Sync both files together.
+
+---
+
+## 1. A custom `message` in `ValidationOptions` is now honored
+
+Previously the pipe built the message from the constraint's own `defaultMessage()` and never looked
+at `metadata.message`, so the message you wrote was silently discarded and the client received the
+generic default instead.
+
+```typescript
+class UpdateUserInput {
+  @IsIn(['admin'], { each: true, message: 'roles may only contain assignable roles (admin)' })
+  @IsOptional()
+  roles?: string[];
+}
+```
+
+| | Before | After |
+|---|---|---|
+| Response | `each value in roles must be one of the following values: $constraint1` | `roles may only contain assignable roles (admin)` |
+
+Custom messages now take precedence over the constraint's default — the same order class-validator's
+own executor uses. The function form (`message: (args) => string`) works too, and its result is
+interpolated afterwards.
+
+**What you may notice:** a custom message that was written but never delivered starts being
+delivered. If a frontend or a test was written against the *default* text your project was
+accidentally serving, it now sees the text the decorator actually asks for.
+
+---
+
+## 2. Default messages no longer leak raw placeholders
+
+Only `$property` was substituted, so every other token reached the client verbatim:
+
+| | Before | After |
+|---|---|---|
+| Response | `each value in roles must be one of the following values: $constraint1` | `each value in roles must be one of the following values: alpha, beta` |
+
+All four special tokens are now interpolated — `$constraint1..N`, `$value`, `$property` and
+`$target` — rendered exactly as class-validator renders them (arrays joined with `, `, symbols by
+their description).
+
+**Scope of the text change:** 44 of class-validator's built-in messages carry a `$constraint` token,
+so those 44 change text. None of the built-ins uses `$value` or `$target`, so no built-in message
+changes *shape* — they stop showing a placeholder and start showing the value it stood for.
+
+**What to check:** any test or frontend string comparison that asserts on a full validation message.
+A test that was pinned to the broken output (`…: $constraint1`) fails and should be updated to the
+interpolated text.
+
+This also applies to `@IsDefined`, which since class-validator 0.13 is the one built-in that does not
+register through `ValidateBy` and therefore took a separate code path with the same two gaps.
+
+---
+
+## 3. Security: `$value` echoes the submitted value, and validation errors are not scrubbed
+
+`$value` now works — which means a custom message containing it renders the value the client
+submitted, straight back into the error response.
+
+**Validation errors bypass the secret-field filtering you may be assuming.**
+`security.secretFields` is applied by `CheckSecurityInterceptor` on the **response** path, whereas
+the `BadRequestException` raised by the pipe goes to the exception filter and is forwarded verbatim.
+The guard inside the renderer is a **type** guard (`boolean | number | string`), not a secrecy guard
+— it will happily echo a password or a token.
+
+```typescript
+// DANGEROUS — the rejected password is echoed back in the error response
+@MinLength(12, { message: 'password "$value" is too short' })
+password: string;
+
+// SAFE — describe the rule, never the submitted value
+@MinLength(12, { message: 'password must be at least $constraint1 characters' })
+password: string;
+```
+
+No built-in message uses `$value`, so reaching this is opt-in: it requires a custom message that
+names the token. Note that class-validator's own `validate()` behaves identically — this is not a
+new exposure introduced by the framework, but it becomes reachable in projects where `$value`
+previously did nothing.
+
+**Action:** grep your input classes for `$value` in custom messages and confirm none of them sits on
+a credential, token, or otherwise sensitive field.
+
+---
+
+## Under the hood
+
+The token renderer is a port of class-validator internals
+(`ValidationUtils.replaceMessageSpecialTokens`, `constraintToString`), which are not part of its
+public API. Because vendor-mode projects resolve their own class-validator, that port can meet a
+version this framework never installed. It is therefore pinned by an invariant test that compares it
+against the installed implementation over a fixture table, so a divergence surfaces as a failing
+test rather than as two renderers disagreeing about one decorator.
+
+---
+
+## Module Documentation
+
+- Request lifecycle and the validation pipe: [`docs/REQUEST-LIFECYCLE.md`](../docs/REQUEST-LIFECYCLE.md)
+- Field decorators and validation: `src/core/common/decorators/unified-field.decorator.ts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.34.0",
+  "version": "11.34.1",
   "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",

package/src/core/common/helpers/validation-message.helper.ts

@@ -0,0 +1,83 @@
+import { ValidationArguments } from 'class-validator';
+
+/**
+ * Renders a single constraint for use in an error message.
+ *
+ * Mirror of class-validator's internal `constraintToString`
+ * (`class-validator/cjs/validation/ValidationUtils`), which is NOT part of its public API.
+ *
+ * See {@link replaceMessageSpecialTokens} for why this lives here and what holds it in sync.
+ */
+export function constraintToString(constraint: unknown): string {
+  if (Array.isArray(constraint)) {
+    return constraint.join(', ');
+  }
+  if (typeof constraint === 'symbol') {
+    constraint = constraint.description;
+  }
+  return `${constraint}`;
+}
+
+/**
+ * Resolves a message (string or function) and interpolates the special tokens
+ * $constraint1..N, $value, $property and $target.
+ *
+ * Mirror of class-validator's internal `ValidationUtils.replaceMessageSpecialTokens`
+ * (`class-validator/cjs/validation/ValidationUtils`), which is NOT part of its public API.
+ * `MapAndValidatePipe` re-implements the validation executor and therefore has to render messages
+ * exactly the way class-validator's own `validate()` would — otherwise the same decorator produces
+ * two different strings depending on which of the two ran.
+ *
+ * WHY IT IS NOT BARREL-EXPORTED
+ * Deliberately absent from `src/index.ts`. It exists to reproduce a dependency's internal
+ * behaviour, so it has to stay free to follow that dependency; exporting it would owe consumers
+ * backward compatibility for a surface we do not control. Vendor-mode consumers resolve their own
+ * class-validator, so the copy in `src/core/` can meet a version this repo never installed —
+ * `tests/unit/validation-message-mirror.spec.ts` compares it against the INSTALLED implementation
+ * over a fixture table so a divergence surfaces as a failing test rather than as two renderers of
+ * one contract.
+ *
+ * SECURITY — `$value` echoes the SUBMITTED value back to the client, and validation errors are
+ * never scrubbed: `security.secretFields` is applied by `CheckSecurityInterceptor` on the RESPONSE
+ * path, whereas the `BadRequestException` raised from the pipe goes to the exception filter and is
+ * forwarded verbatim. The check below is a TYPE guard (boolean | number | string), not a secrecy
+ * guard — it happily admits a password or a token. No built-in message uses `$value`, so reaching
+ * it is opt-in: never put `$value` in a custom message on a sensitive field.
+ */
+export function replaceMessageSpecialTokens(
+  message: ((args: ValidationArguments) => string) | string,
+  validationArguments: ValidationArguments,
+): string {
+  let messageString = '';
+  if (typeof message === 'function') {
+    messageString = message(validationArguments);
+  } else if (typeof message === 'string') {
+    messageString = message;
+  }
+
+  if (messageString && Array.isArray(validationArguments.constraints)) {
+    validationArguments.constraints.forEach((constraint, index) => {
+      messageString = messageString.replace(
+        new RegExp(`\\$constraint${index + 1}`, 'g'),
+        constraintToString(constraint),
+      );
+    });
+  }
+
+  if (
+    messageString &&
+    validationArguments.value !== undefined &&
+    validationArguments.value !== null &&
+    ['boolean', 'number', 'string'].includes(typeof validationArguments.value)
+  ) {
+    messageString = messageString.replace(/\$value/g, `${validationArguments.value}`);
+  }
+  if (messageString) {
+    messageString = messageString.replace(/\$property/g, validationArguments.property);
+  }
+  if (messageString) {
+    messageString = messageString.replace(/\$target/g, validationArguments.targetName);
+  }
+
+  return messageString;
+}

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

@@ -20,6 +20,7 @@ import {
   maxLength,
   min,
   minLength,
+  ValidationArguments,
   ValidationError,
 } from 'class-validator';
 import { ValidationMetadata } from 'class-validator/types/metadata/ValidationMetadata';
@@ -27,6 +28,7 @@ import { inspect } from 'util';
 
 import { getUnifiedFieldKeys, nestedTypeRegistry } from '../decorators/unified-field.decorator';
 import { isBasicType } from '../helpers/input.helper';
+import { replaceMessageSpecialTokens } from '../helpers/validation-message.helper';
 import { ConfigService } from '../services/config.service';
 import { ErrorCode } from '../../modules/error-code/error-codes';
 
@@ -268,18 +270,21 @@ async function validateWithInheritance(object: any, originalPlainValue: any): Pr
                       isValid = validationResult instanceof Promise ? await validationResult : validationResult;
                     }
 
-                    // Get default message and constraint name if validation failed
+                    // Get message and constraint name if validation failed
                     if (!isValid) {
                       // Use metadata.name for the constraint key (e.g., "isEmail", "isString")
                       const constraintName = metadata.name || 'customValidation';
 
-                      if (typeof constraintInstance.defaultMessage === 'function') {
-                        errorMessage = constraintInstance.defaultMessage(validationArgs);
-                        // Replace $property placeholder with actual property name
-                        errorMessage = errorMessage.replace(/\$property/g, propertyName);
-                      } else {
-                        errorMessage = `${propertyName} failed custom validation`;
+                      // A custom message from ValidationOptions takes precedence over the
+                      // constraint's default message — same order as class-validator's executor
+                      let messageTemplate: string | ((args: ValidationArguments) => string) | undefined =
+                        metadata.message as string | ((args: ValidationArguments) => string) | undefined;
+                      if (!messageTemplate && typeof constraintInstance.defaultMessage === 'function') {
+                        messageTemplate = constraintInstance.defaultMessage(validationArgs);
                       }
+                      errorMessage = messageTemplate
+                        ? replaceMessageSpecialTokens(messageTemplate, validationArgs)
+                        : `${propertyName} failed custom validation`;
 
                       // Add to constraints with the proper name
                       propertyError.constraints[constraintName] = errorMessage;
@@ -578,6 +583,19 @@ async function validateWithInheritance(object: any, originalPlainValue: any): Pr
 
           // Add constraint violation if validation failed
           if (!isValid) {
+            // A custom message from ValidationOptions takes precedence over the built-in message
+            if (metadata.message) {
+              errorMessage = replaceMessageSpecialTokens(
+                metadata.message as string | ((args: ValidationArguments) => string),
+                {
+                  constraints: metadata.constraints || [],
+                  object: tempInstance,
+                  property: propertyName,
+                  targetName: targetClass.name,
+                  value: propertyValue,
+                },
+              );
+            }
             propertyError.constraints[constraintType] = errorMessage;
           }
         }