@lenne.tech/nest-server 11.32.3 → 11.33.0

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:

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

@@ -1,46 +1,98 @@
-import { All, Controller, Logger, Req, Res } from '@nestjs/common';
+import { All, Controller, Logger, Options, Req, Res } from '@nestjs/common';
 import { Request, Response } from 'express';
 
 import { Roles } from '../../common/decorators/roles.decorator';
 import { RoleEnum } from '../../common/enums/role.enum';
+import { SkipTenantCheck } from '../tenant/core-tenant.decorators';
 import { CoreTusService } from './core-tus.service';
 
 /**
  * Core TUS Controller
  *
  * Handles all TUS protocol requests and delegates to the @tus/server handler.
- * This controller uses S_EVERYONE by default, allowing all users to upload.
  *
- * Projects can extend this controller to add authentication/authorization:
+ * SECURITY: requires a signed-in caller (`S_USER`) by default. Configure via
+ * `tus: { roles: [...] }` — `TusModule.forRoot()` writes the configured roles
+ * onto these handlers at module-build time, so the decorators below are the
+ * fallback for a controller built outside that path, not the effective value.
+ *
+ * The default used to be `S_EVERYONE`, which the roles guard turns into an
+ * unconditional `return true` WITHOUT authenticating. Since a tus upload writes
+ * into the same shared GridFS bucket the file download routes read from, and
+ * the termination extension is on by default, that meant anonymous callers
+ * could fill — and delete from — a store only privileged callers may read.
+ *
+ * Projects that genuinely need anonymous uploads should say so explicitly:
  *
  * @example
  * ```typescript
- * @Controller('tus')
- * @Roles(RoleEnum.S_USER) // Require authentication
- * export class TusController extends CoreTusController {
- *   // Customize as needed
- * }
+ * // config.env.ts
+ * tus: { roles: [RoleEnum.S_EVERYONE] }
  * ```
  */
+/**
+ * TENANT SCOPING: the same reasoning as `CoreFileController` — a tus upload lands in
+ * the SAME store the file routes read, and that store is reached through the native
+ * driver, so `mongooseTenantPlugin` never scopes it. Without this decorator a
+ * configured non-system `tus.roles` (e.g. `['admin']`) is resolved against
+ * `membership.role`, which would let a workspace "admin" of ANY tenant write into —
+ * and, via the termination extension, delete from — a store that has no tenant
+ * boundary at all.
+ */
 @Controller('tus')
-@Roles(RoleEnum.S_EVERYONE)
+@Roles(RoleEnum.S_USER)
+@SkipTenantCheck()
 export class CoreTusController {
   private readonly logger = new Logger(CoreTusController.name);
 
   constructor(protected readonly tusService: CoreTusService) {}
 
+  /**
+   * Answer the tus discovery / CORS preflight request.
+   *
+   * DELIBERATELY UNAUTHENTICATED, and it must stay that way: a browser sends the
+   * CORS preflight WITHOUT credentials, by specification. Gating OPTIONS behind
+   * `tus.roles` would make every browser upload fail at the preflight — the
+   * endpoint would be unreachable from a web client no matter how valid the
+   * caller's session is.
+   *
+   * Nothing is disclosed: the response carries only server capabilities
+   * (`Tus-Version`, `Tus-Extension`, `Tus-Max-Size`), never upload data or the
+   * existence of any particular upload. `roles` is not applied to this handler.
+   *
+   * Declared before the `@All()` handlers so it wins the route match.
+   */
+  @Options()
+  @Roles(RoleEnum.S_EVERYONE)
+  async handleTusOptions(@Req() req: Request, @Res() res: Response): Promise<void> {
+    return this.handleTus(req, res);
+  }
+
+  /**
+   * Answer the tus discovery / CORS preflight for an upload-specific URL.
+   *
+   * Same reasoning as {@link handleTusOptions}. `@tus/server` answers OPTIONS
+   * identically regardless of the id, so this leaks no information about whether
+   * the upload exists.
+   */
+  @Options(':id')
+  @Roles(RoleEnum.S_EVERYONE)
+  async handleTusOptionsWithId(@Req() req: Request, @Res() res: Response): Promise<void> {
+    return this.handleTus(req, res);
+  }
+
   /**
    * Handle all TUS protocol requests
    *
    * The @tus/server handles:
-   * - OPTIONS: Return server capabilities
+   * - OPTIONS: Return server capabilities (see handleTusOptions — routed separately)
    * - POST: Create new upload
    * - HEAD: Get upload status/offset
    * - PATCH: Continue upload
    * - DELETE: Terminate upload (if termination extension enabled)
    */
   @All()
-  @Roles(RoleEnum.S_EVERYONE)
+  @Roles(RoleEnum.S_USER)
   async handleTus(@Req() req: Request, @Res() res: Response): Promise<void> {
     const server = this.tusService.getServer();
 
@@ -66,7 +118,7 @@ export class CoreTusController {
    * Routes like /tus/:id for HEAD, PATCH, DELETE
    */
   @All(':id')
-  @Roles(RoleEnum.S_EVERYONE)
+  @Roles(RoleEnum.S_USER)
   async handleTusWithId(@Req() req: Request, @Res() res: Response): Promise<void> {
     const server = this.tusService.getServer();