@lenne.tech/nest-server 11.33.0 → 11.33.1

package/docs/REQUEST-LIFECYCLE.md

@@ -162,7 +162,7 @@ JWT-based authentication for existing projects:
 | **File Module** | Upload/download with MongoDB GridFS storage |
 | **REST Endpoints** | `GET /files/id/:id`, `GET /files/:filename` (core, gated by `file.downloadRoles`, default ADMIN); `POST /files/upload`, `DELETE /files/:id` (project-specific) |
 | **GraphQL Endpoints** | `getFileInfo` (`file.downloadRoles`), `uploadFile` / `uploadFiles` (`file.uploadRoles`), `deleteFile` (`file.deleteRoles`) — all default ADMIN |
-| **File access control** | Roles are the coarse filter; per-file rules go in `CoreFileService.checkRights()` using metadata written at upload time. Both file classes carry `@SkipTenantCheck()` — GridFS is not tenant-scoped |
+| **File access control** | Roles are the coarse filter; per-file rules go in `CoreFileService.checkRights()` using metadata written at upload time. Cover BOTH the `id` and the `filename` branch — the filename route authorizes on the by-name lookup alone when presigned S3 downloads are on, and `deleteFileByName()` always does. Working reference: `src/server/modules/file/file.service.ts` (with `file.downloadRoles: [S_USER]` in `src/config.env.ts`, so the rule is actually reached). Both file classes carry `@SkipTenantCheck()` — GridFS is not tenant-scoped |
 | **TUS Module** | Resumable uploads via tus.io protocol (creation, termination, expiration), gated by `tus.roles` (default `S_USER`); `OPTIONS` stays public for the CORS preflight |
 | **GridFS Migration** | Completed TUS uploads auto-migrate to GridFS |
 | **CORS Support** | Automatic CORS headers for browser uploads |

package/migration-guides/11.32.x-to-11.33.x.md

