@lenne.tech/nest-server 11.32.4 → 11.33.1

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

@@ -4,14 +4,291 @@ File upload and download functionality with MongoDB GridFS storage.
 
 ## Endpoints
 
-### Public Endpoints (via CoreFileController)
+### Download Endpoints (via CoreFileController)
 
-| Method | Endpoint           | Description               |
-| ------ | ------------------ | ------------------------- |
-| GET    | `/files/id/:id`    | Download file by ID       |
-| GET    | `/files/:filename` | Download file by filename |
+| Method | Endpoint           | Description               | Gated by        |
+| ------ | ------------------ | ------------------------- | --------------- |
+| GET    | `/files/id/:id`    | Download file by ID       | `downloadRoles` |
+| GET    | `/files/:filename` | Download file by filename | `downloadRoles` |
 
-**Note:** These endpoints are public (`S_EVERYONE`) by default. Projects can restrict access by extending `CoreFileController`.
+### GraphQL members (via CoreFileResolver)
+
+| Member        | Kind     | Gated by        |
+| ------------- | -------- | --------------- |
+| `getFileInfo` | Query    | `downloadRoles` |
+| `uploadFile`  | Mutation | `uploadRoles`   |
+| `uploadFiles` | Mutation | `uploadRoles`   |
+| `deleteFile`  | Mutation | `deleteRoles`   |
+
+> `CoreFileResolver` is registered by no core module. It only takes effect in a project that
+> registers it (or a subclass) itself — enabling GraphQL alone does not.
+
+---
+
+## Configuration
+
+One `file` object configures the module — where the bytes live and who may reach them:
+
+```typescript
+file: {
+  storage: 'gridfs',                 // 'filesystem' | 'gridfs' | 's3' — omit to derive it
+  storageDir: 'uploads/files',       // only for 'filesystem'
+  downloadRoles: [RoleEnum.ADMIN],   // GET /files/id/:id, GET /files/:filename, getFileInfo
+  uploadRoles:   [RoleEnum.ADMIN],   // uploadFile, uploadFiles
+  deleteRoles:   [RoleEnum.ADMIN],   // deleteFile
+},
+```
+
+`storage` and the role knobs are orthogonal: one picks the driver, the others the access.
+
+## Storage drivers
+
+Three equivalent options. They differ only in where the bytes end up:
+
+| Driver         | Bytes                     | Survives a restart       | Shared between replicas | Needs                              |
+| -------------- | ------------------------- | ------------------------ | ----------------------- | ---------------------------------- |
+| `'s3'`         | S3-compatible bucket      | yes                      | **yes**                 | `s3` config + `@aws-sdk/client-s3` |
+| `'gridfs'`     | MongoDB GridFS            | yes                      | yes                     | nothing beyond the database        |
+| `'filesystem'` | local disk (`storageDir`) | only on a mounted volume | **no**                  | nothing                            |
+
+**Metadata always lives in the database**, whichever driver holds the bytes. Filename, content type,
+length and the custom `metadata` a per-file rule reads have to be queryable — `findFileInfo()` filters
+and pages over them, `checkRights()` reads them per request. A directory listing answers none of
+that, and sidecar files would reinvent an index the database already is. So `'filesystem'` moves the
+bytes off the database, not the bookkeeping.
+
+### Choosing the driver
+
+**Set it explicitly and it is enforced.** If the chosen store is not available, the boot **fails**:
+
+```
+file.storage is set to 's3', but that storage is not available.
+Configure `s3` (bucket, credentials/endpoint) and install `@aws-sdk/client-s3`, …
+```
+
+That is deliberate. The previous behaviour fell back to GridFS whenever S3 was selected but
+unusable — the application kept working, so nothing looked broken, while files landed in a store the
+operator did not believe they were in. Afterwards nobody can tell which file went where.
+
+**Leave it unset and it is derived**, most capable first:
+
+1. `'s3'` — when `s3.bucket` is configured
+2. `'gridfs'` — when a database is configured
+3. `'filesystem'` — when neither is
+
+A configured-but-**unreachable** database is an error in its own right (Mongoose fails the boot), never
+a reason to fall through to the disk. Only a database that is not configured **at all** reaches step 3 —
+which today is theoretical, since `CoreModule` always registers Mongoose.
+
+A derived driver is enforced too: `s3.bucket` in the config makes S3 the default, but the bytes still
+go nowhere unless your `FileService` forwards the services to `super()`:
+
+```typescript
+super(connection, 'fs', { configService, s3Service });
+```
+
+### Switching drivers is forward-only
+
+Reads consult **every** store, so files written under a previous driver stay readable and there is no
+migration step and no cut-over moment. New files go to the active driver; `findFileInfo()` returns
+the union, paged once over the merged result.
+
+The boot log names the driver in use, so it never has to be inferred from where files stopped
+appearing:
+
+```
+[CoreFileStorage] File storage: s3 (defaulted — s3.bucket is configured)
+```
+
+---
+
+## Access control
+
+Two layers, and they answer different questions.
+
+### 1. Roles — _may this caller reach the endpoint at all?_
+
+All three role knobs take **plain role strings**, so your own project roles work exactly as they
+would in a hand-written `@Roles()`.
+
+All three default to `[ADMIN]`. That default is restrictive on purpose: the file store is a **single
+bucket shared by every feature** of the project — GridFS or S3, whichever `file.storage` selects —
+and the ids naming its blobs are not secrets. An id is an ObjectId (4-byte timestamp, 5-byte
+per-process random, 3-byte counter), so one upload of your own discloses the per-process value in
+full and bounds the counter, collapsing the id space to a brute-forceable range. `/files/:filename`
+is weaker still: it resolves the **first** match for a name a caller may be able to guess.
+
+Three properties worth knowing:
+
+- **ADMIN always keeps access.** Handler and class roles are UNIONed (`mergeRolesMetadata`), and both
+  classes carry a class-level `@Roles(ADMIN)`. So `downloadRoles: ['editor']` grants editors _in
+  addition to_ admins. These knobs cannot exclude admins.
+- **`[]` is rejected, not honoured.** An all-empty role set reads to the guards as "no roles
+  required" and would OPEN the route. An empty array logs a warning and falls back to the default.
+- **Roles are checked against `user.roles`, never `membership.role`.** Both classes carry
+  `@SkipTenantCheck()`. No store is reached through Mongoose — GridFS goes through the native driver,
+  the S3 and filesystem metadata live in their own `s3-files` / `filesystem-files` collections — so
+  `mongooseTenantPlugin` never scopes them. None is tenant-scoped, and a role name alone therefore
+  cannot express a per-tenant rule. Use layer 2 for that.
+
+### 2. `checkRights()` — _may this caller have THIS file?_
+
+Roles cannot express "…but only their own". That is what the service hook is for:
+
+```typescript
+export class FileService extends CoreFileService {
+  protected override async checkRights(
+    input: any,
+    options?: FileServiceOptions & { checkInputType: FileInputCheckType },
+  ): Promise<boolean> {
+    // Writes, list queries and forced (system) calls stay on the coarse role gate
+    if (options?.force || (options?.checkInputType !== 'filename' && options?.checkInputType !== 'id')) {
+      return true;
+    }
+    if (options.currentUser?.hasRole?.([RoleEnum.ADMIN])) {
+      return true;
+    }
+    const raw =
+      options.checkInputType === 'id' ? await this.getRawFileInfo(input) : await this.getRawFileInfoByName(input);
+    // Fails closed without a user, and on a file that records no owner.
+    return !!raw?.metadata?.ownerId && String(raw.metadata.ownerId) === String(options.currentUser?.id);
+  }
+}
+```
+
+This is not a sketch: it is the rule `src/server/modules/file/file.service.ts` runs, with
+`file: { downloadRoles: [RoleEnum.S_USER] }` in `src/config.env.ts` so the coarse gate actually
+lets it fire. It used to live here and in that file as a **comment**, on the reasoning that the
+`[ADMIN]` default made it unreachable in the reference server anyway — and a commented rule is never
+compiled, never type-checked and never run. That is how a `deleteFileByName()` regression on the
+`filename` branch shipped through a full green suite.
+
+**Cover the `filename` branch too, not just `id`.** An id-only rule is enough while bytes are
+streamed, because the filename route resolves an id and checks it again — but not once
+`file.storage: 's3'` with presigned downloads is enabled, where the filename route authorizes on the
+by-name lookup alone and then redirects, and not for `deleteFileByName()`, which authorizes by name
+only.
+
+**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
+branch looks harmless; widen the gate, which this very section invites you to do, and it hands every
+file to everyone. The ownership rule evaporates precisely when it starts to matter. The same reason
+makes `!!raw?.metadata?.ownerId` load-bearing: without it, an owner-less file compares
+`String(undefined)` against `String(undefined)` and matches.
+
+Callers that really are internal should say so instead of relying on the omission — `{ force: true }`
+where a role decorator already decided (an `@Roles(ADMIN)` admin endpoint), or the real
+`{ currentUser }` where the user is in scope, so that call is **covered** by the ownership rule
+rather than exempt from it. The reference server does both: `src/server/modules/file/` and
+`src/server/modules/user/avatar.controller.ts`. The contract test for the whole rule, covering the
+`id` **and** the `filename` branch, lives in `tests/file-ownership.e2e-spec.ts`.
+
+Three pieces make this work, and all three are needed:
+
+1. **Write the metadata at upload time** — `createFile(file, { metadata: { ownerId: user.id } })`.
+   `CoreFileService.createFile()` passes `serviceOptions.metadata` straight to the storage driver,
+   so it works for both GridFS and S3.
+2. **Read it back with `getRawFileInfo()`** (or `getRawFileInfoByName()`), not `getFileInfo()`. The
+   public getter runs `prepareOutput` → `check()`, which strips fields the caller may not see —
+   including the very field the decision rests on. `getRawFileInfo()` consults every metadata store
+   in the same order `getFileInfo()` uses, so a rule sees the file the download would actually
+   serve — under any driver.
+3. **`options.currentUser` is supplied by the core controller and resolver** for every member.
+
+When `checkRights()` refuses, `getFileStream()` returns `null` and the controller answers **404** —
+deliberately the same answer as an unknown id, so the endpoint cannot be used to probe which files
+exist. Do not turn that into a 403 in an override without accepting that trade-off.
+
+### Serving files to a browser `<img>` / `<a download>`
+
+A markup-driven request cannot send an `Authorization` header, and a CORS preflight sends no
+credentials at all. So anything stricter than `S_EVERYONE` only works from markup when the session
+travels as a **cookie** on a same-site request.
+
+If some files are genuinely public and others are not, the answer is not a role list — it is a
+per-file rule. Record a visibility flag in the metadata at upload time and branch on it in
+`checkRights()`, or expose a separate public route for exactly the files that are meant to be
+public and leave these two gated.
+
+**Presigned S3 downloads** (`file.storage: 's3'` with presigned downloads enabled) sidestep the
+`<img>` problem, because the browser fetches the object directly from S3. Understand what you are
+issuing, though: the URL is a **bearer capability** — anyone holding it can fetch the object until
+it expires, with no session. Authorization happens once, when the URL is issued (through the
+`resolveFile()` call that precedes the redirect on `GET /files/id/:id`, and the
+`getFileInfoByName()` call on `GET /files/:filename`; both run the same `checkRights()`). Keep the
+expiry short, and do not enable it for files whose audience is narrower than "anyone who was ever
+given the link".
+
+### Overriding: read this before you re-declare a member
+
+`CoreFileController` and `CoreFileResolver` are meant to be extended — but role metadata lives on
+the **function object**, so an override carries its own and thereby **opts out of `file.*Roles`
+entirely**. Two consequences that bite in practice:
+
+```typescript
+// WRONG — the route DISAPPEARS. Nest reads PATH_METADATA off the subclass
+// function, which has none, so it is never registered: 404 for everyone,
+// no error, no warning.
+override async getFileById(@Param('id') id: string, @Res() res: Response) {
+  return super.getFileById(id, res);
+}
+
+// WRONG — pins the policy and silently ignores `file.downloadRoles` forever.
+// This exact shape kept generated projects public after the framework default
+// had already been closed.
+@Get('id/:id')
+@Roles(RoleEnum.S_EVERYONE)
+override async getFileById(@Param('id') id: string, @Res() res: Response) {
+  return super.getFileById(id, res);
+}
+
+// RIGHT — don't override at all. Configure it:
+//   file: { downloadRoles: [RoleEnum.S_USER] }
+// and put per-file rules in checkRights().
+```
+
+A class-level `@Roles()` on your subclass cannot relax an inherited member either: the inherited
+function carries its own handler-level roles, and the two are unioned rather than overridden.
+
+### If you override `getFileInfo()`: `GET /files/id/:id` no longer calls it (11.33.0)
+
+Up to 11.32.x, `GET /files/id/:id` called the public `CoreFileService.getFileInfo()` and then let
+`getFileStream()` work out on its own which store held the bytes. With three stores to consult
+(§ Storage drivers) that resolves the same id up to three times per download, so since 11.33.0 the
+route calls **`resolveFile()`** instead, which answers the metadata and the store in one pass.
+
+An override of `getFileInfo()` is therefore **no longer on that route's path**. It is still honoured
+by every other caller it ever had — `deleteFile()`, `duplicateById()` and any project code that
+calls it, such as the `GET /files/info/:id` endpoint projects usually add — which is exactly what
+makes the gap easy to miss: the behaviour disappears on one route while everything else keeps it.
+(The GraphQL `getFileInfo(filename:)` member resolves by NAME and has always gone through
+`getFileInfoByName()`, so it is unaffected either way.)
+
+This does **not** weaken authorization. `resolveFile()` runs the same `checkRights()` with the same
+`serviceOptions`, and answers `null` on refusal, which the controller turns into the same 404. Only
+work you added **on top** of the base `getFileInfo()` — a decorated field, a counter, a log line —
+stops happening on the id route.
+
+The remedy is to override `resolveFile()` as well, keeping the two consistent:
+
+```typescript
+export class FileService extends CoreFileService {
+  override async getFileInfo(id: string | Types.ObjectId, serviceOptions?: FileServiceOptions) {
+    return this.decorate(await super.getFileInfo(id, serviceOptions));
+  }
+
+  // Same treatment for the download route. `store` must be passed through
+  // untouched — the controller hands it to getFileStream() to pick the store.
+  override async resolveFile(id: string | Types.ObjectId, serviceOptions?: FileServiceOptions) {
+    const resolved = await super.resolveFile(id, serviceOptions);
+    return resolved && { ...resolved, info: this.decorate(resolved.info) };
+  }
+}
+```
+
+Per-file **authorization** needs none of this: it belongs in `checkRights()`, which both methods
+call.
 
 ### Admin Endpoints (project-specific)
 
