@lenne.tech/nest-server 11.42.0 → 11.42.2

package/migration-guides/11.42.0-to-11.42.1.md

@@ -0,0 +1,66 @@
+# Migration Guide: 11.42.0 → 11.42.1
+
+## Overview
+
+| Category             | Details                                                                                       |
+| -------------------- | --------------------------------------------------------------------------------------------- |
+| **Bugfix**           | Browser uploads through TUS work with cookie authentication and separate app/API origins (§1) |
+| **New option**       | `tus.allowedOrigins` overrides the derived origins (§1)                                       |
+| **Migration Effort** | None — `pnpm update`                                                                          |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick up the core update; nothing else to change.
+
+## 1. TUS answered a credentialed request with `Access-Control-Allow-Origin: *`
+
+The tus handler writes its responses itself, past the API's CORS layer, and `@tus/server` answers
+`Access-Control-Allow-Origin: *` unless it is given `allowedOrigins`. The core gave it none. With cookie
+authentication and separate app and API origins (`lt dev up`, or `app.example.com` /
+`api.example.com`), the request is credentialed and the API adds
+`Access-Control-Allow-Credentials: true` — a combination every browser refuses:
+
+> The value of the 'Access-Control-Allow-Origin' header in the response must not be the wildcard '*'
+> when the request's credentials mode is 'include'.
+
+So every browser upload failed, while the server answered `201`. Preflights and unauthenticated
+requests were fine, which is why no test noticed — only an **authenticated** request with an `Origin`
+reaches the header.
+
+Since 11.42.1 the tus server takes its origins from `buildCorsConfig()`, the decision REST, GraphQL and
+Better-Auth already share (`appUrl`, `baseUrl`, `cors.allowedOrigins`, `cors.allowAll`), and mirrors an
+allowed `Origin`. A foreign origin gets no `Access-Control-Allow-Origin` at all. To use different
+origins for uploads:
+
+```typescript
+tus: {
+  allowedOrigins: ['https://uploads.example.com'];
+}
+```
+
+Without credentialed CORS configured — cookies off, or no origin resolvable — nothing changes; the tus
+default `*` stays.
+
+## 2. Dependencies
+
+Updated within their majors: `@modelcontextprotocol/sdk` 1.32.0, `mongoose` 9.10.4, `supertest` 7.3.1, and
+the `@aws-sdk/*` S3 packages 3.1146.0 (dev). NestJS stays on 11.
+
+`@modelcontextprotocol/sdk` 1.32.0 lets its CLIENT transports follow redirects only within the same
+origin. The framework uses the server side only, so this matters only to a project that builds its own MCP
+client transport and relied on a cross-origin redirect.
+
+## Troubleshooting
+
+| Symptom                                                                                            | Cause                                          | Fix                                                          |
+| -------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------ |
+| Browser: "must not be the wildcard '*' when the request's credentials mode is 'include'" on `/tus` | 11.42.0 or older                               | Update to 11.42.1                                            |
+| Upload from an origin that is not the app refused by CORS                                          | Origin not in `appUrl` / `cors.allowedOrigins` | Add it to `cors.allowedOrigins`, or set `tus.allowedOrigins` |
+
+## Module Documentation
+
+- [TUS README](../src/core/modules/tus/README.md) — CORS Headers

package/migration-guides/11.42.1-to-11.42.2.md

@@ -0,0 +1,53 @@
+# Migration Guide: 11.42.1 → 11.42.2
+
+## Overview
+
+| Category             | Details                                                                  |
+| -------------------- | ------------------------------------------------------------------------ |
+| **Bugfix**           | Finished TUS uploads answer 204 behind the `compression` middleware (§1) |
+| **Migration Effort** | None — `pnpm update`                                                     |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick up the core update; nothing else to change.
+
+## 1. A finished TUS upload never got an answer although the file was stored
+
+`@tus/server` finishes its responses with `res.end(callback)`, a documented Node signature. The
+`compression` middleware patches `res.end(chunk, encoding)` and treats the first argument as a chunk,
+so the callback reached `Buffer.byteLength()` and threw:
+
+```
+TypeError [ERR_INVALID_ARG_TYPE]: The first argument must be of type string or an instance of Buffer … Received function
+```
+
+The starter's `main.ts` — and therefore every generated project — registers `compression` with
+`filter: () => true` and `threshold: 0`, which removes the two checks that would otherwise skip a
+bodyless 204. The failure hit the final `PATCH`, AFTER the upload had been migrated into the file
+store: the request hung — the headers were already sent, so no error response could follow — the
+client never saw a 2xx, `tus-js-client` never fired `onSuccess`, and no log named `compression`.
+
+Since 11.42.2 `CoreTusService` normalises `res.end(callback)` before the tus server writes
+(`normalizeEndCallback()`, wrapped around `getServer().handle()`), so it holds for the core controller
+and for any project controller that calls the tus server. No change to `main.ts` is needed; a project
+that worked around it by excluding `/tus` from the compression filter can keep or drop that filter.
+
+## 2. TUS request errors are logged with their stack
+
+`CoreTusController` logged only `error.message` for a failed TUS request. A `TypeError` thrown by a
+middleware's patched `res.end` then read like a tus failure, with nothing pointing at the middleware —
+the defect in §1 took several rounds to find for exactly that reason. The stack is now logged too.
+
+## Troubleshooting
+
+| Symptom                                                                                | Cause                                 | Fix               |
+| -------------------------------------------------------------------------------------- | ------------------------------------- | ----------------- |
+| File stored, final PATCH never answers (request hangs), `Received function` in the log | 11.42.1 or older behind `compression` | Update to 11.42.2 |
+
+## Module Documentation
+
+- [TUS README](../src/core/modules/tus/README.md) — Troubleshooting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.42.0",
+  "version": "11.42.2",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -92,7 +92,7 @@
     "@apollo/server": "5.5.1",
     "@as-integrations/express5": "1.1.2",
     "@getbrevo/brevo": "6.0.3",
