@lenne.tech/nest-server 11.34.1 → 11.35.1

package/migration-guides/11.35.0-to-11.35.1.md

@@ -0,0 +1,152 @@
+# Migration Guide: 11.35.0 → 11.35.1
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None in signatures. One **client-visible** change: a refused upload now answers **400** instead of **500**, with Nest's standard error envelope instead of an internal-error one (§1) |
+| **Bugfixes** | `multerFileFilter` rejections finally map to a 4xx (§1). Seven documented helper names are reachable from the package root for the first time (§2). The file-access boot warning can no longer be fooled by a subclassed controller (§3) |
+| **Migration Effort** | Nothing to configure. Read §1 if a frontend, a test, or an alerting rule branches on the status or body of a rejected upload. **Read §3 if you subclass `CoreFileController` / `CoreFileResolver` and re-declare a member** — you may see a new warning at startup, and it is probably telling you something true |
+
+---
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server@11.35.1
+pnpm run build
+pnpm test
+```
+
+No configuration change is required, and no source change is required in a typical project.
+
+**Vendor-mode projects:** §1 and §2 are single-file and independent —
+`src/core/common/helpers/file.helper.ts` and `src/index.ts`. §3 is **not**: it adds
+`src/core/modules/file/core-file-access-audit.initializer.ts` and changes
+`file-roles.config.ts`, `file-roles.helper.ts` and `core.module.ts` together. Taking the initializer
+without the `core.module.ts` provider registration gives you a file that is never constructed — a
+security check that silently does not run, which is worse than not having it. Sync those four
+together.
+
+---
+
+## 1. A refused upload answers 400, not 500
+
+11.32.4 §8 changed `multerFileFilter`'s rejection from a bare string to `new Error(...)`, intending a
+clean 400. It never produced one.
+
+`transformException` in `@nestjs/platform-express` returns any **non-`HttpException`** unchanged. Its
+switch matches only multer's own message constants (`LIMIT_FILE_SIZE`, `LIMIT_UNEXPECTED_FILE`, …),
+and a message this helper writes matches none of them — so the rejection fell off the end of the
+switch, reached Nest's exception layer as a plain error, and the client was told the **server** had
+failed for a file the **client** sent wrong.
+
+Both rejection paths are affected and both are fixed: the allow-list refusal, and the
+scriptable-type refusal (`text/html`, `image/svg+xml`) added by 11.32.4 §6.
+
+| | Before | After |
+|---|---|---|
+| Status | `500 Internal Server Error` | `400 Bad Request` |
+| Body | internal-error envelope | Nest's standard 400 shape |
+| Message text | unchanged | unchanged — same text, still built from the accept list |
+
+**What to check:**
+
+- **Frontends** that branch on the status of an upload response. A rejected file was previously
+  indistinguishable from a storage outage; it now identifies itself, and the message is worth showing
+  to the user.
+- **Tests** pinned to the broken output. A test asserting `500` on a refused upload fails and should
+  be updated to `400`.
+- **Alerting.** Refused uploads no longer raise 5xx. If a dashboard counted them, its numbers drop —
+  that is the fix, not a regression. Conversely, an alert that was tuned to tolerate that noise can
+  be tightened again.
+
+A consumer catching the rejection in code is unaffected: `BadRequestException extends HttpException
+extends Error`, so an `instanceof Error` check keeps working.
+
+---
+
+## 2. Seven documented helpers are now exported from the package root
+
+The 11.34.x → 11.35.x guide's *New Exports* block lists names that `src/index.ts` never exported, so
+importing them from `@lenne.tech/nest-server` failed to compile:
+
+| Name | Module |
+|---|---|
+| `resolveGuardRequest` | `common/helpers/execution-context-request.helper` |
+| `buildRequestContextAwareExecute` | `common/helpers/graphql-ws-context.helper` |
+| `buildRequestContextAwareSubscribe` | same |
+| `createRequestContextAwareExecute` | same |
+| `createRequestContextAwareSubscribe` | same |
+| `getTenantContextResolver` | `common/services/core-tenant-context.registry` |
+| `setTenantContextResolver` | same |
+
+Purely additive — three `export * from` lines. Nothing was renamed or removed, and no existing import
+changes meaning.
+
+**Who this affected:** npm-mode consumers only, and only those who followed the guide. In-tree and
+vendor-mode consumers import over relative paths and never touched the barrel, which is also why
+nothing in this repo noticed: no framework module, test or e2e spec imports from `src/index.ts`, so a
+helper could be written, wired, documented and shipped with the full suite green.
+`tests/unit/public-api-barrel.spec.ts` now reads the expected names out of the migration guides
+themselves and walks the re-export graph, so a documented-but-unexported name fails at test time
+rather than at a consumer's `import`.
+
+---
+
+## 3. The file-access warning now sees a subclassed controller
+
+The boot warning that reports "the file gate is open and nothing declares a per-file policy" read
+**configuration** — `file.downloadRoles` and friends. That is the correct source for a member you
+inherit, and the wrong one for a member you re-declare.
+
+```typescript
+@Controller('files')
+export class FileController extends CoreFileController {
+  @Get('id/:id')
+  @Roles(RoleEnum.S_EVERYONE)      // anonymous downloads
+  override async getFileById(...) { return super.getFileById(...); }
+}
+```
+
+`applyFileRoles()` writes the configured roles onto `CoreFileController.prototype.getFileById`, but
+decorator metadata lives on the **function object** — your override is a different function, it keeps
+its own `@Roles()`, and that is the function Nest registers. The configuration never reaches the
+route. The old warning asked `resolveRoles('downloadRoles', config)`, got `[ADMIN]`, and stayed quiet
+while the route served everyone. Two consumer projects shipped exactly that.
+
+`CoreFileAccessAuditInitializer` now reads the roles off the class you actually registered, at
+`onApplicationBootstrap` (the earliest point at which the route table exists), and names the member:
+
+```
+A registered file endpoint is open beyond platform admins through roles declared in your own class,
+not through configuration (FileController.getFileById → ["s_everyone"]), and no per-file policy is
+declared: file.access is unset and CoreFileService.checkRights() is not overridden. …
+```
+
+**Nothing changes about who may reach what.** Your `@Roles()` still wins; the audit reports and does
+not correct. That is deliberate: rewriting an override's metadata would silently relax a route a
+project pinned on purpose — which is why the TUS module's approach, where configuration wins over the
+override, was not adopted here.
+
+**What to do if the warning appears:**
+
+| If the open access is | Then |
+|---|---|
+| intended, with a per-file rule | declare it: `file.access: 'owner' \| 'tenant' \| …`, or override `CoreFileService.checkRights()`. Either silences the warning, for both halves of the check |
+| intended, genuinely public files | nothing is broken — but the warning is the reminder that ids are enumerable and the routes are not rate-limited |
+| **not** intended | inherit the member instead of re-declaring it, so `file.downloadRoles` governs it again |
+
+**No new warning if you do not subclass**, and none if you subclass without re-declaring a governed
+member — the audit only reports roles the configuration cannot account for, so it never duplicates
+the existing configuration-side warning.
+
+Governed members: `getFileById`, `getFile` (controller); `getFileInfo`, `uploadFile`, `uploadFiles`,
+`deleteFile` (resolver).
+
+---
+
+## Module Documentation
+
+- File module, upload filters and access rules: [`src/core/modules/file/README.md`](../src/core/modules/file/README.md)
+- Request lifecycle and exception handling: [`docs/REQUEST-LIFECYCLE.md`](../docs/REQUEST-LIFECYCLE.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.34.1",
+  "version": "11.35.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/decorators/nested-type.registry.ts

@@ -0,0 +1,42 @@
+/**
+ * Which CLASS a model property declares — the only record of that fact at runtime.
+ *
+ * DELIBERATELY IMPORT-FREE. Two files need this map and they sit on opposite ends of an import
+ * edge: `unified-field.decorator` writes it (and already imports `restricted.decorator` for
+ * `@Restricted`), while `restricted.decorator` reads it. Keeping the map here means the reader adds
+ * no import back into the writer — `restricted.decorator` drives field-level access control and its
+ * position on zero import cycles is a defended property, not an accident.
+ * See `.claude/rules/architecture.md` → "DI Token Placement (SWC-Safe)".
+ *
+ * WHY IT EXISTS AT ALL: TypeScript types are erased, and `design:type` degrades to `Array` for a
+ * typed array and is only emitted for decorated properties. So a nested value read out of MongoDB —
+ * an embedded subdocument, or an array of them — arrives as a PLAIN object whose constructor is
+ * `Object`. Nothing on the value itself can say what it was declared as, which means nothing can
+ * find the `@Restricted` / validation metadata that belongs to it. This map is what closes that gap.
+ *
+ * Filled by `@UnifiedField()` for every non-primitive property. A property declared without
+ * `@UnifiedField` is absent, and consumers must treat "absent" as "unknown", never as "no
+ * restrictions" — see `checkRestricted()` for how that is handled.
+ */
+
+/** Key: `${className}.${propertyName}` — value: the declared (element) type. */
+export const nestedTypeRegistry = new Map<string, any>();
+
+/**
+ * The class a property of `ownerClass` declares, or `undefined` when nothing recorded it.
+ *
+ * Walks the PROTOTYPE CHAIN of the class, because `@UnifiedField()` registers under the class it was
+ * applied to — a property inherited from a base model is recorded under the BASE class name, and a
+ * lookup that only tried the leaf would miss it.
+ */
+export function resolveNestedType(ownerClass: unknown, propertyKey: string): any {
+  let current: any = ownerClass;
+  while (current && current !== Object && typeof current === 'function') {
+    const found = nestedTypeRegistry.get(`${current.name}.${propertyKey}`);
+    if (found) {
+      return found;
+    }
+    current = Object.getPrototypeOf(current);
+  }
+  return undefined;
+}

package/src/core/common/decorators/restricted.decorator.ts

@@ -22,17 +22,37 @@
  * See .claude/rules/architecture.md → "DI Token Placement (SWC-Safe)".
  */
 import 'reflect-metadata';
+import { Logger } from '@nestjs/common';
 import _ = require('lodash');
 
 import { ProcessType } from '../enums/process-type.enum';
-import { RoleEnum } from '../enums/role.enum';
+// isSystemRole comes from the role.enum LEAF (import-free), not from core-tenant.helpers, so this
+// adds no new import edge to a file whose TDZ-immunity is a deliberate safety property.
+import { isSystemRole, RoleEnum } from '../enums/role.enum';
 import { accessDeniedException } from '../exceptions/access-denied.exception';
+// From the import-free LEAF, never from unified-field.decorator: that file imports THIS one for
+// `@Restricted`, so reading the map from there would put this file back on an import cycle.
+import { resolveNestedType } from './nested-type.registry';
+// From an import-free LEAF: the marker is read here and in both interceptors, and this file's
+// position on zero import cycles is a defended property.
+import {
+  hasRestrictionsCheckedMarker,
+  hasUnrecognizedRestrictionsFlag,
+  RESTRICTIONS_CHECKED_KEY,
+} from './restrictions-checked.marker';
 // Import from the id.helper LEAF, never from db.helper: db.helper imports input.helper, which
 // imports this file back — that cycle is what the extraction removed. See id.helper's docblock.
 import { equalIds, getIncludedIds } from '../helpers/id.helper';
 import { RequestContext } from '../services/request-context.service';
 import { RequireAtLeastOne } from '../types/required-at-least-one.type';
-import { checkRoleAccess } from '../../modules/tenant/core-tenant.helpers';
+import { checkRoleAccess, resolveGlobalAndTenantRoles } from '../../modules/tenant/core-tenant.helpers';
+
+export {
+  hasRestrictionsCheckedMarker,
+  hasUnrecognizedRestrictionsFlag,
+  markRestrictionsChecked,
+  RESTRICTIONS_CHECKED_KEY,
+} from './restrictions-checked.marker';
 
 /**
  * Restricted meta key
@@ -121,6 +141,66 @@ export function getRestricted(object: unknown, propertyKey?: string): Restricted
   return metadata;
 }
 
+/**
+ * Resolve the NON-system portion of a field's required roles against the requester.
+ *
+ * Two things must be filtered before the roles reach `checkRoleAccess`, because that function
+ * matches non-hierarchy roles by exact string against a SINGLE available role — the tenant
+ * membership role, when a tenant context is active:
+ *
+ * 1. **System roles.** `S_SELF`, `S_CREATOR`, `S_VERIFIED`, `S_USER` and `S_EVERYONE` are decided
+ *    by the dedicated checks in `checkRestricted` (ownership, verification, session). Passing them
+ *    on means a membership role literally named `'s_self'` satisfies `@Restricted(S_SELF)` on
+ *    ARBITRARY records — no ownership is ever compared. `CoreTenantGuard` already filters these at
+ *    its own call site; this is the same filter for the field-level path.
+ *
+ * 2. **Global-only roles.** `RoleEnum.ADMIN` is platform authority and must be answered from
+ *    `user.roles`, never from a customer-assigned membership role.
+ *
+ * Declared as a hoisted `function` so it stays temporal-dead-zone immune — this file sits on no
+ * import cycle today and the property is defended deliberately (see `.claude/rules/architecture.md`).
+ */
+function checkFieldRoleAccess(roles: string[], user: any): boolean {
+  const { global: globalRoles, tenant: tenantRoles } = resolveGlobalAndTenantRoles(
+    roles.filter((role) => !isSystemRole(role)),
+  );
+
+  if (globalRoles.some((role) => user?.roles?.includes(role))) {
+    return true;
+  }
+
+  // The length guard is NOT redundant: checkRoleAccess returns TRUE for an empty required-roles
+  // list, so calling it with no tenant roles would unlock a field that only required a global one.
+  return tenantRoles.length > 0 && checkRoleAccess(tenantRoles, user?.roles, RequestContext.get()?.tenantRole);
+}
+
+/** Emitted at most once per process — a per-object warning on a hot path would be noise, not signal. */
+let unrecognizedFlagWarned = false;
+
+/**
+ * Warn once when an object carries `_objectAlreadyCheckedForRestrictions` without the framework marker.
+ *
+ * Declared as a hoisted `function` like everything else in this file, so it stays temporal-dead-zone
+ * immune. Uses the Nest `Logger` rather than `console.warn` for two reasons: it is the convention every
+ * other framework warning follows, and `console` output from a hot path is forwarded over vitest's
+ * worker RPC — a late one produces `Closing rpc while "onUserConsoleLog" was pending` in whichever
+ * spec happens to be tearing down. `@nestjs/common` is an external package and already in this file's
+ * transitive graph via `accessDeniedException`, so it adds no project import edge.
+ */
+function warnUnrecognizedRestrictionsFlag(data: unknown): void {
+  if (unrecognizedFlagWarned || !hasUnrecognizedRestrictionsFlag(data)) {
+    return;
+  }
+  unrecognizedFlagWarned = true;
+  new Logger('Restricted').warn(
+    `[Restricted] An object carries "${RESTRICTIONS_CHECKED_KEY}" without the framework marker, so it ` +
+      'is being CHECKED rather than skipped. Since 11.35.0 the opt-out is only honoured for objects ' +
+      'marked via markRestrictionsChecked() — a plain truthy property could arrive from the database ' +
+      'or a payload and would switch off field-level access control. If you set it deliberately, call ' +
+      'markRestrictionsChecked(obj); if this came from stored data, remove the field.',
+  );
+}
+
 /**
  * Check data for restricted properties (properties with `Restricted` decorator)
  * For special Roles and member of group checking the dbObject must be set in options
@@ -150,6 +230,7 @@ export function checkRestricted(
     throwError?: boolean;
   } = {},
   processedObjects: WeakSet<object> = new WeakSet(),
+  declaredType?: any,
 ) {
   // Act like Roles handling: checkObjectItself = false & mergeRoles = true
   // For Input: throwError = true
@@ -168,16 +249,52 @@ export function checkRestricted(
   };
 
   // Primitives
-  if (!data || typeof data !== 'object' || (config.noteCheckedObjects && data._objectAlreadyCheckedForRestrictions)) {
+  // The "already checked" opt-out is recognised by the framework's MARKER, never by a truthy property
+  // of that name: nothing in src/ ever wrote the property, so a truthy one could only have come from
+  // outside — and a document carrying it disabled every field-level check for that object, silently,
+  // on the output path. See restrictions-checked.marker.ts.
+  if (!data || typeof data !== 'object' || (config.noteCheckedObjects && hasRestrictionsCheckedMarker(data))) {
     return data;
   }
 
+  // Say it out loud when the KEY is present without the marker. Two very different callers land here
+  // and they want opposite answers — a project that used to set the flag by hand has lost its opt-out,
+  // a document that carries it from a raw write has lost a bypass it should never have had. A warning
+  // states the situation without guessing which; honouring the value is what the marker exists to stop.
+  warnUnrecognizedRestrictionsFlag(data);
+
   // Prevent infinite recursion
   if (processedObjects.has(data)) {
     return data;
   }
   processedObjects.add(data);
 
+  // WHERE the restriction metadata for `data` lives.
+  //
+  // For an instance of a model class this is simply its constructor, and reading it off the object
+  // works — which is why the top level has always been checked correctly. One level down it stops
+  // working: `CoreModel.map()` is a shallow `Object.assign`, `prepareOutput()` maps only the target
+  // model, and `ResponseModelInterceptor` maps only the top-level item. So an embedded subdocument
+  // read out of MongoDB arrives as a PLAIN object whose constructor is `Object` — and `Object`
+  // carries no `@Restricted` metadata, so every nested restriction silently evaluated to "no
+  // restrictions at all" and the field was returned in full. `declaredType` closes that: the type
+  // the PARENT declared for this property, looked up in the nested-type registry.
+  //
+  // An unregistered nested type still resolves to nothing, exactly as before — the framework cannot
+  // invent a declaration. That is deliberate rather than fail-closed: nested values also legitimately
+  // hold free-form JSON, `Map`s and scalars, and refusing those would break far more than it
+  // protects. Declare nested types with `@UnifiedField({ type: () => X })` to have them enforced.
+  const metadataOwner: any =
+    data.constructor && data.constructor !== Object
+      ? data.constructor
+      : typeof declaredType === 'function'
+        ? declaredType
+        : undefined;
+  // What `Reflect.getMetadata` must walk for PROPERTY lookups: the instance when there is one, the
+  // declared class's prototype otherwise (metadata for property decorators is defined there, and
+  // Reflect traverses the prototype chain either way).
+  const metadataTarget: any = !metadataOwner || data.constructor === metadataOwner ? data : metadataOwner.prototype;
+
   // Array
   if (Array.isArray(data)) {
     if (data.length === 0) {
@@ -189,15 +306,18 @@ export function checkRestricted(
     // Per-item checks are only needed when S_CREATOR or S_SELF restrictions exist
     // (because createdBy/id differ per item).
     const sample = data[0];
-    if (
-      sample &&
-      typeof sample === 'object' &&
-      !Array.isArray(sample) &&
-      sample.constructor &&
-      sample.constructor !== Object
-    ) {
+    // The element type: the sample's own class, or — for an array of embedded subdocuments, which
+    // arrive as plain objects — the type the parent property declared. `declaredType` is the ELEMENT
+    // type here: `@UnifiedField({ isArray: true, type: () => X })` registers `X`, not `X[]`.
+    const sampleOwner: any =
+      sample && typeof sample === 'object' && !Array.isArray(sample) && sample.constructor !== Object
+        ? sample.constructor
+        : typeof declaredType === 'function'
+          ? declaredType
+          : undefined;
+    if (sample && typeof sample === 'object' && !Array.isArray(sample) && sampleOwner) {
       // Check class-level restrictions once
-      const classRestrictions = getRestricted(sample.constructor) || [];
+      const classRestrictions = getRestricted(sampleOwner) || [];
       if (classRestrictions.length) {
         const hasCreatorOrSelf = classRestrictions.some(
           (r) =>
@@ -223,7 +343,7 @@ export function checkRestricted(
           // also validates the class-level restriction as a standalone gate. With the
           // default checkObjectItself=false, class restrictions are merged into each
           // property's restrictions (properties get stripped if the class restriction denies).
-          const sampleResult = checkRestricted(sample, user, config, processedObjects);
+          const sampleResult = checkRestricted(sample, user, config, processedObjects, declaredType);
           if (sampleResult === undefined || sampleResult === null) {
             // Class-level restriction blocks access → entire array is blocked
             if (config.throwError) {
@@ -236,7 +356,7 @@ export function checkRestricted(
           // are O(1) lookups, but we still need to recurse into nested properties per item.
           const result = [sampleResult];
           for (let i = 1; i < data.length; i++) {
-            result.push(checkRestricted(data[i], user, config, processedObjects));
+            result.push(checkRestricted(data[i], user, config, processedObjects, declaredType));
           }
           if (!config.throwError && config.removeUndefinedFromResultArray) {
             return result.filter((item) => item !== undefined);
@@ -247,7 +367,7 @@ export function checkRestricted(
     }
 
     // Fallback: plain objects, mixed types, or S_CREATOR/S_SELF checks needed
-    let result = data.map((item) => checkRestricted(item, user, config, processedObjects));
+    let result = data.map((item) => checkRestricted(item, user, config, processedObjects, declaredType));
     if (!config.throwError && config.removeUndefinedFromResultArray) {
       result = result.filter((item) => item !== undefined);
     }
@@ -256,7 +376,7 @@ export function checkRestricted(
 
   // Check function
   const validateRestricted = (restricted) => {
-    if (config.noteCheckedObjects && data?._objectAlreadyCheckedForRestrictions) {
+    if (config.noteCheckedObjects && hasRestrictionsCheckedMarker(data)) {
       return true;
     }
 
@@ -320,7 +440,7 @@ export function checkRestricted(
           ((owner && 'createdBy' in owner && equalIds(owner.createdBy, user)) ||
             (config.allowCreatorOfParent && owner && !('createdBy' in owner) && config.isCreatorOfParent))) ||
         (roles.includes(RoleEnum.S_VERIFIED) && (user?.verified || user?.verifiedAt || user?.emailVerified)) ||
-        (user?.id && checkRoleAccess(roles, user?.roles, RequestContext.get()?.tenantRole))
+        (user?.id && checkFieldRoleAccess(roles, user))
       ) {
         valid = true;
       }
@@ -375,7 +495,7 @@ export function checkRestricted(
   };
 
   // Check data object
-  const objectRestrictions = getRestricted(data.constructor) || [];
+  const objectRestrictions = getRestricted(metadataOwner) || [];
   if (config.checkObjectItself) {
     const objectIsValid = validateRestricted(objectRestrictions);
     if (!objectIsValid) {
@@ -403,8 +523,9 @@ export function checkRestricted(
       continue;
     }
 
-    // Check restricted
-    const restricted = getRestricted(data, propertyKey) || [];
+    // Check restricted. `metadataTarget` is `data` for a real instance and the declared class's
+    // prototype for a plain nested object — see its definition above.
+    const restricted = getRestricted(metadataTarget, propertyKey) || [];
     const concatenatedRestrictions =
       config.mergeRoles && objectRestrictions.length ? _.uniq(objectRestrictions.concat(restricted)) : restricted;
     const valid = validateRestricted(concatenatedRestrictions);
@@ -420,8 +541,15 @@ export function checkRestricted(
         equalIds(parent, user) ||
         (parent && 'createdBy' in parent ? equalIds(parent.createdBy, user) : config.isCreatorOfParent);
 
-      // Check deep
-      data[propertyKey] = checkRestricted(data[propertyKey], user, config, processedObjects);
+      // Check deep — carrying the type this property DECLARES, so a nested plain object (an
+      // embedded subdocument, or an array of them) can still be matched against its own metadata.
+      data[propertyKey] = checkRestricted(
+        data[propertyKey],
+        user,
+        config,
+        processedObjects,
+        metadataOwner ? resolveNestedType(metadataOwner, propertyKey) : undefined,
+      );
     } else {
       if (config.debug) {
         console.debug(

package/src/core/common/decorators/restrictions-checked.marker.ts

@@ -0,0 +1,87 @@
+/**
+ * "This object has already been checked" — as a MARKER the framework sets, not a property data carries.
+ *
+ * WHY THIS FILE EXISTS: three places short-circuit on
+ * `_objectAlreadyCheckedForRestrictions` — `checkRestricted()` returns the object untouched,
+ * `CheckSecurityInterceptor` skips `securityCheck()`, and `ResponseModelInterceptor` skips the
+ * Plain→Model conversion. The opt-out is legitimate: without it one response is checked three times.
+ *
+ * What was NOT legitimate is how it was recognised. Every read was a plain truthy test on a
+ * well-known property name, and nothing in `src/` ever wrote it — so the only way the flag could ever
+ * be set was from outside the framework. Which means a document carrying
+ * `_objectAlreadyCheckedForRestrictions: true` — from a raw write, a `strict: false` schema, a
+ * restored export — disabled EVERY field-level access check for that object, silently, on the output
+ * path where a skipped check produces no error at all. That is a data-shaped authorization switch,
+ * and data must never be able to flip one.
+ *
+ * The fix keeps the feature and removes the forgeability: the marker's VALUE is a module-private
+ * symbol. JSON, BSON and any client payload can produce the key, and none of them can produce that
+ * value. The property is also non-enumerable, so it never reaches a response body and cannot re-enter
+ * through a round trip as exactly the data shape above.
+ *
+ * DELIBERATELY IMPORT-FREE, so `restricted.decorator` (whose position on zero import cycles is a
+ * defended property) and both interceptors can read it without a new import edge between them.
+ * See `.claude/rules/architecture.md` → "DI Token Placement (SWC-Safe)".
+ */
+
+/**
+ * The property name, unchanged since it is part of the observable API — a project may look for it.
+ * Only the way it is RECOGNISED changed.
+ */
+export const RESTRICTIONS_CHECKED_KEY = '_objectAlreadyCheckedForRestrictions';
+
+/**
+ * The only value that counts as "checked". Module-private on purpose: it is not exported, so nothing
+ * outside this file — and nothing that arrives as data — can reproduce it.
+ */
+const MARKER = Symbol('restrictionsChecked');
+
+/**
+ * Mark an object as already checked, so the framework's own layers do not check it again.
+ *
+ * Non-enumerable and non-writable: it must not appear in `Object.keys()`, in `JSON.stringify()` or in
+ * a Mongoose write. `configurable: true` so the same object can be re-marked without throwing.
+ *
+ * Returns the object, so it can be used inline.
+ */
+export function markRestrictionsChecked<T>(data: T): T {
+  if (!data || typeof data !== 'object') {
+    return data;
+  }
+  Object.defineProperty(data, RESTRICTIONS_CHECKED_KEY, {
+    configurable: true,
+    enumerable: false,
+    value: MARKER,
+    writable: false,
+  });
+  return data;
+}
+
+/**
+ * Has the framework marked this object as checked?
+ *
+ * The identity comparison is the whole point — `!!data[KEY]` would be satisfied by any truthy value,
+ * including one that came out of the database.
+ */
+export function hasRestrictionsCheckedMarker(data: unknown): boolean {
+  return !!data && typeof data === 'object' && (data as Record<string, unknown>)[RESTRICTIONS_CHECKED_KEY] === MARKER;
+}
+
+/**
+ * Does this object carry the KEY without the marker — i.e. an unforgeable-looking value that is not
+ * actually the marker?
+ *
+ * Used to warn once rather than to decide anything. Two callers can produce this state, and they want
+ * opposite answers: a project that used to set the flag by hand (`obj[KEY] = true`) has silently lost
+ * its opt-out and should hear about it, while a document that carries the field from a raw write has
+ * silently LOST a bypass it should never have had. A warning names the situation without guessing
+ * which one it is; treating it as "checked" is what this file exists to stop.
+ */
+export function hasUnrecognizedRestrictionsFlag(data: unknown): boolean {
+  return (
+    !!data &&
+    typeof data === 'object' &&
+    RESTRICTIONS_CHECKED_KEY in (data as object) &&
+    (data as Record<string, unknown>)[RESTRICTIONS_CHECKED_KEY] !== MARKER
+  );
+}

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

@@ -22,11 +22,12 @@ import {
 import { GraphQLScalarType, isEnumType } from 'graphql';
 
 import { RoleEnum } from '../enums/role.enum';
+// Re-exported below so no import path broke. The map moved into an import-free leaf because
+// `restricted.decorator` — which this file imports — now READS it; see that leaf's docblock.
+import { nestedTypeRegistry } from './nested-type.registry';
 import { Restricted, RestrictedType } from './restricted.decorator';
 
-// Registry to store nested type information for validation
-// Key: `${className}.${propertyName}`, Value: nested type constructor
-export const nestedTypeRegistry = new Map<string, any>();
+export { nestedTypeRegistry, resolveNestedType } from './nested-type.registry';
 
 /**
  * Registry to map enum objects to their names.