@@ -46,39 +323,6 @@ export class FileController extends CoreFileController {
 }
 ```
 
-### Restrict Download Access
-
-To require authentication for downloads, override the inherited methods:
-
-```typescript
-@Controller('files')
-@Roles(RoleEnum.ADMIN)
-export class FileController extends CoreFileController {
-  constructor(protected override readonly fileService: FileService) {
-    super(fileService);
-  }
-
-  // Override to require authentication for ID-based download
-  @Get('id/:id')
-  @Roles(RoleEnum.S_USER) // Require logged-in user
-  override async getFileById(@Param('id') id: string, @Res() res: Response) {
-    return super.getFileById(id, res);
-  }
-
-  // Override to require authentication for filename-based download
-  @Get(':filename')
-  @Roles(RoleEnum.S_USER)
-  override async getFile(@Param('filename') filename: string, @Res() res: Response) {
-    return super.getFile(filename, res);
-  }
-}
-```
-
-Access can also be restricted per file by overriding `CoreFileService.checkRights()`. When it
-refuses, `getFileStream()` returns `null` and the controller answers **404** — deliberately the same
-answer as an unknown id, so the endpoint cannot be used to probe which files exist. Do not change
-this to a 403 in an override without accepting that trade-off.
-
 ### Error responses
 
 | Situation                                                                              | Status | Body                                                                                                  |
@@ -137,12 +381,13 @@ multerFileFilter({ extensions: ['.svg'], mimeTypes: ['image/svg+xml'] }, { allow
 
 ## GraphQL Support
 
-File operations are also available via GraphQL through `CoreFileResolver`:
+File operations are also available via GraphQL through `CoreFileResolver` — in a project that
+registers it. See [Access control](#access-control) for which knob gates which member.
 
 ```graphql
