@lenne.tech/nest-server 11.42.1 → 11.42.3

package/docs/REQUEST-LIFECYCLE.md

@@ -208,6 +208,7 @@ JWT-based authentication for existing projects:
 | **Custom Scalars** | `Date`, `DateTime` (timestamp), `JSON`, `Any` |
 | **Subscriptions** | WebSocket support via `graphql-ws` with auth. The `PUB_SUB` provider is built from a factory: `CoreRedisPubSub` when `redis` is configured (delivery is then cluster-wide), the in-memory `PubSub` otherwise (delivery only to clients connected to the publishing replica). **Constraint once Redis is in play: every published payload must be JSON-serializable** — it crosses the wire as JSON, so `Date`, class instances, `Map`/`Set` and `undefined` do not survive the round trip. An in-process `PubSub` never had this constraint, so a payload that worked on one replica can silently lose fields on a cluster. Publish plain objects and ISO strings |
 | **Subscription request context** | Since 11.35.0 `CoreModule` installs a context-aware `execute` / `subscribe` pair (inside `subscriptions`, where `ApolloDriver` forwards it) on all three GraphQL driver builders, so every WebSocket operation runs inside a `RequestContext`. Before that a WS operation had **none** — no Express middleware runs on an upgrade, and `CoreTenantGuard.getRequest()` finds no `req` on a subscription context — and `mongooseTenantPlugin` reads "no context" as "system operation, no filter", so a tenant-scoped read while delivering a subscription message returned EVERY tenant's rows. The tenant comes from the handshake's tenant header **validated against an active membership**, else from the subscriber's memberships; an unresolvable tenant leaves the safety net to refuse the read. The async iterator is wrapped too, not only the subscribe call: graphql-js runs `resolve` / `filter` / field resolvers inside its `next()`. See `.claude/rules/role-system.md` → "Tenant context on non-HTTP transports" |
+| **Subscription re-check** | Since 11.42.3 that context is not trusted for the life of the socket. Every connection a `CoreModule` `onConnect` accepts is registered (`registerWsConnection()`) and checked again — at once on an invalidation (tenant guard, role change, password reset, Better-Auth deleting the session), otherwise before the next operation or event once `graphQl.subscriptionRevalidationMs` (30 s) has passed. The check re-runs the handshake's authentication and the tenant resolution; a connection whose rights changed is closed with 4403 (retried by the graphql-ws client, which then reconnects with its current rights) and the event that triggered the check is dropped. Before, a removed membership, a deactivated tenant, a withdrawn role or a revoked session kept receiving events on an open socket until the client reconnected. See `.claude/rules/role-system.md` → "Open WebSockets" |
 | **Complexity Analysis** | Query cost calculation to prevent DoS attacks |
 | **Enum Registration** | `registerEnum()` helper for GraphQL enum types |
 | **Upload Support** | `graphqlUploadExpress()` for multipart file uploads |

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/migration-guides/11.42.2-to-11.42.3.md

