@lenne.tech/nest-server 11.34.1 → 11.35.0

package/migration-guides/11.34.x-to-11.35.x.md

@@ -0,0 +1,832 @@
+# Migration Guide: 11.34.x → 11.35.x
+
+## Why this is a MINOR
+
+Per `.claude/rules/versioning.md` the MAJOR mirrors NestJS, so **MINOR is where breaking changes
+live**. This release makes a previously-accepted (and always-wrong) input fail loudly: `roles`
+values with the `s_*` system-role prefix are now rejected. A request that used to succeed can now
+fail, so it is `11.35.0` rather than a `11.34.2` patch.
+
+> **Coming from 11.34.0?** You are skipping `11.34.1`, which changed client-visible validation
+> error messages (a custom `message` now reaches the client, and default messages no longer carry
+> raw `$constraint1` placeholders). If you assert on validation error text anywhere, read
+> [`11.34.0-to-11.34.1.md`](./11.34.0-to-11.34.1.md) as well — it interacts directly with the new
+> message introduced here.
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Security** | System roles (`s_*`) can no longer be written into `user.roles` — enforced on three layers, not just documented (§1) |
+| **Breaking Changes** | Any write carrying an `s_`-prefixed role now fails: the user endpoints answer 400, `setRoles()` throws, and a direct Mongoose write throws. **This includes project roles that merely start with `s_`** (e.g. `s_manager`) — see §2 (§1, §2) |
+| **Security** | GraphQL SUBSCRIPTIONS ran with no request context, so a tenant-scoped read on that path returned every tenant's rows (§7) |
+| **Security** | Nested `@Restricted` silently did nothing on embedded subdocuments (§8) |
+| **Security** | A reused filename made file storage authorize one document and serve another (§9) |
+| **Security** | TUS uploads had no owner, and any authenticated caller could append to or delete somebody else's upload (§10) |
+| **Security** | `@Roles()` on a `@Subscription` was enforced by nobody when multi-tenancy was active (§12) |
+| **Security** | The `@Restricted` opt-out flag could be forged by stored data (§13) |
+| **Security** | The reference file rule waved LISTINGS through, so a project exposing `findFileInfo()` leaked a full inventory (§15) |
+| **New Feature** | `file.access` — the per-file rule as a declaration, one setting per project class; default keeps today's behaviour (§16) |
+| **New Exports** | `isSystemRole`, `looksLikeSystemRole`, `SYSTEM_ROLE_PREFIX`, `SYSTEM_ROLE_REJECT_PATTERN`, `mongooseSystemRolePlugin` (§4); the WS context wrappers, the tenant-context registry, `resolveNestedType`, `TUS_OWNER_METADATA_KEY` (New Exports) |
+| **Migration Effort** | **None**, unless you use an `s_`-prefixed role name or already have `s_*` values stored (§3), OR your subscriptions read tenant-scoped data (§7), OR your models carry nested `@Restricted` fields (§8) |
+
+## Quick Migration
+
+```bash
+# npm mode
+pnpm update @lenne.tech/nest-server@11.35.0
+pnpm run build && pnpm test
+
+# vendor mode
+/lt-dev:backend:update-nest-server-core
+```
+
+Then run the one-time audit in §3.
+
+### Vendor mode: which files, and which ones belong together
+
+`/lt-dev:backend:update-nest-server-core` adopts these for you, but the GROUPINGS matter — every one of
+them is half-wired if you take one side and not the other, and a half-wired enforcement layer is worse
+than none because it reads as protection.
+
+**Seven new files:**
+
+| File | Belongs with |
+|------|--------------|
+| `common/plugins/mongoose-system-role.plugin.ts` | `common/enums/role.enum.ts` — the plugin is the unconditional layer, the enum holds the predicates (§1) |
+| `common/decorators/nested-type.registry.ts` | `decorators/restricted.decorator.ts` + `decorators/unified-field.decorator.ts` — the registry is written by one and read by the other (§8) |
+| `common/decorators/restrictions-checked.marker.ts` | `decorators/restricted.decorator.ts` + both interceptors — all four read the marker; an old truthy check anywhere reopens the bypass (§13) |
+| `common/helpers/graphql-ws-context.helper.ts` | `common/services/core-tenant-context.registry.ts` + `core.module.ts` + `modules/tenant/core-tenant.guard.ts` — the context is useless without the resolver, and unreached without the `core.module.ts` wiring (§7) |
+| `common/services/core-tenant-context.registry.ts` | as above |
+| `common/helpers/execution-context-request.helper.ts` | all three guards: `modules/auth/guards/roles.guard.ts`, `modules/better-auth/better-auth-roles.guard.ts`, `modules/tenant/core-tenant.guard.ts`. Adopting it for one guard leaves the others blind on the WebSocket (§12) |
+| `modules/file/file-access.helper.ts` + `modules/file/file-roles.config.ts` | `modules/file/core-file.service.ts`. `file-roles.config.ts` is a SPLIT of `file-roles.helper.ts` — take both, or the service closes an import cycle that dies under SWC (§16) |
+
+**Changed elsewhere:** `core.module.ts`, `index.ts`,
+`common/interfaces/server-options.interface.ts`, `common/helpers/gridfs.helper.ts`,
+`common/plugins/mongoose-tenant.plugin.ts`, `common/services/core-s3.service.ts`,
+`modules/file/{core-file.service,file-metadata.helper,file-roles.helper}.ts`,
+`modules/tus/{core-tus.service,tus.constants,index}.ts`, `modules/user/inputs/core-user.input.ts`,
+`modules/user/core-user.service.ts`, `modules/tenant/core-tenant.helpers.ts`, and the three module
+READMEs (`file`, `tenant`, `tus`) plus `modules/file/INTEGRATION-CHECKLIST.md`.
+
+**Also worth taking:** `src/test/test.helper.ts` (subscription `connectionParams`, and a refused
+subscription now rejects instead of delivering an indistinguishable `null` — without it you cannot test
+a role-gated subscription at all) and `src/server/modules/file/file.service.ts` as the reference rule.
+
+## 1. Security: `s_*` values can no longer be stored in `user.roles`
+
+### What happened
+
+`roles` in `CoreUserInput` was an unvalidated `string[]`. The `@Restricted(INPUT, ADMIN)` on the
+field limits **who** may send it, but nothing limited **what** it may hold. `hasRole()` is a plain
+string intersection, so a stored `'s_self'` satisfied every `S_SELF` check — for the core user
+module that includes `updateUser` / `deleteUser` on **arbitrary** users (mail/password change →
+account takeover), without the account carrying `admin`. The rule "NEVER store S_ roles in
+user.roles" existed only as documentation.
+
+The actor must already be an admin (no escalation from below), but a typo or copy-paste in an
+admin tool was enough to mint a dormant skeleton key — one that passes an eyeball review, because
+the account shows no privileged role.
+
+### What changed — three layers, deliberately redundant
+
+| Layer | Covers | On violation | Configurable |
+|-------|--------|--------------|--------------|
+| `CoreUserInput.roles` validator | the input/DTO path (REST + GraphQL, create + update) | 400 with a per-field message | no, but **a subclass override replaces it** — see §2 |
+| `CoreUserService.setRoles()` | the framework's canonical role-assignment API, which writes straight through `findByIdAndUpdate` | `BadRequestException` before the DB round-trip | no |
+| `mongooseSystemRolePlugin` | **every** Mongoose write, including `force: true`, `runWithBypassRoleGuard()` and direct `Model` calls | throws | **no** — registered unconditionally |
+
+The third layer is why the claim "enforced" is now accurate rather than aspirational. It is
+separate from `mongooseRoleGuardPlugin` on purpose:
+
+- `mongooseRoleGuardPlugin` answers *who may change roles*. It is configurable
+  (`security.mongooseRoleGuardPlugin`), it can be bypassed, and it **strips** the change.
+- `mongooseSystemRolePlugin` answers *which values may exist at all*. It cannot be configured or
+  bypassed, and it **throws** — silently dropping the value would hide exactly the admin-tool
+  misconfiguration that creates the problem.
+
+Being an ADMIN, or holding a bypass, grants authority over the *change*. It never grants permission
+to write a value that is invalid by construction.
+
+### The guard refuses what a write INTRODUCES, not what is already stored
+
+This distinction is load-bearing, not leniency. `CrudService.update()` writes the whole object back,
+so an ordinary login (`updateRefreshToken` → `update`) re-sends the stored `roles` verbatim. If the
+plugin refused that, upgrading would **lock every already-contaminated account out of the system** —
+and would do the same, fleet-wide, to any project whose own role name starts with `s_`.
+
+| Write | Result |
+|-------|--------|
+| Adding `s_self` to a document that does not have it | refused |
+| Writing back `['admin', 's_manager']` on a document that already stores exactly that | allowed |
+| Adding `s_self` on top of an already-stored `s_manager` | refused (the message names only `s_self`) |
+| Removing an `s_*` value (`$pull`, or a narrower array) | allowed — this is the cleanup path |
+
+A stale value therefore keeps working until you clean it up. It does **not** keep working as a
+harmless quirk: the account remains a skeleton key for as long as the value is stored, which is why
+the audit in §3 is not optional. `updateMany` is the one exception — it can span documents with
+different stored values, so there is no single baseline and any system role in its payload is
+refused outright.
+
+## 2. Two ways to lose the protection (read this if you subclass or use `s_` role names)
+
+### 2a. A project role starting with `s_` is now rejected
+
+The check is a **prefix rule**, not an allowlist of the six `RoleEnum.S_*` members. Any value that
+starts with `s_` after trimming — case-insensitively — is refused:
+
+| Value | Result |
+|-------|--------|
+| `s_self`, `S_SELF`, `' s_self'` | rejected |
+| `s_manager`, `s_support` (your own roles) | **rejected** |
+| `gs_editor`, `admin`, `editor` | accepted |
+
+This is deliberate: the framework cannot distinguish a project role from a future system role, and
+a false rejection is fixable by renaming while a false acceptance is a silent authorization hole.
+
+**If you use an `s_`-prefixed role name, rename it before upgrading.** Update the stored values,
+your `@Roles()` / `@Restricted()` usages and any seed data together — the framework does not
+migrate stored data, it only refuses to write new violations.
+
+### 2b. Redeclaring `roles` in a subclass REPLACES the validator
+
+`MapAndValidatePipe` walks the prototype chain child-first and skips a property once a child class
+has validated it. So a project input that redeclares `roles` — for **any** reason, even just to add
+a description — silently loses the inherited guard on the input path:
+
+```typescript
+// LOSES the s_* guard on the input path
+@InputType()
+export class UserInput extends CoreUserInput {
+  @UnifiedField({ description: 'Roles', isArray: true, isOptional: true, type: String })
+  override roles?: string[] = undefined;
+}
+
+// CORRECT: re-declare the guard alongside whatever you are adding
+import { SYSTEM_ROLE_PREFIX, SYSTEM_ROLE_REJECT_PATTERN } from '@lenne.tech/nest-server';
+
+@InputType()
+export class UserInput extends CoreUserInput {
+  @UnifiedField({
+    description: 'Roles',
+    isArray: true,
+    isOptional: true,
+    type: String,
+    validator: opts => [
+      IsString(opts),
+      IsIn(['admin', 'editor'], opts),   // your own allowlist, if you want one
+      Matches(SYSTEM_ROLE_REJECT_PATTERN, {
+        ...opts,
+        message: `System roles (${SYSTEM_ROLE_PREFIX}*) must never be stored in user.roles`,
+      }),
+    ],
+  })
+  override roles?: string[] = undefined;
+}
+```
+
+An `IsIn` allowlist happens to exclude `s_*` values incidentally, so that particular override stays
+safe — but do not rely on the accident. **`mongooseSystemRolePlugin` backstops all of this**, so an
+override degrades the error message rather than reopening the hole. You still want the DTO-level
+guard for the better message and to fail before the DB round-trip.
+
+## 3. What you should do
+
+1. **Audit once** for values already stored:
+   ```js
+   db.users.find({ roles: /^\s*s_/i })
+   ```
+   Any hit is either a genuine misconfiguration (remove it — depending on your endpoints it was
+   exploitable) or one of your own `s_`-prefixed role names (rename it, see §2a). The upgrade does
+   not touch stored data.
+
+2. **Check your user inputs** for a `roles` override (§2b).
+
+3. **Optional hardening:** narrow the accepted values to your project's own assignable set with
+   `IsIn([...], opts)` — using the combined form in §2b, so the framework guard survives.
+
+## Compatibility Notes
+
+| Pattern | Status |
+|---------|--------|
+| Custom project roles without an `s_` prefix | Unaffected |
+| `roles: []` / omitting `roles` | Unaffected |
+| Subclassing `CoreUserInput` **without** redeclaring `roles` | Unaffected — the validator is inherited |
+| Subclassing **with** a `roles` override | Input-path validator lost; plugin still enforces (§2b) |
+| `CoreUserCreateInput` / sign-up flows | Covered — the field is inherited |
+| `setRoles()` | Now throws on `s_*` (§1) |
+| `force: true`, `runWithBypassRoleGuard()`, direct `Model` writes | Now throw via the plugin — previously unchecked |
+| `$pull` of an `s_*` value | **Allowed** — removing a bad value is the cleanup this release asks for |
+| BetterAuth `additionalUserFields` | Unaffected — `roles` was already locked to `input: false` |
+| `isSystemRole` imported from `.../tenant/core-tenant.helpers` | Still works (re-exported); the definition moved to `common/enums/role.enum` |
+| Tenant membership roles | **Covered — see §5.** A membership named `admin` no longer satisfies `@Roles(RoleEnum.ADMIN)`, and one named `s_self` no longer satisfies `@Restricted(S_SELF)` |
+
+## Troubleshooting
+
+**`Validation failed for 1 field: roles (matches)` (HTTP 400)**
+The input path rejected an `s_*` value. The top-level message is built from constraint *names*; the
+readable text is in the response body beside it:
+`{ "roles": { "matches": "System roles (s_*) must never be stored in user.roles" } }`.
+Over GraphQL that body is not forwarded — check the REST response, or the server log, to see which
+value was refused.
+
+**`System roles (s_*) must never be stored in user.roles: s_manager`**
+Thrown by `setRoles()` or by `mongooseSystemRolePlugin`. The offending values are named in the
+message. If this is one of your own role names, see §2a.
+
+**A previously working seed / migration now fails**
+Expected — the plugin covers seeds and migrations too. Rename the role, or remove the `s_*` value.
+There is no bypass, by design.
+
+**My subclass stopped rejecting `s_*` with a nice error, but writes still fail**
+That is §2b: the override replaced the input validator, and the plugin caught the write instead.
+Re-declare the guard as shown there.
+
+## 5. Tenant boundary: a membership role can no longer confer global authority
+
+### What happened
+
+Roles from three trust levels shared one namespace and were compared with `===`. Membership roles
+are **customer-assigned free text** (`addMember()` accepts any non-empty string), and whoever may
+manage members is typically a tenant owner — a customer. Two escalations followed:
+
+| A tenant owner sets their membership role to… | …and thereby satisfied |
+|---|---|
+| `admin` | `@Roles(RoleEnum.ADMIN)` — the **global platform** role, in tenant context |
+| `s_self` | `@Restricted(S_SELF)` on **arbitrary** records — ownership was never compared |
+
+Note that enums do not help here: `RoleEnum.ADMIN` *is* the string `'admin'` at runtime.
+
+### What changed
+
+Each required role is now resolved against the source entitled to answer it:
+
+| Required | Resolved against |
+|----------|------------------|
+| `RoleEnum.ADMIN` | `user.roles` — **never** `membership.role` |
+| tenant/project roles | `membership.role` in tenant context, `user.roles` otherwise |
+| system roles | their dedicated checks, never a string comparison |
+
+OR semantics across both halves, so `@Roles(ADMIN, 'owner')` still reads as alternatives.
+Additionally, `addMember()` / `updateMemberRole()` now **throw** on a system role or a global-only
+role (case-insensitive, trimmed).
+
+### The intended model is unchanged
+
+```typescript
+// Global admin — full access to EVERY tenant. Unchanged, still works.
+user.roles = [RoleEnum.ADMIN];
+
+// Per-tenant admin — one tenant only. Name it anything except a framework role.
+await tenantService.addMember(tenantId, userId, 'tenantAdmin');   // or 'spaceAdmin'
+@Roles('tenantAdmin')
+```
+
+### What you should do
+
+- **Nothing**, if your tenant roles are named `owner` / `manager` / `member` / `tenantAdmin` /
+  `spaceAdmin` or similar.
+- **If any membership role is literally `admin`** (or an `s_*` name): rename it. Existing rows keep
+  working as an ordinary tenant role — they are simply no longer mistaken for the global role — but
+  new assignments of that name are refused. Find them with:
+  ```js
+  db.tenantmembers.find({ role: { $in: [/^\s*admin\s*$/i, /^\s*s_/i] } })
+  ```
+- **Adding your own framework-wide role?** Classify it in `GLOBAL_ONLY_ROLES`;
+  `tests/unit/role-classification-invariants.spec.ts` fails until you do.
+
+### Declare YOUR OWN global roles
+
+The framework only knows its own vocabulary. If you guard a platform-wide endpoint with
+`@Roles('auditor')`, say so — otherwise `auditor` is an ordinary role and, in tenant context, gets
+answered from `membership.role`:
+
+```typescript
+multiTenancy: {
+  roleHierarchy:   { member: 1, tenantAdmin: 2, owner: 3 },  // per tenant
+  globalOnlyRoles: ['auditor', 'support'],                    // platform-wide, user.roles only
+}
+```
+
+The scope is stored as an **attribute**, not encoded in the role name — which is what keeps this
+open for admin-managed roles in the database later: a `RoleScopeSource` reading from Mongo can be
+registered next to the config source and every guard keeps working unchanged. (Encoding the scope
+in the string instead, e.g. `t:owner`, would put it in a value that whoever creates the role can
+mistype, and would add a normalization step inside the authorization path.)
+
+### ⚠️ Boot now FAILS on an incoherent role vocabulary
+
+`CoreTenantModule.forRoot()` refuses to start on:
+
+| Configuration | Why it fails |
+|---|---|
+| `roleHierarchy: { admin: 3, … }` | a tenant role named after a framework role — the escalation above |
+| `globalOnlyRoles: ['x']` + `roleHierarchy: { x: 2 }` | one role, two sources of truth |
+| `globalOnlyRoles: ['s_user']` | system roles are never granted or stored |
+
+**This is the most likely upgrade blocker.** The framework's own docs previously recommended
+`roleHierarchy: { viewer: 1, editor: 2, manager: 2, admin: 3, owner: 4 }` — case 1. If you copied
+that example, rename `admin` to `tenantAdmin` in your config, in your `@Roles()` usages, and in
+stored membership rows:
+
+```js
+db.tenantmembers.updateMany({ role: 'admin' }, { $set: { role: 'tenantAdmin' } })
+```
+
+An ambiguous authorization rule is worse than a server that does not start, which is why this
+throws rather than warns.
+
+### Optional: `strictMembershipRoles` (deny by default)
+
+```typescript
+multiTenancy: {
+  roleHierarchy:            { member: 1, tenantAdmin: 2, owner: 3 },
+  additionalMembershipRoles: ['auditorOfTenant'],   // exact-match roles without a level
+  strictMembershipRoles:     true,
+}
+```
+
+Only declared roles may be assigned **and** may satisfy a required role. Not the default: a project
+may legitimately use exact-match roles that appear only in `@Roles()` and in its membership data,
+and denying those at the guard by default would be a silent, fleet-wide lockout. Turn it on for the
+strictest posture — recommended for regulated data.
+
+## 6. Data isolation: aggregations that join another collection
+
+### What happened
+
+`mongooseTenantPlugin` prepended a `$match` to the pipeline of the collection being aggregated.
+That constrains the **source** collection only. `$lookup`, `$unionWith` and `$graphLookup` read a
+**different** collection — and that collection's own `aggregate` hook never fires, because the join
+runs inside the source pipeline.
+
+So an aggregation shaped like an ordinary report returned every tenant's rows from the joined
+collection:
+
+```js
+// Ran as tenant A — and returned tenant B's rows too
+ItemModel.aggregate([
+  { $lookup: { from: 'records', pipeline: [], as: 'records' } },
+]);
+```
+
+`$unionWith` behaved the same way. Verified by test, not by reading.
+
+### What changed
+
+The plugin now walks the pipeline and injects the tenant filter into every cross-collection stage,
+recursively (these stages nest, and `$facet` holds a sub-pipeline per key):
+
+| Stage | Where the filter goes |
+|-------|----------------------|
+| `$lookup` | prepended to its `pipeline` (MongoDB 5.0+ allows this alongside `localField`/`foreignField`) |
+| `$unionWith` | prepended to its `pipeline`; the string shorthand is expanded to the object form |
+| `$graphLookup` | merged into `restrictSearchWithMatch`, so it applies to every recursive step |
+
+A joined collection is only constrained when it is **itself** tenant-scoped. Joining a global
+lookup table is untouched — filtering it by `tenantId` would silently return nothing.
+
+### `estimatedDocumentCount()` now throws inside a tenant context
+
+It reads collection metadata rather than running a query, so MongoDB ignores any filter — there is
+nothing to inject, and an unchanged result hands a tenant the row count of the whole collection.
+Use `countDocuments()`, which is filtered. A platform admin without a tenant header is unaffected.
+
+### What you should do
+
+- **Review aggregations that join tenant-scoped collections.** They now return only your own
+  tenant's rows. If one silently relied on the previous behaviour, its results will shrink — which
+  is the correction, not a regression.
+- `estimatedDocumentCount()` → `countDocuments()` on tenant-scoped models.
+
+## 7. Data isolation: GraphQL subscriptions now run inside a request context
+
+### What happened
+
+`RequestContextMiddleware` is Express middleware. A WebSocket UPGRADE is not a `request` event, so it
+traverses no middleware — and `CoreTenantGuard.getRequest()` looks for `context.req`, which a
+subscription context (the graphql-ws `extra` object) does not have, so the guard returned `true`
+without deciding anything.
+
+The result was invisible from the query itself. `mongooseTenantPlugin` reads "no RequestContext" as
+"system operation, no filter" — correct for a cron job or a migration, and exactly wrong here. **A
+tenant-scoped read performed while delivering a subscription message returned every tenant's rows**,
+and the plugin's own safety net could not fire, because there was no context in which to notice.
+`mongooseRoleGuardPlugin` and the audit-fields plugin were equally blind on that path.
+
+### What changed
+
+`CoreModule` now installs a context-aware `execute` / `subscribe` pair on all three of its GraphQL
+driver builders. Every WebSocket operation — subscriptions AND the queries/mutations graphql-ws
+carries — runs inside a `RequestContext` holding:
+
+| Field | Source |
+|-------|--------|
+| `currentUser` | the user the connection authenticated as (`onConnect`) |
+| `tenantId` | the handshake's tenant header, **validated against an active membership** |
+| `tenantIds` | the subscriber's active memberships, when no header was sent |
+| `language` | `accept-language` from the handshake, when present |
+
+The context is established for the initial subscribe **and for every delivered message** — the
+per-event execution (`resolve`, `filter`, every field resolver) runs inside the async iterator's
+`next()`, long after `subscribe()` returned, so wrapping only the subscribe call would have covered
+nothing that matters.
+
+### What you should do
+
+- **Nothing, if your subscription resolvers do not read tenant-scoped data.**
+- **If they do:** they are now filtered. A resolver that silently returned rows from every tenant
+  returns only the subscriber's from now on — that is the correction.
+- **A tenant-scoped read with NO resolvable tenant is now REFUSED** (the safety net), where it
+  previously returned everything. That happens when the socket is anonymous, or when the handshake
+  names a tenant the subscriber is not a member of. Send the tenant via `connectionParams`:
+  ```typescript
+  createClient({ connectionParams: { Authorization: `Bearer ${token}`, 'x-tenant-id': tenantId } })
+  ```
+- **System-internal work inside a subscription** (a cron-like side effect) must now say so
+  explicitly, exactly as elsewhere: `RequestContext.runWithBypassTenantGuard(() => …)`.
+- `TestHelper` gained a `connectionParams` option so a tenant-scoped subscription can be tested.
+
+**Vendor mode:** new file `src/core/common/helpers/graphql-ws-context.helper.ts` plus
+`src/core/common/services/core-tenant-context.registry.ts`; changed `src/core.module.ts` and
+`src/core/modules/tenant/core-tenant.guard.ts`. All four belong together.
+
+## 8. `@Restricted` now applies to nested embedded subdocuments
+
+### What happened
+
+`checkRestricted()` read restriction metadata off the VALUE's constructor. `CoreModel.map()` is a
+shallow `Object.assign`, `prepareOutput()` maps only the target model and `ResponseModelInterceptor`
+only the top-level item — so an embedded subdocument read out of MongoDB is a **plain object**, whose
+constructor is `Object`, which carries no metadata. Every nested `@Restricted` therefore evaluated to
+"no restrictions" and the field was returned in full. The same class WAS filtered correctly when the
+value happened to be an instance, which is why this went unnoticed.
+
+```typescript
+@ObjectType()
+class Insurance {
+  @UnifiedField({ roles: RoleEnum.ADMIN, type: () => String })
+  policyNumber?: string;          // ← returned to EVERY caller before 11.35.0
+}
+
+@ObjectType()
+class Patient extends CorePersistenceModel {
+  @UnifiedField({ type: () => Insurance })
+  insurance?: Insurance;
+}
+```
+
+### What changed
+
+The nested type registry that `@UnifiedField` already fills is now also read by `checkRestricted()`,
+so a plain nested value is matched against the class its parent DECLARED — at every level, and for
+every item of a declared array.
+
+### What you should do
+
+- **Audit your models for nested `@Restricted` fields.** They start working now. A response that used
+  to include a nested restricted field will lose it for callers who may not see it (correct), and an
+  INPUT carrying one now throws 403 for such a caller where it was previously accepted.
+- **Declare nested types**: only `@UnifiedField({ type: () => X })` records what a property holds. A
+  property with no declared type stays unchecked — deliberately, because such a value is just as
+  legitimately free-form JSON, a `Map` or a scalar, and failing closed there would strip far more than
+  it protects.
+- A **class-level** `@Restricted` on a nested type strips the nested value's contents and leaves an
+  empty container (the documented `checkObjectItself: false` default) — it does not remove the key.
+
+## 9. File storage: a reused filename resolves to the MOST RECENT file
+
+### What happened
+
+Filenames are unique in no store and are client-supplied on both the multer and the tus path. Under
+GridFS, `bucket.find({ filename })` returned natural order (the oldest document) while
+`openDownloadStreamByName()` defaults to `revision: -1` (the newest). So with two files sharing a
+name, `getFileInfoByName()` / `getRawFileInfoByName()` authorized against one document and
+`getFileStreamByName()` / `getBufferByName()` / `duplicateByName()` served another: **a per-file
+ownership rule approved the caller's own file and handed over somebody else's bytes** — across
+tenants, since the file stores carry no tenant scope. The S3 and filesystem drivers resolved an id
+first and never had the split, which is exactly why one suite per driver could not see it.
+
+### What changed
+
+- All three stores resolve a by-name lookup to the **most recent** file of that name
+  (`uploadDate` desc, `_id` as tie-break). Under GridFS that matches its own revision semantics, so
+  the bytes a caller receives do not move; what changed is that the document authorization inspects is
+  the one being served.
+- Under S3 / filesystem the pick moves from "natural order" (usually the oldest) to the newest.
+- Every by-name read path resolves a document and then reads **by id**.
+
+### What you should do
+
+- **Prefer the id routes** (`GET /files/id/:id`, `getFileInfo`, `getFileStream`). The by-name route is
+  inherently ambiguous and is documented as such.
+- **If you duplicate files:** `duplicateById()` keeps the source's filename and the copy carries no
+  `metadata` by design. From now on that copy WINS the name, so an ownership rule keyed on
+  `metadata.ownerId` refuses it. Pass `serviceOptions.metadata` to give the copy its own owner, or
+  give it its own name.
+
+## 10. TUS: uploads now have an owner, and only the owner may touch them
+
+### What happened
+
+`tus.roles` (default `S_USER` since 11.33.0) decides who may reach the tus endpoint. It says nothing
+about WHICH upload a caller may touch, and the protocol is built around a per-upload URL: `HEAD`
+(offset), `PATCH` (append bytes) and `DELETE` (terminate) all addressed an upload by id with only that
+coarse gate. Two consequences:
+
+1. **Nothing recorded the uploader.** The finished file's metadata carried no owner, so the per-file
+   ownership rule `CoreFileService.checkRights()` documents could never authorize a tus-uploaded
+   file — it failed closed for everyone but ADMIN. A project following the documented pattern ended up
+   with files nobody could download.
+2. **Nothing checked the toucher.** Any other authenticated caller who learned an id could append
+   bytes to somebody else's upload — bytes then migrated into the file store under the ORIGINAL
+   uploader's filename — or destroy it.
+
+### What changed
+
+- `onUploadCreate` records the authenticated caller in the upload's metadata under
+  `TUS_OWNER_METADATA_KEY` (`ltOwnerId`), **overwriting** any client-supplied value.
+- `onIncomingRequest` refuses a request naming an upload the caller does not own, with **404** (the
+  same "a refusal is indistinguishable from a missing resource" policy the file module uses).
+- The finished file's metadata gains `ownerId`, so the documented ownership rule works.
+
+### What you should do
+
+- **Nothing for a normal authenticated upload flow.**
+- **An owner-LESS upload stays reachable by anyone who may reach the endpoint** — deliberately: uploads
+  created before this release carry no owner, and neither does an intentionally public form
+  (`tus.roles: [RoleEnum.S_EVERYONE]`). Denying those would break in-flight uploads on upgrade and a
+  documented configuration.
+- **Overriding `CoreTusService`?** `readRequestUserId()` and `assertUploadOwnership()` are `protected`
+  — override to read the owner from elsewhere (an API key, a signed form token) or to let a support
+  role resume any upload.
+
+## 11. `excludeSchemas` now warns when it disables isolation
+
+`multiTenancy.excludeSchemas` is an OFF SWITCH for data isolation, per model: a listed schema gets no
+tenant filter at all. The plugin only ever attaches to schemas that DECLARE a `tenantId` field, so
+listing such a model overrides its author's intent — and nothing said so. The framework's own docs
+carried `excludeSchemas: ['User', 'Session']` in a copyable `@example` from 11.20.0 onwards, which on a
+project with per-tenant users switches filtering off for the account collection.
+
+The plugin now logs a warning once per model, naming it. **That suggestion is withdrawn from the
+docs**: it is only correct for the global-user model (one account reaching several tenants, memberships
+carrying the scope). If your users have a `tenantId`, remove `User` from `excludeSchemas`. Do not add a
+model just because a `populate()` returns null across tenants — that is the isolation working.
+
+## 12. `@Roles()` on a `@Subscription` is now enforced
+
+### What happened
+
+All three role guards resolved the request the same way, and all three got the WebSocket wrong the
+same way:
+
+```typescript
+ctx.getContext()?.req || context.switchToHttp().getRequest()
+```
+
+A subscription's GraphQL context is the graphql-ws `extra` object, which has no `req`. The HTTP
+fallback then runs on a GraphQL context, where `switchToHttp().getRequest()` yields the resolver's
+ROOT value — `undefined` at subscribe time. So the guards were handed nothing, and what they did with
+nothing differed in the worst possible way:
+
+| Configuration | Behaviour before 11.35.0 |
+|---------------|--------------------------|
+| `multiTenancy` active | `CoreTenantGuard` hit `if (!request) return true` and GRANTED access. The role guard delegates non-system roles to it, so `@Roles()` on a subscription was checked by **nobody**: a plain `member` reached a `tenantAdmin`-gated subscription and received its messages |
+| no `multiTenancy` | the role guard found no token and refused EVERYONE, so the decorator silently meant "locked" instead of "open" |
+
+### What changed
+
+One shared resolver (`resolveGuardRequest`, `src/core/common/helpers/execution-context-request.helper.ts`)
+used by `RolesGuard`, `BetterAuthRolesGuard` and `CoreTenantGuard`. It recognises the subscription
+context and returns it as the request-like object — everything a guard needs is on it, because
+`CoreModule`'s `onConnect` records the authenticated `user` and the client's `connectionParams`.
+
+It deliberately does NOT accept any object with a `user` field: a subscription PAYLOAD very plausibly
+has one (`pubSub.publish('userCreated', user)`), and treating that as the caller would turn the
+published user into the apparent requester. The graphql-ws marker (`socket` / `request` /
+`connectionParams`) is required.
+
+### What you should do
+
+- **A `@Roles()`-gated subscription now behaves like the query of the same name.** If a subscriber
+  used to receive messages they were not entitled to, they stop.
+- **A subscription that was silently locked in a non-tenant project starts working.** Check that its
+  `@Roles()` says what you meant.
+- **Send the tenant with the handshake** when a subscription is tenant-scoped:
+  `createClient({ connectionParams: { Authorization: …, 'x-tenant-id': … } })`. A handshake naming a
+  tenant the subscriber is not a member of is now refused at the guard (403) instead of being scoped
+  to nothing.
+- `TestHelper` subscriptions now REJECT on an error-bearing message instead of pushing an
+  indistinguishable `null` — attach the handler when you start the subscription, not after a wait, or
+  Node reports the rejection as unhandled.
+
+## 13. The `@Restricted` opt-out can no longer be forged by data
+
+`_objectAlreadyCheckedForRestrictions` short-circuits three layers: `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 — but it was recognised by a **truthy test on a well-known property name**, and nothing in the
+framework ever wrote it. So a document carrying `_objectAlreadyCheckedForRestrictions: true` (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.
+
+The property name is unchanged; only the way it is recognised is. The value must now be a
+module-private symbol, set through `markRestrictionsChecked(obj)` — non-enumerable, so it never
+reaches a response body and cannot re-enter through a round trip.
+
+**If you set the flag by hand**, switch to the helper:
+
+```diff
++ import { markRestrictionsChecked } from '@lenne.tech/nest-server';
+
+  const result = await super.create(createInput, { currentUser, force: true });
+  if (result) {
+-   (result as any)._objectAlreadyCheckedForRestrictions = true;
++   markRestrictionsChecked(result);
+  }
+```
+
+A plain truthy value is no longer honoured, and the framework warns once naming the situation. Not
+honouring it is the safe direction: the object is CHECKED rather than skipped — but "checked" means the
+fields you set the flag to preserve are now stripped, so this is a change you will SEE.
+
+> **Make this change together with the framework update, not before it.** `markRestrictionsChecked()`
+> does not exist in 11.34.x, so a call-site change that lands first breaks the build. In vendor mode the
+> call sites and the core arrive in one change anyway (`/lt-dev:backend:update-nest-server-core`); in npm
+> mode, bump the dependency and the call sites in the same commit.
+
+**How to find every site:**
+
+```bash
+grep -rn "_objectAlreadyCheckedForRestrictions" --include="*.ts" src | grep -v "src/core/"
+```
+
+The shape to look for is a service that ran `super.create(...)` / `super.update(...)` with
+`force: true` and then marked the RESULT so the response interceptors would leave it alone. That is the
+legitimate use — it is only the RECOGNITION that changed, never the intent.
+
+## 14. A boot warning for files in a multi-tenant deployment
+
+The file stores are reached outside Mongoose (GridFS and S3 through their own drivers), so
+`mongooseTenantPlugin` never scopes them — which is why `CoreFileController` / `CoreFileResolver`
+carry `@SkipTenantCheck()`. The consequence is easy to miss and impossible to fix with configuration:
+`file.downloadRoles: ['editor']` resolves `'editor'` against `user.roles`, a GLOBAL attribute, so
+every holder of that role reaches EVERY tenant's files.
+
+`CoreFileService` now warns at construction time when **all three** of these hold:
+
+1. `multiTenancy` is configured and enabled,
+2. at least one of `file.downloadRoles` / `uploadRoles` / `deleteRoles` contains a role other than
+   `ADMIN`,
+3. `CoreFileService.checkRights()` is NOT overridden.
+
+Nothing else warns — the default admin-only gate is silent, and so is a project that has a per-file
+rule. If you see it, write `tenantId` into the file metadata at upload time
+(`serviceOptions.metadata`) and compare it in an overridden `checkRights()`; see
+`src/core/modules/file/README.md` § Access control.
+
+## 15. The reference `checkRights()` now refuses an unrestricted LISTING
+
+`findFileInfo()` consults the same per-file hook with `checkInputType: 'filterArgs'`, and the reference
+rule — the shape every project copies out of `src/server/modules/file/file.service.ts` — narrowed only
+`'id'` and `'filename'`. Everything else, listings included, was waved through.
+
+Core exposes no listing endpoint, so this was never a live hole in the framework. It was a hole in the
+shape projects copy, and it bites at the moment a project surfaces `findFileInfo()` — which is exactly
+when nobody re-reads the rule. `CoreFileInfo` carries `filename`, `length`, `uploadDate` and the `id`,
+so an unrestricted listing is a full INVENTORY of every upload, across tenants. For medical data the
+filename frequently IS the content.
+
+**The rule now refuses `'filterArgs'`**, because a yes/no hook cannot narrow a listing: it is asked once
+for the whole query, not once per row. Writes (`'file'` / `'files'`) still fall through to the coarse
+role gate — an upload has no owner to compare against yet.
+
+**A per-user listing is expressed by FORCING the constraint server-side:**
+
+```typescript
+this.fileService.findFileInfo(
+  { filter: { singleFilter: { field: 'metadata.ownerId', operator: ComparisonOperatorEnum.EQ,
+                              value: String(currentUser.id) } } },
+  { force: true },
+);
+```
+
+Note what that is NOT: it does not inspect the caller's own `filterArgs` to check whether they are
+already narrowed. **`filterArgs` is client-controlled**, so approving a filter shape means validating
+attacker input — and any such check is one filter shape away from being wrong. Override the filter;
+never approve it.
+
+### What you should do
+
+- **If you copied the reference rule and expose `findFileInfo()`:** non-admins now get `null` instead of
+  a listing. Add the forced-filter call above wherever a per-user listing is intended.
+- **If you never expose `findFileInfo()`:** nothing changes.
+
+## 16. New: `file.access` — the per-file rule as a declaration
+
+Purely additive; the default (`'custom'`) is byte-for-byte the previous behaviour, including the absence
+of any extra query.
+
+The per-file rule is the only place a sentence like "…but only their own" can live, because that
+sentence needs data and no role name carries data. The framework used to ship it as an `@example` to
+copy — and the copy went wrong twice in this framework's own history, both times permissively:
+`if (!options.currentUser) return true` (which is also what an anonymous request looks like), and
+narrowing only `'id'` / `'filename'` so a listing was waved through. Neither reads as careless. That is
+the argument for a preset.
+
+| `file.access` | project class | own `checkRights()`? |
+|---|---|---|
+| `'custom'` (**default**) | anything the framework cannot guess — you write the rule | yes |
+| `'public'` | open: anyone may read and write | no |
+| `'authenticated'` | login-restricted: every signed-in user may use every file | no |
+| `'owner'` | per-user: only the uploader, plus ADMIN | no |
+| `'tenant'` | per-tenant: only the own validated tenant, plus ADMIN | no |
+
+`'owner'` and `'tenant'` read `metadata.ownerId` / `metadata.tenantId`, and `CoreFileService` **stamps
+them as it writes** while one of them is active — a preset that only READ those would be a rule about
+data that does not exist, i.e. every file ADMIN-only. (That is not hypothetical: it is exactly the shape
+TUS uploads had before this release.) Stamping never overrides a value the caller supplied, and stamps
+nothing under `'custom'`, so no existing project's documents change.
+
+Both presets: ADMIN is never locked out; writes fall through to `uploadRoles` / `deleteRoles`; a LISTING
+is refused (a yes/no hook cannot narrow one — see §15); a missing user or a missing owner field fails
+CLOSED. The tenant preset reads the VALIDATED tenant from `RequestContext`, the same source
+`mongooseTenantPlugin` filters by, so a file decision and a database decision cannot disagree.
+
+An unknown value resolves to `'owner'`, not `'custom'`: a typo means somebody believes they have an
+ownership rule, and confirming that belief is the one error nobody can see from outside.
+
+### What you should do
+
+- **Nothing** — the default changes no behaviour.
+- **Adopting a preset?** Set `file.access`, then **backfill** `metadata.ownerId` / `metadata.tenantId`
+  on existing files. Until you do, they are ADMIN-only.
+- **Already override `checkRights()`?** Keep doing that. The override wins and the preset never runs;
+  `'custom'` simply says so out loud.
+
+### The boot warning widened with it
+
+`warnOnUnscopedFilesInTenantMode` is now `warnOnUndecidedFileAccess`, and it no longer requires
+multi-tenancy. It warns when the role gate goes beyond `ADMIN` **and** neither `file.access` nor a
+`checkRights()` override declares a policy — i.e. when nobody has decided. Declaring `'public'` or
+`'authenticated'` silences it, which is the point: the warning is about the difference between a
+decision and an omission. `downloadRoles: [S_USER]` with no rule leaks every file to every signed-in
+user whether or not tenants exist, and file ids are enumerable.
+
+## New Exports
+
+```typescript
+import {
+  markRestrictionsChecked,            // the ONLY way to set the @Restricted opt-out now
+  hasRestrictionsCheckedMarker,       // …and the way to read it
+  RESTRICTIONS_CHECKED_KEY,
+  resolveGuardRequest,                // the shared guard request resolver (incl. subscriptions)
+  warnOnUndecidedFileAccess,       // renamed from warnOnUnscopedFilesInTenantMode
+  resolveFileAccessPreset,         // file.access resolution
+  decideFileAccess,                // the pure per-file decision behind the presets
+  fileAccessNeedsRawDocument,
+  buildRequestContextAwareExecute,    // the WS execute wrapper CoreModule installs
+  buildRequestContextAwareSubscribe,  // the WS subscribe wrapper CoreModule installs
+  createRequestContextAwareExecute,   // …the injectable forms, for a custom driver
+  createRequestContextAwareSubscribe,
+  getTenantContextResolver,           // tenant resolution for transports without an Express request
+  setTenantContextResolver,
+  nestedTypeRegistry,                 // moved to an import-free leaf; re-exported where it was
+  resolveNestedType,                  // the declared type of a model property
+  TUS_OWNER_METADATA_KEY,             // 'ltOwnerId'
+} from '@lenne.tech/nest-server';
+```
+
+```typescript
+import {
+  isSystemRole,               // exact, case-sensitive — the RUNTIME rule the guards use
+  looksLikeSystemRole,        // trimmed + case-insensitive — the STORAGE rule
+  SYSTEM_ROLE_PREFIX,         // 's_'
+  SYSTEM_ROLE_REJECT_PATTERN, // @Matches pattern mirroring looksLikeSystemRole
+  mongooseSystemRolePlugin,
+  GLOBAL_ONLY_ROLES,          // roles only the platform may grant — currently [ADMIN]
+  isGlobalOnlyRole,           // exact — the RUNTIME rule
+  looksLikeGlobalOnlyRole,    // trimmed + case-insensitive — the STORAGE rule
+  isForbiddenMembershipRole,  // may this value be a tenant membership role at all?
+  resolveGlobalAndTenantRoles,// splits required roles by which source may answer them
+} from '@lenne.tech/nest-server';
+```
+
+The two predicates differ on purpose: runtime checks compare role strings exactly (so `'S_SELF'`
+never granted anything and must not be treated as a system role by the guards), while the storage
+question deserves the stricter, defensive answer.
+
+## Module Documentation
+
+- Role system, `S_` prefix rules, `@Roles` vs `@Restricted`: [`.claude/rules/role-system.md`](../.claude/rules/role-system.md)
+- Request lifecycle, validation pipe, interceptor chain: [`docs/REQUEST-LIFECYCLE.md`](../docs/REQUEST-LIFECYCLE.md)
+- Reference implementation of a project user input: `src/server/modules/user/inputs/user.input.ts`
+
+## References
+
+- Previous guide: [`11.34.0-to-11.34.1.md`](./11.34.0-to-11.34.1.md)
+- `CoreUserInput`: `src/core/modules/user/inputs/core-user.input.ts`
+- `mongooseSystemRolePlugin`: `src/core/common/plugins/mongoose-system-role.plugin.ts`
+- Regression evidence: mutations `user-roles-accepts-system-roles` and
+  `non-dto-write-paths-accept-system-roles` in `tests/regression-mutations.json`