-    "@modelcontextprotocol/sdk": "1.31.0",
+    "@modelcontextprotocol/sdk": "1.32.0",
     "@nestjs/apollo": "13.4.5",
     "@nestjs/common": "11.2.7",
     "@nestjs/core": "11.2.7",
@@ -126,7 +126,7 @@
     "json-to-graphql-query": "2.3.0",
     "lodash": "4.18.1",
     "mongodb": "7.6.0",
-    "mongoose": "9.10.3",
+    "mongoose": "9.10.4",
     "multer": "2.4.0",
     "node-mailjet": "6.0.11",
     "nodemailer": "10.0.13",
@@ -135,7 +135,7 @@
     "reflect-metadata": "0.2.2",
     "rfdc": "1.4.1",
     "rxjs": "7.8.2",
-    "supertest": "7.3.0",
+    "supertest": "7.3.1",
     "ts-morph": "28.0.0",
     "undici": "7.30.0",
     "ws": "8.21.3",
@@ -182,9 +182,9 @@
     }
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "3.1145.0",
-    "@aws-sdk/lib-storage": "3.1145.0",
-    "@aws-sdk/s3-request-presigner": "3.1145.0",
+    "@aws-sdk/client-s3": "3.1146.0",
+    "@aws-sdk/lib-storage": "3.1146.0",
+    "@aws-sdk/s3-request-presigner": "3.1146.0",
     "@better-auth/core": "1.7.7",
     "@better-auth/passkey": "1.7.7",
     "@compodoc/compodoc": "2.0.0",

package/src/core/common/interfaces/server-options.interface.ts