@@ -0,0 +1,145 @@
+# Migration Guide: 11.42.2 → 11.42.3
+
+## Overview
+
+| Category             | Details                                                                                                                         |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| **Security**         | An open GraphQL WebSocket loses what its user lost — membership, tenant, role, session — instead of keeping it until reconnect (§1) |
+| **Security**         | IAM sign-out ends the session on the server, not only in the browser (§2)                                                       |
+| **Bugfix**           | The IAM WebSocket handshake accepts a valid bearer token (§3)                                                                   |
+| **Security**         | The legacy WebSocket handshake verifies the token's signature and expiry, as HTTP does (§4)                                     |
+| **New option**       | `graphQl.subscriptionRevalidationMs` (default 30000) (§1)                                                                       |
+| **Migration Effort** | None for most projects — `pnpm update`. Check §1 if you replaced `onConnect` yourself                                           |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick up the core update. No configuration change is required.
+
+## 1. Open WebSockets are re-checked, and closed when the rights behind them changed
+
+A GraphQL WebSocket was authorized once: `onConnect` validated the token and recorded the user, the
+subscribe wrapper resolved the tenant, and every event and operation on the socket ran on that
+snapshot until the client reconnected. Removing someone from a tenant, switching a tenant off,
+withdrawing a role or ending a session took effect on every new request and on none of the sockets
+that were already open — for a browser tab, often hours.
+
+Since 11.42.3 every connection `CoreModule`'s `onConnect` accepts is registered with the rights it was
+authorized with, and checked again:
+
+| Trigger                                                                                                                                                 | When                                                                                  |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `CoreTenantGuard.invalidateUser()` / `invalidateTenant()` / `invalidateAll()`, `CoreUserService.setRoles()`, an `update()` of `roles` / `verified` / `emailVerified`, the legacy password reset | at once                                                                               |
+| Better-Auth deleting a session: sign-out, a revoked session, a reset with `revokeSessionsOnPasswordReset`                                               | at once                                                                               |
+| A change nobody invalidated (a membership edited directly in the database, an expired session)                                                         | before the next event or operation, once `graphQl.subscriptionRevalidationMs` has passed |
+
+A connection whose rights changed is closed with **4403**. The graphql-ws client retries that code: it
+reconnects, resubscribes and continues with the rights the user holds now, or is refused at the
+handshake when the session is gone. Nothing changes for a connection whose rights did not change.
+
+```typescript
+// config.env.ts — optional, the default is 30000
+graphQl: {
+  subscriptionRevalidationMs: 30000, // 0 = re-check on every event and operation, false = only on invalidation
+},
+```
+
+**If you replaced `onConnect`** through `graphQl.driver.subscriptions`, register what you accept, or
+your connections keep the old "checked once" behaviour:
+
+```typescript
+import { registerWsConnection } from '@lenne.tech/nest-server';
+
+onConnect: async (context) => {
+  const user = await authenticate(context); // your own handshake
+  context.extra.user = user;
+  registerWsConnection({
+    carrier: context.extra,
+    reauthenticate: () => authenticate(context), // the user the token belongs to NOW, or null
+    socket: context.extra.socket,
+    user,
+  });
+  return context.extra;
+},
+```
+
+**If your client does not use graphql-ws** (or turned its retries off), make sure it reconnects after a
+4403 close; otherwise the user's live updates stop until the page is reloaded.
+
+A dropped event is checked after graphql-js executed it and before it is sent: the reads made while
+computing it happened, but nothing of it reaches the client. Subscription resolvers should not write.
+
+## 2. IAM sign-out ends the session on the server
+
+`CoreBetterAuthService.revokeSession()` — used by `POST /iam/sign-out` and the `betterAuthSignOut`
+mutation — passed the session token to Better-Auth's `signOut` only as an `Authorization` header.
+Better-Auth reads that header only with its `bearer` plugin, which the framework does not install. The
+sign-out therefore answered `{ success: true }`, cleared the cookies, and deleted nothing: the session
+stayed valid server-side, and the same token kept authenticating requests until it expired.
+
+The token is now passed as the signed session cookie Better-Auth reads, and the header is kept for
+projects that added the bearer plugin themselves. **No action is needed.** Sessions signed out before
+the update are still valid until they expire; if that matters for your deployment, delete them from the
+`session` collection.
+
+## 3. The IAM WebSocket handshake accepts a valid bearer token
+
+Both IAM driver builders authenticated the handshake through `getSession()` with an `Authorization`
+header — the same header Better-Auth ignores without its `bearer` plugin. Every IAM WebSocket handshake
+with a bearer token was refused as `Invalid or expired session`, so authenticated subscriptions did not
+work in IAM-only projects at all.
+
+The handshake now resolves the token the way the HTTP middleware does for the same header: a Better-Auth
+JWT first, then the session store, and `getSession()` as the last resort. If you built a workaround
+(for example a custom `onConnect`), you can remove it — and register the connection as shown in §1 if
+you keep it.
+
+## 4. The legacy WebSocket handshake verifies the token
+
+Legacy access tokens are verified on HTTP by passport-jwt: signature and expiry. The legacy WebSocket
+handshake read them with `decodeJwt()` instead, which checks neither — only the payload's `tokenId` had
+to match the device. An expired token, or a copy of one re-signed with any key, therefore kept opening
+sockets for as long as the device's refresh token was not rotated.
+
+The handshake, and the re-check from §1, now use `CoreAuthService.verifyJwt()`, which applies passport's
+rule: `jwt.secretOrKeyProvider` when configured, else `jwt.secretOrPrivateKey || jwt.secret`. A token
+that is not a JWT at all is refused as unauthorized instead of closing the socket with 4500 and a
+TypeError as the reason.
+
+**What this changes for a legacy WebSocket client:** a connection now ends when its token does — at
+expiry, or when the client refreshes its tokens (a refresh rotates the device's `tokenId`, which already
+invalidated the old token on HTTP). The socket is closed with 4403 and graphql-ws reconnects, so pass
+the CURRENT token on every connect rather than the one the client had at start-up:
+
+```typescript
+createClient({
+  url,
+  connectionParams: () => ({ Authorization: `Bearer ${getCurrentAccessToken()}` }), // a function, not an object
+});
+```
+
+The same holds for an IAM client that authenticates its socket with a Better-Auth JWT (§3): the JWT
+expires after `betterAuth.jwt.expiresIn` (15 minutes by default). A session token lives as long as its
+session.
+
+An AuthService passed to `CoreModule.forRoot()` that does not extend `CoreAuthService` may lack
+`verifyJwt()`; it keeps the unverified read and logs a warning once. Extend `CoreAuthService` to close it.
+
+## Troubleshooting
+
+| Symptom                                                                    | Cause                                                          | Fix                                                  |
+| -------------------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------- |
+| A client's WebSocket closes with 4403 after a role or membership change    | Intended: the rights behind the connection changed             | Let the client reconnect (graphql-ws does by default) |
+| Live updates stop after a role change and never resume                     | The client does not reconnect after a 4403 close               | Enable reconnects (graphql-ws `retryAttempts`)       |
+| Revoked access still receives events on a project with its own `onConnect` | The custom `onConnect` does not register the connection        | Call `registerWsConnection()` (§1)                   |
+| IAM subscriptions are refused with `Invalid or expired session`            | 11.42.2 or older                                               | Update to 11.42.3                                    |
+| A WebSocket reconnects and is refused shortly after a token refresh or expiry | The client reconnects with the token it had at start-up      | Pass `connectionParams` as a function (§4)           |
+| `has no verifyJwt()` warning at the first legacy WebSocket                  | The AuthService does not extend `CoreAuthService`             | Extend `CoreAuthService` (§4)                        |
+
+## Module Documentation
+
+- [Tenant README](../src/core/modules/tenant/README.md) — Deactivated tenants
+- [Better-Auth README](../src/core/modules/better-auth/README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.42.1",
+  "version": "11.42.3",
   "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",

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

@@ -0,0 +1,382 @@
+import { Logger } from '@nestjs/common';
+
+import { ConfigService } from '../services/config.service';
+import { getTenantContextResolver, ResolvedTenantContext } from '../services/core-tenant-context.registry';
+
+/**
+ * The authorization lifecycle of an OPEN GraphQL WebSocket connection.
+ *
+ * WHY THIS EXISTS: a WebSocket is authorized at the handshake. `onConnect` validates the session and
+ * records the user; the subscribe wrapper (`graphql-ws-context.helper.ts`) resolves the tenant. Before
+ * 11.42.3 nothing ever looked again — every delivered event and every further operation on the socket
+ * ran on that snapshot. Removing somebody from a tenant, switching a tenant off, withdrawing a role or
+ * ending a session therefore took effect on every NEW request and on none of the sockets that were
+ * already open, for as long as the client kept them open. For a browser tab that is hours.
+ *
+ * WHAT IT DOES: each connection is registered with the rights it was authorized with — the user's id,
+ * roles and verification state, and the tenant scope its operations resolved — plus a function that
+ * re-runs the handshake's authentication. Those rights are checked again
+ *
+ *  - when an INVALIDATION names the connection (`revalidateWsConnectionsOf()` from a membership or
+ *    role change, `revalidateWsConnectionsForTenant()` from a tenant switch, a password reset), at
+ *    once and before any further event, and
+ *  - before an event is delivered or an operation runs, once the last check is older than
+ *    `graphQl.subscriptionRevalidationMs` (default 30 s) — the bound for a change nobody invalidated,
+ *    such as a session that was signed out or a membership edited directly in the database.
+ *
+ * A connection whose rights CHANGED — narrowed or widened — is closed with 4403. It is not patched in
+ * place, deliberately: a subscription may have chosen its topic or its filter from the tenant at
+ * subscribe time, and only a fresh subscribe re-derives that. The graphql-ws client RETRIES 4403 (its
+ * own comment: "might grant access after retry"), so the user reconnects and continues with the
+ * rights they hold now, or is refused at `onConnect` if the session is gone.
+ *
+ * WHAT IT DOES NOT DO: an event is checked AFTER graphql-js executed it and BEFORE it is sent. Reads
+ * made while computing a dropped event still happened — under the old context — but nothing of them
+ * reaches the client. Subscription resolvers that WRITE are outside what this can take back.
+ */
+
+/**
+ * Close code for a connection whose authorization changed: graphql-ws's `CloseCode.Forbidden`. Its
+ * client retries it, which is what makes the close a re-authorization rather than a hang-up.
+ */
+export const WS_AUTHORIZATION_CHANGED_CLOSE_CODE = 4403;
+
+/** Default for `graphQl.subscriptionRevalidationMs`. */
+export const DEFAULT_SUBSCRIPTION_REVALIDATION_MS = 30_000;
+
+/** The parts of a socket this helper needs: closing it, and noticing that it closed. */
+export interface IWsConnectionSocket {
+  close(code: number, reason?: string): void;
+  once?(event: 'close', listener: (...args: any[]) => void): unknown;
+}
+
+export interface IWsConnectionRegistration {
+  /**
+   * The object every operation of the connection receives as its GraphQL context: `extra` for
+   * graphql-ws, the object `onConnect` returns for subscriptions-transport-ws (which copies it per
+   * operation — the registration survives that copy).
+   */
+  carrier: object;
+
+  /**
+   * Re-run the handshake's authentication. Resolves to the user the credential authenticates as NOW,
+   * or to a falsy value when it no longer does. A rejection counts as falsy. Without it only the
+   * tenant scope is re-checked.
+   */
+  reauthenticate?: () => any;
+
+  /** The raw socket — closed when the rights changed, and watched so a closed connection is forgotten. */
+  socket?: IWsConnectionSocket;
+
+  /** The user the handshake authenticated. */
+  user: any;
+}
+
+/** Who an invalidation is about. Any one field is enough; `userId` is the `users` document id. */
+export interface IWsConnectionIdentity {
+  email?: string;
+  iamId?: string;
+  userId?: string;
+}
+
+/** @internal The registered state of one connection. */
+export interface WsConnection {
+  readonly email?: string;
+  readonly iamId?: string;
+  readonly reauthenticate?: () => any;
+  readonly socket?: IWsConnectionSocket;
+  /** The tenant scope the connection's operations resolved, once one has. */
+  tenant?: ResolvedTenantContext;
+  /** The tenant header the client sent — constant for the life of the connection. */
+  readonly tenantHeader?: string;
+  terminated: boolean;
+  readonly user: any;
+  readonly userFingerprint: string;
+  readonly userId?: string;
+  /** @internal */
+  inflight?: Promise<boolean>;
+  /** @internal */
+  stale: boolean;
+  /** @internal */
+  tenantFingerprint?: string;
+  /** @internal */
+  validatedAt: number;
+}
+
+/**
+ * Module-private and not `Symbol.for()`: nothing a client sends — `connectionParams` are JSON — can
+ * produce it, so a registration cannot be forged or overwritten from outside. Enumerable on purpose:
+ * subscriptions-transport-ws hands each operation an `Object.assign` copy of the connection context,
+ * and only enumerable own properties survive that.
+ */
+const WS_CONNECTION = Symbol('ltWsConnection');
+
+/**
+ * Connections that can be found by an invalidation. Only those with a socket to watch: without a
+ * `close` event there is no moment to forget them, and a registry that only grows is a leak. A
+ * connection without one is still re-checked by the interval, through its carrier.
+ */
+const liveConnections = new Set<WsConnection>();
+
+const logger = new Logger('GraphQlWsConnection');
+
+/**
+ * Resolve `graphQl.subscriptionRevalidationMs` to an interval, or `false` for "off".
+ *
+ * Only an explicit `false` switches the interval off. Anything else that is not a usable interval
+ * falls back to the DEFAULT, never to "off": this bounds how long revoked access keeps flowing, and a
+ * typo in an environment variable must not be the thing that removes the bound. `0` is a legitimate
+ * value meaning "on every operation and every event".
+ */
+export function resolveSubscriptionRevalidationMs(value: unknown): false | number {
+  if (value === false || value === 'false') {
+    return false;
+  }
+  const numeric = typeof value === 'string' && value.trim() !== '' ? Number(value) : value;
+  if (typeof numeric === 'number' && Number.isFinite(numeric) && numeric >= 0) {
+    return numeric;
+  }
+  return DEFAULT_SUBSCRIPTION_REVALIDATION_MS;
+}
+
+function configuredRevalidationMs(): false | number {
+  const graphQl = ConfigService.configFastButReadOnly?.graphQl;
+  return resolveSubscriptionRevalidationMs(graphQl ? graphQl.subscriptionRevalidationMs : undefined);
+}
+
+/** What a connection's rights depend on, as a comparable string. Role ORDER does not count. */
+function fingerprintUser(user: any): string {
+  if (!user) {
+    return '';
+  }
+  const roles = Array.isArray(user.roles) ? user.roles.map((role: unknown) => String(role)).sort() : [];
+  const verified = !!(user.verified || user.verifiedAt || user.emailVerified);
+  return JSON.stringify([String(user.id ?? user._id ?? ''), roles, verified]);
+}
+
+function fingerprintTenant(tenant: ResolvedTenantContext | undefined): string {
+  const tenantIds = Array.isArray(tenant?.tenantIds) ? tenant.tenantIds.map((id) => String(id)).sort() : null;
+  return JSON.stringify([tenant?.tenantId ?? null, tenantIds, tenant?.tenantRole ?? null, !!tenant?.isAdminBypass]);
+}
+
+/** Same lookup the context wrapper uses — see `readTenantHeader()` in graphql-ws-context.helper.ts. */
+export function readWsTenantHeader(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;
+}
+
+/**
+ * Register a connection after a successful handshake. Call it from `onConnect`, with the same user
+ * the handshake recorded on the carrier.
+ */
+export function registerWsConnection(registration: IWsConnectionRegistration): void {
+  const { carrier, reauthenticate, socket, user } = registration;
+  if (!carrier || typeof carrier !== 'object') {
+    return;
+  }
+  const userId = user?.id ?? user?._id;
+  const connection: WsConnection = {
+    email: typeof user?.email === 'string' ? user.email.toLowerCase() : undefined,
+    iamId: typeof user?.iamId === 'string' ? user.iamId : undefined,
+    reauthenticate,
+    socket,
+    stale: false,
+    tenantHeader: readWsTenantHeader(carrier),
+    terminated: false,
+    user,
+    userFingerprint: fingerprintUser(user),
+    userId: userId !== undefined && userId !== null ? String(userId) : undefined,
+    validatedAt: Date.now(),
+  };
+  Object.defineProperty(carrier, WS_CONNECTION, { configurable: true, enumerable: true, value: connection });
+
+  if (socket && typeof socket.once === 'function') {
+    liveConnections.add(connection);
+    socket.once('close', () => {
+      connection.terminated = true;
+      liveConnections.delete(connection);
+    });
+  }
+}
+
+/** The registered connection a GraphQL context belongs to, if any. */
+export function getWsConnection(contextValue: any): undefined | WsConnection {
+  if (!contextValue || typeof contextValue !== 'object') {
+    return undefined;
+  }
+  const connection = contextValue[WS_CONNECTION];
+  return connection && typeof connection === 'object' ? connection : undefined;
+}
+
+/**
+ * Close a connection whose authorization no longer holds. Idempotent; always answers `false` so a
+ * caller can `return terminate(...)`.
+ */
+function terminate(connection: WsConnection, reason: string): false {
+  if (connection.terminated) {
+    return false;
+  }
+  connection.terminated = true;
+  liveConnections.delete(connection);
+  logger.log(`Closing GraphQL WebSocket of user ${connection.userId ?? '(unknown)'}: ${reason}`);
+  try {
+    // A close reason is limited to 123 bytes on the wire; these are short and ASCII.
+    connection.socket?.close(WS_AUTHORIZATION_CHANGED_CLOSE_CODE, reason);
+  } catch {
+    // Already closing — the outcome is the same.
+  }
+  return false;
+}
+
+async function revalidate(connection: WsConnection): Promise<boolean> {
+  connection.stale = false;
+  try {
+    let user = connection.user;
+    if (connection.reauthenticate) {
+      user = await connection.reauthenticate();
+      if (!user) {
+        return terminate(connection, 'Session no longer valid');
+      }
+    }
+    if (fingerprintUser(user) !== connection.userFingerprint) {
+      return terminate(connection, 'User authorization changed');
+    }
+    if (connection.tenantFingerprint !== undefined) {
+      const resolver = getTenantContextResolver();
+      const tenant = resolver ? await resolver.resolve(user, connection.tenantHeader) : {};
+      if (fingerprintTenant(tenant) !== connection.tenantFingerprint) {
+        return terminate(connection, 'Tenant access changed');
+      }
+    }
+    if (connection.terminated) {
+      return false;
+    }
+    connection.validatedAt = Date.now();
+    return true;
+  } catch {
+    // Fail closed: a check that cannot be made is not a check that passed. The client reconnects,
+    // and the handshake decides again.
+    return terminate(connection, 'Authorization check failed');
+  }
+}
+
+/**
+ * Is the connection still authorized as it was registered? Re-checks when an invalidation marked it,
+ * or when its last check is older than `graphQl.subscriptionRevalidationMs`; otherwise answers from
+ * the last check without any I/O. Concurrent callers share one re-check.
+ *
+ * `false` means the connection has been closed and nothing more may be delivered or executed on it.
+ */
+export function ensureWsConnectionCurrent(connection: WsConnection): Promise<boolean> {
+  if (connection.terminated) {
+    return Promise.resolve(false);
+  }
+  const interval = configuredRevalidationMs();
+  if (!connection.stale && (interval === false || Date.now() - connection.validatedAt < interval)) {
+    return Promise.resolve(true);
+  }
+  if (!connection.inflight) {
+    connection.inflight = revalidate(connection).finally(() => {
+      connection.inflight = undefined;
+      // An invalidation that arrived while this check was running may have been answered from data
+      // that predates it — check once more rather than lose it.
+      if (connection.stale && !connection.terminated) {
+        void ensureWsConnectionCurrent(connection);
+      }
+    });
+  }
+  return connection.inflight;
+}
+
+/**
+ * Record the tenant scope an operation on this connection resolved.
+ *
+ * The first resolution becomes the connection's scope. A later operation resolving a DIFFERENT one
+ * means the rights changed underneath the subscriptions that are already running on the old scope —
+ * the connection is closed, and `false` returned.
+ */
+export function noteWsConnectionTenant(connection: WsConnection, tenant: ResolvedTenantContext | undefined): boolean {
+  if (connection.terminated) {
+    return false;
+  }
+  const fingerprint = fingerprintTenant(tenant);
+  if (connection.tenantFingerprint === undefined) {
+    connection.tenant = tenant ? { ...tenant } : {};
+    connection.tenantFingerprint = fingerprint;
+    return true;
+  }
+  if (fingerprint !== connection.tenantFingerprint) {
+    return terminate(connection, 'Tenant access changed');
+  }
+  return true;
+}
+
+/** Mark a connection for an immediate re-check and start it. */
+function markStale(connection: WsConnection): void {
+  connection.stale = true;
+  void ensureWsConnectionCurrent(connection);
+}
+
+/**
+ * Re-check, at once, every open connection of a user — after a membership, role or credential change.
+ * Answers the number of connections affected. Process-local: the tenant guard's Redis broadcast is
+ * what carries a membership invalidation to the other replicas.
+ */
+export function revalidateWsConnectionsOf(identity: IWsConnectionIdentity): number {
+  const userId = identity?.userId !== undefined && identity?.userId !== null ? String(identity.userId) : undefined;
+  const iamId = identity?.iamId || undefined;
+  const email = typeof identity?.email === 'string' ? identity.email.toLowerCase() : undefined;
+  if (!userId && !iamId && !email) {
+    return 0;
+  }
+  let count = 0;
+  for (const connection of liveConnections) {
+    if (
+      (userId && connection.userId === userId) ||
+      (iamId && connection.iamId === iamId) ||
+      (email && connection.email === email)
+    ) {
+      markStale(connection);
+      count++;
+    }
+  }
+  return count;
+}
+
+/** Re-check, at once, every open connection scoped to a tenant — after the tenant was switched on or off. */
+export function revalidateWsConnectionsForTenant(tenantId: string): number {
+  if (!tenantId) {
+    return 0;
+  }
+  const id = String(tenantId);
+  let count = 0;
+  for (const connection of liveConnections) {
+    const tenant = connection.tenant;
+    if (tenant && (tenant.tenantId === id || (Array.isArray(tenant.tenantIds) && tenant.tenantIds.includes(id)))) {
+      markStale(connection);
+      count++;
+    }
+  }
+  return count;
+}
+
+/** Re-check every open connection — after a change whose reach is unknown (`invalidateAll()`). */
+export function revalidateAllWsConnections(): number {
+  let count = 0;
+  for (const connection of liveConnections) {
+    markStale(connection);
+    count++;
+  }
+  return count;
+}