@lenne.tech/nest-server 11.32.4 → 11.33.0

package/src/core/modules/system-setup/core-system-setup.service.ts

@@ -8,6 +8,25 @@ import { CoreBetterAuthUserMapper } from '../better-auth/core-better-auth-user.m
 import { CoreBetterAuthService } from '../better-auth/core-better-auth.service';
 import { ErrorCode } from '../error-code/error-codes';
 
+/**
+ * Collection holding the bootstrap claim markers.
+ *
+ * Native collection access is intentional here: no Mongoose schema exists for it
+ * (see docs/native-driver-security.md).
+ */
+const SETUP_LOCK_COLLECTION = 'system-setup-locks';
+
+/**
+ * How long an initial-admin claim may stand before another replica takes it over.
+ *
+ * Long enough that a slow but live creation is never stolen, short enough that a crashed
+ * claimer does not lock the deployment out for good.
+ */
+const INITIAL_ADMIN_CLAIM_STALE_AFTER_MS = 5 * 60_000;
+
+/** `_id` of the marker claiming the initial-admin creation */
+const INITIAL_ADMIN_LOCK_ID = 'initial-admin';
+
 /**
  * Input for creating the initial admin user
  */
@@ -101,6 +120,10 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
       return;
     }
 
+    // The atomic claim lives in createInitialAdmin() so that BOTH entry points — this
+    // one and the anonymous POST /system-setup/init — serialize on the same marker.
+    // Claiming here as well would take the claim twice on this path and leave the
+    // public path unguarded.
     try {
       const result = await this.createInitialAdmin({
         email: initialAdmin.email,
@@ -109,8 +132,11 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
       });
       this.logger.log(`Auto-created initial admin on startup: ${result.email}`);
     } catch (error) {
+      // The claim is released by createInitialAdmin() itself, which is the only place
+      // that takes it — so a replica that crashed mid-creation cannot block setup on
+      // every future boot, and the marker has exactly one owner.
       if (error instanceof ForbiddenException) {
-        this.logger.log('Initial admin auto-creation skipped (users already exist)');
+        this.logger.log('Initial admin auto-creation skipped (users already exist or claimed elsewhere)');
       } else {
         this.logger.warn(
           `Initial admin auto-creation failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
@@ -119,6 +145,58 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
     }
   }
 
+  /**
+   * Try to claim the initial-admin creation for this instance
+   *
+   * The upsert on a fixed `_id` is atomic, so exactly one of N concurrently booting
+   * replicas sees no previous document and wins the claim.
+   *
+   * @returns true when this instance may create the initial admin
+   */
+  protected async claimInitialAdminSetup(): Promise<boolean> {
+    try {
+      const collection = this.connection.collection(SETUP_LOCK_COLLECTION);
+
+      // The marker is a CLAIM, not a permanent record: a replica SIGKILLed between claiming and
+      // creating (OOM, node drain, a failed first rollout — all ordinary) never reaches the
+      // release in the catch below. Without an expiry that leaves a deployment with zero users
+      // and no way in, recoverable only by deleting a document from an undocumented collection.
+      // A stale claim is therefore taken over rather than obeyed.
+      const staleBefore = new Date(Date.now() - INITIAL_ADMIN_CLAIM_STALE_AFTER_MS);
+      await collection.deleteOne({ _id: INITIAL_ADMIN_LOCK_ID as any, claimedAt: { $lt: staleBefore } });
+
+      const previous = await collection.findOneAndUpdate(
+        { _id: INITIAL_ADMIN_LOCK_ID as any },
+        { $setOnInsert: { claimedAt: new Date() } },
+        { returnDocument: 'before', upsert: true },
+      );
+
+      // No previous document → this instance inserted the marker and owns the setup
+      return !previous;
+    } catch (error) {
+      // Two replicas upserting the same `_id` at the very same moment: one insert wins,
+      // the other gets a duplicate key error — which means the claim is taken.
+      if (error instanceof Error && (error.message?.includes('duplicate key') || error.message?.includes('E11000'))) {
+        return false;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Remove the initial-admin claim marker so a later boot can retry the setup
+   */
+  protected async releaseInitialAdminSetupClaim(): Promise<void> {
+    try {
+      await this.connection.collection(SETUP_LOCK_COLLECTION).deleteOne({ _id: INITIAL_ADMIN_LOCK_ID as any });
+    } catch (error) {
+      // Never mask the failure that triggered the release
+      this.logger.warn(
+        `Failed to release initial admin setup claim: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+    }
+  }
+
   /**
    * Check if the system needs initial setup (zero users)
    */
@@ -153,6 +231,17 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
       throw new ForbiddenException(ErrorCode.SYSTEM_SETUP_BETTERAUTH_REQUIRED);
     }
 
