@lenne.tech/nest-server 11.34.0 → 11.35.0

package/docs/REQUEST-LIFECYCLE.md

@@ -205,6 +205,7 @@ JWT-based authentication for existing projects:
 | **Apollo Server** | Full GraphQL server with schema-first or code-first |
 | **Custom Scalars** | `Date`, `DateTime` (timestamp), `JSON`, `Any` |
 | **Subscriptions** | WebSocket support via `graphql-ws` with auth. The `PUB_SUB` provider is built from a factory: `CoreRedisPubSub` when `redis` is configured (delivery is then cluster-wide), the in-memory `PubSub` otherwise (delivery only to clients connected to the publishing replica). **Constraint once Redis is in play: every published payload must be JSON-serializable** — it crosses the wire as JSON, so `Date`, class instances, `Map`/`Set` and `undefined` do not survive the round trip. An in-process `PubSub` never had this constraint, so a payload that worked on one replica can silently lose fields on a cluster. Publish plain objects and ISO strings |
+| **Subscription request context** | Since 11.35.0 `CoreModule` installs a context-aware `execute` / `subscribe` pair (inside `subscriptions`, where `ApolloDriver` forwards it) on all three GraphQL driver builders, so every WebSocket operation runs inside a `RequestContext`. Before that a WS operation had **none** — no Express middleware runs on an upgrade, and `CoreTenantGuard.getRequest()` finds no `req` on a subscription context — and `mongooseTenantPlugin` reads "no context" as "system operation, no filter", so a tenant-scoped read while delivering a subscription message returned EVERY tenant's rows. The tenant comes from the handshake's tenant header **validated against an active membership**, else from the subscriber's memberships; an unresolvable tenant leaves the safety net to refuse the read. The async iterator is wrapped too, not only the subscribe call: graphql-js runs `resolve` / `filter` / field resolvers inside its `next()`. See `.claude/rules/role-system.md` → "Tenant context on non-HTTP transports" |
 | **Complexity Analysis** | Query cost calculation to prevent DoS attacks |
 | **Enum Registration** | `registerEnum()` helper for GraphQL enum types |
 | **Upload Support** | `graphqlUploadExpress()` for multipart file uploads |
@@ -1217,6 +1218,64 @@ export class User extends CorePersistenceModel {
 }
 ```
 
+#### Nested data: only a DECLARED type is enforced (11.35.0+)
+
+The check recurses, but it can only find metadata for a nested value whose class it knows. An embedded
+subdocument read out of MongoDB is a **plain object** (`CoreModel.map()` is a shallow `Object.assign`;
+`prepareOutput()` and `ResponseModelInterceptor` map the top level only), and `Object` carries no
+`@Restricted` metadata. Before 11.35.0 that meant every nested restriction silently evaluated to "no
+restrictions at all"; since 11.35.0 the nested type registry `@UnifiedField` fills is consulted, so a
+plain nested value is matched against the class its parent DECLARED — at every level, and for every
+item of a declared array.
+
+```typescript
+@UnifiedField({ type: () => Insurance })                    // enforced
+insurance?: Insurance;
+
+@UnifiedField({ isArray: true, type: () => Insurance })     // enforced, every item
+insurances?: Insurance[];
+
+@UnifiedField({ isAny: true })                              // NOT reached — nothing declares the type
+extra?: any;
+```
+
+An undeclared nested type stays unchecked on purpose: such a value is just as legitimately free-form
+JSON, a `Map` or a scalar, and failing closed would strip far more than it protects. **If a nested
+field must be protected, declare its type.** A class-level `@Restricted` on a nested type strips the
+contents and leaves an empty container (the `checkObjectItself: false` default).
+
+### File access — two layers, and why neither is optional
+
+Files are the one resource whose authorization does NOT go through `CrudService.process()`, so the
+decorator model above does not reach them. GridFS is reached through the native MongoDB driver and S3
+through its own SDK, which means `mongooseTenantPlugin` never runs on a file store — and that is why
+`CoreFileController` and `CoreFileResolver` carry `@SkipTenantCheck()`.
+
+| Layer | What it answers | Where |
+|-------|-----------------|-------|
+| `file.downloadRoles` / `uploadRoles` / `deleteRoles` | "may this caller reach the route at all" | applied onto the base-class members at boot by `applyFileRoles()`, read by the role guards |
+| `CoreFileService.checkRights()` | "…but only THIS file" | the service, once per operation, with `checkInputType` naming the path (`'id'`, `'filename'`, `'filterArgs'`, `'file'`, `'files'`) |
+
+**The first layer cannot express the second.** The role names resolve against `user.roles` — a global
+attribute — never against `membership.role`, so no configuration can say "only their own tenant's
+files". That sentence needs data, and the data lives in the file's `metadata`.
+
+**File ids are not secrets.** An ObjectId is 4 bytes of timestamp + 5 bytes of randomness generated once
+PER PROCESS + a 3-byte incrementing counter, so a caller who holds one valid id (their own upload) knows
+the random part and a counter reference point; neighbouring files sit on neighbouring values. The file
+routes are also not rate-limited by the framework. So a widened role gate without a per-file rule is
+practically enumerable, not theoretically.
+
+Since 11.35.0 the second layer is a declaration rather than code — `file.access`, one value per project
+class (`'public'`, `'authenticated'`, `'owner'`, `'tenant'`, or `'custom'` to write your own, the
+default). `'owner'` / `'tenant'` also STAMP the metadata they decide on as the service writes. When the
+gate is widened past `ADMIN` and neither `file.access` nor an override declares a policy, the service
+warns at boot — the difference between a decision and an omission is the only thing a boot check can
+usefully detect.
+
+Full model, per-driver behaviour and the audit checklist: `src/core/modules/file/README.md` § Access
+control and `src/core/modules/file/INTEGRATION-CHECKLIST.md`.
+
 ### @UnifiedField() — Schema & Validation
 
 Single decorator that replaces `@Field()`, `@ApiProperty()`, `@IsOptional()`, and more:
@@ -1459,7 +1518,7 @@ const allOrders = await RequestContext.runWithBypassTenantGuard(async () => {
 
 // Exclude specific schemas from tenant filtering
 multiTenancy: {
-  excludeSchemas: ['User', 'Session'], // model names, not collection names
+  excludeSchemas: [], // model names, not collection names — this turns isolation OFF per model
 }
 ```
 

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`