@@ -3606,6 +3606,23 @@ export interface ITusConfig {
    */
   allowedHeaders?: string[];
 
+  /**
+   * Origins the tus handler may answer a cross-origin request with (`Access-Control-Allow-Origin`).
+   *
+   * Unset, they come from the API's own CORS configuration — `buildCorsConfig()`, the function REST,
+   * GraphQL and Better-Auth share (`appUrl`, `baseUrl`, `cors.allowedOrigins`, `cors.allowAll`).
+   * Without credentialed CORS configured (cookies off, or no origin resolvable) the tus server keeps
+   * its own default, `*`.
+   *
+   * The wildcard is what broke browser uploads with cookie authentication and separate app/API
+   * origins before 11.42.1: a credentialed response with `Access-Control-Allow-Origin: *` is refused
+   * by every browser, although the server answered 201.
+   *
+   * @default undefined (derived from the API CORS configuration)
+   * @since 11.42.1
+   */
+  allowedOrigins?: string[];
+
   /**
    * Allowed MIME types for uploads.
    * If undefined, all types are allowed.

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

@@ -107,6 +107,17 @@ The TUS server automatically handles CORS headers for browser-based clients:
 - `Upload-Offset`
 - `Upload-Metadata`
 
+**`Access-Control-Allow-Origin` follows the API's CORS configuration (11.42.1+).** The tus handler
+writes its responses itself, and without `allowedOrigins` `@tus/server` answers `*`. With cookie
+authentication and separate app and API origins the request is credentialed, and every browser
+refuses `*` there — uploads failed in the browser although the server answered 201. The origins now
+come from `buildCorsConfig()` (`appUrl`, `baseUrl`, `cors.allowedOrigins`, `cors.allowAll`), the same
+decision REST, GraphQL and Better-Auth make; `tus.allowedOrigins` overrides. Without credentialed CORS
+(cookies off, or no origin resolvable) the tus default `*` stays.
+
+The preflight (`OPTIONS`) is answered by Nest's CORS layer and was never affected — test an
+**authenticated** request with an `Origin` header when checking this.
+
 ---
 
 ## Configuration
@@ -515,6 +526,21 @@ from elsewhere (an API key, a signed form token), or to let a support role resum
 2. Verify MongoDB connection is established
 3. Check server logs for initialization errors
 
+### Upload is stored but the client never sees success (fixed in 11.42.2)
+
+**Symptom:** the file appears in the file store (`Upload … migrated to …` in the log), but the final
+`PATCH` never answers (the request hangs: the headers are already sent, so no error response can
+follow), `tus-js-client` never fires `onSuccess`, and the log shows
+`ERR_INVALID_ARG_TYPE … Received function`.
+
+**Cause:** `@tus/server` finishes its responses with `res.end(callback)`, and the `compression`
+middleware patches `res.end(chunk, encoding)` and reads the callback as a chunk. The starter registers
+`compression` with `filter: () => true` and `threshold: 0`, so it also handles the bodyless 204.
+
+**Solution:** update to 11.42.2 — `CoreTusService` normalises `res.end(callback)` before the tus
+server writes (`normalizeEndCallback()`), for the core controller and any project controller that
+calls `getServer().handle()`. No change to `main.ts` is needed.
+
 ### Upload stalls or fails to resume
 
 **Cause:** Upload expired or server restarted

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

@@ -105,7 +105,9 @@ export class CoreTusController {
     try {
       await server.handle(req, res);
     } catch (error) {
-      this.logger.error(`TUS request error: ${error.message}`);
+      // The stack, not just the message: a TypeError from a middleware's patched `res.end` reads
+      // like a tus failure without it, and that cost a project several rounds of diagnosis (11.42.2).
+      this.logger.error(`TUS request error: ${error.message}`, error?.stack);
       if (!res.headersSent) {
         res.status(500).json({ message: 'Upload error' });
       }
@@ -131,7 +133,7 @@ export class CoreTusController {
     try {
       await server.handle(req, res);
     } catch (error) {
-      this.logger.error(`TUS request error for upload ${req.params.id}: ${error.message}`);
+      this.logger.error(`TUS request error for upload ${req.params.id}: ${error.message}`, error?.stack);
       if (!res.headersSent) {
         res.status(500).json({ message: 'Upload error' });
       }

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

@@ -9,6 +9,7 @@ import { Readable } from 'stream';
 
 import { GridFSHelper } from '../../common/helpers/gridfs.helper';
 import { ITusConfig } from '../../common/interfaces/server-options.interface';
+import { buildCorsConfig } from '../../common/helpers/cookies.helper';
 import { ConfigService } from '../../common/services/config.service';
 import { CoreRedisService } from '../../common/services/core-redis.service';
 import { CoreS3Service } from '../../common/services/core-s3.service';
@@ -53,6 +54,9 @@ export interface CoreTusServiceOptions {
   s3Service?: CoreS3Service;
 }
 
+/** Marks a response whose `end()` was already normalised (see `normalizeEndCallback()`). */
+const END_CALLBACK_NORMALIZED = Symbol('tusEndCallbackNormalized');
+
 /**
  * Core TUS Service
  *
@@ -638,6 +642,46 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
     return { metadata };
   }
 
+  /**
+   * The origins the tus handler may answer a cross-origin request with — or `undefined` to keep the
+   * tus server's own default (`*`).
+   *
+   * The tus handler writes its responses itself, past the API's CORS layer, and without
+   * `allowedOrigins` @tus/server sets `Access-Control-Allow-Origin: *`. On a credentialed request —
+   * cookie authentication with separate app and API origins — every browser refuses that, so no
+   * browser upload could succeed although the server answered 201. Preflights and 401s were fine
+   * (Nest answers those), which is why nothing noticed: only an AUTHENTICATED request reaches it.
+   *
+   * Taken from `tus.allowedOrigins` when set, else from `buildCorsConfig()` — the same decision REST,
+   * GraphQL and Better-Auth make. Without credentialed CORS configured the previous default stays.
+   */
+  protected resolveCorsOrigins(): ((origin: string) => boolean) | undefined {
+    const toOrigin = (value: string): string => {
+      try {
+        return new URL(value).origin;
+      } catch {
+        return value;
+      }
+    };
+    const fromList = (list: string[]) => {
+      const allowed = new Set(list.filter((entry) => typeof entry === 'string').map(toOrigin));
+      return (origin: string) => allowed.has(toOrigin(origin));
+    };
+
+    if (Array.isArray(this.config.allowedOrigins) && this.config.allowedOrigins.length) {
+      return fromList(this.config.allowedOrigins);
+    }
+    const options = this.options?.configService?.configFastButReadOnly ?? ConfigService.configFastButReadOnly ?? {};
+    const cors = buildCorsConfig(options);
+    if (cors.credentials !== true) {
+      return undefined;
+    }
+    if (cors.origin === true) {
+      return () => true;
+    }
+    return Array.isArray(cors.origin) ? fromList(cors.origin as string[]) : undefined;
+  }
+
   /**
    * The VALIDATED tenant a new upload belongs to, or `undefined`.
    *
@@ -716,8 +760,12 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
     // correct for the single-replica deployment that configuration describes.
     const locker = this.createLocker();
 
+    const cors = this.resolveCorsOrigins();
     const server = new Server({
       allowedHeaders: this.config.allowedHeaders || DEFAULT_TUS_ALLOWED_HEADERS,
+      // Without these, @tus/server answers every request with `Access-Control-Allow-Origin: *`,
+      // which a browser refuses on a credentialed (cookie) request — see resolveCorsOrigins().
+      ...(cors ? { allowedCredentials: true, allowedOrigins: cors } : {}),
       datastore,
       ...(locker ? { locker } : {}),
       maxSize: this.config.maxSize,
@@ -749,9 +797,66 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
       respectForwardedHeaders: true,
     });
 
+    // Every caller of getServer().handle() — the core controller and any project controller — gets
+    // the response normalised before @tus/server writes to it. See normalizeEndCallback().
+    const handle = server.handle.bind(server);
+    server.handle = (req, res) => {
+      this.normalizeEndCallback(res);
+      return handle(req, res);
+    };
+
     return server;
   }
 
+  /**
+   * Makes `res.end(callback)` safe for middlewares that patch `res.end` with the old two-argument form.
+   *
+   * @tus/server finishes its responses through srvx with `res.end(callback)` — a documented Node
+   * signature. `compression` (and any middleware written like it) patches `res.end(chunk, encoding)`
+   * and treats the first argument as a chunk unconditionally, so the callback reaches
+   * `Buffer.byteLength()` and throws `ERR_INVALID_ARG_TYPE ... Received function`. The starter
+   * registers `compression` with `filter: () => true, threshold: 0`, which removes the checks that
+   * would otherwise skip a bodyless 204, so every finished upload failed AFTER the file had been
+   * stored: the client never saw a 2xx and retried an upload that was already complete.
+   *
+   * The wrapper moves a function argument into the callback slot and runs it on `finish`, which is
+   * what Node itself does with it — or on `close`, so a connection dropped after `end()` resolves srvx
+   * too. A response destroyed before `end()` stays unresolved, exactly as with plain Node.
+   * Idempotent per response. Protected so a project can widen it.
+   */
+  protected normalizeEndCallback(res: any): void {
+    if (!res || typeof res.end !== 'function' || res[END_CALLBACK_NORMALIZED]) {
+      return;
+    }
+    const end = res.end;
+    res.end = function normalizedEnd(this: any, chunk?: unknown, encoding?: unknown, callback?: unknown) {
+      if (typeof chunk === 'function') {
+        callback = chunk;
+        chunk = undefined;
+        encoding = undefined;
+      } else if (typeof encoding === 'function') {
+        callback = encoding;
+        encoding = undefined;
+      }
+      if (typeof callback === 'function') {
+        let called = false;
+        const done = () => {
+          if (!called) {
+            called = true;
+            (callback as () => void)();
+          }
+        };
+        this.once('finish', done);
+        this.once('close', done);
+      }
+      if (chunk === undefined) {
+        return end.call(this);
+      }
+      return encoding === undefined ? end.call(this, chunk) : end.call(this, chunk, encoding);
+    };
+    res[END_CALLBACK_NORMALIZED] = true;
+  }
+
   /**
    * Parse TUS metadata into object
    * @tus/server v2 already parses metadata into an object

package/src/core/modules/tus/interfaces/tus-config.interface.ts

@@ -31,13 +31,16 @@ export const DEFAULT_TUS_ALLOWED_HEADERS: string[] = [];
  * Default TUS configuration
  */
 export const DEFAULT_TUS_CONFIG: Required<
-  Omit<ITusConfig, 'allowedTypes' | 'creation' | 'expiration'> & {
+  Omit<ITusConfig, 'allowedOrigins' | 'allowedTypes' | 'creation' | 'expiration'> & {
+    allowedOrigins: undefined;
     allowedTypes: undefined;
     creation: boolean;
     expiration: ITusExpirationConfig;
   }
 > = {
   allowedHeaders: DEFAULT_TUS_ALLOWED_HEADERS,
+  // Derived from the API CORS configuration (CoreTusService.resolveCorsOrigins())
+  allowedOrigins: undefined,
   allowedTypes: undefined,
   checksum: true,
   concatenation: true,