@lenne.tech/nest-server 11.34.0 → 11.35.0

package/src/core/common/helpers/graphql-ws-context.helper.ts

@@ -0,0 +1,192 @@
+// `require`, NOT an ESM import: `@nestjs/graphql` builds the schema with the instance Node's CJS
+// cache holds, and graphql REFUSES a schema "from another module or realm". An ESM import can resolve
+// to a second copy of the module (a bundler's interop namespace, or a duplicated install), and the
+// wrapper would then reject the very schema it was handed. The repo already uses this form for
+// `graphql-upload` and `lodash` for the same reason.
+import graphql = require('graphql');
+
+import { getTenantContextResolver } from '../services/core-tenant-context.registry';
+import { ConfigService } from '../services/config.service';
+import { IRequestContext, RequestContext } from '../services/request-context.service';
+
+/**
+ * A `RequestContext` for GraphQL operations that arrive over a WEBSOCKET.
+ *
+ * WHY THIS EXISTS — the gap it closes is a silent, complete tenant bypass:
+ *
+ * `RequestContextMiddleware` is Express middleware (`consumer.apply(...).forRoutes('*')`). A
+ * WebSocket UPGRADE is not a `request` event, so it traverses no middleware — and `CoreTenantGuard`
+ * cannot help either, because its `getRequest()` looks for `context.req`, which a subscription
+ * context (the graphql-ws `extra` object) does not have, so the guard returns `true` without
+ * deciding anything.
+ *
+ * The consequence was invisible from the query itself. `mongooseTenantPlugin.shouldBypass()` reads
+ * "no RequestContext" as "system operation, no filter" — correct for a cron job or a migration, and
+ * exactly wrong here. So a tenant-scoped read performed while delivering a subscription message
+ * returned EVERY tenant's rows, and the plugin's own safety net (which throws when a tenant-scoped
+ * schema is touched without a tenant) never fired, because there was no context to notice.
+ *
+ * WHERE IT HOOKS IN: `GqlSubscriptionService` reads `execute` and `subscribe` off the GraphQL module
+ * options and hands them to BOTH WebSocket transports (`graphql-ws` and `subscriptions-transport-ws`),
+ * defaulting to graphql-js's own. Those two functions are the only place where the whole WS operation
+ * — including every field resolver and the `resolve`/`filter` callbacks of a subscription — is
+ * reachable as one call. HTTP does not go through them (Apollo runs its own pipeline), so wrapping
+ * them touches the WS path only.
+ *
+ * THE ASYNC-ITERATOR PART IS LOAD-BEARING. `subscribe()` returns an AsyncIterator, and graphql-js
+ * runs the per-event execution — `resolve`, `filter`, every field resolver — inside that iterator's
+ * `next()`, which the transport pulls LONG AFTER `subscribe()` returned. Establishing the context
+ * only around the `subscribe()` call therefore covers the initial subscribe and nothing else: the
+ * store is gone by the time the first message is delivered. Wrapping `next()` (and `return`/`throw`)
+ * is what puts every delivered message inside the context.
+ */
+
+/** Minimal shape of what graphql-js `execute`/`subscribe` receive. */
+interface GraphQlArgs {
+  contextValue?: any;
+  [key: string]: any;
+}
+
+type ExecuteFn = (args: GraphQlArgs) => any;
+
+/**
+ * Read the tenant header out of whatever the transport left on the context.
+ *
+ * Both WS transports are covered, and the reason there are three sources is that they genuinely
+ * differ: `graphql-ws` gets `extra.headers` from `CoreModule`'s `onConnect` (the client's
+ * `connectionParams`), `subscriptions-transport-ws` returns `{ headers }` from its own `onConnect`,
+ * and the raw upgrade request is the fallback for a project with a custom `onConnect` that forwards
+ * neither. Header names are matched case-insensitively — `connectionParams` are client-supplied JSON
+ * and arrive with whatever casing the client used, unlike Node's lower-cased HTTP headers.
+ */
+function readTenantHeader(contextValue: any): string | undefined {
+  const headerName = (ConfigService.configFastButReadOnly?.multiTenancy?.headerName ?? 'x-tenant-id').toLowerCase();
+  const sources = [contextValue?.headers, contextValue?.connectionParams, contextValue?.request?.headers];
+  for (const source of sources) {
+    if (!source || typeof source !== 'object') {
+      continue;
+    }
+    for (const [key, value] of Object.entries(source as Record<string, unknown>)) {
+      if (key.toLowerCase() === headerName && typeof value === 'string' && value) {
+        return value;
+      }
+    }
+  }
+  return undefined;
+}
+
+/** The user the connection authenticated as, as `CoreModule`'s `onConnect` recorded it. */
+function readUser(contextValue: any): any {
+  return contextValue?.user ?? contextValue?.extra?.user ?? undefined;
+}
+
+/**
+ * Build the context for one WebSocket operation.
+ *
+ * Returns `undefined` when the operation is NOT a WebSocket one (an HTTP context carries `req`, and
+ * the middleware has already established a context for it) — wrapping that again would replace a
+ * live, lazily-evaluated context with a snapshot.
+ */
+export async function buildWsRequestContext(contextValue: any): Promise<IRequestContext | undefined> {
+  if (!contextValue || typeof contextValue !== 'object' || contextValue.req) {
+    return undefined;
+  }
+
+  const user = readUser(contextValue);
+  const context: IRequestContext = { currentUser: user };
+
+  // Language: same source as the HTTP path, when the transport carried it.
+  const acceptLanguage =
+    contextValue.headers?.['accept-language'] ??
+    contextValue.connectionParams?.['accept-language'] ??
+    contextValue.request?.headers?.['accept-language'];
+  if (typeof acceptLanguage === 'string') {
+    context.language = acceptLanguage;
+  }
+
+  const resolver = getTenantContextResolver();
+  if (resolver) {
+    // A failure here must NOT be answered with an unscoped context — that is the leak this file
+    // exists to close. Leaving the tenant fields unset makes the plugin's safety net refuse
+    // tenant-scoped reads, which is the safe direction.
+    try {
+      Object.assign(context, await resolver.resolve(user, readTenantHeader(contextValue)));
+    } catch {
+      // Intentionally swallowed: see above. Non-tenant operations keep working.
+    }
+  }
+
+  return context;
+}
+
+/**
+ * Run an AsyncIterator's pulls inside `context`.
+ *
+ * `next()` is where graphql-js executes the per-event selection set, so this is what carries the
+ * context into every delivered message rather than only into the initial subscribe.
+ */
+export function withRequestContextAsyncIterator<T>(
+  iterator: AsyncIterator<T> & { [Symbol.asyncIterator]?: () => AsyncIterator<T> },
+  context: IRequestContext,
+): AsyncIterableIterator<T> {
+  const wrapped: AsyncIterableIterator<T> = {
+    next: (...args: [] | [undefined]) => RequestContext.run(context, () => iterator.next(...(args as []))),
+    [Symbol.asyncIterator]() {
+      return wrapped;
+    },
+  };
+  if (iterator.return) {
+    wrapped.return = (value?: any) => RequestContext.run(context, () => iterator.return!(value));
+  }
+  if (iterator.throw) {
+    wrapped.throw = (error?: any) => RequestContext.run(context, () => iterator.throw!(error));
+  }
+  return wrapped;
+}
+
+/** Is this an AsyncIterator (a subscription source) rather than a plain execution result? */
+function isAsyncIterable(value: any): boolean {
+  return !!value && typeof value === 'object' && typeof value[Symbol.asyncIterator] === 'function';
+}
+
+/**
+ * Wrap graphql-js `execute` so a query/mutation sent over the WebSocket runs in a request context.
+ *
+ * Not only subscriptions: `graphql-ws` carries queries and mutations too, and those had the same gap.
+ */
+export function createRequestContextAwareExecute(execute: ExecuteFn): ExecuteFn {
+  return async (args: GraphQlArgs) => {
+    const context = await buildWsRequestContext(args?.contextValue);
+    if (!context) {
+      return execute(args);
+    }
+    return RequestContext.run(context, () => execute(args));
+  };
+}
+
+/** Wrap graphql-js `subscribe` so both the subscribe AND every delivered message run in a context. */
+export function createRequestContextAwareSubscribe(subscribe: ExecuteFn): ExecuteFn {
+  return async (args: GraphQlArgs) => {
+    const context = await buildWsRequestContext(args?.contextValue);
+    if (!context) {
+      return subscribe(args);
+    }
+    const result = await RequestContext.run(context, () => subscribe(args));
+    return isAsyncIterable(result) ? withRequestContextAsyncIterator(result as AsyncIterator<any>, context) : result;
+  };
+}
+
+/**
+ * The pair `CoreModule` installs — graphql's own `execute` / `subscribe`, wrapped.
+ *
+ * Zero-arg factories rather than pre-built constants so nothing is captured at module-evaluation
+ * time, and so `core.module.ts` needs no graphql import of its own (see the `require` note at the top
+ * of this file for why that import form matters).
+ */
+export function buildRequestContextAwareExecute(): (args: GraphQlArgs) => any {
+  return createRequestContextAwareExecute(graphql.execute as any);
+}
+
+export function buildRequestContextAwareSubscribe(): (args: GraphQlArgs) => any {
+  return createRequestContextAwareSubscribe(graphql.subscribe as any);
+}

