@lenne.tech/nest-server 11.34.0 → 11.35.0

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

package/src/core/modules/file/core-file.service.ts

@@ -10,9 +10,12 @@ import { GridFSHelper } from '../../common/helpers/gridfs.helper';
 import { check } from '../../common/helpers/input.helper';
 import { prepareOutput } from '../../common/helpers/service.helper';
 import { ConfigService } from '../../common/services/config.service';
+import { RequestContext } from '../../common/services/request-context.service';
 import { CoreS3Service } from '../../common/services/core-s3.service';
 import { MaybePromise } from '../../common/types/maybe-promise.type';
 import { CoreFileInfo } from './core-file-info.model';
+import { decideFileAccess, fileAccessNeedsRawDocument, resolveFileAccessPreset } from './file-access.helper';
+import { warnOnUndecidedFileAccess } from './file-roles.config';
 import { FileServiceOptions } from './interfaces/file-service-options.interface';
 import { FileUploadSource } from './interfaces/file-upload.interface';
 import {
@@ -83,6 +86,17 @@ export abstract class CoreFileService {
     this.storageResolution = resolveFileStorage(ConfigService.configFastButReadOnly);
     assertFileStorageAvailable(this.storageResolution, this.isStorageAvailable(this.storageResolution.driver));
     logFileStorage(this.storageResolution);
+
+    // Warn when the gate is open and nothing declares the per-file policy — see the helper for why
+    // the conditions are this narrow and why it is not gated on multi-tenancy. Checked here rather than in `CoreModule.forRoot()` because only
+    // an instance can answer whether `checkRights()` was overridden: the base implementation is a
+    // fixed function, so an identity comparison against it is exact and needs no naming convention.
+    const config = ConfigService.configFastButReadOnly;
+    warnOnUndecidedFileAccess({
+      fileConfig: config?.file,
+      hasPerFileRule: this.checkRights !== CoreFileService.prototype.checkRights,
+      multiTenancyEnabled: !!config?.multiTenancy && config.multiTenancy.enabled !== false,
+    });
   }
 
   /**
@@ -148,12 +162,16 @@ export abstract class CoreFileService {
     }
     const { createReadStream, filename, mimetype } = await file;
     const readStream = createReadStream();
+    // Resolved ONCE for all three driver branches: under an `'owner'` / `'tenant'` preset this adds
+    // the very fields the preset decides on, so an upload through this service is authorizable
+    // without any project code. Under the default preset it is `serviceOptions.metadata` verbatim.
+    const metadata = this.accessMetadata(serviceOptions);
     if (this.filesystemStorage) {
       const fsFileInfo = await FilesystemFileHelper.writeFile(this.filesystemDir, this.filesystemFiles, {
         body: readStream,
         contentType: mimetype,
         filename,
-        ...(serviceOptions?.metadata ? { metadata: serviceOptions.metadata } : {}),
+        ...(metadata ? { metadata } : {}),
       });
       return this.prepareOutput(fsFileInfo as unknown as CoreFileInfo, serviceOptions);
     }
@@ -165,14 +183,14 @@ export abstract class CoreFileService {
         buffer: await streamToBuffer(readStream),
         contentType: mimetype,
         filename,
-        ...(serviceOptions?.metadata ? { metadata: serviceOptions.metadata } : {}),
+        ...(metadata ? { metadata } : {}),
       });
       return this.prepareOutput(s3FileInfo as unknown as CoreFileInfo, serviceOptions);
     }
     const fileInfo = await GridFSHelper.writeFileFromStream(this.files, readStream, {
       contentType: mimetype,
       filename,
-      ...(serviceOptions?.metadata ? { metadata: serviceOptions.metadata } : {}),
+      ...(metadata ? { metadata } : {}),
     });
     return this.prepareOutput(fileInfo as unknown as CoreFileInfo, serviceOptions);
   }
@@ -537,6 +555,16 @@ export abstract class CoreFileService {
 
   /**
    * Get file stream (for big files) via filename
+   *
+   * Every branch resolves a DOCUMENT first and reads by its id — including the GridFS one, which
+   * used to fall through to `openDownloadStreamByName()`. That call defaults to `revision: -1` (the
+   * newest file of that name) while the by-name METADATA lookup answered the oldest, so with two
+   * files sharing a name this method streamed bytes belonging to a different document than the one
+   * `checkRights()` had just been asked about. An ownership rule then approved the caller's own file
+   * and handed over somebody else's — across tenants, since the file stores carry no tenant scope.
+   *
+   * `findFileByName()` is now newest-first in all three stores, so the bytes a caller receives are
+   * unchanged; what changed is that the document authorization inspected is the one being served.
    */
   async getFileStreamByName(filename: string, serviceOptions?: FileServiceOptions): Promise<Readable> {
     if (!(await this.checkRights(filename, { ...serviceOptions, checkInputType: 'filename' }))) {
@@ -550,7 +578,13 @@ export abstract class CoreFileService {
     if (fsFileInfo) {
       return FilesystemFileHelper.getStream(this.filesystemDir, fsFileInfo._id);
     }
-    return GridFSHelper.openDownloadStreamByName(this.files, filename);
+    const gridFsInfo = await GridFSHelper.findFileByName(this.files, filename);
+    if (!gridFsInfo) {
+      // Unchanged answer for an unknown name: GridFS is the terminal store and reports the miss
+      // itself, asynchronously on the stream, which the controller turns into a 404.
+      return GridFSHelper.openDownloadStreamByName(this.files, filename);
+    }
+    return GridFSHelper.openDownloadStream(this.files, gridFsInfo._id);
   }
 
   /**
@@ -584,7 +618,14 @@ export abstract class CoreFileService {
     if (fsFileInfo) {
       return FilesystemFileHelper.getBuffer(this.filesystemDir, fsFileInfo._id);
     }
-    return await GridFSHelper.readFileToBuffer(this.files, { filename });
+    // By id, for the same reason as getFileStreamByName(): reading by NAME here would pick the
+    // newest revision while checkRights() was asked about whichever document findFileByName()
+    // answered.
+    const gridFsInfo = await GridFSHelper.findFileByName(this.files, filename);
+    if (!gridFsInfo) {
+      return await GridFSHelper.readFileToBuffer(this.files, { filename });
+    }
+    return await GridFSHelper.readFileToBuffer(this.files, { _id: gridFsInfo._id });
   }
 
   /**
@@ -766,15 +807,43 @@ export abstract class CoreFileService {
    * `tests/file-ownership.e2e-spec.ts`. Prefer reading it there over copying
    * from here.
    *
+   * **Cover the `filterArgs` branch, and REFUSE it.** `findFileInfo()` consults this hook ONCE for the
+   * whole query, so there is no answer that means "…but only their own files". Returning `true` 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()` — which is exactly when
+   * nobody re-reads the rule.
+   *
+   * 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.**
+   *
    * @example
    * ```typescript
    * protected override async checkRights(
    *   input: any,
    *   options?: FileServiceOptions & { checkInputType: FileInputCheckType },
    * ): Promise<boolean> {
-   *   if (options?.force || (options?.checkInputType !== 'filename' && options?.checkInputType !== 'id')) {
+   *   // Writes stay on the coarse gate: an upload has no owner to compare against yet.
+   *   if (options?.force || options?.checkInputType === 'file' || options?.checkInputType === 'files') {
    *     return true;
    *   }
+   *   // A LISTING cannot be narrowed by a yes/no hook — it is asked once for the whole query, not
+   *   // once per row — so refuse the unrestricted one. See the note above.
+   *   if (options?.checkInputType === 'filterArgs') {
+   *     return false;
+   *   }
    *   if (options.currentUser?.hasRole?.([RoleEnum.ADMIN])) {
    *     return true;
    *   }
@@ -788,11 +857,99 @@ export abstract class CoreFileService {
    * }
    * ```
    */
+  /**
+   * The metadata a file is written with — the caller's, plus whatever the active preset decides on.
+   *
+   * A preset that only READ `metadata.ownerId` / `metadata.tenantId` would be a rule about data that
+   * does not exist: every file ADMIN-only. That is not hypothetical — it is exactly the shape TUS
+   * uploads had before 11.35.0, and the report came back from downstream rather than from a test.
+   *
+   * Three properties, each of which is a decision:
+   *
+   * - **Only under a preset that needs it.** With `file.access` unset (or `'public'` /
+   *   `'authenticated'`) this returns `serviceOptions.metadata` untouched, so no existing project's
+   *   documents grow a field.
+   * - **Never overrides what the caller supplied.** A project that records ownership itself — or
+   *   deliberately attributes a file to someone else, as an admin provisioning flow does — keeps
+   *   winning. `TUS_OWNER_METADATA_KEY` is the opposite case and overwrites on purpose, because there
+   *   the value arrives from the CLIENT.
+   * - **Stamps nothing it cannot know.** An anonymous upload gets no owner, which leaves the file
+   *   ADMIN-only rather than owned by `undefined`.
+   *
+   * `protected` so a project can add its own dimension (a project id, a case number) by overriding and
+   * calling `super`.
+   */
+  protected accessMetadata(serviceOptions?: FileServiceOptions): Record<string, any> | undefined {
+    const preset = resolveFileAccessPreset(ConfigService.configFastButReadOnly?.file);
+    if (preset !== 'owner' && preset !== 'tenant') {
+      return serviceOptions?.metadata;
+    }
+
+    const stamped: Record<string, any> = { ...serviceOptions?.metadata };
+    const ownerId = serviceOptions?.currentUser?.id;
+    if (stamped.ownerId === undefined && ownerId !== undefined && ownerId !== null && ownerId !== '') {
+      stamped.ownerId = String(ownerId);
+    }
+    if (preset === 'tenant') {
+      // The VALIDATED tenant, same source the read decision uses.
+      const tenantId = RequestContext.get()?.tenantId;
+      if (stamped.tenantId === undefined && tenantId) {
+        stamped.tenantId = tenantId;
+      }
+    }
+    return Object.keys(stamped).length ? stamped : undefined;
+  }
+
   protected checkRights(
-    _input: any,
-    _options?: FileServiceOptions & { checkInputType: FileInputCheckType },
+    input: any,
+    options?: FileServiceOptions & { checkInputType: FileInputCheckType },
   ): MaybePromise<boolean> {
-    return true;
+    // `MaybePromise<boolean>`, NOT `Promise<boolean>`, and not `async`. Narrowing the declared return
+    // type would break every consumer whose override returns a plain `boolean` — which the old
+    // signature explicitly invited — and TypeScript rejects that at the OVERRIDE, in their code, with
+    // an error that points at their file rather than at this change. `async` forces `Promise<T>`, so
+    // the async work lives in a separate method instead.
+    return this.resolveAccessPreset(input, options);
+  }
+
+  /**
+   * The async half of {@link checkRights}, split out only so the public seam can keep its
+   * `MaybePromise<boolean>` signature (see there).
+   */
+  private async resolveAccessPreset(
+    input: any,
+    options?: FileServiceOptions & { checkInputType: FileInputCheckType },
+  ): Promise<boolean> {
+    const preset = resolveFileAccessPreset(ConfigService.configFastButReadOnly?.file);
+
+    // `'custom'` is the default and returns true for every input — byte-for-byte the pre-11.35.0
+    // behaviour, including the absence of any lookup. An existing project sees no change at all.
+    if (preset === 'custom') {
+      return true;
+    }
+
+    // The lookup is skipped where the decision cannot use it: a forced (system) call, a write, a
+    // listing, and the two blanket presets. So enabling a preset never adds a query to a path that
+    // does not read a document — which matters most for `force: true`, the idiom internal callers use
+    // on hot paths precisely because they have already been decided about.
+    const raw =
+      !options?.force && fileAccessNeedsRawDocument(preset, options?.checkInputType)
+        ? options?.checkInputType === 'id'
+          ? await this.getRawFileInfo(input)
+          : await this.getRawFileInfoByName(input)
+        : undefined;
+
+    return decideFileAccess({
+      checkInputType: options?.checkInputType,
+      currentUser: options?.currentUser,
+      force: options?.force,
+      preset,
+      raw,
+      // The VALIDATED tenant, from the same source `mongooseTenantPlugin` filters by — never a raw
+      // header, and never `serviceOptions`, so a file decision and a database decision cannot
+      // disagree about which tenant the request is in.
+      tenantId: RequestContext.get()?.tenantId,
+    });
   }
 
   /**

package/src/core/modules/file/file-access.helper.ts

@@ -0,0 +1,149 @@
+/**
+ * The four project classes as ONE dial — `file.access`.
+ *
+ * WHY THIS EXISTS: 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. Until 11.35.0 the framework
+ * shipped that rule as an `@example` to copy, and the copy went wrong twice in this repository's own
+ * history — both times in the permissive direction:
+ *
+ *  - `if (!options.currentUser) return true` reads as "system-internal call", and is also exactly what
+ *    an ANONYMOUS request looks like;
+ *  - narrowing only `'id'` / `'filename'` waves `'filterArgs'` through, which hands over a full
+ *    inventory of every upload the moment a project surfaces `findFileInfo()`.
+ *
+ * Neither mistake is careless — both read as correct. That is the argument for a preset: the rule is
+ * always the same handful of sentences, so the framework should own them and the project should
+ * declare which one it wants.
+ *
+ * | `file.access`     | project class                                                  |
+ * |-------------------|----------------------------------------------------------------|
+ * | `'custom'`        | the project writes its own rule — **the default**; the framework abstains entirely |
+ * | `'public'`        | open: anyone may read and write, the role gate is the whole policy |
+ * | `'authenticated'` | login-restricted: every signed-in user may use every file       |
+ * | `'owner'`         | per-user: only the uploader (plus ADMIN)                        |
+ * | `'tenant'`        | per-tenant: only within one's own validated tenant (plus ADMIN) |
+ *
+ * NOTHING CHANGES FOR AN EXISTING PROJECT. `'custom'` is the default and returns `true` for every
+ * input, which is byte-for-byte what `CoreFileService.checkRights()` did before. A project that
+ * overrides `checkRights()` keeps full control regardless of the setting — the override IS the rule,
+ * and the preset never runs.
+ *
+ * THE DECISION IS A PURE FUNCTION. It takes an already-loaded raw document instead of a service, so
+ * every row of the table can be stated in a unit test without a database, and so the service's only
+ * remaining job is to decide whether a lookup is needed at all
+ * ({@link fileAccessNeedsRawDocument}) — a listing and a write never need one.
+ *
+ * DELIBERATELY A LEAF: it imports the role enum and nothing else. `file-roles.helper` already had to
+ * be split for the same reason (it imports the endpoint classes, which inject `CoreFileService`), and
+ * this file is read FROM the service. See `.claude/rules/architecture.md` → "DI Token Placement".
+ */
+import { RoleEnum } from '../../common/enums/role.enum';
+
+/** Which of the four project classes this deployment is. */
+export type FileAccessPreset = 'authenticated' | 'custom' | 'owner' | 'public' | 'tenant';
+
+/** The input types `CoreFileService.checkRights()` distinguishes. */
+type CheckInputType = 'file' | 'filename' | 'files' | 'filterArgs' | 'id';
+
+const PRESETS: readonly FileAccessPreset[] = ['authenticated', 'custom', 'owner', 'public', 'tenant'] as const;
+
+/**
+ * Which preset a project asked for.
+ *
+ * An UNKNOWN value resolves to `'owner'`, the strictest of the data-driven presets — never to
+ * `'custom'`. A typo (`access: 'onwer'`) means somebody believes they have an ownership rule; giving
+ * them "the framework abstains" would confirm that belief and be wrong in the one direction that
+ * cannot be noticed from the outside. A too-strict answer surfaces as a 404 on the first request,
+ * which is a bug report; a too-permissive one surfaces as an incident.
+ *
+ * @default 'custom'
+ */
+export function resolveFileAccessPreset(fileConfig?: { access?: FileAccessPreset }): FileAccessPreset {
+  const configured = fileConfig?.access;
+  if (configured === undefined || configured === null) {
+    return 'custom';
+  }
+  return PRESETS.includes(configured) ? configured : 'owner';
+}
+
+/**
+ * Does the decision for this (preset, input type) pair read the stored document?
+ *
+ * Asked by the service so it can skip the metadata lookup where the answer cannot use it. A write has
+ * no document yet, a listing is not about one document, and the two blanket presets answer without
+ * looking — loading anyway would add a query per call for nothing.
+ */
+export function fileAccessNeedsRawDocument(preset: FileAccessPreset, checkInputType?: CheckInputType): boolean {
+  if (preset !== 'owner' && preset !== 'tenant') {
+    return false;
+  }
+  return checkInputType === 'id' || checkInputType === 'filename';
+}
+
+/**
+ * Decide one file access question.
+ *
+ * @param options.raw the stored metadata document, loaded by the caller when
+ *   {@link fileAccessNeedsRawDocument} says so. `null` means "no such file", which must not be
+ *   confused with "no restriction".
+ * @param options.tenantId the VALIDATED tenant of the current request (`RequestContext.tenantId`),
+ *   never a raw header — an unvalidated header would be worse than no tenant at all.
+ */
+export function decideFileAccess(options: {
+  checkInputType?: CheckInputType;
+  currentUser?: { hasRole?: (roles: string[]) => boolean; id?: any };
+  force?: boolean;
+  preset: FileAccessPreset;
+  raw?: null | Record<string, any>;
+  tenantId?: string;
+}): boolean {
+  const { checkInputType, currentUser, force, preset, raw, tenantId } = options;
+
+  // A system caller says so explicitly. This is the documented alternative to the
+  // `if (!currentUser) return true` shortcut: the exemption is stated at the call site, in the diff,
+  // rather than inferred from an absence that an anonymous request produces too.
+  if (force) {
+    return true;
+  }
+
+  // The framework abstains — identical to the pre-11.35.0 base implementation.
+  if (preset === 'custom' || preset === 'public') {
+    return true;
+  }
+
+  if (preset === 'authenticated') {
+    // Deliberately independent of the role gate: it still holds when `downloadRoles` is `S_EVERYONE`,
+    // which is the case where a project believes the login requirement is somewhere else.
+    return !!currentUser?.id;
+  }
+
+  // ADMIN is platform authority and is never locked out — the same union the role guards apply.
+  if (currentUser?.hasRole?.([RoleEnum.ADMIN])) {
+    return true;
+  }
+
+  // Writes stay on the coarse role gate (`file.uploadRoles` / `deleteRoles`): an upload has no stored
+  // document yet, so there is nothing to compare against. Ownership of the RESULT is established by
+  // the metadata the service stamps as it writes.
+  if (checkInputType === 'file' || checkInputType === 'files') {
+    return true;
+  }
+
+  // A LISTING cannot be narrowed by a yes/no answer — this hook is asked once for the whole query,
+  // not once per row. Refusing is the only honest answer; a per-user listing is expressed by forcing
+  // the filter server-side and passing `force: true`. See CoreFileService.checkRights().
+  if (checkInputType === 'filterArgs') {
+    return false;
+  }
+
+  if (preset === 'owner') {
+    // Requiring the field to be PRESENT is load-bearing twice over: without it an owner-less file
+    // compares `String(undefined)` with `String(undefined)` and matches, so every unowned file would
+    // be readable by every caller whose id is also missing — i.e. by anonymous requests.
+    return !!raw?.metadata?.ownerId && String(raw.metadata.ownerId) === String(currentUser?.id);
+  }
+
+  // 'tenant': both sides must be present. No tenant in context is a cron job on the HTTP path and an
+  // unresolvable header on the WebSocket path; neither may read tenant-scoped bytes.
+  return !!tenantId && !!raw?.metadata?.tenantId && String(raw.metadata.tenantId) === String(tenantId);
+}

package/src/core/modules/file/file-metadata.helper.ts

@@ -74,17 +74,25 @@ export async function findMetadataById(
 }
 
 /**
- * Find one metadata document by filename.
+ * Find one metadata document by filename — the MOST RECENT file with that name.
  *
- * Resolves the FIRST match — filenames are not unique in any of these stores, and
- * are client-supplied on both the multer and the tus path. Prefer the id lookup
- * wherever the caller has an id.
+ * 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 lookup wherever the caller has an id.
+ * What must not be ambiguous is WHICH of the candidates every by-name path picks — an ownership
+ * rule reads one document and the download must serve that same one.
+ *
+ * A bare `findOne({ filename })` returns natural order, which is neither documented nor stable
+ * under compaction. Newest-first matches GridFS's own by-name revision semantics
+ * (`openDownloadStreamByName` defaults to `revision: -1`), so all three storage drivers answer the
+ * same question the same way; `_id` breaks the tie for two files written in one millisecond.
  */
 export async function findMetadataByName(
   collection: FileCollection,
   filename: string,
 ): Promise<FileMetadataInfo | null> {
-  return (await collection.findOne({ filename })) as FileMetadataInfo | null;
+  // `uploadDate` FIRST — MongoDB applies sort keys in document order, so leading with `_id` would
+  // make the tie-break the primary key.
+  return (await collection.findOne({ filename }, { sort: { uploadDate: -1, _id: -1 } })) as FileMetadataInfo | null;
 }
 
 /** Find metadata documents by filter */