@lenne.tech/nest-server 11.32.4 → 11.33.1

package/src/core/modules/tus/tus-redis-locker.ts

@@ -0,0 +1,139 @@
+import { Logger } from '@nestjs/common';
+import { randomUUID } from 'node:crypto';
+
+import { CoreRedisService } from '../../common/services/core-redis.service';
+
+/** Release callback handed to the current lock holder when someone else wants the resource */
+type RequestRelease = () => Promise<void> | void;
+
+/**
+ * TUS lock that is exclusive across REPLICAS, not just within one process.
+ *
+ * `@tus/server` defaults to an in-memory locker, which is exactly right for one process and
+ * useless behind a load balancer: two replicas each hold their own lock for the same upload id
+ * and both accept a PATCH, so two byte ranges are written to one upload and the file ends up
+ * interleaved. Resumable uploads are long-lived and clients retry aggressively, so a request
+ * pair landing on different replicas is the normal case, not a rare one.
+ *
+ * The lock is a Redis key with a TTL held only while a request is being served, refreshed by a
+ * heartbeat so a slow but live PATCH keeps it, and released in `unlock()`. A holder that dies
+ * mid-request stops refreshing and the key expires — the upload becomes writable again instead
+ * of being stuck until someone intervenes.
+ */
+export class TusRedisLock {
+  protected heartbeat?: NodeJS.Timeout;
+
+  /** Random per-acquisition value, so only the actual holder can release or refresh the lock */
+  protected token?: string;
+
+  constructor(
+    protected readonly redisService: CoreRedisService,
+    protected readonly key: string,
+    protected readonly ttlMs: number,
+    protected readonly acquireTimeoutMs: number,
+  ) {}
+
+  /**
+   * Wait for exclusive access to the upload, or throw once the timeout is reached.
+   *
+   * `cancelReq` is the TUS mechanism for cooperative handover: when a newer request wants an
+   * upload we already hold, the holder is asked to let go rather than made to wait it out.
+   */
+  async lock(signal: AbortSignal, cancelReq: RequestRelease): Promise<void> {
+    const deadline = Date.now() + this.acquireTimeoutMs;
+    // randomUUID, not Math.random: this token is the ONLY thing separating "holds the lock" from
+    // "does not" in the compare-and-delete below and in the heartbeat's PEXPIRE. A collision lets
+    // one holder refresh or release another's lock, and two replicas then interleave byte ranges
+    // into one upload — the exact corruption this locker exists to prevent.
+    const token = `${process.pid}-${randomUUID()}`;
+
+    for (;;) {
+      const acquired = await this.redisService.getClient().set(this.key, token, 'PX', this.ttlMs, 'NX');
+
+      if (acquired === 'OK') {
+        this.token = token;
+        this.startHeartbeat();
+        return;
+      }
+
+      // Tell whoever holds it that someone else is waiting. Signalling on every attempt is
+      // deliberate: the holder may be on another replica and only learns of us through this.
+      await cancelReq();
+
+      if (signal.aborted || Date.now() > deadline) {
+        throw new Error(`Could not acquire the upload lock for "${this.key}" within ${this.acquireTimeoutMs}ms`);
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+
+  /** Release the lock — only if we still hold it */
+  async unlock(): Promise<void> {
+    this.stopHeartbeat();
+    const token = this.token;
+    this.token = undefined;
+    if (!token) {
+      return;
+    }
+
+    // Compare-and-delete: after our TTL expired the key may already belong to someone else,
+    // and deleting it blindly would unlock an upload another replica is actively writing.
+    const script = `if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('DEL', KEYS[1]) end return 0`;
+    try {
+      await this.redisService.getClient().eval(script, 1, this.key, token);
+    } catch {
+      // The key expires on its own; a failed release costs at most one TTL of waiting.
+    }
+  }
+
+  /** Keep the lock alive while the request is still being served */
+  protected startHeartbeat(): void {
+    this.heartbeat = setInterval(
+      () => {
+        const token = this.token;
+        if (!token) {
+          return;
+        }
+        const script = `if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('PEXPIRE', KEYS[1], ARGV[2]) end return 0`;
+        this.redisService
+          .getClient()
+          .eval(script, 1, this.key, token, this.ttlMs)
+          .catch(() => undefined);
+      },
+      Math.max(1000, Math.floor(this.ttlMs / 3)),
+    );
+    this.heartbeat.unref?.();
+  }
+
+  protected stopHeartbeat(): void {
+    if (this.heartbeat) {
+      clearInterval(this.heartbeat);
+      this.heartbeat = undefined;
+    }
+  }
+}
+
+/**
+ * Locker handed to `@tus/server` when Redis is configured (see {@link TusRedisLock}).
+ */
+export class TusRedisLocker {
+  protected readonly logger = new Logger(TusRedisLocker.name);
+
+  constructor(
+    protected readonly redisService: CoreRedisService,
+    /** How long a lock survives without a heartbeat — a dead holder's upload frees itself */
+    protected readonly ttlMs = 30_000,
+    /** How long a request waits for a busy upload before giving up with 500 */
+    protected readonly acquireTimeoutMs = 10_000,
+  ) {}
+
+  newLock(id: string): TusRedisLock {
+    return new TusRedisLock(
+      this.redisService,
+      this.redisService.key('tus-lock', id),
+      this.ttlMs,
+      this.acquireTimeoutMs,
+    );
+  }
+}

package/src/core/modules/tus/tus.module.ts

@@ -3,10 +3,13 @@ import { getConnectionToken } from '@nestjs/mongoose';
 import { Connection } from 'mongoose';
 
 import { ITusConfig } from '../../common/interfaces/server-options.interface';
+import { ConfigService } from '../../common/services/config.service';
+import { CoreRedisService } from '../../common/services/core-redis.service';
+import { CoreS3Service } from '../../common/services/core-s3.service';
 import { CoreTusController } from './core-tus.controller';
 import { CoreTusService } from './core-tus.service';
 import { TUS_CONFIG } from './tus.constants';
-import { normalizeTusConfig } from './interfaces/tus-config.interface';
+import { DEFAULT_TUS_CONFIG, normalizeTusConfig } from './interfaces/tus-config.interface';
 
 /**
  * @deprecated Import from `./tus.constants` instead. Re-exported only so existing deep imports keep
@@ -111,6 +114,42 @@ export class TusModule implements OnModuleInit {
     return this.customController || CoreTusController;
   }
 
+  /**
+   * Write the configured roles onto the tus handlers.
+   *
+   * An empty array is rejected rather than honoured: the guards read an
+   * all-empty role set as "no roles required" and return true, so `roles: []`
+   * would OPEN the endpoints instead of closing them.
+   */
+  private static applyRoles(controller: Type<CoreTusController>, roles?: string[]): void {
+    if (
+      roles !== undefined &&
+      (!Array.isArray(roles) || roles.length === 0 || roles.some((r) => typeof r !== 'string'))
+    ) {
+      this.logger.warn(
+        `Ignoring tus.roles: expected a non-empty array of role strings, got ${JSON.stringify(roles)}. ` +
+          `Falling back to ${JSON.stringify(DEFAULT_TUS_CONFIG.roles)}.`,
+      );
+    }
+
+    const effective =
+      Array.isArray(roles) && roles.length > 0 && roles.every((r) => typeof r === 'string')
+        ? roles
+        : DEFAULT_TUS_CONFIG.roles;
+
+    Reflect.defineMetadata('roles', effective, controller);
+    // NOTE: handleTusOptions / handleTusOptionsWithId are deliberately absent.
+    // They answer the CORS preflight, which a browser sends WITHOUT credentials,
+    // so gating them would break every browser upload. They expose capabilities
+    // only, never upload data — see CoreTusController.
+    for (const member of ['handleTus', 'handleTusWithId']) {
+      const handler = (controller.prototype as Record<string, unknown>)[member];
+      if (typeof handler === 'function') {
+        Reflect.defineMetadata('roles', effective, handler);
+      }
+    }
+  }
+
   /**
    * Creates a dynamic module for TUS uploads
    *
@@ -156,6 +195,25 @@ export class TusModule implements OnModuleInit {
     // Enable TUS
     this.tusEnabled = true;
 
+    // Apply the configured roles to the controller that will actually be
+    // registered. Same mechanism as CorePermissionsModule: the value is only
+    // known at runtime, and the guards read exactly this metadata key.
+    //
+    // A custom controller is covered whether it inherits the handlers or
+    // re-declares them. Re-declaring @All()/@Roles() does NOT opt out: this
+    // writes onto `controller.prototype[member]`, which for an override resolves
+    // to the SUBCLASS's own function, and forRoot() runs after decorator
+    // evaluation — so config wins either way.
+    //
+    // That differs from the file module on purpose. `applyFileRoles()` targets
+    // the BASE class by name, so a subclass override there genuinely does keep
+    // its own metadata. Do not reason from one to the other.
+    //
+    // The real opt-outs here are: give the handler a different name (this only
+    // touches the members it knows), or register the controller outside
+    // TusModule entirely.
+    this.applyRoles(this.getControllerClass(), config.roles);
+
     return {
       controllers: [this.getControllerClass()],
       exports: [TUS_CONFIG, CoreTusService],
@@ -166,13 +224,27 @@ export class TusModule implements OnModuleInit {
           useValue: config,
         },
         {
-          inject: [getConnectionToken(), TUS_CONFIG],
+          inject: [
+            getConnectionToken(),
+            TUS_CONFIG,
+            ConfigService,
+            { optional: true, token: CoreS3Service },
+            { optional: true, token: CoreRedisService },
+          ],
           provide: CoreTusService,
-          useFactory: async (connection: Connection, tusConfig: ITusConfig) => {
-            const service = new CoreTusService(connection);
+          useFactory: async (
+            connection: Connection,
+            tusConfig: ITusConfig,
+            configService: ConfigService,
+            s3Service?: CoreS3Service,
+            redisService?: CoreRedisService,
+          ) => {
+            const service = new CoreTusService(connection, { configService, redisService, s3Service });
             service.configure(tusConfig);
-            // Manually call onModuleInit since useFactory bypasses lifecycle hooks
-            await service.onModuleInit();
+            // NestJS DOES call onModuleInit on a factory-provided instance — its hook iterates
+            // every non-alias provider, however it was constructed. Calling it here as well ran
+            // init TWICE per boot: two TUS servers, two S3 stores, and two hourly expiration
+            // intervals of which onModuleDestroy clears only the second.
             return service;
           },
         },

package/src/core.module.ts

@@ -33,6 +33,10 @@ import { mongoosePasswordPlugin } from './core/common/plugins/mongoose-password.
 import { mongooseRoleGuardPlugin } from './core/common/plugins/mongoose-role-guard.plugin';
 import { mongooseTenantPlugin } from './core/common/plugins/mongoose-tenant.plugin';
 import { ConfigService } from './core/common/services/config.service';
+import { CoreCronJobsInitializer } from './core/common/services/core-cron-jobs.initializer';
+import { CoreRedisService } from './core/common/services/core-redis.service';
+import { CoreS3Service } from './core/common/services/core-s3.service';
+import { CoreTrustProxyInitializer } from './core/common/services/core-trust-proxy.initializer';
 import { EmailService } from './core/common/services/email.service';
 import { MailjetService } from './core/common/services/mailjet.service';
 import { ModelDocService } from './core/common/services/model-doc.service';
@@ -42,6 +46,7 @@ import { CoreBetterAuthUserMapper } from './core/modules/better-auth/core-better
 import { CoreBetterAuthModule } from './core/modules/better-auth/core-better-auth.module';
 import { CoreBetterAuthService } from './core/modules/better-auth/core-better-auth.service';
 import { ErrorCodeModule } from './core/modules/error-code/error-code.module';
+import { applyFileRoles } from './core/modules/file/file-roles.helper';
 import { CoreHealthCheckModule } from './core/modules/health-check/core-health-check.module';
 import { CoreHubModule } from './core/modules/hub/core-hub.module';
 import { isHubEnabled, isHubQueriesEnabled } from './core/modules/hub/hub-config.helper';
@@ -259,6 +264,15 @@ export class CoreModule implements NestModule {
       return connection;
     };
 
+    // Apply the configured roles to the core file endpoints.
+    //
+    // The file module ships abstract classes only — there is no CoreFileModule
+    // with its own forRoot() — so this is the one place that runs early enough
+    // to rewrite the role metadata before Nest builds its route table.
+    // Consumers that OVERRIDE a member re-declare the metadata on their own
+    // function and opt out of this; see applyFileRoles() for why.
+    applyFileRoles(config.file);
+
     // Check secrets
     const jwtConfig = config.jwt;
     if (jwtConfig?.secret && jwtConfig.secret && jwtConfig.refresh && jwtConfig.refresh.secret === jwtConfig.secret) {
@@ -274,6 +288,10 @@ export class CoreModule implements NestModule {
       },
 
       // Core Services
+      CoreCronJobsInitializer,
+      CoreRedisService,
+      CoreS3Service,
+      CoreTrustProxyInitializer,
       EmailService,
       TemplateService,
       MailjetService,
@@ -530,7 +548,14 @@ export class CoreModule implements NestModule {
     }
 
     // Set exports
-    const exports: any[] = [ConfigService, EmailService, TemplateService, MailjetService];
+    const exports: any[] = [
+      ConfigService,
+      CoreRedisService,
+      CoreS3Service,
+      EmailService,
+      TemplateService,
+      MailjetService,
+    ];
     if (!process.env.VITEST && isGraphQlEnabled) {
       exports.push(ComplexityPlugin);
     }

package/src/index.ts

@@ -30,8 +30,10 @@ export * from './core/common/exceptions/access-denied.exception';
 export * from './core/common/filters/http-exception-log.filter';
 export * from './core/common/helpers/common.helper';
 export * from './core/common/helpers/config.helper';
+export * from './core/common/helpers/content-disposition.helper';
 export * from './core/common/helpers/context.helper';
 export * from './core/common/helpers/cookies.helper';
+export * from './core/common/helpers/graceful-shutdown.helper';
 export * from './core/common/helpers/db.helper';
 export * from './core/common/helpers/decorator.helper';
 export * from './core/common/helpers/file.helper';
@@ -86,7 +88,12 @@ export * from './core/common/scalars/date.scalar';
 export * from './core/common/scalars/json.scalar';
 export * from './core/common/services/brevo.service';
 export * from './core/common/services/config.service';
+export * from './core/common/services/core-cron-jobs.registry';
 export * from './core/common/services/core-cron-jobs.service';
+export * from './core/common/services/core-redis.service';
+export * from './core/common/services/core-redis-pubsub';
+export * from './core/common/services/core-s3.service';
+export * from './core/common/services/rate-limit-store';
 export * from './core/common/services/crud.service';
 export * from './core/common/services/email.service';
 export * from './core/common/services/mailjet.service';
@@ -169,6 +176,9 @@ export * from './core/modules/file/core-file-info.model';
 export * from './core/modules/file/core-file.controller';
 export * from './core/modules/file/core-file.resolver';
 export * from './core/modules/file/core-file.service';
+export * from './core/modules/file/file-roles.helper';
+export * from './core/modules/file/file-storage.helper';
+export * from './core/modules/file/filesystem-file.helper';
 export * from './core/modules/file/interfaces/file-service-options.interface';
 export * from './core/modules/file/interfaces/file-upload.interface';
 

package/src/main.ts

@@ -9,6 +9,7 @@ import envConfig from './config.env';
 import { FilterArgs } from './core/common/args/filter.args';
 import { buildCorsConfig, isCookiesEnabled, isCorsDisabled } from './core/common/helpers/cookies.helper';
 import { HttpExceptionLogFilter } from './core/common/filters/http-exception-log.filter';
+import { installGracefulShutdown } from './core/common/helpers/graceful-shutdown.helper';
 import { handleFatalBootstrapError, installProcessDiagnostics } from './core/common/helpers/process-diagnostics.helper';
 import { CorePersistenceModel } from './core/common/models/core-persistence.model';
 import { CoreAuthModel } from './core/modules/auth/core-auth.model';
@@ -121,7 +122,12 @@ async function bootstrap() {
   // and `docker stop` waits out its full grace period before SIGKILL — dropping in-flight requests
   // and skipping every onModuleDestroy(). enableShutdownHooks() is what closes the app and drains
   // the loop; installProcessDiagnostics() then correctly defers to it instead of re-raising.
-  server.enableShutdownHooks();
+  //
+  // installGracefulShutdown() IS enableShutdownHooks() when no `shutdownDelayMs` is configured.
+  // With one, it additionally keeps the instance fully healthy for that long before closing —
+  // which a NestJS lifecycle hook cannot do, because every one of them already runs inside
+  // close(), after the modules are destroyed. See the helper for the ordering.
+  installGracefulShutdown(server);
 
   // Start server on configured port
   await server.listen(envConfig.port, envConfig.hostname);

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

@@ -20,9 +20,13 @@ import { FileService } from './file.service';
 /**
  * File controller
  *
- * Extends CoreFileController to provide public download endpoints:
- * - GET /files/id/:id - Download file by ID (public)
- * - GET /files/:filename - Download file by filename (public)
+ * Extends CoreFileController and INHERITS its download endpoints unchanged:
+ * - GET /files/id/:id     - Download file by ID
+ * - GET /files/:filename  - Download file by filename
+ *
+ * Both are gated by `file.downloadRoles` (default ADMIN). They are deliberately
+ * not overridden here: role metadata lives on the function object, so an
+ * override would carry its own and silently opt the route out of that config.
  *
  * Adds admin-only endpoints:
  * - POST /files/upload - Upload file (admin)
@@ -68,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 });
   }
 
   /**
@@ -81,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

@@ -1,6 +1,4 @@
 import { Args, Mutation, Query, Resolver } from '@nestjs/graphql';
-import { createWriteStream } from 'fs';
-import fs = require('fs');
 import GraphQLUpload = require('graphql-upload/GraphQLUpload.js');
 
 import { Roles } from '../../../core/common/decorators/roles.decorator';
@@ -30,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 });
   }
 
   // ===========================================================================
@@ -43,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 });
   }
 
   /**
@@ -61,21 +63,11 @@ export class FileResolver {
   @Mutation(() => Boolean)
   @Roles(RoleEnum.ADMIN)
   async uploadFiles(@Args({ name: 'files', type: () => [GraphQLUpload] }) files: FileUpload[]) {
-    // Save files in filesystem
-    const promises: Promise<any>[] = [];
-    for (const file of files) {
-      const { createReadStream, filename } = await file;
-      await fs.promises.mkdir('./uploads', { recursive: true });
-      promises.push(
-        new Promise((resolve, reject) =>
-          createReadStream()
-            .pipe(createWriteStream(`./uploads/${filename}`))
-            .on('finish', () => resolve(true))
-            .on('error', (error) => reject(error)),
-        ),
-      );
-    }
-    await Promise.allSettled(promises);
+    // Store in the central file storage (GridFS/S3), never on the pod's own disk:
+    // `./uploads` is relative to the process working directory, so with more than
+    // one replica the file lands wherever the request happened to be routed and is
+    // unreadable everywhere else — and gone after a restart.
+    await this.fileService.createFiles(files);
     return true;
   }
 }

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

@@ -1,16 +1,24 @@
-import { Injectable } from '@nestjs/common';
+import { Injectable, Optional } from '@nestjs/common';
 import { InjectConnection } from '@nestjs/mongoose';
 import { Connection } from 'mongoose';
 
-import { CoreFileService } from '../../../core/modules/file/core-file.service';
+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, FileInputCheckType } from '../../../core/modules/file/core-file.service';
+import { FileServiceOptions } from '../../../core/modules/file/interfaces/file-service-options.interface';
 
 /**
  * File service
  */
 @Injectable()
 export class FileService extends CoreFileService {
-  constructor(@InjectConnection() protected override readonly connection: Connection) {
-    super(connection);
+  constructor(
+    @InjectConnection() protected override readonly connection: Connection,
+    protected readonly configService: ConfigService,
+    @Optional() protected readonly s3Service?: CoreS3Service,
+  ) {
+    super(connection, 'fs', { configService, s3Service });
   }
 
   /**
@@ -19,4 +27,81 @@ export class FileService extends CoreFileService {
   async duplicate(fileName: string, newName: string): Promise<any> {
     return this.files.openDownloadStreamByName(fileName).pipe(this.files.openUploadStream(newName));
   }
+
+  /**
+   * Per-file authorization for the two inherited download routes.
+   *
+   * 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 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.
+   *
+   * 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.
+   *
+   * 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

@@ -1,12 +1,13 @@
-import { Post, UploadedFile, UseInterceptors } from '@nestjs/common';
+import { Logger, Post, UploadedFile, UseInterceptors } from '@nestjs/common';
 import { Controller } from '@nestjs/common/decorators/core/controller.decorator';
 import { FileInterceptor } from '@nestjs/platform-express';
 
-import envConfig from '../../../config.env';
 import { CurrentUser } from '../../../core/common/decorators/current-user.decorator';
 import { Roles } from '../../../core/common/decorators/roles.decorator';
 import { RoleEnum } from '../../../core/common/enums/role.enum';
-import { multerOptionsForImageUpload } from '../../../core/common/helpers/file.helper';
+import { getStringIds } from '../../../core/common/helpers/db.helper';
+import { multerFileToUpload, multerOptionsForImageUpload } from '../../../core/common/helpers/file.helper';
+import { FileService } from '../file/file.service';
 import { User } from './user.model';
 import { UserService } from './user.service';
 
@@ -16,10 +17,15 @@ import { UserService } from './user.service';
 @Controller('avatar')
 @Roles(RoleEnum.ADMIN)
 export class AvatarController {
+  protected readonly logger = new Logger(AvatarController.name);
+
   /**
    * Import services
    */
-  constructor(protected readonly usersService: UserService) {}
+  constructor(
+    protected readonly usersService: UserService,
+    protected readonly fileService: FileService,
+  ) {}
 
   /**
    * Upload files
@@ -29,12 +35,43 @@ export class AvatarController {
   @UseInterceptors(
     FileInterceptor(
       'file',
-      multerOptionsForImageUpload({
-        destination: `${envConfig.staticAssets.path}/avatars`,
-      }),
+      // `memory: true`, NOT a disk destination: the avatar goes into the central
+      // file storage (GridFS/S3) so every replica can serve it and a restart or
+      // reschedule does not lose it. A pod-local `staticAssets` path is readable
+      // by exactly one replica.
+      multerOptionsForImageUpload({ memory: true }),
     ),
   )
-  uploadFile(@UploadedFile() file: Express.Multer.File, @CurrentUser() user: User): Promise<string> {
-    return this.usersService.setAvatar(file, user);
+  async uploadFile(@UploadedFile() file: Express.Multer.File, @CurrentUser() user: User): Promise<string> {
+    // Record the owner. `file.downloadRoles` defaults to ADMIN, so without this the
+    // uploader could not fetch their own avatar back — roles answer "may this caller
+    // reach the route", never "may this caller have THIS file". FileService.checkRights()
+    // reads this metadata to answer the second question.
+    const stored = await this.fileService.createFile(multerFileToUpload(file), {
+      metadata: { ownerId: getStringIds(user.id) },
+    });
+    const previousAvatar = await this.usersService.setAvatar(stored.id, user);
+
+    // 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, { currentUser: user });
+      } catch (error) {
+        this.logger.warn(
+          `Could not remove previous avatar ${previousAvatar}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        );
+      }
+    }
+
+    return stored.id;
   }
 }