+    // The count check above is check-then-act, and this method is reachable ANONYMOUSLY
+    // via POST /system-setup/init. Two concurrent callers with DIFFERENT emails both pass
+    // it and both get an admin — the E11000 handler below only catches the same-email
+    // case. The claim is the same marker the boot path uses, so the HTTP path and the
+    // auto-bootstrap also serialize against each other instead of racing: an attacker
+    // racing a fresh deployment can no longer obtain an admin account ALONGSIDE the
+    // configured one.
+    if (!(await this.claimInitialAdminSetup())) {
+      throw new ForbiddenException(ErrorCode.SYSTEM_SETUP_NOT_AVAILABLE);
+    }
+
     try {
       // Access BetterAuth internal context (same pattern as core-better-auth-api.middleware.ts)
       const context = await authInstance.$context;
@@ -208,6 +297,11 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
         success: true,
       };
     } catch (error) {
+      // Release the claim we took above: a caller that failed mid-creation must not
+      // leave a deployment with zero users and no way in. The marker is additionally
+      // stale-expiring, so this is belt AND braces for the crash-before-release case.
+      await this.releaseInitialAdminSetupClaim();
+
       // Handle duplicate email (race condition via MongoDB unique index)
       if (error instanceof Error && (error.message?.includes('duplicate key') || error.message?.includes('E11000'))) {
         throw new ForbiddenException(ErrorCode.SYSTEM_SETUP_NOT_AVAILABLE);

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

@@ -238,7 +238,7 @@ multiTenancy: {
 - **Config-change detection:** Cache is flushed when `multiTenancy` config changes (e.g., `roleHierarchy` update).
 - **Bounded:** Max 500 entries with FIFO eviction. Memory overhead: ~100-250 KB.
 
-**Important:** The cache is process-local. In horizontally scaled deployments (multiple instances), membership changes on one instance are not reflected on other instances until the TTL expires. Set `cacheTtlMs: 0` for security-sensitive deployments.
+**Important:** The cache storage itself is always process-local — every replica keeps its own map. What changed in 11.33.0 is how _invalidations_ travel: with `redis` configured they are broadcast, without it they are not (see below). A membership change that happens **outside** `invalidateUser()` / `invalidateAll()` — a direct DB write, an admin tool, a migration — is still invisible to every replica until `cacheTtlMs` expires. Set `cacheTtlMs: 0` for security-sensitive deployments.
 
 ### Manual Cache Invalidation
 
@@ -256,6 +256,26 @@ export class TenantService extends CoreTenantService {
 
 Use `invalidateAll()` to flush the entire cache (e.g., after bulk operations).
 
+Both are **instance** methods on the singleton `CoreTenantGuard` — inject it and call
+`this.tenantGuard?.invalidateUser(userId)`. There is no static equivalent.
+
+#### Cross-replica invalidation (since 11.33.0)
+
+`invalidateUser()` / `invalidateAll()` are no longer a purely local clear:
+
+| Setup                  | What happens                                                                                                                                                                                                                                       |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`redis` configured** | The local caches are cleared **and** the invalidation is published to `<keyPrefix>:tenant-cache:invalidate`. Every replica subscribed to that channel clears its own caches, so a membership change takes effect fleet-wide within one round trip. |
+| **No `redis`**         | Only the calling process clears. Other replicas keep serving the stale membership until `cacheTtlMs` expires — the pre-11.33.0 behaviour.                                                                                                          |
+
+Mechanism, for anyone extending the guard (`core-tenant.guard.ts`):
+
+- The channel is namespaced with the framework's Redis key prefix, so two applications sharing one Redis instance do not clear each other's caches. Two **stages** of the same application do, unless you set `redis.keyPrefix` or `redis.db`.
+- The message is `{ scope: 'user', userId }` or `{ scope: 'all' }`, JSON-encoded.
+- Subscription uses the shared subscriber connection from `CoreRedisService.getSubscriber()`; the listener is held in a field and detached on destroy, because that connection is shared.
+- **A received broadcast clears locally and does NOT re-publish** (`applyInvalidation()` → `clearUser()` / `clearAll()`, the no-broadcast variants). Re-publishing would bounce the message around the cluster forever.
+- **Publishing is fire-and-forget and failures are debug-level only.** A missed broadcast is not an error: it merely leaves the other replicas' caches stale until their TTL — exactly the no-Redis behaviour. Nothing about a request path depends on the broadcast succeeding.
+
 ### SkipTenantCheck
 
 For high-frequency endpoints that don't access tenant-scoped data, use `@SkipTenantCheck()` to avoid the membership lookup entirely.

package/src/core/modules/tenant/core-tenant.guard.ts

@@ -4,7 +4,9 @@ import {
   ForbiddenException,
   Injectable,
   Logger,
+  OnApplicationBootstrap,
   OnModuleDestroy,
+  Optional,
   UnauthorizedException,
 } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
@@ -14,6 +16,7 @@ import { Model } from 'mongoose';
 
 import { RoleEnum } from '../../common/enums/role.enum';
 import { ConfigService } from '../../common/services/config.service';
+import { CoreRedisService } from '../../common/services/core-redis.service';
 import { ErrorCode } from '../error-code/error-codes';
 import { CoreTenantMemberModel } from './core-tenant-member.model';
 import { SKIP_TENANT_CHECK_KEY } from './core-tenant.decorators';
@@ -42,6 +45,14 @@ interface CachedTenantIds {
   ids: string[];
 }
 
+/**
+ * Cache invalidation message broadcast between replicas via Redis pub/sub
+ */
+interface TenantCacheInvalidation {
+  scope: 'all' | 'user';
+  userId?: string;
+}
+
 /**
  * Global guard for multi-tenancy with defense-in-depth security.
  *
@@ -103,7 +114,7 @@ interface CachedTenantIds {
  *   - No user + checkable roles → 401 (authentication required)
  */
 @Injectable()
-export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
+export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnModuleDestroy {
   private readonly logger = new Logger(CoreTenantGuard.name);
 
   /**
@@ -111,6 +122,12 @@ export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
    * Key: `${userId}:${tenantId}`, Value: cached membership result with expiry.
    * Eliminates repeated DB queries for the same user+tenant combination.
    */
+  /** Channel this guard subscribed to, so it can unsubscribe again */
+  private invalidationChannel?: string;
+
+  /** The shared-subscriber listener, kept so it can be detached on destroy */
+  private invalidationListener?: (channel: string, message: string) => void;
+
   private readonly membershipCache = new Map<string, CachedMembership>();
 
   /**
@@ -131,6 +148,7 @@ export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
   constructor(
     private readonly reflector: Reflector,
     @InjectModel(TENANT_MEMBER_MODEL_TOKEN) private readonly memberModel: Model<CoreTenantMemberModel>,
+    @Optional() protected readonly redisService?: CoreRedisService,
   ) {
     // Clean up expired cache entries every 60 seconds
     this.cleanupInterval = setInterval(() => this.evictExpired(), 60_000);
@@ -139,7 +157,50 @@ export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
     }
   }
 
+  /**
+   * Subscribe to the cross-replica cache invalidation channel.
+   *
+   * Runs after ALL onModuleInit hooks so that CoreRedisService is connected.
+   * Without Redis this is a no-op and the caches stay process-local.
+   */
+  async onApplicationBootstrap(): Promise<void> {
+    if (!this.redisService?.enabled) {
+      return;
+    }
+    const channel = this.redisService.key('tenant-cache', 'invalidate');
+    try {
+      const subscriber = this.redisService.getSubscriber();
+      // Held in a field, not an anonymous closure: the subscriber connection is SHARED between
+      // features, so a listener that is never detached keeps dispatching into a destroyed
+      // guard's caches for the life of the process — and a second app in the same process
+      // inherits the previous one's listener alongside its own.
+      this.invalidationChannel = channel;
+      this.invalidationListener = (incomingChannel: string, message: string) => {
+        if (incomingChannel === channel) {
+          this.applyInvalidation(message);
+        }
+      };
+      subscriber.on('message', this.invalidationListener);
+      await subscriber.subscribe(channel);
+    } catch (error) {
+      this.logger.debug(`Tenant cache invalidation subscribe failed: ${(error as Error).message}`);
+    }
+  }
+
   onModuleDestroy(): void {
+    if (this.invalidationListener) {
+      try {
+        const subscriber = this.redisService?.getSubscriber();
+        subscriber?.off('message', this.invalidationListener);
+        if (this.invalidationChannel) {
+          void subscriber?.unsubscribe(this.invalidationChannel).catch(() => undefined);
+        }
+      } catch {
+        // Redis already gone — nothing to detach from
+      }
+      this.invalidationListener = undefined;
+    }
+
     if (this.cleanupInterval) {
       clearInterval(this.cleanupInterval);
       this.cleanupInterval = null;
@@ -152,31 +213,28 @@ export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
    * Invalidate all cache entries for a specific user.
    * Call this when memberships change (add/remove/update).
    *
+   * When Redis is enabled, the invalidation is additionally broadcast to all other
+   * replicas — otherwise their process-local caches would stay stale for up to cacheTtlMs.
+   *
    * Note: userId must not contain ':' characters (used as cache key delimiter).
    * MongoDB ObjectIds and standard UUID formats are safe.
    *
    * @param userId - The user ID whose cache entries should be invalidated
    */
   invalidateUser(userId: string): void {
-    for (const key of this.membershipCache.keys()) {
-      if (key.startsWith(`${userId}:`)) {
-        this.membershipCache.delete(key);
-      }
-    }
-    for (const key of this.tenantIdsCache.keys()) {
-      if (key === userId || key.startsWith(`${userId}:`)) {
-        this.tenantIdsCache.delete(key);
-      }
-    }
+    this.clearUser(userId);
+    this.publishInvalidation({ scope: 'user', userId });
   }
 
   /**
    * Clear all cache entries.
    * Useful when configuration changes (e.g., roleHierarchy) or for testing.
+   *
+   * When Redis is enabled, the invalidation is additionally broadcast to all other replicas.
    */
   invalidateAll(): void {
-    this.membershipCache.clear();
-    this.tenantIdsCache.clear();
+    this.clearAll();
+    this.publishInvalidation({ scope: 'all' });
   }
 
   async canActivate(context: ExecutionContext): Promise<boolean> {
@@ -192,7 +250,8 @@ export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
       const isTestEnv =
         process.env.VITEST === 'true' || process.env.NODE_ENV === 'test' || process.env.NODE_ENV === 'e2e';
       this.cacheTtlMs = config.cacheTtlMs ?? (isTestEnv ? 0 : 30_000);
-      this.invalidateAll();
+      // Local-only flush: every replica detects the config change itself, no broadcast needed
+      this.clearAll();
     }
 
     const request = this.getRequest(context);
@@ -494,6 +553,68 @@ export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
   // Cache helpers
   // ===================================================================================================================
 
+  /**
+   * Apply an invalidation message received from another replica.
+   * Clears locally only — re-publishing would bounce the message around the cluster.
+   */
+  protected applyInvalidation(message: string): void {
+    let parsed: TenantCacheInvalidation;
+    try {
+      parsed = JSON.parse(message);
+    } catch {
+      this.logger.debug(`Ignoring malformed tenant cache invalidation message: ${message}`);
+      return;
+    }
+    if (parsed?.scope === 'all') {
+      this.clearAll();
+    } else if (parsed?.scope === 'user' && parsed.userId) {
+      this.clearUser(parsed.userId);
+    }
+  }
+
+  /**
+   * Clear both caches locally (no broadcast)
+   */
+  protected clearAll(): void {
+    this.membershipCache.clear();
+    this.tenantIdsCache.clear();
+  }
+
+  /**
+   * Remove all entries of a user from both caches locally (no broadcast)
+   */
+  protected clearUser(userId: string): void {
+    for (const key of this.membershipCache.keys()) {
+      if (key.startsWith(`${userId}:`)) {
+        this.membershipCache.delete(key);
+      }
+    }
+    for (const key of this.tenantIdsCache.keys()) {
+      if (key === userId || key.startsWith(`${userId}:`)) {
+        this.tenantIdsCache.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Broadcast an invalidation to the other replicas (fire-and-forget).
+   * No-op without Redis; failures are logged at debug level only — a missed
+   * broadcast merely leaves the other replicas' caches stale until their TTL.
+   */
+  protected publishInvalidation(message: TenantCacheInvalidation): void {
+    if (!this.redisService?.enabled) {
+      return;
+    }
+    try {
+      void this.redisService
+        .getClient()
+        .publish(this.redisService.key('tenant-cache', 'invalidate'), JSON.stringify(message))
+        .catch((error: Error) => this.logger.debug(`Tenant cache invalidation publish failed: ${error.message}`));
+    } catch (error) {
+      this.logger.debug(`Tenant cache invalidation publish failed: ${(error as Error).message}`);
+    }
+  }
+
   /**
    * Look up a membership with process-level TTL cache.
    * Avoids repeated DB queries when the same user accesses the same tenant repeatedly.

package/src/core/modules/tenant/core-tenant.module.ts

@@ -75,10 +75,14 @@ export class CoreTenantModule {
         provide: CoreTenantService,
         useClass: Service,
       },
-      {
-        provide: APP_GUARD,
-        useClass: Guard,
-      },
+      // Registered under its OWN token first, then aliased to APP_GUARD — the pattern
+      // CoreAuthModule uses for RolesGuard. A bare `{ provide: APP_GUARD, useClass: Guard }`
+      // makes Nest mint an internal token for the instance, so `@Optional() CoreTenantGuard`
+      // in CoreTenantService resolves to undefined and every invalidateUser()/invalidateAll()
+      // — including the cross-replica Redis broadcast — silently did nothing.
+      Guard,
+      ...(Guard === CoreTenantGuard ? [] : [{ provide: CoreTenantGuard, useExisting: Guard }]),
+      { provide: APP_GUARD, useExisting: Guard },
     ];
 
     // When a custom model name is used, alias the default injection token to the custom model.

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

@@ -2,18 +2,61 @@
 
 **For customizing TUS uploads in projects using `@lenne.tech/nest-server`.**
 
-> **Note:** TUS is **enabled by default** with no configuration needed. This checklist is only for projects that need to customize behavior (e.g., require authentication).
+> **Note:** TUS is **enabled by default** with no configuration needed. This checklist is only for projects that need to customize behavior (e.g., widen or narrow who may upload).
+
+> **Since 11.33.0 uploads require a signed-in user.** `tus.roles` defaults to `[RoleEnum.S_USER]`; it used to be `S_EVERYONE`. If your project accepts attachments on a public form, you must opt back in explicitly — see Step 0.
 
 ---
 
 ## Do You Need This Checklist?
 
-| Scenario                                     | Checklist Needed?                                    |
-| -------------------------------------------- | ---------------------------------------------------- |
-| Use TUS with defaults (everyone can upload)  | No - works automatically                             |
-| Require authentication for uploads           | Yes - Step 1                                         |
-| Custom upload handling (notifications, etc.) | Yes - Step 2                                         |
-| Disable TUS completely                       | No - just use `TusModule.forRoot({ config: false })` |
+| Scenario                                           | Checklist Needed?                                    |
+| -------------------------------------------------- | ---------------------------------------------------- |
+| Use TUS with defaults (signed-in users may upload) | No - works automatically                             |
+| **Allow anonymous uploads** (public form)          | **Yes - Step 0** (the default no longer allows this) |
+| Restrict uploads to specific roles                 | Yes - Step 0                                         |
+| Custom upload handling (notifications, etc.)       | Yes - Step 2                                         |
+| Hard-code a policy that config must NOT change     | Yes - Step 1                                         |
+| Disable TUS completely                             | No - just use `TusModule.forRoot({ config: false })` |
+
+---
+
+## Step 0: Configure `tus.roles` (Who May Upload)
+
+This is the normal way to set TUS permissions — no controller subclass needed.
+
+```typescript
+// src/config.env.ts
+tus: {
+  roles: [RoleEnum.S_USER],          // default since 11.33.0
+  // roles: [RoleEnum.S_EVERYONE],   // opt back in to anonymous uploads (public form)
+  // roles: ['editor', 'contributor'], // project-specific roles work too
+},
+```
+
+Plain role **strings**, exactly like a hand-written `@Roles()` call, so project roles work alongside
+the `RoleEnum` system roles.
+
+**Three properties worth knowing:**
+
+1. **`roles: []` is rejected**, with a warning, and the default applies. An all-empty role set reads
+   to the guards as "no roles required" and returns `true` — honouring it literally would _open_ the
+   endpoints, the exact opposite of what someone writing `[]` intends. Same for a non-array or an
+   array holding a non-string.
+
+2. **`OPTIONS` stays public regardless.** `handleTusOptions` / `handleTusOptionsWithId` keep their
+   own `@Roles(RoleEnum.S_EVERYONE)`, because that is the CORS preflight — browsers send it
+   **without credentials**, and it returns server capabilities only. Gating it would make every
+   browser upload fail before the first byte.
+
+3. **Pair it with the file roles.** A TUS upload lands in the same store `file.downloadRoles`
+   guards (default `[RoleEnum.ADMIN]`), so with both at their defaults a signed-in user may upload
+   but cannot read the result back. Either widen `file.downloadRoles`, or write an owner into the
+   metadata at upload time and authorize per file in `CoreFileService.checkRights()`. TUS uploads
+   already carry `metadata.tusUploadId` plus the original TUS metadata.
+
+**Verify:** `curl -X OPTIONS <baseUrl>/tus` still answers `204` with the TUS capability headers,
+while `POST /tus` without a token answers `401`.
 
 ---
 
@@ -30,22 +73,42 @@ https://github.com/lenneTech/nest-server/tree/develop/src/server
 
 ---
 
-## Step 1: Custom Controller (Require Authentication)
+## Step 1: Custom Controller (Custom Upload Logic)
+
+> Only needed for custom handler behaviour. For "who may upload", use Step 0 — it needs no subclass.
 
 **Create:** `src/server/modules/tus/tus.controller.ts`
 
 ```typescript
 import { Controller } from '@nestjs/common';
-import { CoreTusController, Roles, RoleEnum } from '@lenne.tech/nest-server';
+import { CoreTusController } from '@lenne.tech/nest-server';
 
 @Controller('tus')
-@Roles(RoleEnum.S_USER) // Require authenticated user
 export class TusController extends CoreTusController {
-  // All methods inherit the S_USER requirement
-  // Override methods here for custom logic
+  // Inherits the handlers; `tus.roles` from config applies to them.
+  // Override methods here for custom logic.
 }
 ```
 
+**How `tus.roles` reaches a custom controller — and why you should not fight it with `@Roles()`:**
+
+`TusModule.forRoot()` calls `applyRoles()` on the class it actually registers, writing the configured
+roles onto that class **and** onto its `handleTus` / `handleTusWithId`, resolved through the
+prototype chain. `forRoot()` runs after the controller's decorators have been evaluated, so it wins:
+
+| You write on the subclass                            | Effective at runtime                                                                                                   |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Nothing                                              | `tus.roles` (config)                                                                                                   |
+| A class-level `@Roles(...)`                          | `tus.roles` — overwritten by `applyRoles()`                                                                            |
+| A re-declared `handleTus` with its own `@Roles(...)` | `tus.roles` — overwritten too, because `applyRoles()` writes onto whichever function `prototype.handleTus` resolves to |
+
+So `tus.roles` is the single source of truth for TUS permissions. If you need a policy that
+configuration cannot change, either give your handler a **different method name** (`applyRoles()`
+only targets `handleTus` / `handleTusWithId`), or register the controller outside `TusModule`.
+
+> This differs from the file module, where `applyFileRoles()` targets the **base** class methods by
+> name — there an override genuinely does opt out.
+
 **Update ServerModule:**
 
 ```typescript
@@ -104,6 +167,10 @@ export class TusService extends CoreTusService {
   path: '/tus',
   maxSize: 50 * 1024 * 1024 * 1024, // 50 GB
   expiration: { expiresIn: '24h' },
+  roles: [RoleEnum.S_USER],         // since 11.33.0 (was S_EVERYONE)
+  // s3Staging: true when `s3` is configured — stages in-progress uploads in
+  // s3.stagingBucket instead of on pod-local disk, so resumable uploads survive
+  // replica restarts and need no sticky sessions. Set false to force local disk.
 }
 ```
 
@@ -132,20 +199,25 @@ TusModule.forRoot({ config: false });
 
 - [ ] `npm run build` succeeds
 - [ ] `npm test` passes
-- [ ] `OPTIONS /tus` returns TUS capabilities
-- [ ] Upload via tus-js-client works
-- [ ] File appears in GridFS after upload completion
-- [ ] (If customized) Authentication is required for uploads
+- [ ] `OPTIONS /tus` returns TUS capabilities **without a token** (the CORS preflight must stay public)
+- [ ] `POST /tus` **without** a token answers `401` (or `204` if you deliberately set `roles: [S_EVERYONE]`)
+- [ ] Upload via tus-js-client works for a user holding a role from `tus.roles`
+- [ ] File appears in the configured file store after upload completion (GridFS by default; S3 or filesystem per `file.storage`)
+- [ ] The uploaded file can also be **downloaded** by its intended audience — check `file.downloadRoles` too
 
 ---
 
 ## Common Mistakes
 
-| Mistake                              | Symptom                        | Fix                                               |
-| ------------------------------------ | ------------------------------ | ------------------------------------------------- |
-| Forgot to register custom controller | Default S_EVERYONE permissions | Add `controller: TusController` to forRoot()      |
-| Custom controller missing @Roles     | No authentication required     | Add `@Roles(RoleEnum.S_USER)` to controller class |
-| Using wrong endpoint path            | 404 on upload                  | Ensure client uses same path as config            |
+| Mistake                                            | Symptom                                                   | Fix                                                                                             |
+| -------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Assuming uploads are still public (pre-11.33.0)    | `401` on the very first `POST /tus` from a public form    | `tus: { roles: [RoleEnum.S_EVERYONE] }` — Step 0                                                |
+| `tus: { roles: [] }` meaning "nobody"              | Warning in the log, default `[S_USER]` applied instead    | An empty role set would OPEN the routes; name the roles explicitly — Step 0                     |
+| Gating `OPTIONS` in a custom controller            | Every browser upload fails before the first byte          | Leave `handleTusOptions*` on `@Roles(RoleEnum.S_EVERYONE)` — the preflight sends no credentials |
+| Expecting a subclass `@Roles()` to win over config | Roles look ignored                                        | `applyRoles()` overwrites them — Step 1 table                                                   |
+| Forgot to register custom controller               | Custom handler logic never runs (core controller is used) | Add `controller: TusController` to `forRoot()`                                                  |
+| Upload succeeds but the file cannot be downloaded  | `403` on `GET /files/id/:id`                              | `file.downloadRoles` defaults to `[ADMIN]` — widen it, or authorize per file in `checkRights()` |
+| Using wrong endpoint path                          | 404 on upload                                             | Ensure client uses same path as config                                                          |
 
 ---
 

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

@@ -262,7 +262,31 @@ upload.start(); // Resumes from where it left off
 
 ### Require Authentication
 
-By default, TUS allows everyone (`S_EVERYONE`) to upload. To require authentication, create a custom controller:
+Since 11.33.0 TUS requires a signed-in caller by default (`tus.roles`, default `[S_USER]`). The
+previous default was `S_EVERYONE`, which let anonymous callers write into — and, with the
+termination extension, delete from — the same GridFS bucket the download routes guard.
+
+Set it in `config.env.ts`:
+
+```typescript
+tus: {
+  roles: [RoleEnum.S_USER];
+} // default
+tus: {
+  roles: [RoleEnum.S_EVERYONE];
+} // opt back in to anonymous uploads
+tus: {
+  roles: ['editor', 'contributor'];
+} // project-specific roles work too
+```
+
+`roles: []` is rejected with a warning rather than honoured — an all-empty role set reads to the
+guards as "no roles required" and would open the endpoints instead of closing them.
+
+`OPTIONS` stays public regardless: it is the CORS preflight, which browsers send without
+credentials, and it discloses only server capabilities.
+
+Alternatively, create a custom controller:
 
 ```typescript
 // src/server/modules/tus/tus.controller.ts
@@ -332,7 +356,7 @@ GET /files/:filename
 
 # Via GraphQL
 query {
-  file(id: "...") {
+  getFileInfo(filename: "...") {
     id
     filename
     contentType
@@ -343,6 +367,15 @@ query {
 
 **Recommendation:** Use the ID-based endpoint (`/files/id/:id`) for TUS uploads as filenames may not be unique.
 
+> **These download routes are gated.** They require `file.downloadRoles`, which defaults to
+> `[RoleEnum.ADMIN]` — while uploading here only requires `tus.roles` (default `S_USER`). So out of
+> the box a signed-in user can upload but cannot read their own file back.
+>
+> Do not fix that by widening `downloadRoles` to `S_USER`: that would let every signed-in user read
+> _every_ file in the shared bucket. Write an owner into the file metadata at upload time and
+> authorize per file in `CoreFileService.checkRights()` — see the File module's README, section
+> "Access control".
+
 ### File Metadata
 
 The following metadata is stored with each GridFS file: