@lenne.tech/nest-server 11.34.1 → 11.35.0

package/src/core/common/plugins/mongoose-tenant.plugin.ts

@@ -1,8 +1,48 @@
-import { ForbiddenException } from '@nestjs/common';
+import { ForbiddenException, Logger } from '@nestjs/common';
 
 import { ConfigService } from '../services/config.service';
 import { RequestContext } from '../services/request-context.service';
 
+/** Models already warned about, so the message appears once per process rather than per query. */
+const isolationDisabledWarned = new Set<string>();
+
+/**
+ * Say out loud that isolation is off for a schema that was built for it.
+ *
+ * `excludeSchemas` is a legitimate feature — a genuinely global lookup table has no tenant. But this
+ * plugin only ever attaches to schemas that DECLARE a `tenantId` field, so reaching here means the
+ * author of that schema intended per-tenant rows and the configuration silently overrides them.
+ * Nothing said so, and the shape is easy to arrive at by accident: the framework's own documentation
+ * 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 user collection.
+ *
+ * A warning, not a boot failure. An ambiguous ROLE vocabulary fails the boot because its access
+ * decisions cannot be resolved coherently; this configuration is perfectly coherent — it is simply
+ * one nobody may make without noticing.
+ *
+ * The membership model is skipped: `CoreModule` adds it to `excludeSchemas` itself because
+ * membership is tenant-spanning by design, so warning about it would be the framework complaining
+ * about its own correct default.
+ */
+function warnIsolationDisabled(modelName: string): void {
+  if (isolationDisabledWarned.has(modelName)) {
+    return;
+  }
+  isolationDisabledWarned.add(modelName);
+
+  const membershipModel = ConfigService.configFastButReadOnly?.multiTenancy?.membershipModel ?? 'TenantMember';
+  if (modelName === membershipModel) {
+    return;
+  }
+
+  new Logger('mongooseTenantPlugin').warn(
+    `Tenant isolation is DISABLED for "${modelName}": the schema declares a tenantId field, but ` +
+      `"${modelName}" is listed in multiTenancy.excludeSchemas — so no tenant filter is applied and ` +
+      `every query on it sees every tenant's rows. Remove it from excludeSchemas unless this ` +
+      `collection is genuinely global.`,
+  );
+}
+
 /**
  * Mongoose plugin that provides automatic tenant-based data isolation.
  * Only activates on schemas that have a `tenantId` path defined.
@@ -63,6 +103,19 @@ export function mongooseTenantPlugin(schema) {
       if (filter !== undefined) {
         this.where(filter);
       }
+
+      // The filter above constrains WHICH rows are touched, never what the update WRITES. So a
+      // caller could legitimately match their own row and then rewrite its tenantId — moving it
+      // into a tenant they control, or simply out of reach of its rightful owner.
+      const single = resolveSingleTenantId(modelName);
+      if (single) {
+        const update: any = typeof this.getUpdate === 'function' ? this.getUpdate() : undefined;
+        for (const candidate of [update?.tenantId, update?.$set?.tenantId, update?.$setOnInsert?.tenantId]) {
+          if (candidate !== undefined) {
+            assertOwnTenant(candidate, single, false);
+          }
+        }
+      }
     });
   }
 
@@ -70,14 +123,23 @@ export function mongooseTenantPlugin(schema) {
   // Intentional asymmetry: writes only set tenantId when truthy (not null).
   // Only uses single tenantId from header — tenantIds array is for reads only.
   schema.pre('save', function () {
+    // Document hooks: `this` is the document instance — modelName is on the constructor (the Model class)
+    const modelName = (this.constructor as any).modelName;
+    const tenantId = resolveSingleTenantId(modelName);
+    if (!tenantId) {
+      return;
+    }
+
     if (this.isNew && !this['tenantId']) {
-      // Document hooks: `this` is the document instance — modelName is on the constructor (the Model class)
-      const modelName = (this.constructor as any).modelName;
-      const tenantId = resolveSingleTenantId(modelName);
-      if (tenantId) {
-        this['tenantId'] = tenantId;
-      }
+      this['tenantId'] = tenantId;
+      return;
     }
+
+    // A tenantId that is already on the document did NOT come from this hook. Stamping only when
+    // absent is right for system writes, but on its own it means a caller-supplied value survives —
+    // so an explicit foreign tenantId would place the row in someone else's tenant, and modifying it
+    // on an existing document would move the row out of this one.
+    assertOwnTenant(this['tenantId'], tenantId, this.isNew);
   });
 
   // === insertMany (Mongoose 9: first arg is docs array, no next callback) ===
@@ -89,6 +151,8 @@ export function mongooseTenantPlugin(schema) {
       for (const doc of docs) {
         if (!doc.tenantId) {
           doc.tenantId = tenantId;
+        } else {
+          assertOwnTenant(doc.tenantId, tenantId, true);
         }
       }
     }
@@ -123,17 +187,182 @@ export function mongooseTenantPlugin(schema) {
     }
   });
 
-  // === Aggregate: prepend $match stage ===
+  // === estimatedDocumentCount: unfilterable, so refuse it inside a tenant context ===
+  //
+  // It reads collection metadata rather than running a query, so MongoDB ignores any filter — there
+  // is nothing to inject. Returning it unchanged would hand a tenant the row count of the WHOLE
+  // collection, i.e. every other tenant's volume. Throwing is the only honest option; callers that
+  // want a tenant's own count use countDocuments(), which IS filtered.
+  schema.pre('estimatedDocumentCount', function () {
+    const modelName = (this as any).model?.modelName;
+    if (shouldBypass(modelName)) {
+      return;
+    }
+    const context = RequestContext.get();
+    if (context?.isAdminBypass && !context?.tenantId) {
+      return; // platform admin without a tenant header legitimately sees everything
+    }
+    throw new ForbiddenException(
+      "estimatedDocumentCount() cannot be tenant-filtered and would expose other tenants' row counts — " +
+        'use countDocuments() instead',
+    );
+  });
+
+  // === Aggregate: prepend $match stage, and secure every cross-collection stage ===
   schema.pre('aggregate', function () {
     // Aggregate hooks: `this` is the Aggregation pipeline — the model is on the internal `_model` property
-    const modelName = (this as any)._model?.modelName;
+    const model = (this as any)._model;
+    const modelName = model?.modelName;
     const filter = resolveTenantFilter(modelName);
-    if (filter !== undefined) {
-      this.pipeline().unshift({ $match: filter });
+    if (filter === undefined) {
+      return;
+    }
+
+    const pipeline = this.pipeline();
+
+    // $out and $merge are the only aggregation stages that WRITE, and neither can be constrained
+    // the way a read stage can: $out REPLACES a whole collection, and $merge writes rows whose
+    // tenantId comes from the pipeline rather than from the caller's context. Either one turns an
+    // aggregation into a way to launder rows across the boundary — or, with $out, to erase another
+    // tenant's collection outright. There is nothing to inject here, so a tenant-scoped caller is
+    // refused; system code that legitimately needs them runs under runWithBypassTenantGuard().
+    const writeStage = pipeline.find((stage: any) => stage && (stage.$out !== undefined || stage.$merge !== undefined));
+    if (writeStage) {
+      throw new ForbiddenException(
+        `Aggregation write stages ($out / $merge) are not permitted inside a tenant context — ` +
+          'they cannot be tenant-filtered. Run them as a system operation if this is intended.',
+      );
     }
+
+    pipeline.unshift({ $match: filter });
+
+    // The $match above only constrains the SOURCE collection. `$lookup`, `$unionWith` and
+    // `$graphLookup` read a DIFFERENT collection, and that collection's own `aggregate` hook never
+    // fires — the join runs inside this pipeline. Without the pass below, a single aggregation
+    // returns every tenant's rows from the joined collection, which is exactly the shape a
+    // reporting query takes.
+    secureCrossCollectionStages(pipeline, model);
   });
 }
 
+/**
+ * Inject the tenant filter into every stage that reads another collection.
+ *
+ * Recurses, because these stages nest: a `$lookup.pipeline` may itself contain a `$lookup`, and
+ * `$facet` holds a sub-pipeline per key.
+ *
+ * A joined collection is only constrained when it is itself tenant-scoped (its model has a
+ * `tenantId` path and is not excluded). Joining a global lookup table stays untouched — filtering
+ * it by `tenantId` would silently return nothing.
+ */
+function secureCrossCollectionStages(pipeline: any[], model: any): void {
+  if (!Array.isArray(pipeline)) {
+    return;
+  }
+
+  for (const stage of pipeline) {
+    if (!stage || typeof stage !== 'object') {
+      continue;
+    }
+
+    if (stage.$lookup) {
+      const filter = filterForCollection(stage.$lookup.from, model);
+      if (filter) {
+        // MongoDB 5.0+ allows `pipeline` alongside localField/foreignField, so this works for the
+        // concise join form too, not only the explicit-pipeline one.
+        stage.$lookup.pipeline = [{ $match: filter }, ...(stage.$lookup.pipeline ?? [])];
+      }
+      secureCrossCollectionStages(stage.$lookup.pipeline, model);
+    }
+
+    if (stage.$unionWith) {
+      // Two forms: `$unionWith: 'coll'` and `$unionWith: { coll, pipeline }`.
+      if (typeof stage.$unionWith === 'string') {
+        const filter = filterForCollection(stage.$unionWith, model);
+        if (filter) {
+          stage.$unionWith = { coll: stage.$unionWith, pipeline: [{ $match: filter }] };
+        }
+      } else {
+        const filter = filterForCollection(stage.$unionWith.coll, model);
+        if (filter) {
+          stage.$unionWith.pipeline = [{ $match: filter }, ...(stage.$unionWith.pipeline ?? [])];
+        }
+        secureCrossCollectionStages(stage.$unionWith.pipeline, model);
+      }
+    }
+
+    if (stage.$graphLookup) {
+      const filter = filterForCollection(stage.$graphLookup.from, model);
+      if (filter) {
+        // $graphLookup takes no pipeline; `restrictSearchWithMatch` is its filter hook and applies
+        // to EVERY recursive step, which is what a traversal needs.
+        stage.$graphLookup.restrictSearchWithMatch = {
+          ...stage.$graphLookup.restrictSearchWithMatch,
+          ...filter,
+        };
+      }
+    }
+
+    if (stage.$facet && typeof stage.$facet === 'object') {
+      for (const branch of Object.values(stage.$facet)) {
+        secureCrossCollectionStages(branch as any[], model);
+      }
+    }
+  }
+}
+
+/**
+ * Tenant filter for a JOINED collection, or `undefined` when none applies.
+ *
+ * Resolves the collection name back to its model so the same "is this tenant-scoped?" rule applies
+ * as for a direct query. An unknown collection name yields no filter: the plugin cannot tell
+ * whether it is tenant-scoped, and inventing a `tenantId` constraint for a collection that has no
+ * such field would turn a working join into an empty result.
+ */
+function filterForCollection(collectionName: unknown, sourceModel: any): Record<string, any> | undefined {
+  if (typeof collectionName !== 'string' || !collectionName) {
+    return undefined;
+  }
+
+  const models = sourceModel?.db?.models ?? {};
+  for (const name of Object.keys(models)) {
+    const candidate = models[name];
+    if (candidate?.collection?.name !== collectionName) {
+      continue;
+    }
+    if (!candidate.schema?.path('tenantId')) {
+      return undefined; // not tenant-scoped — leave the join alone
+    }
+    const filter = resolveTenantFilter(name);
+    // `{}` means "admin bypass, sees everything" — nothing to inject.
+    return filter && Object.keys(filter).length ? filter : undefined;
+  }
+
+  return undefined;
+}
+
+/**
+ * Refuse a tenantId that is not the caller's own.
+ *
+ * Covers both directions of the same boundary:
+ * - creating a row with a FOREIGN tenantId → planting data in someone else's tenant;
+ * - changing an existing row's tenantId → moving data out of this one.
+ *
+ * Throwing rather than overwriting is deliberate. Silently rewriting the value would make a request
+ * that asked for something impossible look like it succeeded, and for tenant-scoped medical data
+ * "the write went somewhere other than you asked" is not a recoverable ambiguity.
+ */
+function assertOwnTenant(value: unknown, ownTenantId: string, isNew: boolean): void {
+  if (value === undefined || value === null || value === ownTenantId) {
+    return;
+  }
+  throw new ForbiddenException(
+    isNew
+      ? `Cannot create a document in a foreign tenant (got "${String(value)}", own tenant is "${ownTenantId}")`
+      : `Cannot move a document to a foreign tenant (got "${String(value)}", own tenant is "${ownTenantId}")`,
+  );
+}
+
 /**
  * Check common bypass conditions.
  *
@@ -146,7 +375,10 @@ function shouldBypass(modelName?: string): boolean {
   const context = RequestContext.get();
   if (!context) return true;
   if (context.bypassTenantGuard) return true;
-  if (modelName && mtConfig.excludeSchemas?.includes(modelName)) return true;
+  if (modelName && mtConfig.excludeSchemas?.includes(modelName)) {
+    warnIsolationDisabled(modelName);
+    return true;
+  }
 
   return false;
 }

package/src/core/common/services/core-s3.service.ts

@@ -92,7 +92,15 @@ export class CoreS3Service implements OnApplicationShutdown, OnModuleInit {
       this.logger.warn('Ignoring the `s3` configuration: no `bucket` is set, so S3 cannot be used.');
       return;
     }
-    const presigned = raw.presignedDownloads;
+    // `enabled: false` disables, exactly as everywhere else in the config (see
+    // .claude/rules/configurable-features.md). Reading any object as "enabled" made this the one
+    // knob where the documented pre-configuration idiom silently turned a feature ON — and it is a
+    // feature that hands out session-less bearer URLs.
+    const rawPresigned = raw.presignedDownloads;
+    const presigned =
+      rawPresigned && typeof rawPresigned === 'object' && (rawPresigned as { enabled?: boolean }).enabled === false
+        ? undefined
+        : rawPresigned;
     this.config = {
       accessKeyId: raw.accessKeyId,
       autoCreateBucket: raw.autoCreateBucket ?? false,

package/src/core/common/services/core-tenant-context.registry.ts

@@ -0,0 +1,50 @@
+/**
+ * How a non-HTTP transport asks the tenant machinery "which tenant is this caller in?".
+ *
+ * DELIBERATELY IMPORT-FREE apart from a type-only import, so it stays a leaf — and it lives under
+ * `src/core/common/` rather than next to the tenant module for a second reason: the reader is
+ * `graphql-ws-context.helper`, also in `src/core/common/`, and `src/core/common/**` must not import
+ * from `src/core/modules/**`. The writer (`CoreTenantGuard`) imports in the allowed direction.
+ * A registry rather than DI because the GraphQL wiring in `core.module.ts` must not depend on a
+ * provider that only exists when multi-tenancy is configured. Same pattern as
+ * `core-cron-jobs.registry.ts`. See `.claude/rules/architecture.md` → "DI Token Placement (SWC-Safe)".
+ *
+ * WHY IT EXISTS: `CoreTenantGuard` answers this question from an Express request and writes the
+ * answer onto it (`request.tenantId` / `request.tenantIds`), which `RequestContextMiddleware` then
+ * exposes through AsyncLocalStorage. A WebSocket never traverses either — no Express middleware runs
+ * on an upgrade, and the guard's own `getRequest()` returns nothing for a subscription context, so it
+ * returns `true` without deciding anything. This registry is what lets the WebSocket path ask the
+ * same question through the same membership logic and cache.
+ */
+import type { IRequestContext } from './request-context.service';
+
+/** The tenant-relevant slice of a request context — everything the Mongoose tenant plugin reads. */
+export type ResolvedTenantContext = Pick<IRequestContext, 'isAdminBypass' | 'tenantId' | 'tenantIds' | 'tenantRole'>;
+
+export interface TenantContextResolver {
+  /**
+   * @param user the authenticated user (with `roles`), or undefined for an anonymous caller
+   * @param headerTenantId the raw tenant id the transport carried, if any — NEVER trusted; it is
+   *   validated against an active membership before it is returned
+   */
+  resolve(user: { id: string; roles?: string[] } | undefined, headerTenantId?: string): Promise<ResolvedTenantContext>;
+}
+
+let resolver: TenantContextResolver | undefined;
+
+/** Registered by `CoreTenantGuard` on init. Idempotent — test fixtures build the guard repeatedly. */
+export function setTenantContextResolver(next: TenantContextResolver | undefined): void {
+  resolver = next;
+}
+
+/**
+ * The registered resolver, or `undefined` when multi-tenancy is not in play.
+ *
+ * `undefined` must NOT be read as "no tenant restrictions": it means nothing can answer the
+ * question, so a caller establishes a context WITHOUT tenant information and lets the Mongoose
+ * plugin's safety net refuse tenant-scoped reads. That is the difference between "this data is not
+ * tenant-scoped" and "nobody knows which tenant this is".
+ */
+export function getTenantContextResolver(): TenantContextResolver | undefined {
+  return resolver;
+}

package/src/core/modules/auth/guards/roles.guard.ts

@@ -9,6 +9,8 @@ import {
 } from '@nestjs/common';
 import { ModuleRef, Reflector } from '@nestjs/core';
 import { GqlExecutionContext } from '@nestjs/graphql';
+
+import { resolveGuardRequest } from '../../../common/helpers/execution-context-request.helper';
 import { firstValueFrom, isObservable } from 'rxjs';
 
 import { RoleEnum } from '../../../common/enums/role.enum';
@@ -341,10 +343,10 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
    * Integrate request from GraphQL
    */
   getRequest(context: ExecutionContext) {
-    const ctx = GqlExecutionContext.create(context);
-    // For GraphQL: ctx.getContext() is the GQL context with `.req` property
-    // For REST/HTTP: ctx.getContext() returns the `next` function (truthy but without `.req`)
-    // Using `?.req ||` ensures we fall back to the HTTP request for REST controllers
-    return ctx.getContext()?.req || context.switchToHttp().getRequest();
+    // Shared with BetterAuthRolesGuard and CoreTenantGuard — see execution-context-request.helper.
+    // For GraphQL over HTTP the context carries `.req`; for REST it does not (it is the `next`
+    // function) and the HTTP fallback applies; for a GraphQL SUBSCRIPTION neither holds, and the
+    // subscription context itself is the request-like object.
+    return resolveGuardRequest(context, (ctx) => GqlExecutionContext.create(ctx).getContext());
   }
 }

