@lenne.tech/nest-server 11.32.4 → 11.33.0

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)

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';
@@ -61,21 +59,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,7 +1,9 @@
-import { Injectable } from '@nestjs/common';
+import { Injectable, Optional } from '@nestjs/common';
 import { InjectConnection } from '@nestjs/mongoose';
 import { Connection } from 'mongoose';
 
+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';
 
 /**
@@ -9,8 +11,12 @@ import { CoreFileService } from '../../../core/modules/file/core-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 +25,37 @@ export class FileService extends CoreFileService {
   async duplicate(fileName: string, newName: string): Promise<any> {
     return this.files.openDownloadStreamByName(fileName).pipe(this.files.openUploadStream(newName));
   }
+
+  /**
+   * NOTE — where the per-file rule would go.
+   *
+   * 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.
+   *
+   * 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:
+   *
+   * ```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);
+   * }
+   * ```
+   *
+   * `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.
+   */
 }

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,36 @@ 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.
+    if (previousAvatar) {
+      try {
+        await this.fileService.deleteFile(previousAvatar);
+      } catch (error) {
+        this.logger.warn(
+          `Could not remove previous avatar ${previousAvatar}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        );
+      }
+    }
+
+    return stored.id;
   }
 }

package/src/server/modules/user/user.model.ts

@@ -6,6 +6,7 @@ import { Document, Schema } from 'mongoose';
 import { Restricted } from '../../../core/common/decorators/restricted.decorator';
 import { Translatable } from '../../../core/common/decorators/translatable.decorator';
 import { UnifiedField } from '../../../core/common/decorators/unified-field.decorator';
+import { ProcessType } from '../../../core/common/enums/process-type.enum';
 import { RoleEnum } from '../../../core/common/enums/role.enum';
 import { CoreUserModel } from '../../../core/modules/user/core-user.model';
 import { PersistenceModel } from '../../common/models/persistence.model';
@@ -24,13 +25,18 @@ export class User extends CoreUserModel implements PersistenceModel {
   // ===================================================================================================================
 
   /**
-   * URL to avatar file of the user
+   * ID of the user's avatar file, assigned by POST /avatar/upload
+   *
+   * Readable by everyone, writable by NO ONE through a generic update: it is a file id the
+   * server hands out, and the avatar endpoint deletes the file the previous value points at.
+   * While it was freely writable, a signed-in user could put someone else's file id here and
+   * have the next upload delete that file for them.
    */
   @UnifiedField({
-    description: 'URL to avatar file of the user',
+    description: "ID of the user's avatar file (set via POST /avatar/upload)",
     isOptional: true,
     mongoose: true,
-    roles: RoleEnum.S_EVERYONE,
+    roles: [{ processType: ProcessType.INPUT, roles: RoleEnum.S_NO_ONE }],
   })
   avatar: string = undefined;
 

package/src/server/modules/user/user.module.ts

@@ -1,8 +1,11 @@
-import { Module } from '@nestjs/common';
+import { forwardRef, Module } from '@nestjs/common';
 import { MongooseModule } from '@nestjs/mongoose';
 import { PubSub } from 'graphql-subscriptions';
 
 import { ConfigService } from '../../../core/common/services/config.service';
+import { CoreRedisPubSub } from '../../../core/common/services/core-redis-pubsub';
+import { CoreRedisService } from '../../../core/common/services/core-redis.service';
+import { FileModule } from '../file/file.module';
 import { AvatarController } from './avatar.controller';
 import { UserController } from './user.controller';
 import { User, UserSchema } from './user.model';
@@ -15,7 +18,9 @@ import { UserService } from './user.service';
 @Module({
   controllers: [AvatarController, UserController],
   exports: [MongooseModule, UserResolver, UserService, 'USER_CLASS'],
-  imports: [MongooseModule.forFeature([{ name: User.name, schema: UserSchema }])],
+  // forwardRef: FileModule already imports UserModule, and the avatar upload now
+  // needs FileService to reach the central storage — so the two reference each other.
+  imports: [MongooseModule.forFeature([{ name: User.name, schema: UserSchema }]), forwardRef(() => FileModule)],
   providers: [
     UserResolver,
     ConfigService,
@@ -25,8 +30,12 @@ import { UserService } from './user.service';
       useValue: User,
     },
     {
+      // Redis-backed when Redis is enabled (subscriptions reach all replicas),
+      // process-local in-memory PubSub otherwise
       provide: 'PUB_SUB',
-      useValue: new PubSub(),
+      useFactory: (redisService?: CoreRedisService) =>
+        redisService?.enabled ? new CoreRedisPubSub(redisService) : new PubSub(),
+      inject: [{ optional: true, token: CoreRedisService }],
     },
   ],
 })