package/src/core/common/helpers/gridfs.helper.ts

@@ -198,10 +198,26 @@ export class GridFSHelper {
   }
 
   /**
-   * Find file metadata by filename
+   * Find file metadata by filename — the MOST RECENT file with that name.
+   *
+   * The sort is load-bearing, not cosmetic. `bucket.find({ filename })` returns natural order,
+   * which in practice is the OLDEST document first, while `openDownloadStreamByName()` defaults to
+   * `revision: -1` — the NEWEST. Filenames are unique in no store and are client-supplied, so with
+   * two files of one name this method answered one document and the download served another: an
+   * ownership rule built on `getRawFileInfoByName()` approved the caller's own file and the stream
+   * handed over the other one.
+   *
+   * Newest-first (rather than oldest-first) because it is the BYTES semantics that must not move:
+   * GridFS treats a re-upload under the same name as a new revision and serves the latest, so
+   * aligning the metadata lookup with that keeps every existing download answering the same bytes
+   * and only corrects the document describing them. `_id` breaks the tie, so two files written in
+   * the same millisecond still order totally.
    */
   static async findFileByName(bucket: GridFSBucket, filename: string): Promise<GridFSFileInfo | null> {
-    const files = await bucket.find({ filename }).toArray();
+    // `uploadDate` FIRST: MongoDB applies sort keys in document order, so leading with `_id` would
+    // make the tie-break the primary key and could disagree with the driver's own by-name revision
+    // order (which sorts on `uploadDate` alone).
+    const files = await bucket.find({ filename }, { limit: 1, sort: { uploadDate: -1, _id: -1 } }).toArray();
     return files.length > 0 ? GridFSHelper.normalizeFileInfo(files[0]) : null;
   }
 

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/interceptors/check-security.interceptor.ts