-# Query file by ID
+# Read file info by filename (downloadRoles)
 query {
-  file(id: "...") {
+  getFileInfo(filename: "...") {
     id
     filename
     contentType
@@ -150,24 +395,23 @@ query {
   }
 }
 
-# Query file by filename
-query {
-  fileByFilename(filename: "...") {
+# Upload a file via the GraphQL Upload scalar (uploadRoles)
+mutation {
+  uploadFile(file: Upload!) {
     id
     filename
-    contentType
   }
 }
 
-# Upload file (via GraphQL Upload scalar)
+# Upload several files (uploadRoles)
 mutation {
-  uploadFile(file: Upload!) {
+  uploadFiles(files: [Upload!]!) {
     id
     filename
   }
 }
 
-# Delete file
+# Delete by filename (deleteRoles)
 mutation {
   deleteFile(filename: "...") {
     id
@@ -175,21 +419,32 @@ mutation {
 }
 ```
 
+> Earlier revisions of this file documented `file(id:)` and `fileByFilename(filename:)`. Neither has
+> ever existed on `CoreFileResolver`; the query is `getFileInfo(filename:)`.
+
 ---
 
 ## Integration with TUS
 
-Files uploaded via TUS are automatically stored in GridFS and can be accessed through the same endpoints:
+Files uploaded via TUS land in the same GridFS bucket and are read back through the same endpoints —
+which means the same `downloadRoles` gate applies:
 
 ```bash
-# After TUS upload completes, download by ID
+# After the TUS upload completes, download by ID (requires downloadRoles)
 GET /files/id/<gridfs-file-id>
 
-# Or by filename (if unique)
+# Or by filename, if unique (requires downloadRoles)
 GET /files/<original-filename>
 ```
 
-**Recommendation:** Use ID-based downloads for TUS uploads as filenames may not be unique.
+**Recommendation:** use ID-based downloads for TUS uploads, since filenames may not be unique.
+
+**Watch the pairing.** TUS uploads are gated separately by `tus.roles` (default `S_USER`). The
+common "user uploads their own file, then views it" flow therefore needs both sides to line up: a
+signed-in user may upload, but with the default `downloadRoles: [ADMIN]` they cannot read the result
+back. Either widen `downloadRoles`, or — better — write an owner into the metadata at upload time
+and authorize per file in `checkRights()`. TUS uploads already carry `metadata.tusUploadId` and the
+original TUS metadata, so there is a natural place to add one.
 
 ---
 

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

@@ -2,10 +2,14 @@ import { BadRequestException, Controller, Get, Logger, NotFoundException, Param,
 import type { Response } from 'express';
 import type { Readable } from 'stream';
 
+import { CurrentUser } from '../../common/decorators/current-user.decorator';
 import { Roles } from '../../common/decorators/roles.decorator';
 import { RoleEnum } from '../../common/enums/role.enum';
+import { buildContentDisposition } from '../../common/helpers/content-disposition.helper';
 import { ErrorCode } from '../error-code/error-codes';
+import { SkipTenantCheck } from '../tenant/core-tenant.decorators';
 import { CoreFileService } from './core-file.service';
+import type { FileServiceOptions } from './interfaces/file-service-options.interface';
 
 const fileStreamLogger = new Logger('CoreFileController');
 
@@ -24,6 +28,16 @@ const fileStreamLogger = new Logger('CoreFileController');
  */
 const FILE_DELIVERY_HEADERS = ['Cache-Control', 'Content-Disposition', 'Content-Type', 'ETag'];
 
+/**
+ * Re-exported from the leaf it now lives in, so no import path broke.
+ *
+ * It moved because the S3 presigned-URL branch in `src/core/common/services/` needs the SAME
+ * value, and `src/core/common/**` must not import from `src/core/modules/**`. While the two
+ * rendered it separately, the same file downloaded under a different name depending on whether
+ * `s3.presignedDownloads` was on.
+ */
+export { buildContentDisposition };
+
 /**
  * Pipe a GridFS download to the response without letting a read error kill the socket.
  *
@@ -79,9 +93,24 @@ export function pipeFileToResponse(stream: Readable, res: Response): Response {
 
 /**
  * File controller
+ *
+ * TENANT SCOPING: the class carries `@SkipTenantCheck()`, so the roles below are
+ * checked against `user.roles` and never against `membership.role`.
+ *
+ * That is not a convenience — it is required for the gate to mean what it says.
+ * GridFS is reached through the NATIVE MongoDB driver, so `mongooseTenantPlugin`
+ * never runs on `fs.files`: one bucket holds every tenant's blobs, unscoped.
+ * Without this decorator and with `multiTenancy` active, a role string like
+ * `'admin'` would be satisfied by any member whose MEMBERSHIP role is `admin` —
+ * a workspace admin of tenant A could then read tenant B's files.
+ *
+ * A genuinely tenant-aware policy therefore cannot be expressed by a role name.
+ * Write `tenantId` into the file metadata at upload time and compare it in an
+ * overridden `CoreFileService.checkRights()`.
  */
 @Controller('files')
 @Roles(RoleEnum.ADMIN)
+@SkipTenantCheck()
 export abstract class CoreFileController {
   /**
    * Include services
@@ -100,31 +129,101 @@ export abstract class CoreFileController {
     return pipeFileToResponse(stream, res);
   }
 
+  /**
+   * Presigned S3 URL for a download, or undefined to stream through the API.
+   *
+   * Deliberately fail-soft. A presigned URL is an OPTIMIZATION — it offloads bytes
+   * from the API — so nothing about it may cost the caller their download: a
+   * missing `@aws-sdk/s3-request-presigner`, an S3 outage or a project service
+   * predating this method must all fall through to the streaming path, which
+   * still runs the same rights check and answers a refusal exactly like an
+   * unknown id. Turning any of those into a 500 would also leak that the file
+   * exists, which the streaming path takes care never to do.
+   */
+  protected async resolveDownloadUrl(id: string, serviceOptions?: FileServiceOptions): Promise<string | undefined> {
+    try {
+      // `serviceOptions` carries the current user into the service's own rights
+      // check. Omitting it made this second check run with `currentUser:
+      // undefined`: for the ownership rule documented in the README that fails
+      // CLOSED, so presigned downloads silently never fired — not even for
+      // admins, since `currentUser?.hasRole(...)` was undefined too. For an
+      // override that reads a missing user as "system-internal, allow" it was a
+      // no-op instead. Neither is what the path that mints a session-less
+      // capability should be doing.
+      return await this.fileService.getDownloadUrl?.(id, serviceOptions);
+    } catch (error) {
+      fileStreamLogger.warn(
+        `Presigned download URL unavailable, falling back to streaming: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+      return undefined;
+    }
+  }
+
   /**
    * Download file by ID
    *
    * More reliable than filename-based download as IDs are unique.
    * Recommended for TUS uploads and when filename uniqueness cannot be guaranteed.
+   *
+   * SECURITY: gated by `file.downloadRoles` (default `[ADMIN]`). The decorator
+   * below is the fallback — `CoreModule.forRoot()` rewrites it from config.
+   * See `src/core/modules/file/README.md` § Access control for the full model
+   * and the 11.32.4 → 11.33.0 migration guide for why the default changed.
    */
   @Get('id/:id')
-  @Roles(RoleEnum.S_EVERYONE)
-  async getFileById(@Param('id') id: string, @Res() res: Response) {
+  @Roles(RoleEnum.ADMIN)
+  async getFileById(
+    @Param('id') id: string,
+    @Res() res: Response,
+    @CurrentUser() currentUser?: any,
+  ): Promise<Response> {
     if (!id) {
       throw new BadRequestException(ErrorCode.REQUIRED_FIELD_MISSING);
     }
 
-    const file = await this.fileService.getFileInfo(id);
+    const serviceOptions = { currentUser };
+    // One lookup for both answers — metadata AND which store holds the bytes.
+    // getFileInfo() followed by getFileStream() had each probe the three stores
+    // from scratch, since neither told the other which one had answered. Same
+    // rights check, same 404-on-refusal.
+    const resolved = await this.fileService.resolveFile(id, serviceOptions);
+    const file = resolved?.info;
     if (!file) {
       throw new NotFoundException(ErrorCode.FILE_NOT_FOUND);
     }
-    const filestream = await this.fileService.getFileStream(id);
+    // S3-stored file with presigned downloads enabled: let the client fetch the
+    // bytes from S3 directly instead of streaming them through the API.
+    //
+    // AUTHORIZATION on this branch rests entirely on the `resolveFile()` call
+    // above, which runs the very same `checkRights()` `getFileInfo()` did and
+    // answers null on refusal, so the throw above turns it into a 404 —
+    // `getFileStream()` is never reached here. Keep that call before this
+    // block. Note also that the issued URL is a bearer capability: anyone
+    // holding it can fetch the object until it expires, without a session. Keep
+    // the expiry short, and do not enable presigned downloads for files whose
+    // audience is narrower than "anyone who was once allowed to see the link".
+    // Only S3-stored bytes can be handed over as a presigned URL, and `resolveFile`
+    // already established the store — so a GridFS or filesystem download no longer
+    // pays a pointless S3 metadata lookup to find that out.
+    const url = resolved.store === 's3' ? await this.resolveDownloadUrl(id, serviceOptions) : undefined;
+    if (url) {
+      this.setNoStore(res);
+      // `res.redirect()` is typed `void`, so returning it directly widened this method's inferred
+      // return type to `Promise<void | Response>` — a source-invisible BREAKING change for every
+      // project that overrides `getFileById`/`getFile` with an explicit `Promise<Response>` and
+      // delegates to super. Nest ignores the returned value once `@Res()` is used, so returning
+      // `res` is equivalent and keeps the published contract intact. The explicit annotation on
+      // both methods pins it, so inference can never silently widen it again.
+      res.redirect(302, url);
+      return res;
+    }
+    const filestream = await this.fileService.getFileStream(id, serviceOptions, resolved.store);
     // `getFileStream` answers null when the service's own rights check refuses.
     // Same answer as an unknown id: never confirm that the file exists.
     if (!filestream) {
       throw new NotFoundException(ErrorCode.FILE_NOT_FOUND);
     }
-    res.header('Content-Type', file.contentType || 'application/octet-stream');
-    res.header('Content-Disposition', `attachment; filename=${file.filename}`);
+    this.setFileHeaders(res, file);
     return this.pipeFileToResponse(filestream, res);
   }
 
@@ -133,24 +232,81 @@ export abstract class CoreFileController {
    *
    * Note: If multiple files have the same filename, only the first match is returned.
    * For unique file access, use GET /files/id/:id instead.
+   *
+   * SECURITY: gated by `file.downloadRoles` — see `getFileById()`. Prefer the
+   * id route when widening: this one resolves the FIRST match for a name a
+   * caller may be able to guess, so it leaks across files that share a name.
    */
   @Get(':filename')
-  @Roles(RoleEnum.S_EVERYONE)
-  async getFile(@Param('filename') filename: string, @Res() res: Response) {
+  @Roles(RoleEnum.ADMIN)
+  async getFile(
+    @Param('filename') filename: string,
+    @Res() res: Response,
+    @CurrentUser() currentUser?: any,
+  ): Promise<Response> {
     if (!filename) {
       throw new BadRequestException(ErrorCode.REQUIRED_FIELD_MISSING);
     }
 
-    const file = await this.fileService.getFileInfoByName(filename);
+    const serviceOptions = { currentUser };
+    const file = await this.fileService.getFileInfoByName(filename, serviceOptions);
     if (!file) {
       throw new NotFoundException(ErrorCode.FILE_NOT_FOUND);
     }
-    const filestream = await this.fileService.getFileStream(file.id);
+    // See getFileById(): authorization on the presigned branch rests on the
+    // getFileInfoByName() call above.
+    const url = await this.resolveDownloadUrl(file.id, serviceOptions);
+    if (url) {
+      this.setNoStore(res);
+      res.redirect(302, url);
+      return res;
+    }
+    const filestream = await this.fileService.getFileStream(file.id, serviceOptions);
     if (!filestream) {
       throw new NotFoundException(ErrorCode.FILE_NOT_FOUND);
     }
-    res.header('Content-Type', file.contentType || 'application/octet-stream');
-    res.header('Content-Disposition', `attachment; filename=${file.filename}`);
+    this.setFileHeaders(res, file);
     return this.pipeFileToResponse(filestream, res);
   }
+
+  /**
+   * Set the response headers that describe the file being delivered.
+   *
+   * `Cache-Control: private, no-store` is the security-relevant one. These
+   * routes are authorization-gated, and RFC 9111 lets a shared cache store a
+   * response that carries no cache directive. A reverse proxy or CDN with a
+   * blanket `/files/*` rule would then be free to hand an authorized response
+   * to the next, unauthorized requester — reopening at the proxy layer exactly
+   * what the role gate closes at the application layer. The directive costs one
+   * header and removes that entire class of misconfiguration.
+   *
+   * `no-store` also suppresses browser disk caching, which is the conservative
+   * choice for a bucket that may hold documents. A project serving public,
+   * immutable assets can override this to `public, max-age=…` — GridFS blobs
+   * are immutable once written, so a validator built from `_id` + `uploadDate`
+   * is sound. Do that only for files that are genuinely public.
+   */
+  protected setFileHeaders(res: Response, file: { contentType?: string; filename?: string }): void {
+    this.setNoStore(res);
+    res.header('Content-Type', file.contentType || 'application/octet-stream');
+    // See {@link buildContentDisposition} for why the two filename parameters are
+    // rendered differently, and for the injection cases the sanitiser closes.
+    res.header('Content-Disposition', buildContentDisposition(file.filename));
+  }
+
+  /**
+   * Mark a download response as uncacheable by any shared cache.
+   *
+   * Applies to BOTH delivery paths. On the streaming path it stops a reverse
+   * proxy or CDN with a blanket `/files/*` rule from handing an authorized
+   * response to the next, unauthorized requester. On the presigned path it
+   * matters more, not less: that response's `Location` is a bearer capability
+   * that works with no session, from any IP, until it expires — and while a 302
+   * is not heuristically cacheable per RFC 9111, `proxy_cache_valid 200 302 …`
+   * is the single most-copied nginx caching snippet, and Cloudflare's "Cache
+   * Everything" stores it too.
+   */
+  protected setNoStore(res: Response): void {
+    res.header('Cache-Control', 'private, no-store');
+  }
 }