package/src/core/modules/better-auth/better-auth-roles.guard.ts

@@ -8,6 +8,8 @@ import {
 } from '@nestjs/common';
 import { GqlExecutionContext } from '@nestjs/graphql';
 
+import { resolveGuardRequest } from '../../common/helpers/execution-context-request.helper';
+
 import { RoleEnum } from '../../common/enums/role.enum';
 import { ErrorCode } from '../error-code';
 import { isMultiTenancyActive, isSystemRole, mergeRolesMetadata } from '../tenant/core-tenant.helpers';
@@ -178,19 +180,11 @@ export class BetterAuthRolesGuard implements CanActivate {
    * Handles both GraphQL and HTTP contexts
    */
   private getRequest(context: ExecutionContext): any {
-    // Try GraphQL context first
-    try {
-      const gqlContext = GqlExecutionContext.create(context);
-      const ctx = gqlContext.getContext();
-      if (ctx?.req) {
-        return ctx.req;
-      }
-    } catch {
-      // GraphQL context not available
-    }
-
-    // Fallback to HTTP context
-    return context.switchToHttp().getRequest();
+    // Shared with RolesGuard and CoreTenantGuard — see execution-context-request.helper. The GraphQL
+    // WEBSOCKET branch is what makes `@Roles()` work on a subscription at all: the subscription
+    // context carries the authenticated user (CoreModule's onConnect records it), while `.req` does
+    // not exist there and the HTTP fallback yields the resolver root.
+    return resolveGuardRequest(context, (ctx) => GqlExecutionContext.create(ctx).getContext());
   }
 
   /**

package/src/core/modules/file/INTEGRATION-CHECKLIST.md

@@ -88,6 +88,63 @@ If some files are genuinely public and others are not, do not solve it with a ro
 record a visibility flag in the metadata and branch in `checkRights()`, or expose a separate public
 route for exactly the public files and leave the core routes gated.
 
+## Pick your project class first — the whole model is one dial with five settings
+
+`file.access` is the per-file rule as a DECLARATION instead of code. Until 11.35.0 the framework shipped
+that rule only as an `@example` to copy, and the copy went wrong twice in its own history — both times
+permissively (`if (!currentUser) return true`, and waving `'filterArgs'` through). Decide which row you
+are, then verify only that row.
+
+| Project class                                                  | `file.access`            | roles                                 | own `checkRights()`? |
+| -------------------------------------------------------------- | ------------------------ | ------------------------------------- | -------------------- |
+| **Open** — anyone may read and write                           | `'public'`               | `[RoleEnum.S_EVERYONE]`               | no                   |
+| **Login-restricted** — every signed-in user may use every file | `'authenticated'`        | `[RoleEnum.S_USER]`                   | no                   |
+| **Per-user** — only the uploader                               | `'owner'`                | `[RoleEnum.S_USER]`                   | no                   |
+| **Tenant-based** — only within one's own tenant                | `'tenant'`               | `[RoleEnum.S_USER]` or a project role | no                   |
+| **Regulated** — explicit read right, explicit write right      | `'custom'` (the default) | a narrow role                         | **yes**              |
+
+What the presets do, and what they deliberately do not:
+
+- `'owner'` / `'tenant'` read `metadata.ownerId` / `metadata.tenantId`, which `CoreFileService` **stamps
+  as it writes** once one of them is active — so an upload through the service is authorizable with no
+  project code. ADMIN is never locked out, writes fall through to the role gate (an upload has no owner
+  to compare against yet), a LISTING is refused, and a missing user or a missing owner field FAILS
+  CLOSED.
+- **Files written before you enabled the preset carry no such metadata and are therefore ADMIN-only.**
+  That is the fail-closed direction; a one-off backfill fixes it.
+- `'public'` / `'authenticated'` add no data rule at all. They exist so that "no per-file rule" is a
+  DECISION in `config.env.ts` rather than an omission — and that is what silences the boot warning.
+- **Declaring the class never widens the role gate.** `'public'` still needs
+  `downloadRoles: [S_EVERYONE]`. Two decisions, on purpose.
+- **The last row is the point of the dial.** A regulated project has rights the framework cannot guess
+  (a read right, a write right, a case assignment), so it stays on `'custom'` and writes the rule — and
+  everything the presets do is then its checklist: cover `'id'` and `'filename'`, refuse `'filterArgs'`,
+  gate the writes, fail closed without a user, require the owner field to be present.
+
+Two rules hold for every row:
+
+1. **The coarse gate can grant but never exclude ADMIN** — both file classes carry a class-level
+   `@Roles(ADMIN)` and the guards union class + handler metadata.
+2. **A per-file sentence needs data.** No role name can express "…but only their own" — which is why
+   there is a hook at all, and why the presets stamp the data they decide on.
+
+## The threat model, in four sentences
+
+Read this before the checklist — it is what the checklist is checking.
+
+**File ids are not secrets, and they are ENUMERABLE.** A MongoDB ObjectId is 4 bytes of timestamp +
+5 bytes of randomness generated ONCE PER PROCESS + a 3-byte incrementing counter. Every id minted by
+one server process therefore shares the same random part, so a caller who obtains a single valid id —
+their own upload is enough — knows that part and a counter reference point; the ids of files the same
+process created nearby in time sit on adjacent counter values. There is also **no rate limit on the
+file routes** (the framework's limiters cover auth, IAM and AI only), so nothing throttles walking
+that range.
+
+The consequence: **the role gate is a coarse audience filter, never a per-file secret.**
+`downloadRoles: [S_USER]` without an overridden `checkRights()` means every signed-in user can read
+every file, and enumeration makes that practically reachable rather than theoretical. If files are
+personal or medical, a per-file rule is not optional.
+
 ## Verification Checklist
 
 - [ ] `pnpm run build` succeeds
@@ -108,6 +165,40 @@ route for exactly the public files and leave the core routes gated.
 - [ ] `OPTIONS /tus` answers without credentials (browser preflight)
 - [ ] Avatars / images in the frontend still render for the roles that should see them
 
+### Security checklist — the questions an audit will ask
+
+- [ ] **Is the project class declared?** Either `file.access` names one, or `checkRights()` is
+      overridden. If `downloadRoles` goes beyond `ADMIN` and NEITHER is true, every holder of that
+      role reads every file by enumeration — and the framework warns at boot, in every deployment,
+      tenant or not. Declaring `'public'` / `'authenticated'` is a valid answer; leaving it unset is
+      not
+- [ ] **On `file.access: 'owner'` / `'tenant'`: is old data backfilled?** Files uploaded before the
+      preset was enabled carry no `ownerId` / `tenantId` and stay ADMIN-only until they do
+- [ ] **If you wrote your own rule, does it cover all four branches?** `'id'`, `'filename'`, `'filterArgs'` and the writes.
+      `'filename'` is not redundant (the presigned path authorizes on the by-name lookup alone, and
+      `deleteFileByName()` authorizes by name only), and `'filterArgs'` must be **refused** — a yes/no
+      hook cannot narrow a listing, so returning `true` there hands over a full inventory
+- [ ] **Does the rule FAIL CLOSED on a missing `currentUser`?** `if (!options.currentUser) return true`
+      reads as "system call" but is also what an anonymous request looks like
+- [ ] **Does it require the owner field to be PRESENT?** Without `!!raw?.metadata?.ownerId`, an
+      owner-less file compares `undefined` with `undefined` and matches
+- [ ] **Is a per-user LISTING forced server-side?** Build the filter from `currentUser` and pass
+      `{ force: true }`. Never inspect the caller's own `filterArgs` to decide whether they are
+      already narrowed — that is validating client input
+- [ ] **Multi-tenant: is `tenantId` in the metadata and compared?** The stores are reached outside
+      Mongoose, so `mongooseTenantPlugin` never scopes them and a role name cannot express a tenant
+      rule. Nothing else can do this for you
+- [ ] **Is `s3.presignedDownloads` off** (it is by default) — or, if on, is the expiry short and the
+      audience genuinely "anyone who once held the link"? The URL works without a session, from any
+      IP, and cannot be revoked
+- [ ] **Are `/files/*` and `/tus/*` rate-limited in the reverse proxy?** The framework does not
+      throttle them, and ids are enumerable
+- [ ] **Do downloads go through the ID route, not the filename route?** Filenames are unique in no
+      store and are chosen by the uploader, so a name can be squatted; the by-name path resolves the
+      MOST RECENT file of that name
+- [ ] **Does anything read files WITHOUT `CoreFileService`?** Direct GridFS or S3-SDK access bypasses
+      `checkRights()` entirely
+
 ## Common Mistakes
 
 | Mistake                                            | Symptom                                  | Fix                                                                                                                    |
@@ -117,4 +208,7 @@ route for exactly the public files and leave the core routes gated.
 | `downloadRoles: []`                                | Warning logged, default applied          | Use a non-empty array; `[]` would read as "no roles required" and open the route                                       |
 | Expecting `metadata` back from `getFileInfo()`     | `undefined`                              | Use `getRawFileInfo()` inside `checkRights()`                                                                          |
 | `downloadRoles: ['member']` with multiTenancy      | Works from code, fails from `<img>`      | Both file classes carry `@SkipTenantCheck()`; roles resolve against `user.roles`. Use `checkRights()` for tenant rules |
-| Signed-in user can upload via TUS but not download | 403 on their own file                    | `tus.roles` and `file.downloadRoles` are separate. Add an owner to the metadata and authorize per file                 |
+| Signed-in user can upload via TUS but not download | 403 on their own file                    | `tus.roles` and `file.downloadRoles` are separate. Add an owner to the metadata and authorize per file                 |
+| Rule narrows only `'id'` / `'filename'`            | `findFileInfo()` returns every file      | Refuse `'filterArgs'`; force a per-user filter server-side with `{ force: true }`                                      |
+| Treating the file id as unguessable                | Enumerable inventory                     | Ids share a per-process random part and an incrementing counter — authorize every read, do not rely on the id          |
+| Approving the caller's `filterArgs` as "narrowed"  | Bypass via a different filter shape      | `filterArgs` is client-controlled. Override the filter; never approve it                                               |

package/src/core/modules/file/README.md

@@ -189,6 +189,67 @@ streamed, because the filename route resolves an id and checks it again — but
 by-name lookup alone and then redirects, and not for `deleteFileByName()`, which authorizes by name
 only.
 
+**A reused filename resolves to the MOST RECENT file (11.35.0+).** Filenames are unique in no store
+and are client-supplied on both the multer and the tus path, so a by-name lookup is inherently
+ambiguous — prefer the id routes. What must NOT be ambiguous is which of the candidates each by-name
+path picks. Until 11.35.0 the GridFS driver got that wrong in the worst possible way:
+`bucket.find({ filename })` answered natural order (the oldest document) while
+`openDownloadStreamByName()` defaults to `revision: -1` (the newest), so `getFileInfoByName()` /
+`getRawFileInfoByName()` authorized against one document and `getFileStreamByName()` /
+`getBufferByName()` / `duplicateByName()` served another. An 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. All three drivers now resolve the most recent file (`uploadDate` desc, `_id` as tie-break) and
+every by-name read path resolves a document and then reads **by id**.
+
+One consequence worth knowing: `duplicateById()` keeps the source's filename and the copy carries no
+`metadata` by design, so the copy WINS the name and an ownership rule keyed on `metadata.ownerId`
+refuses it. Give the copy its own metadata or its own name.
+
+### Before you write a rule: `file.access` may already be it
+
+The four common project shapes are presets, so the rule below is only needed for the fifth — a project
+whose rights the framework cannot guess.
+
+| `file.access`        | project class                                          | own `checkRights()`? |
+| -------------------- | ------------------------------------------------------ | -------------------- |
+| `'public'`           | open: anyone may read and write                        | no                   |
+| `'authenticated'`    | login-restricted: every signed-in user                 | no                   |
+| `'owner'`            | per-user: only the uploader (plus ADMIN)               | no                   |
+| `'tenant'`           | per-tenant: only the own validated tenant (plus ADMIN) | no                   |
+| `'custom'` (default) | anything else — you write the rule                     | yes                  |
+
+`'owner'` and `'tenant'` read `metadata.ownerId` / `metadata.tenantId` and `CoreFileService` **stamps
+them as it writes** while the preset is active, so an upload through the service is authorizable without
+project code. Files written before you enabled it carry no such metadata and stay ADMIN-only — the
+fail-closed direction, fixable with a one-off backfill. Declaring the class never widens the role gate,
+and it never overrides an explicit `checkRights()` override: the override IS the rule.
+
+Everything the presets do is also the checklist for a hand-written rule, so read on either way.
+
+**Cover the `filterArgs` branch, and REFUSE it.** `findFileInfo()` consults the hook once for the whole
+query, so no answer can mean "…but only their own files". Returning `true` — which the reference rule
+used to do — hands a caller a full inventory of every upload: `CoreFileInfo` carries `filename`,
+`length`, `uploadDate` and the `id`, and for medical data the filename frequently IS the content. Core
+exposes no listing endpoint, so this only bites once a project surfaces `findFileInfo()`.
+
+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.
+
 **Never add `if (!options.currentUser) return true`.** It reads as "system-internal call, the guard
 already decided" — but "no user in context" is also exactly what an **anonymous** request looks like.
 While `downloadRoles` is narrower than `S_EVERYONE` the role gate turns those away first, so the