@@ -3,6 +3,7 @@ import { Observable } from 'rxjs';
 import { map } from 'rxjs/operators';
 
 import { getContextData } from '../helpers/context.helper';
+import { hasRestrictionsCheckedMarker } from '../decorators/restrictions-checked.marker';
 import { getStringIds } from '../helpers/db.helper';
 import { processDeep } from '../helpers/input.helper';
 import { ConfigService } from '../services/config.service';
@@ -66,7 +67,9 @@ export class CheckSecurityInterceptor implements NestInterceptor {
       objectData = data;
 
       // Check if data already checked
-      if (this.config.noteCheckedObjects && data?._objectAlreadyCheckedForRestrictions) {
+      // Recognised by the framework MARKER, not by a truthy property of that name — see
+      // restrictions-checked.marker.ts for why a document must not be able to skip securityCheck().
+      if (this.config.noteCheckedObjects && hasRestrictionsCheckedMarker(data)) {
         return data;
       }
 

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

@@ -6,6 +6,7 @@ import { resolveResponseModelClass } from '../helpers/interceptor.helper';
 import { CoreModel } from '../models/core-model.model';
 import { ConfigService } from '../services/config.service';
 import { ModelRegistry } from '../services/model-registry.service';
+import { hasRestrictionsCheckedMarker } from '../decorators/restrictions-checked.marker';
 
 /**
  * Interceptor that automatically converts plain objects and Mongoose documents
@@ -48,7 +49,7 @@ export class ResponseModelInterceptor implements NestInterceptor {
         }
 
         // Already processed by another interceptor
-        if (data._objectAlreadyCheckedForRestrictions) {
+        if (hasRestrictionsCheckedMarker(data)) {
           return data;
         }
 
@@ -90,7 +91,7 @@ export class ResponseModelInterceptor implements NestInterceptor {
     }
 
     // Already processed
-    if (item._objectAlreadyCheckedForRestrictions) {
+    if (hasRestrictionsCheckedMarker(item)) {
       return item;
     }
 

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

@@ -855,6 +855,41 @@ export interface IErrorCode {
  * therefore be expressed in `checkRights()`, not by a role name alone.
  */
 export interface IFileConfig {
+  /**
+   * WHICH PROJECT CLASS this deployment is — the per-file rule, as a declaration instead of code.
+   *
+   * The role knobs below are the coarse audience filter ("may this caller reach the route at all").
+   * They cannot express "…but only their own", because that sentence needs data. That is what
+   * `CoreFileService.checkRights()` is for — and shipping it only as an `@example` to copy went wrong
+   * twice in this framework's own history, both times permissively. So the four shapes are presets:
+   *
+   * | value             | project class                                                    |
+   * |-------------------|------------------------------------------------------------------|
+   * | `'custom'`        | you override `checkRights()` yourself — **the default**, the framework abstains |
+   * | `'public'`        | open: anyone may read and write; the role gate is the whole policy |
+   * | `'authenticated'` | login-restricted: every signed-in user may use every file         |
+   * | `'owner'`         | per-user: only the uploader, plus ADMIN                           |
+   * | `'tenant'`        | per-tenant: only within one's own validated tenant, plus ADMIN    |
+   *
+   * `'owner'` and `'tenant'` read `metadata.ownerId` / `metadata.tenantId`, which the service STAMPS
+   * as it writes once one of them is active — so an upload through `CoreFileService` is authorizable
+   * without any project code. Files written BEFORE the preset was enabled carry no such metadata and
+   * are therefore ADMIN-only; that is the fail-closed direction, and a one-off backfill fixes it.
+   *
+   * Two things this setting never does: it never overrides an explicit `checkRights()` override (the
+   * override IS the rule), and it never widens the role gate. `'public'` still requires
+   * `downloadRoles: [S_EVERYONE]` — declaring the class and opening the gate are two decisions on
+   * purpose.
+   *
+   * An UNKNOWN value resolves to `'owner'`, not to `'custom'`: a typo means somebody believes they
+   * have an ownership rule, and confirming that belief is the one error that cannot be seen from
+   * outside.
+   *
+   * @default 'custom'
+   * @since 11.35.0
+   */
+  access?: 'authenticated' | 'custom' | 'owner' | 'public' | 'tenant';
+
   /**
    * Roles allowed to DELETE files (`deleteFile` mutation).
    *
@@ -996,9 +1031,28 @@ export interface IMultiTenancy {
 
   /**
    * Model names (NOT collection names) to exclude from tenant filtering.
-   * These schemas will not have tenant isolation applied.
-   * The TenantMember model is always excluded automatically.
-   * @example ['User', 'Session']
+   *
+   * **This is an OFF SWITCH for data isolation, per model.** A listed schema gets no tenant filter at
+   * all: every query on it sees every tenant's rows. That is correct for a genuinely global
+   * collection, and it is a data leak for anything else.
+   *
+   * A schema is only affected if it HAS a `tenantId` field — the plugin attaches to no other. So
+   * listing a model that declares `tenantId` overrides its author's intent, and since 11.35.0 the
+   * plugin logs a warning naming the model when that happens. **Do not list a model just because a
+   * `populate()` returns null** — that is the isolation working; scope the reference instead, or
+   * confirm the referenced collection really is global.
+   *
+   * `User` is the one to think hardest about. It belongs here only when users are GLOBAL (one account
+   * reaches several tenants, memberships carry the scope). If your users are per-tenant — they have a
+   * `tenantId` — listing `User` switches isolation off for the account collection, which is usually
+   * the last place you want it off. Earlier versions of this doc suggested `['User', 'Session']` as an
+   * example; that suggestion is withdrawn, because it is only right for the global-user model.
+   *
+   * The membership model (`multiTenancy.membershipModel`, default `TenantMember`) is added
+   * automatically and needs no entry — membership is tenant-spanning by design.
+   *
+   * @default []
+   * @example [] // start here; add a model only when you can say why it is global
    */
   excludeSchemas?: string[];
 
@@ -1039,23 +1093,86 @@ export interface IMultiTenancy {
    * @default { member: 1, manager: 2, owner: 3 }
    * @since 11.21.0
    *
+   * SECURITY: never name a tenant role after a GLOBAL role. `RoleEnum.ADMIN` (`'admin'`) and every
+   * other member of `GLOBAL_ONLY_ROLES` is rejected here — a tenant role of that name used to
+   * satisfy `@Roles(RoleEnum.ADMIN)` in tenant context, i.e. a customer could grant themselves
+   * platform authority. Use a tenant-specific name (`tenantAdmin`, `spaceAdmin`) instead, and
+   * declare your own platform-wide roles in {@link globalOnlyRoles}. The boot check refuses a
+   * hierarchy that violates this.
+   *
    * @example
    * ```typescript
    * // config.env.ts
    * multiTenancy: {
-   *   roleHierarchy: { viewer: 1, editor: 2, manager: 2, admin: 3, owner: 4 }
+   *   roleHierarchy: { viewer: 1, editor: 2, manager: 2, tenantAdmin: 3, owner: 4 }
    * }
    *
    * // roles.ts
    * import { createHierarchyRoles } from '@lenne.tech/nest-server';
-   * export const HR = createHierarchyRoles({ viewer: 1, editor: 2, manager: 2, admin: 3, owner: 4 });
+   * export const HR = createHierarchyRoles({ viewer: 1, editor: 2, manager: 2, tenantAdmin: 3, owner: 4 });
    *
    * // resolver.ts
-   * @Roles(HR.EDITOR) // requires level >= 2 (editor, manager, admin, owner)
+   * @Roles(HR.EDITOR) // requires level >= 2 (editor, manager, tenantAdmin, owner)
    * ```
    */
   roleHierarchy?: Record<string, number>;
 
+  /**
+   * Project-defined roles that carry GLOBAL (platform-wide) authority.
+   *
+   * `RoleEnum.ADMIN` is always treated this way; this option extends the set with your own.
+   * A role listed here is ALWAYS resolved against `user.roles` and NEVER against a tenant
+   * membership role — no matter what the `X-Tenant-Id` header says.
+   *
+   * **Why this matters.** Membership roles are customer-assigned free text, and in tenant context
+   * required roles are otherwise compared against `membership.role`. Without this list, a global
+   * endpoint guarded by `@Roles('auditor')` is reachable by any tenant member whose membership role
+   * happens to be `'auditor'` — granted by their own tenant owner, not by you.
+   *
+   * Declaring a role here is therefore a security statement: "only the platform may grant this".
+   * A role that appears BOTH here and in {@link roleHierarchy} fails the boot check, because it
+   * would have to be resolved against two different sources at once.
+   *
+   * @default [] (only RoleEnum.ADMIN is global)
+   * @since 11.35.0
+   *
+   * @example
+   * ```typescript
+   * multiTenancy: {
+   *   roleHierarchy:   { member: 1, tenantAdmin: 2, owner: 3 },  // per tenant
+   *   globalOnlyRoles: ['auditor', 'support'],                    // platform-wide
+   * }
+   * ```
+   */
+  globalOnlyRoles?: string[];
+
+  /**
+   * Refuse membership roles that are not declared anywhere (deny by default).
+   *
+   * When `true`, `addMember()` / `updateMemberRole()` accept only roles present in
+   * {@link roleHierarchy} or {@link additionalMembershipRoles}. When `false` (default, backward
+   * compatible), any non-reserved string is accepted.
+   *
+   * An undeclared membership role can never GRANT anything either way — the guards only match
+   * declared tenant roles — but with this on, the mistake surfaces as a 400 at assignment time
+   * instead of as a membership that silently authorizes nothing.
+   *
+   * @default false
+   * @since 11.35.0
+   */
+  strictMembershipRoles?: boolean;
+
+  /**
+   * Membership roles that are valid but carry no hierarchy level (exact-match roles).
+   *
+   * Only consulted when {@link strictMembershipRoles} is `true`. Use it for roles like `'auditor'`
+   * that are meaningful per tenant but do not sit in the level ordering.
+   *
+   * @default []
+   * @since 11.35.0
+   */
+  additionalMembershipRoles?: string[];
+
   /**
    * TTL in milliseconds for the tenant guard's in-memory membership cache.
    * The cache avoids repeated DB lookups when the same user accesses the same tenant.
@@ -2210,7 +2327,8 @@ export interface IServerOptions {
    *
    * // Enable with excluded schemas and custom header
    * multiTenancy: {
-   *   excludeSchemas: ['User', 'Session'],
+   *   // excludeSchemas turns isolation OFF per model — see IMultiTenancy.excludeSchemas
+   *   excludeSchemas: [],
    *   headerName: 'x-tenant-id',
    * },
    * ```
@@ -2852,6 +2970,20 @@ export interface IS3Config {
   presignedDownloads?:
     | boolean
     | {
+        /**
+         * Explicitly disable while keeping the settings around — the repo-wide
+         * "presence implies enabled, unless `enabled: false`" pattern.
+         *
+         * It is spelled out in the type because it is REACHABLE WITHOUT THE TYPE: `NEST_SERVER_CONFIG`
+         * and the `NSC__*` variables deliver plain JSON, so `{"enabled": false}` could always be set —
+         * and `CoreS3Service` used to read any object as "enabled", which meant presigned downloads
+         * came on while the boot warning (which does honour the key) stayed silent. Two code paths
+         * answering one question differently is how a bearer-capability download gets switched on by
+         * accident.
+         * @default true (when the config object is present)
+         */
+        enabled?: boolean;
+
         /**
          * Presigned URL validity in seconds.
          *

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;
           }
         }