@lenne.tech/nest-server 11.42.1 → 11.42.3

package/src/core/common/helpers/graphql-ws-context.helper.ts

@@ -5,9 +5,15 @@
 // `graphql-upload` and `lodash` for the same reason.
 import graphql = require('graphql');
 
-import { getTenantContextResolver } from '../services/core-tenant-context.registry';
-import { ConfigService } from '../services/config.service';
+import { getTenantContextResolver, ResolvedTenantContext } from '../services/core-tenant-context.registry';
 import { IRequestContext, RequestContext } from '../services/request-context.service';
+import {
+  ensureWsConnectionCurrent,
+  getWsConnection,
+  noteWsConnectionTenant,
+  readWsTenantHeader,
+  WsConnection,
+} from './graphql-ws-connection.helper';
 
 /**
  * A `RequestContext` for GraphQL operations that arrive over a WEBSOCKET.
@@ -39,6 +45,12 @@ import { IRequestContext, RequestContext } from '../services/request-context.ser
  * only around the `subscribe()` call therefore covers the initial subscribe and nothing else: the
  * store is gone by the time the first message is delivered. Wrapping `next()` (and `return`/`throw`)
  * is what puts every delivered message inside the context.
+ *
+ * AND THE CONTEXT IS RE-CHECKED (11.42.3). A context built here is a snapshot of the connection's
+ * rights. For a connection registered with `registerWsConnection()` — every connection `CoreModule`'s
+ * own `onConnect` accepts — each operation and each delivered event first asks
+ * `ensureWsConnectionCurrent()` whether that snapshot still holds, and a connection whose rights
+ * changed is closed instead of served. See `graphql-ws-connection.helper.ts`.
  */
 
 /** Minimal shape of what graphql-js `execute`/`subscribe` receive. */
@@ -58,21 +70,12 @@ type ExecuteFn = (args: GraphQlArgs) => any;
  * and the raw upgrade request is the fallback for a project with a custom `onConnect` that forwards
  * neither. Header names are matched case-insensitively — `connectionParams` are client-supplied JSON
  * and arrive with whatever casing the client used, unlike Node's lower-cased HTTP headers.
+ *
+ * Lives in `graphql-ws-connection.helper.ts`, because a connection's re-check has to resolve the
+ * tenant from exactly the same header this does.
  */
 function readTenantHeader(contextValue: any): string | undefined {
-  const headerName = (ConfigService.configFastButReadOnly?.multiTenancy?.headerName ?? 'x-tenant-id').toLowerCase();
-  const sources = [contextValue?.headers, contextValue?.connectionParams, contextValue?.request?.headers];
-  for (const source of sources) {
-    if (!source || typeof source !== 'object') {
-      continue;
-    }
-    for (const [key, value] of Object.entries(source as Record<string, unknown>)) {
-      if (key.toLowerCase() === headerName && typeof value === 'string' && value) {
-        return value;
-      }
-    }
-  }
-  return undefined;
+  return readWsTenantHeader(contextValue);
 }
 
 /** The user the connection authenticated as, as `CoreModule`'s `onConnect` recorded it. */
@@ -109,28 +112,83 @@ export async function buildWsRequestContext(contextValue: any): Promise<IRequest
     // A failure here must NOT be answered with an unscoped context — that is the leak this file
     // exists to close. Leaving the tenant fields unset makes the plugin's safety net refuse
     // tenant-scoped reads, which is the safe direction.
+    let resolved: ResolvedTenantContext = {};
     try {
-      Object.assign(context, await resolver.resolve(user, readTenantHeader(contextValue)));
+      resolved = (await resolver.resolve(user, readTenantHeader(contextValue))) ?? {};
+      Object.assign(context, resolved);
     } catch {
       // Intentionally swallowed: see above. Non-tenant operations keep working.
     }
+
+    // The first operation fixes the connection's tenant scope; a later one that resolves a different
+    // scope closes the connection, because subscriptions already running on it still carry the old
+    // one (see noteWsConnectionTenant()).
+    const connection = getWsConnection(contextValue);
+    if (connection) {
+      noteWsConnectionTenant(connection, resolved);
+    }
   }
 
   return context;
 }
 