@@ -207,18 +207,51 @@ export class FileService extends CoreFileService {
     input: any,
     options?: FileServiceOptions & { checkInputType: FileInputCheckType },
   ): Promise<boolean> {
-    if (options?.checkInputType !== 'id' || options.force) {
+    // 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])) {
+    if (options.currentUser?.hasRole?.([RoleEnum.ADMIN])) {
       return true;
     }
-    const raw = await this.getRawFileInfo(input);
-    return !!raw && String(raw.metadata?.ownerId) === String(options.currentUser?.id);
+    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);
   }
 }
 ```
 
+**Cover the `filename` branch, not only `id`.** An id-only rule is enough while bytes are streamed —
+the filename route resolves an id and checks it again — but not once `s3.presignedDownloads` is on
+(the filename route then authorizes on the by-name lookup alone and redirects), and not for
+`deleteFileByName()`, which authorizes by name only. This is not hypothetical: 11.33.0 shipped a
+`deleteFileByName()` that authorized the caller and then re-resolved the file with an EMPTY context,
+so an overridden `checkRights()` was asked two different questions about one request and the owner
+got `File not found` for their own file. Both halves — the by-name branch and the forwarding — are
+covered by the reference server as of the next release.
+
+**Do not add an `if (!options.currentUser) return true` branch.** It reads as "system-internal call,
+the guard already decided", and that is not what it means: "no user in context" is also exactly what
+an ANONYMOUS request looks like. While `downloadRoles` is narrower than `S_EVERYONE` the coarse gate
+rejects those first and the branch looks harmless — widen the gate, which §A.2 explicitly offers, and
+the same branch hands every file to everyone. The ownership rule then evaporates precisely when it
+starts to matter. For the same reason the final comparison requires `metadata.ownerId` to be
+**present**: `String(undefined) === String(undefined)` would match an owner-less file against an
+absent user.
+
+Callers that genuinely are internal should say so, rather than relying on the omission:
+`{ force: true }` where a role decorator has already decided (an `@Roles(ADMIN)` admin endpoint), or
+the real `{ currentUser }` where the user is in scope (a controller cleaning up a file it just
+replaced — that delete should be COVERED by the ownership rule, not exempt from it). The reference
+server does both; see `src/server/modules/file/` and `src/server/modules/user/avatar.controller.ts`.
+
+The reference server also **runs** the rule above rather than documenting it: `src/config.env.ts`
+sets `file: { downloadRoles: [RoleEnum.S_USER] }` in every environment and
+`src/server/modules/file/file.service.ts` implements `checkRights()`. Copy from there — it is
+compiled and exercised by the test suite; this guide is not.
+
 Three new pieces make this possible, and all three were missing before: `createFile()` now forwards
 `serviceOptions.metadata` to storage; `getRawFileInfo()` / `getRawFileInfoByName()` read the raw
 document (the public `getFileInfo()` runs `prepareOutput` → `check()` and strips the very field the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.33.0",
+  "version": "11.33.1",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",

package/src/config.env.ts

@@ -2,6 +2,7 @@ import { CronExpression } from '@nestjs/schedule';
 import * as dotenv from 'dotenv';
 import { join } from 'path';
 
+import { RoleEnum } from './core/common/enums/role.enum';
 import { getEnvironmentConfig } from './core/common/helpers/config.helper';
 import { IServerOptions } from './core/common/interfaces/server-options.interface';
 
@@ -100,6 +101,36 @@ const config: { [env: string]: IServerOptions } = {
       autoRegister: false,
     },
     execAfterInit: 'pnpm run docs:bootstrap',
+    // File access — the COARSE gate on the two inherited download routes
+    // (`GET /files/id/:id`, `GET /files/:filename`), which `FileController` inherits
+    // from `CoreFileController` unchanged so this config can reach them.
+    //
+    // Since 11.33.0 those routes are role-gated and default to `[ADMIN]`. That default
+    // is the safe one for a project that has not thought about file access yet, but it
+    // is the WRONG one for this reference server: it ships an avatar upload every
+    // signed-in user may use, so an admin-only download would make `user.avatar`
+    // unreadable by the very user it belongs to.
+    //
+    // So the gate is widened to "signed in" and the real decision is made per file in
+    // `FileService.checkRights()` (own file, or ADMIN). Roles can only answer "may this
+    // caller reach the route"; they can never answer "may this caller have THIS file".
+    // Widening here is therefore not a relaxation — it MOVES the decision to the layer
+    // that can actually make it. It is also what makes the pairing testable at all: under
+    // `[ADMIN]` the guard answers first and an ownership rule could never fire, which is
+    // how the two halves drifted apart and shipped a bug. See
+    // `migration-guides/11.32.x-to-11.33.x.md` § A.3.
+    //
+    // `uploadRoles` / `deleteRoles` stay at their `[ADMIN]` default. They govern
+    // `CoreFileResolver` members only, and this server registers its own `FileResolver`
+    // and `FileController` write endpoints, each carrying `@Roles(RoleEnum.ADMIN)`
+    // explicitly — so the two knobs are inert here, and leaving them unset keeps the
+    // framework default visible rather than restating it.
+    //
+    // NOTE for markup-driven downloads: anything stricter than `S_EVERYONE` only works
+    // from an `<img>` / `<a download>` when the session travels as a COOKIE on a
+    // same-site request. A Bearer-only frontend has to fetch such URLs programmatically
+    // and build an object URL.
+    file: { downloadRoles: [RoleEnum.S_USER] },
     filter: {
       maxLimit: null,
     },
@@ -224,6 +255,9 @@ const config: { [env: string]: IServerOptions } = {
     },
     env: 'development',
     execAfterInit: 'pnpm run docs:bootstrap',
+    // Coarse download gate widened to any signed-in user; the per-file rule lives in
+    // `FileService.checkRights()`. Full rationale in the `ci` block above.
+    file: { downloadRoles: [RoleEnum.S_USER] },
     filter: {
       maxLimit: null,
     },
@@ -376,6 +410,9 @@ const config: { [env: string]: IServerOptions } = {
       autoRegister: false,
     },
     execAfterInit: 'pnpm run docs:bootstrap',
+    // Coarse download gate widened to any signed-in user; the per-file rule lives in
+    // `FileService.checkRights()`. Full rationale in the `ci` block above.
+    file: { downloadRoles: [RoleEnum.S_USER] },
     filter: {
       maxLimit: null,
     },
@@ -534,6 +571,9 @@ const config: { [env: string]: IServerOptions } = {
       autoRegister: false,
     },
     execAfterInit: 'pnpm run docs:bootstrap',
+    // Coarse download gate widened to any signed-in user; the per-file rule lives in
+    // `FileService.checkRights()`. Full rationale in the `ci` block above.
+    file: { downloadRoles: [RoleEnum.S_USER] },
     filter: {
       maxLimit: null,
     },
@@ -670,6 +710,11 @@ const config: { [env: string]: IServerOptions } = {
     },
     env: 'production',
     execAfterInit: 'pnpm run docs:bootstrap',
+    // Coarse download gate widened to any signed-in user; the per-file rule lives in
+    // `FileService.checkRights()`. Full rationale in the `ci` block above. Deliberately the
+    // SAME value as every other environment: a per-file rule that only runs outside
+    // production is a rule nobody has actually tested where it matters.
+    file: { downloadRoles: [RoleEnum.S_USER] },
     filter: {
       maxLimit: null,
     },

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

@@ -65,8 +65,18 @@ decision worth making explicitly.
 caller have THIS file". For the latter, write an owner or tenant into the metadata at upload time
 (`createFile(file, { metadata: { ownerId } })`) and compare it in `checkRights()` via
 `getRawFileInfo()` / `getRawFileInfoByName()`. The public `getFileInfo()` strips restricted fields
-and is unusable for the decision. `getRawFileInfo()` checks S3 metadata first, then GridFS, so the
-same rule works under either `file.storage`.
+and is unusable for the decision. Both raw lookups consult every store — S3 metadata first, then the
+filesystem store, then GridFS — so the same rule works under any `file.storage`.
+
+Handle **both** `checkInputType: 'id'` and `'filename'`. An id-only rule is enough while bytes are
+streamed (the filename route resolves an id and re-checks it), but not with presigned S3 downloads,
+and not for `deleteFileByName()`, which authorizes by name only.
+
+**Copy from the executed reference, not from prose:** `src/server/modules/file/file.service.ts`
+implements exactly this rule, and `src/config.env.ts` widens `file.downloadRoles` to `[S_USER]` so
+it is actually reached. Note the internal callers there too — `{ force: true }` on the
+`@Roles(ADMIN)` endpoints, and a real `{ currentUser }` in `AvatarController` — because a rule that
+reads a missing user as "internal, allow" fails open the moment the coarse gate is widened.
 
 ### 5. Decide how the frontend fetches files
 
@@ -82,8 +92,10 @@ route for exactly the public files and leave the core routes gated.
 
 - [ ] `pnpm run build` succeeds
 - [ ] Anonymous `GET /files/id/<id>` answers **401**
-- [ ] A signed-in non-privileged user answers **403** (not 401 — a 401 makes SPA auth layers log the
-      user out)
+- [ ] A signed-in non-privileged user answers **403** when the ROLE GATE is what refuses (not 401 —
+      a 401 makes SPA auth layers log the user out). If you widened `downloadRoles` and let
+      `checkRights()` decide instead, the expected answer is **404**, byte-identical to an unknown
+      id — a 403 there would confirm the file exists
 - [ ] A caller holding a configured role downloads successfully
 - [ ] If you set `file.downloadRoles`, the value actually takes effect — if it does not, something
       in your controller is overriding the member (see step 2)

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

@@ -141,18 +141,49 @@ export class FileService extends CoreFileService {
     input: any,
     options?: FileServiceOptions & { checkInputType: FileInputCheckType },
   ): Promise<boolean> {
-    if (options?.checkInputType !== 'id' || options.force) {
+    // 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])) {
+    if (options.currentUser?.hasRole?.([RoleEnum.ADMIN])) {
       return true;
     }
-    const raw = await this.getRawFileInfo(input);
-    return !!raw && String(raw.metadata?.ownerId) === String(options.currentUser?.id);
+    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 } })`.

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