+/**
+ * What an operation on a connection whose authorization no longer holds receives instead of being
+ * executed. The socket is closed at the same moment, so a client normally sees the close first; this
+ * matters for a connection without a socket to close.
+ */
+function refusedResult(): { errors: InstanceType<typeof graphql.GraphQLError>[] } {
+  return {
+    errors: [
+      new graphql.GraphQLError('The authorization of this connection changed — reconnect.', {
+        extensions: { code: 'FORBIDDEN' },
+      }),
+    ],
+  };
+}
+
+/**
+ * Re-check a registered connection before an operation runs on it. `true` for an unregistered
+ * connection — a project's own `onConnect` that does not register keeps the previous behaviour.
+ */
+async function connectionStillAuthorized(contextValue: any): Promise<boolean> {
+  const connection = getWsConnection(contextValue);
+  return connection ? ensureWsConnectionCurrent(connection) : true;
+}
+
 /**
  * Run an AsyncIterator's pulls inside `context`.
  *
  * `next()` is where graphql-js executes the per-event selection set, so this is what carries the
  * context into every delivered message rather than only into the initial subscribe.
+ *
+ * With a `connection`, every executed event is held back until `ensureWsConnectionCurrent()` confirms
+ * the connection's rights still hold. One that no longer holds is DROPPED and the stream ends — the
+ * event was computed under the old context, so delivering it would hand out exactly what was revoked.
+ * The check comes after the execution because the event only exists once graphql-js produced it; a
+ * check at pull time would be hours early for a quiet subscription.
  */
 export function withRequestContextAsyncIterator<T>(
   iterator: AsyncIterator<T> & { [Symbol.asyncIterator]?: () => AsyncIterator<T> },
   context: IRequestContext,
+  connection?: WsConnection,
 ): AsyncIterableIterator<T> {
+  const next = (...args: [] | [undefined]) => RequestContext.run(context, () => iterator.next(...(args as [])));
   const wrapped: AsyncIterableIterator<T> = {
-    next: (...args: [] | [undefined]) => RequestContext.run(context, () => iterator.next(...(args as []))),
+    next: connection
+      ? async (...args: [] | [undefined]) => {
+          const result = await next(...args);
+          if (result.done || (await ensureWsConnectionCurrent(connection))) {
+            return result;
+          }
+          try {
+            await RequestContext.run(context, () => iterator.return?.());
+          } catch {
+            // The source is being torn down anyway; nothing to report.
+          }
+          return { done: true, value: undefined } as IteratorResult<T>;
+        }
+      : next,
     [Symbol.asyncIterator]() {
       return wrapped;
     },
@@ -156,10 +214,16 @@ function isAsyncIterable(value: any): boolean {
  */
 export function createRequestContextAwareExecute(execute: ExecuteFn): ExecuteFn {
   return async (args: GraphQlArgs) => {
+    if (!(await connectionStillAuthorized(args?.contextValue))) {
+      return refusedResult();
+    }
     const context = await buildWsRequestContext(args?.contextValue);
     if (!context) {
       return execute(args);
     }
+    if (getWsConnection(args?.contextValue)?.terminated) {
+      return refusedResult();
+    }
     return RequestContext.run(context, () => execute(args));
   };
 }
@@ -167,12 +231,21 @@ export function createRequestContextAwareExecute(execute: ExecuteFn): ExecuteFn
 /** Wrap graphql-js `subscribe` so both the subscribe AND every delivered message run in a context. */
 export function createRequestContextAwareSubscribe(subscribe: ExecuteFn): ExecuteFn {
   return async (args: GraphQlArgs) => {
+    if (!(await connectionStillAuthorized(args?.contextValue))) {
+      return refusedResult();
+    }
     const context = await buildWsRequestContext(args?.contextValue);
     if (!context) {
       return subscribe(args);
     }
+    const connection = getWsConnection(args?.contextValue);
+    if (connection?.terminated) {
+      return refusedResult();
+    }
     const result = await RequestContext.run(context, () => subscribe(args));
-    return isAsyncIterable(result) ? withRequestContextAsyncIterator(result as AsyncIterator<any>, context) : result;
+    return isAsyncIterable(result)
+      ? withRequestContextAsyncIterator(result as AsyncIterator<any>, context, connection)
+      : result;
   };
 }
 

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

@@ -1490,8 +1490,9 @@ export interface IMultiTenancy {
    * - tenant API tokens: **403**
    * - public (`S_EVERYONE`) routes: not blocked, but no tenant context is set
    * - no header: the tenant is dropped from the user's tenant list, so its data stays out of reach
-   * - GraphQL over WebSocket: no tenant is resolved for a NEW subscription; one already open keeps
-   *   its tenant until the client reconnects (as it does after a removed membership)
+   * - GraphQL over WebSocket: no tenant is resolved for a NEW subscription; one already open is
+   *   closed (4403) once `invalidateTenant()` is called, or at its next event after
+   *   `graphQl.subscriptionRevalidationMs` without it (since 11.42.3)
    *
    * A platform administrator under `adminBypass` still reaches the tenant — somebody has to be able to
    * look into it and switch it back on.
@@ -2567,6 +2568,35 @@ export interface IServerOptions {
          * Module options (forRootAsync)
          */
         options?: GqlModuleAsyncOptions;
+
+        /**
+         * How long an open GraphQL WebSocket connection may go without re-checking its authorization,
+         * in milliseconds.
+         *
+         * A WebSocket is authorized at the handshake. Before 11.42.3 that was also the last check: a
+         * removed membership, a deactivated tenant, a withdrawn role or a revoked session took effect
+         * on every new request and on none of the sockets already open. Now a connection is re-checked
+         * at once when an invalidation names it (`CoreTenantGuard.invalidateUser()` /
+         * `invalidateTenant()` / `invalidateAll()`, a role change through `CoreUserService`, a
+         * password reset), and before an event is delivered or an operation runs once its last check
+         * is older than this value — the bound for a change nobody invalidated, such as a sign-out or a
+         * membership edited directly in the database. A connection whose rights changed is closed with
+         * 4403, which the graphql-ws client retries: it reconnects and continues with the current
+         * rights, or is refused at the handshake.
+         *
+         * - `undefined` → 30000
+         * - `0` → re-check on every operation and every event (one session lookup each)
+         * - `false` → no time-based re-check; invalidations still apply
+         * - anything else that is not a non-negative number → 30000, never "off"
+         *
+         * Applies to connections registered by `CoreModule`'s own `onConnect`. A project that replaces
+         * `onConnect` through `graphQl.driver.subscriptions` registers its connections with
+         * `registerWsConnection()` to keep this.
+         *
+         * @default 30000
+         * @since 11.42.3
+         */
+        subscriptionRevalidationMs?: false | number;
       };
 
   /**

package/src/core/modules/auth/services/core-auth.service.ts

@@ -69,11 +69,48 @@ export class CoreAuthService {
 
   /**
    * Decode JWT
+   *
+   * Reads the payload WITHOUT checking signature or expiry — never decide access on its result.
+   * Use `verifyJwt()` for that.
    */
   decodeJwt(token: string): JwtPayload {
     return this.jwtService.decode(token) as JwtPayload;
   }
 
+  /**
+   * Verify an access token's signature and expiry and answer its payload, or `null` when it does not
+   * verify.
+   *
+   * The same check passport-jwt applies on the HTTP path (`JwtStrategy`), for transports that have no
+   * passport in front of them — today the GraphQL WebSocket. The key is resolved in passport's order:
+   * `jwt.secretOrKeyProvider` when configured, else `jwt.secretOrPrivateKey || jwt.secret`. Until
+   * 11.42.3 the WebSocket handshake used `decodeJwt()`, so an expired token, or a copy re-signed with
+   * any key, was accepted there as long as its `tokenId` still matched the device.
+   *
+   * @since 11.42.3
+   */
+  async verifyJwt(token: string): Promise<JwtPayload | null> {
+    if (!token || typeof token !== 'string') {
+      return null;
+    }
+    try {
+      const provider = this.configService.getFastButReadOnly('jwt.secretOrKeyProvider');
+      const secret =
+        typeof provider === 'function'
+          ? await new Promise<string>((resolve, reject) =>
+              provider({}, token, (error: unknown, key: string) => (error ? reject(error) : resolve(key))),
+            )
+          : this.configService.getFastButReadOnly('jwt.secretOrPrivateKey') ||
+            this.configService.getFastButReadOnly('jwt.secret');
+      if (!secret) {
+        return null;
+      }
+      return (await this.jwtService.verifyAsync(token, { secret })) as JwtPayload;
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * Logout user (from device)
    */

package/src/core/modules/better-auth/better-auth.config.ts

@@ -8,6 +8,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 
 import { resolveServerUrls, strippedApiHostname } from '../../common/helpers/cookies.helper';
+import { revalidateWsConnectionsOf } from '../../common/helpers/graphql-ws-connection.helper';
 import { IBetterAuth, ICorsConfig } from '../../common/interfaces/server-options.interface';
 import { detectCookiePrefixDrift, resolveBetterAuthCookiePrefix } from './better-auth-cookie-prefix.helper';
 
@@ -753,6 +754,48 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Crea
   };
 }
 
+/**
+ * Ends the GraphQL WebSocket connections that rode on a session the moment the session is deleted —
+ * a sign-out, a revoked session, a password reset with `revokeSessionsOnPasswordReset`, a deleted user.
+ *
+ * Without it such a connection stays open until `graphQl.subscriptionRevalidationMs` (30 s by
+ * default) catches it on its next event. Better-Auth's `onPasswordReset` cannot do this job: all
+ * three reset routes call it BEFORE they delete the sessions, so a re-check from there would still
+ * find them valid.
+ *
+ * A plugin rather than `databaseHooks` in the options, because Better-Auth collects a plugin's
+ * `init().options.databaseHooks` as a SEPARATE source: a project's own `options.databaseHooks`
+ * neither replaces this one nor is replaced by it — unlike everything spread from `options`.
+ *
+ * It only asks for a re-check of the user's connections. The re-check resolves each connection's
+ * own token again, so a connection on a DIFFERENT, still-valid session of the same user stays open.
+ * It never throws: a failure here must not fail the sign-out.
+ */
+export function wsSessionRevocationPlugin(): BetterAuthPlugin {
+  return {
+    id: 'lt-ws-session-revocation',
+    init: () => ({
+      options: {
+        databaseHooks: {
+          session: {
+            delete: {
+              after: async (session: { userId?: unknown }) => {
+                try {
+                  if (session?.userId) {
+                    revalidateWsConnectionsOf({ iamId: String(session.userId) });
+                  }
+                } catch {
+                  // Never fail the deletion over a re-check; the revalidation interval still applies.
+                }
+              },
+            },
+          },
+        },
+      },
+    }),
+  } as BetterAuthPlugin;
+}
+
 /**
  * Formats a package name to a human-readable display name.
  * Converts kebab-case and snake_case to Title Case.
@@ -873,7 +916,9 @@ function buildPlugins(
   options: { passkeyNormalization: PasskeyNormalizationResult; serverEnv?: string },
 ): BetterAuthPlugin[] {
   const { passkeyNormalization, serverEnv } = options;
-  const plugins: BetterAuthPlugin[] = [];
+  // Always first and always on: it changes nothing about authentication itself, it only ends the
+  // WebSocket connections that rode on a session once the session is gone.
+  const plugins: BetterAuthPlugin[] = [wsSessionRevocationPlugin()];
 
   // JWT Plugin for API client compatibility
   // JWT is enabled by default unless explicitly disabled (jwt: false or jwt: { enabled: false })

package/src/core/modules/better-auth/core-better-auth.service.ts

@@ -804,9 +804,17 @@ export class CoreBetterAuthService implements OnModuleInit {
     }
 
     try {
-      // Create headers with the session token
+      // Better-Auth's signOut finds the session through its SIGNED session cookie. An `Authorization`
+      // header is read only by its `bearer` plugin, which the framework does not install — so until
+      // 11.42.3 this call deleted nothing: the caller got `true`, the controller cleared the cookies,
+      // and the session stayed valid server-side, authenticating the same token until it expired.
+      // The header stays for projects that added the bearer plugin themselves.
       const headers = new Headers();
       headers.set('Authorization', `Bearer ${sessionToken}`);
+      const secret = this.config?.secret;
+      if (secret) {
+        headers.set('cookie', `${this.getSessionCookieName()}=${signCookieValueIfNeeded(sessionToken, secret, true)}`);
+      }
 
       // Call Better-Auth's signOut endpoint
       await api.signOut({ headers });

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

@@ -236,14 +236,14 @@ multiTenancy: {
 }
 ```
 
-| Path                                                           | Deactivated tenant                                                                                                           |
-| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| Header + tenant role, or `S_USER` / `S_VERIFIED` with a header | **403** `Tenant is inactive`                                                                                                 |
-| Tenant API token                                               | **403**                                                                                                                      |
-| `S_EVERYONE` with a header                                     | not blocked, but no tenant context is set                                                                                    |
-| No header                                                      | dropped from the user's tenant list — its data stays out of reach                                                            |
-| GraphQL over WebSocket                                         | no tenant resolved for a new subscription — an open one keeps its tenant until it reconnects (as after a removed membership) |
-| Admin under `adminBypass`                                      | still allowed — somebody has to be able to switch it back on                                                                 |
+| Path                                                           | Deactivated tenant                                                                                                                                                                         |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Header + tenant role, or `S_USER` / `S_VERIFIED` with a header | **403** `Tenant is inactive`                                                                                                                                                               |
+| Tenant API token                                               | **403**                                                                                                                                                                                    |
+| `S_EVERYONE` with a header                                     | not blocked, but no tenant context is set                                                                                                                                                  |
+| No header                                                      | dropped from the user's tenant list — its data stays out of reach                                                                                                                          |
+| GraphQL over WebSocket                                         | no tenant resolved for a new subscription; an open one is closed (4403) on `invalidateTenant()`, or at its next event once `graphQl.subscriptionRevalidationMs` has passed (since 11.42.3) |
+| Admin under `adminBypass`                                      | still allowed — somebody has to be able to switch it back on                                                                                                                               |
 
 The hook is asked **after** the membership check, so a non-member learns nothing about a tenant's
 state. Return `false` for inactive; anything else counts as active. Answers are cached for

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

@@ -16,6 +16,11 @@ import { Model } from 'mongoose';
 
 import { RoleEnum } from '../../common/enums/role.enum';
 import { resolveGuardRequest } from '../../common/helpers/execution-context-request.helper';
+import {
+  revalidateAllWsConnections,
+  revalidateWsConnectionsForTenant,
+  revalidateWsConnectionsOf,
+} from '../../common/helpers/graphql-ws-connection.helper';
 import { ConfigService } from '../../common/services/config.service';
 import { ResolvedTenantContext, setTenantContextResolver } from '../../common/services/core-tenant-context.registry';
 import { CoreRedisService } from '../../common/services/core-redis.service';
@@ -208,6 +213,9 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
     if (!config || config.enabled === false) {
       return {};
     }
+    // The WebSocket path reaches this without passing canActivate(), so it has to pick up a changed
+    // `cacheTtlMs` itself — otherwise an API whose traffic is all WebSocket keeps the 30 s default.
+    this.syncConfig(config);
 
     const trimmed =
       headerTenantId && typeof headerTenantId === 'string' && headerTenantId.length <= 128
@@ -301,7 +309,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
    * `cacheTtlMs`. Broadcast to every replica when Redis is enabled.
    */
   invalidateTenant(tenantId: string): void {
-    this.tenantActiveCache.delete(tenantId);
+    this.clearTenant(tenantId);
     this.publishInvalidation({ scope: 'tenant', tenantId });
   }
 
@@ -339,16 +347,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
       return true;
     }
 
-    // Detect config changes (e.g., roleHierarchy modified in tests) and flush caches
-    if (this.lastSeenConfig !== config) {
-      this.lastSeenConfig = config;
-      // Default 30s in production, 0 (disabled) in test environments to avoid stale data between test cases
-      const isTestEnv =
-        process.env.VITEST === 'true' || process.env.NODE_ENV === 'test' || process.env.NODE_ENV === 'e2e';
-      this.cacheTtlMs = config.cacheTtlMs ?? (isTestEnv ? 0 : 30_000);
-      // Local-only flush: every replica detects the config change itself, no broadcast needed
-      this.clearAll();
-    }
+    this.syncConfig(config);
 
     const request = this.getRequest(context);
     if (!request) {
@@ -711,7 +710,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
     } else if (parsed?.scope === 'user' && parsed.userId) {
       this.clearUser(parsed.userId);
     } else if (parsed?.scope === 'tenant' && parsed.tenantId) {
-      this.tenantActiveCache.delete(parsed.tenantId);
+      this.clearTenant(parsed.tenantId);
     }
   }
 
@@ -722,6 +721,17 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
     this.membershipCache.clear();
     this.tenantIdsCache.clear();
     this.tenantActiveCache.clear();
+    // Open WebSocket connections were authorized against what was just thrown away.
+    revalidateAllWsConnections();
+  }
+
+  /**
+   * Forget a tenant's cached `isTenantActive` answer locally (no broadcast), and re-check the open
+   * WebSocket connections scoped to it.
+   */
+  protected clearTenant(tenantId: string): void {
+    this.tenantActiveCache.delete(tenantId);
+    revalidateWsConnectionsForTenant(tenantId);
   }
 
   /**
@@ -738,6 +748,25 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
         this.tenantIdsCache.delete(key);
       }
     }
+    // A membership change reaches the user's OPEN WebSocket connections too, not just new requests.
+    // After the caches above, so the re-check reads the membership as it is now.
+    revalidateWsConnectionsOf({ userId });
+  }
+
+  /**
+   * Pick up a changed `multiTenancy` config: the cache TTL, and a flush of everything cached under
+   * the old one. Local-only — every replica detects the change itself, no broadcast needed.
+   */
+  private syncConfig(config: object & { cacheTtlMs?: number }): void {
+    if (this.lastSeenConfig === config) {
+      return;
+    }
+    this.lastSeenConfig = config;
+    // Default 30s in production, 0 (disabled) in test environments to avoid stale data between test cases
+    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.clearAll();
   }
 
   /**

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

@@ -526,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

@@ -54,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
  *
@@ -794,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