@@ -557,7 +557,13 @@ export abstract class CoreFileService {
     if (!(await this.checkRights(filename, { ...serviceOptions, checkInputType: 'filename' }))) {
       return null;
     }
-    const fileInfo = await this.getFileInfoByName(filename);
+    // Forward the caller's context, exactly as deleteFile() does for getFileInfo().
+    // Without it this method authorizes the caller and then re-resolves the file with
+    // an EMPTY context, so an overridden checkRights() is asked two different
+    // questions about one request. For an ownership rule that means the lookup denies
+    // — and the caller gets `File not found` for a file that exists and that they were
+    // just authorized for, which reads as a missing file rather than a refused one.
+    const fileInfo = await this.getFileInfoByName(filename, serviceOptions);
     if (!fileInfo) {
       throw new NotFoundException(`File not found with filename ${filename}`);
     }
@@ -665,20 +671,48 @@ export abstract class CoreFileService {
    * routes. Metadata to compare against must be written at upload time via
    * `serviceOptions.metadata` and read back with `getRawFileInfo()`.
    *
+   * **A missing `currentUser` must DENY.** This is the one part of the rule that
+   * is easy to get backwards: "no user in context" is NOT "system-internal call"
+   * — it is also exactly what an ANONYMOUS request looks like. The coarse gate
+   * turns those away while `downloadRoles` is narrower than `S_EVERYONE`, so an
+   * `if (!options.currentUser) return true` shortcut looks harmless — right up to
+   * the moment a project widens the gate, at which point it hands every file to
+   * everyone and the ownership rule evaporates precisely when it starts to
+   * matter. Genuinely internal callers say so with `force: true`, or pass the
+   * user they already have; see `src/server/modules/file` and
+   * `src/server/modules/user/avatar.controller.ts`.
+   *
+   * **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 `s3.presignedDownloads` 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.
+   *
+   * The example below is the rule `src/server/modules/file/file.service.ts`
+   * actually runs — it is compiled, type-checked and exercised end to end by
+   * every file-touching e2e spec, plus the dedicated contract test in
+   * `tests/file-ownership.e2e-spec.ts`. Prefer reading it there over copying
+   * from here.
+   *
    * @example
    * ```typescript
    * protected override async checkRights(
    *   input: any,
    *   options?: FileServiceOptions & { checkInputType: FileInputCheckType },
    * ): Promise<boolean> {
-   *   if (options?.checkInputType !== 'id' || options.force) {
+   *   if (options?.force || (options?.checkInputType !== 'filename' && options?.checkInputType !== 'id')) {
    *     return true;
    *   }
-   *   if (options.currentUser?.hasRole([RoleEnum.ADMIN])) {
+   *   if (options.currentUser?.hasRole?.([RoleEnum.ADMIN])) {
    *     return true;
    *   }
-   *   const raw = await this.getRawFileInfo(input);
-   *   return !!raw && String(raw.metadata?.ownerId) === String(options.currentUser?.id);
+   *   const raw = options.checkInputType === 'id'
+   *     ? await this.getRawFileInfo(input)
+   *     : await this.getRawFileInfoByName(input);
+   *   // Fails closed without a user: `String(undefined)` cannot equal a real owner id.
+   *   // Requiring the owner to be PRESENT is load-bearing too — comparing a missing
+   *   // ownerId against a missing user id would compare 'undefined' with 'undefined'.
+   *   return !!raw?.metadata?.ownerId && String(raw.metadata.ownerId) === String(options.currentUser?.id);
    * }
    * ```
    */

package/src/server/modules/file/file.controller.ts

@@ -72,7 +72,11 @@ export class FileController extends CoreFileController {
   @Get('info/:id')
   @Roles(RoleEnum.ADMIN)
   async getFileInfo(@Param('id') id: string) {
-    return await this.fileService.getFileInfo(id);
+    // `force`: this route is @Roles(ADMIN) — the guard has already decided, and an overridden
+    // checkRights() must not be asked to re-derive that from an absent user. "No currentUser"
+    // is also what an anonymous request looks like, so a rule that reads it as "internal call"
+    // fails open; saying `force: true` states the intent instead of hiding it in an omission.
+    return await this.fileService.getFileInfo(id, { force: true });
   }
 
   /**
@@ -85,6 +89,7 @@ export class FileController extends CoreFileController {
       throw new BadRequestException('Missing ID');
     }
 
-    return await this.fileService.deleteFile(id);
+    // `force`: @Roles(ADMIN) above is the whole gate for this endpoint — see getFileInfo().
+    return await this.fileService.deleteFile(id, { force: true });
   }
 }

package/src/server/modules/file/file.resolver.ts

@@ -28,7 +28,10 @@ export class FileResolver {
   @Query(() => FileInfo, { nullable: true })
   @Roles(RoleEnum.ADMIN)
   async getFileInfo(@Args({ name: 'filename', type: () => String }) filename: string) {
-    return await this.fileService.getFileInfoByName(filename);
+    // `force`: @Roles(ADMIN) is the whole gate for this admin API. Omitting options instead
+    // would leave an overridden checkRights() to guess "internal call" from an absent user —
+    // indistinguishable from an anonymous request, and therefore the wrong thing to allow on.
+    return await this.fileService.getFileInfoByName(filename, { force: true });
   }
 
   // ===========================================================================
@@ -41,7 +44,8 @@ export class FileResolver {
   @Mutation(() => FileInfo)
   @Roles(RoleEnum.ADMIN)
   async deleteFile(@Args({ name: 'filename', type: () => String }) filename: string) {
-    return await this.fileService.deleteFileByName(filename);
+    // `force`: @Roles(ADMIN) is the whole gate here — see getFileInfo().
+    return await this.fileService.deleteFileByName(filename, { force: true });
   }
 
   /**

package/src/server/modules/file/file.service.ts

@@ -2,9 +2,11 @@ import { Injectable, Optional } from '@nestjs/common';
 import { InjectConnection } from '@nestjs/mongoose';
 import { Connection } from 'mongoose';
 
+import { RoleEnum } from '../../../core/common/enums/role.enum';
 import { ConfigService } from '../../../core/common/services/config.service';
 import { CoreS3Service } from '../../../core/common/services/core-s3.service';
-import { CoreFileService } from '../../../core/modules/file/core-file.service';
+import { CoreFileService, FileInputCheckType } from '../../../core/modules/file/core-file.service';
+import { FileServiceOptions } from '../../../core/modules/file/interfaces/file-service-options.interface';
 
 /**
  * File service
@@ -27,35 +29,79 @@ export class FileService extends CoreFileService {
   }
 
   /**
-   * NOTE — where the per-file rule would go.
+   * Per-file authorization for the two inherited download routes.
    *
-   * This reference server deliberately does NOT override `checkRights()`. With
-   * `file.downloadRoles` at its default `[ADMIN]`, the roles guard answers before
-   * the service is reached, so an owner rule here could never fire — and a rule
-   * that cannot fire is worse than none, because it reads as protection.
+   * THIS IS DELIBERATELY EXECUTED CODE, NOT AN ILLUSTRATION. It used to be a
+   * commented-out `@example` here, on the reasoning that `file.downloadRoles`
+   * defaults to `[ADMIN]`, the roles guard therefore answers before the service
+   * is reached, and a rule that cannot fire is worse than none. The reasoning was
+   * locally sound and globally harmful: a comment is never compiled, never
+   * type-checked and never run, so nothing in this repository exercised the
+   * `Core*` inheritance seam that every consuming project depends on — and a
+   * `deleteFileByName()` bug that dropped `serviceOptions` on the way to its
+   * inner lookup shipped green through 2777 tests, to be found downstream hours
+   * after release. The commented example was itself wrong (it allowed on a
+   * missing `currentUser`), and it was copied verbatim.
    *
-   * The pairing only becomes useful once the coarse gate is widened. A project
-   * that wants "signed-in users may fetch THEIR OWN files" sets
-   * `file: { downloadRoles: [RoleEnum.S_USER] }` and then overrides:
+   * The tension is resolved the other way round now: `config.env.ts` widens the
+   * coarse gate to `[RoleEnum.S_USER]` in every environment, which is what real
+   * projects do, so the rule below actually runs on every download this server
+   * serves.
    *
-   * ```typescript
-   * protected override async checkRights(input, options) {
-   *   if (options?.force || options?.checkInputType !== 'id') {
-   *     return true;   // writes and filename reads stay on the role gate
-   *   }
-   *   if (!options.currentUser) {
-   *     return true;   // system-internal call: the guard already decided
-   *   }
-   *   if (options.currentUser.hasRole?.([RoleEnum.ADMIN])) {
-   *     return true;
-   *   }
-   *   const raw = await this.getRawFileInfo(input);
-   *   return !!raw?.metadata?.ownerId && String(raw.metadata.ownerId) === String(options.currentUser.id);
-   * }
-   * ```
+   * The rule: ADMIN sees everything; everyone else sees only files whose
+   * `metadata.ownerId` is their own id. `AvatarController` writes that metadata
+   * at upload time. A file with NO owner recorded — the admin uploads via
+   * `/files/upload` and the GraphQL mutations, and TUS uploads, which carry
+   * `tusUploadId` but no owner — is therefore ADMIN-only.
    *
-   * `AvatarController` already writes the `metadata.ownerId` such a rule reads,
-   * so enabling it in a downstream project is a config change plus this method.
-   * See `src/core/modules/file/README.md` § Access control.
+   * Two properties worth knowing:
+   *
+   * - **A refusal answers 404, not 403.** That is the framework's doing, not
+   *   this method's: returning `false` makes the caller answer as if the file
+   *   did not exist, because a 403 would confirm that the id names a real file
+   *   and turn the endpoint into an existence oracle.
+   * - **A missing `currentUser` DENIES.** This is the one part that is easy to
+   *   get backwards. "No user in context" is NOT "system-internal call" — it is
+   *   also exactly what an ANONYMOUS request looks like. Today the coarse gate
+   *   turns those away before this hook runs, so an `if (!options.currentUser)
+   *   return true` shortcut looks harmless; widen `downloadRoles` to
+   *   `S_EVERYONE` and the same branch hands every file to everyone, so the
+   *   ownership rule evaporates precisely when it starts to matter. Genuinely
+   *   internal callers say so instead: `FileController` / `FileResolver` pass
+   *   `{ force: true }` because their `@Roles(ADMIN)` already decided, and
+   *   `AvatarController` passes the real `{ currentUser }` so its cleanup delete
+   *   is COVERED by this rule rather than exempt from it.
+   *
+   * BOTH the `id` and the `filename` branch are covered. Covering only `id` is
+   * enough while bytes are streamed, because the filename route resolves an id
+   * and checks it again — but not once `s3.presignedDownloads` is enabled, where
+   * the filename route authorizes on the by-name lookup alone and then redirects.
+   * The by-name half is also where the shipped `deleteFileByName()` bug lived.
+   *
+   * See `src/core/modules/file/README.md` § Access control, and
+   * `tests/file-ownership.e2e-spec.ts` for the end-to-end contract test.
    */
+  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;
+    }
+
+    // The RAW document on purpose: the public getFileInfo() runs prepareOutput(), which
+    // strips `metadata` — the very field this decision rests on.
+    const raw =
+      options.checkInputType === 'id' ? await this.getRawFileInfo(input) : await this.getRawFileInfoByName(input);
+
+    // Fails closed on a missing user: `String(undefined)` can never equal a real owner id.
+    // Requiring `metadata.ownerId` to be PRESENT is load-bearing too — without it an
+    // owner-less file would compare `String(undefined)` against `String(undefined)` and match.
+    return !!raw?.metadata?.ownerId && String(raw.metadata.ownerId) === String(options.currentUser?.id);
+  }
 }

package/src/server/modules/user/avatar.controller.ts

@@ -55,9 +55,16 @@ export class AvatarController {
     // Drop the replaced file. A failure here must not fail the upload: the new avatar
     // is already stored and referenced, so an orphaned object is a cleanup concern,
     // not a request error.
+    //
+    // `{ currentUser: user }`, not an empty context: the uploader IS in scope here, so a
+    // per-file rule in FileService.checkRights() should COVER this delete (the previous
+    // avatar is their own file) rather than be exempted from it. Passing nothing would ask
+    // the rule to infer "internal call" from an absent user — which is also what an
+    // anonymous request looks like, and is exactly the shortcut that makes an ownership
+    // rule evaporate once `file.downloadRoles` is widened.
     if (previousAvatar) {
       try {
-        await this.fileService.deleteFile(previousAvatar);
+        await this.fileService.deleteFile(previousAvatar, { currentUser: user });
       } catch (error) {
         this.logger.warn(
           `Could not remove previous avatar ${previousAvatar}: ${error instanceof Error ? error.message : 'Unknown error'}`,