@lenne.tech/nest-server 11.42.4 → 11.42.5

package/migration-guides/11.42.3-to-11.42.4.md

@@ -19,7 +19,8 @@ pnpm update --depth Infinity proxy-addr
 ```
 
 Then add the `@graphql-tools/utils` override from §3 to `pnpm-workspace.yaml`, run `pnpm install`,
-and check §3 for an older `@graphql-tools/utils` 11.x copy, which the override does not reach.
+refresh `source-map-js` (§3), check §3 for an older `@graphql-tools/utils` 11.x copy, which the
+override does not reach, and commit `pnpm-workspace.yaml` together with `pnpm-lock.yaml`.
 Vendor-mode projects pick up the core update and need the same two dependency steps. The body limit
 needs no configuration: unset, both parsers keep the 100 kB they had.
 
@@ -62,6 +63,12 @@ server.useBodyParser('json', { limit: '2mb' });
 bodyParser: { json: { limit: '2mb' } },
 ```
 
+**Starter-based projects:** `config.env.ts` builds `local` / `e2e` / `ci` from `localConfig()` and the
+deployed environments from `deployedConfig()`. Put the limit where BOTH see it — the starter ships a
+shared `PROJECT_BODY_PARSER` constant for this since its 11.42.4 update — or set
+`NSC__BODY_PARSER__JSON__LIMIT` in the environment. A value only in the deployed block leaves the e2e
+suite and `lt dev up` at 100 kB.
+
 The config is applied during module init, so it holds in every test that builds the app with
 `Test.createTestingModule(...).createNestApplication()` — which never runs `main.ts`, so a
 `useBodyParser()` call there never reached the e2e suite. Once configured, the value also replaces a
@@ -101,7 +108,7 @@ refused request, with method, path (without query string) and the config key to
 The status code is unchanged. Only clients that compare the message text against
 `'request entity too large'` need adjusting — branch on the status or on `LTNS_0304` instead.
 
-## 3. Two dependency advisories your project must fix itself
+## 3. Dependency advisories your project must fix itself
 
 `pnpm` overrides apply only to the project that runs the install, so the framework's own fixes do not
 reach your tree — see [docs/security-overrides.md](../docs/security-overrides.md).
@@ -110,6 +117,7 @@ reach your tree — see [docs/security-overrides.md](../docs/security-overrides.
 | ------- | -------- | ----------------------- |
 | `proxy-addr` | [GHSA-jqcg-44mw-7w3h](https://github.com/advisories/GHSA-jqcg-44mw-7w3h) — **critical**: IP spoofing through an IPv4-mapped IPv6 address in a trusted subnet. Patched `>=2.0.8` | A lockfile refresh. `express` requests `^2.0.7`, so `2.0.8` is in range, but an existing lockfile stays on `2.0.7` |
 | `@graphql-tools/utils` | [GHSA-7mx3-vvmw-hjmv](https://github.com/advisories/GHSA-7mx3-vvmw-hjmv) — high: prototype pollution in `mergeDeep` (schema assembly). Covers `<=12.0.0` — **11.x included, with no 11.x fix**. Patched `>=12.0.1` | An override for the copy `@nestjs/graphql` 13.4.5 exact-pins (`12.0.0`), and — in an older lockfile — a refresh of `@graphql-tools/schema` / `merge`, which can still pull in 11.x (see below) |
+| `source-map-js` | [GHSA-68fv-2mgg-jv7q](https://github.com/advisories/GHSA-68fv-2mgg-jv7q) — high: event-loop DoS through indexed source-map section offsets. Patched `>=1.2.2`. **Dev tooling only** (vitest > vite > postcss), but `pnpm audit` — and therefore `check` — reports it | A lockfile refresh: `pnpm update --depth Infinity source-map-js`. If `postcss` keeps a `1.2.1` copy, re-resolve it the same way rather than with `pnpm dedupe`, which moves unrelated peers too |
 
 `proxy-addr` is what Express uses to compute `request.ip` from `X-Forwarded-For` as far as
 `trustProxy` allows. With `trustProxy` set, every IP-keyed rate limit — the framework's own and any of
@@ -146,7 +154,13 @@ The current releases (schema 10.1.3, merge 9.2.6) request utils `^12.0.3`, which
 (22.22) and Node 24 satisfy that; if your `engines.node` still declares a lower floor, raise it — the
 override above cannot hold this copy back, because `^12.0.3` does not intersect its key.
 
-Then `pnpm install` and `pnpm audit` — both advisories must be gone.
+Then `pnpm install` and `pnpm audit` — the advisories must be gone.
+
+**Commit `pnpm-workspace.yaml` and `pnpm-lock.yaml` together.** Every step above leaves a consistent
+lockfile once it has run to the end, but the override only reaches the lockfile through the
+`pnpm install` that follows it. A `pnpm-workspace.yaml` committed with the override and without the
+re-installed lockfile fails every `pnpm install --frozen-lockfile` — typically the Docker image build.
+Check with `pnpm install --frozen-lockfile` locally before you push.
 
 ## 4. Native Better-Auth endpoints accept the session when the secret is auto-generated
 

package/migration-guides/11.42.4-to-11.42.5.md

@@ -0,0 +1,104 @@
+# Migration Guide: 11.42.4 → 11.42.5
+
+## Overview
+
+| Category             | Details                                                                                                     |
+| -------------------- | ----------------------------------------------------------------------------------------------------------- |
+| **New feature**      | `TestHelper.mcpSession()` / `TestHelper.mcp()` — MCP tests without hand-written SSE parsing (§1)            |
+| **Tooling**          | `check:overrides` accepts a declared "fix exists, but this consumer cannot use it" suppression that expires by itself (§2) |
+| **Docs**             | The 11.42.3 → 11.42.4 guide gained three steps; check them if you already applied it (§3)                   |
+| **Breaking Changes** | None                                                                                                        |
+| **Migration Effort** | None required — `pnpm update`. Adopting the helpers is optional                                             |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick up the core update; the new helpers arrive with `src/test/`. No configuration
+change is required.
+
+## 1. TestHelper: MCP tests without SSE parsing
+
+Projects that enable the AI module's MCP server (`ai.mcp` in `config.env.ts`) should test their tools over
+MCP as well as over REST/GraphQL: MCP has its own role filter and sessions, and a refused tool comes back as
+a result with `isError: true`, not as an HTTP error. Until now such a test had to set the right `Accept`
+header, carry the `mcp-session-id` header, and parse the SSE stream by hand. `TestHelper` now does that:
+
+```typescript
+const session = await testHelper.mcpSession({ token: userToken });
+
+expect((await session.listTools()).map((tool) => tool.name)).not.toContain('delete_user');
+
+const refused = await session.callTool('delete_user', { id });
+expect(refused.isError).toBe(true);
+
+const result = await session.callTool('find_users', { query: '@test.com' });
+expect(result.json.data.length).toBeGreaterThan(0);
+
+await session.close();
+```
+
+`testHelper.mcp(message, { statusCode, sessionId, token })` sends a single JSON-RPC message for the
+HTTP-level cases (401 without a token, 404 for another user's session). Full reference: `src/test/README.md`
+→ "MCP Testing".
+
+The helpers are additive and build on `testHelper.rest()`, so `token` and `cookies` behave as there. They add
+no dependency, so vendor-mode projects receive them with `src/test/`. A project with its own MCP module (not
+the AI module's `/ai/mcp`) passes its endpoint as `path`.
+
+## 2. `check:overrides`: a suppression for a fix the consumer cannot use
+
+`auditConfig.ignoreGhsas` used to be usable only for advisories with no fix at all — the moment any fix
+appeared, `check:overrides` failed with `FIX AVAILABLE`. That is right in the common case and a dead end in
+one: the fix exists, but the package that pulls in the vulnerable version cannot use it (for example, a
+patched major removed an export the consumer imports).
+
+That case can now be declared next to the suppression:
+
+```yaml
+auditConfig:
+  ignoreGhsas:
+    - GHSA-x6jw-m9v5-85vh
+  unusableFixConsumers:
+    GHSA-x6jw-m9v5-85vh: '@nuxt/devtools@3.4.1 cannot use 4.0.1'
+```
+
+The declaration expires by itself: `check:overrides` fails with `RE-TEST` as soon as the consumer leaves the
+tree or changes version, the advisory offers a patched version nobody assessed (a backport), or anything other
+than exactly that consumer version pulls the vulnerable package — including a direct dependency of your own
+project. An undeclared suppression of a fixed advisory still fails on sight.
+
+This is a change to the guard script, not to the published runtime: projects created from
+nest-server-starter or lt-monorepo receive it with their template update. Exhaust the remedies first (raise
+the vulnerable package, raise or patch the consumer); the rules and the reasoning are in
+`.claude/rules/package-management.md` → "When the fix exists and the consumer cannot use it".
+
+## 3. Three steps added to the 11.42.3 → 11.42.4 guide
+
+If you already applied [11.42.3 → 11.42.4](./11.42.3-to-11.42.4.md), check these — they were added after its
+release:
+
+1. **`source-map-js` < 1.2.2** ([GHSA-68fv-2mgg-jv7q](https://github.com/advisories/GHSA-68fv-2mgg-jv7q),
+   high, dev tooling only) is also reported by `pnpm audit`: `pnpm update --depth Infinity source-map-js`.
+2. **Commit `pnpm-workspace.yaml` and `pnpm-lock.yaml` together.** An override only reaches the lockfile through
+   the `pnpm install` that follows it; a workspace file committed without the re-installed lockfile fails every
+   `pnpm install --frozen-lockfile`, typically the Docker image build.
+3. **Starter-based projects:** set `bodyParser` where both `localConfig()` and `deployedConfig()` see it (the
+   starter ships a shared `PROJECT_BODY_PARSER` constant), or via `NSC__BODY_PARSER__JSON__LIMIT`. A value only
+   in the deployed block leaves the e2e suite and `lt dev up` at 100 kB.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| ------- | ----- | --- |
+| `check:overrides` fails with `RE-TEST` on a declared suppression | The consumer moved, a new patched version appeared, or another package (or your project directly) now pulls the vulnerable package | Re-assess: take the fix if it is now usable, otherwise update the declaration with what you re-checked (§2) |
+| `check:overrides` fails with `FIX AVAILABLE` | A suppressed advisory gained a fix, and no declaration explains why it cannot be used | Take the fix; declare only after the remedies are exhausted (§2) |
+| `session.callTool()` throws instead of returning `isError` | The JSON-RPC call itself failed (protocol error), not the tool | Assert on `session.request(...)` for protocol-level errors (§1) |
+
+## Module Documentation
+
+- [TestHelper README — MCP Testing](../src/test/README.md)
+- [AI module README](../src/core/modules/ai/README.md)
+- `.claude/rules/package-management.md` — suppressions, overrides and the `check:overrides` guard

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.42.4",
+  "version": "11.42.5",
   "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/test/README.md

@@ -243,4 +243,82 @@ const result = await testHelper.graphQl(
 );
 ```
 
-See `TestGraphQLConfig` and `TestGraphQLOptions` interfaces in `test.helper.ts` for full configuration options.
+See `TestGraphQLConfig` and `TestGraphQLOptions` interfaces in `test.helper.ts` for full configuration options.
+
+## MCP Testing (`testHelper.mcp()` / `testHelper.mcpSession()`)
+
+An MCP client reaches the same services as REST and GraphQL through its own door: the MCP server of the AI module
+(`/ai/mcp`, enabled with `ai.mcp` in `config.env.ts`) has its own role filter, its own sessions, and reports a refused
+or failing tool as a result with `isError: true` instead of an HTTP error. A project that enables MCP therefore tests
+its tools over MCP too, next to its API tests.
+
+The transport answers requests as an SSE stream. These helpers handle the stream, the session header and the
+handshake, so a test reads results directly.
+
+### `mcpSession(options?)`
+
+Opens a session the way every MCP client does (`initialize`, then `notifications/initialized`) for the user of `token`
+or `cookies`:
+
+```typescript
+const session = await testHelper.mcpSession({ token: userToken });
+
+// tools/list — filtered by the user's roles
+const names = (await session.listTools()).map((tool) => tool.name);
+expect(names).toContain('find_users');
+
+// tools/call — `json` is the first text content parsed as JSON (the tool's own result)
+const result = await session.callTool('find_users', { query: '@test.com' });
+expect(result.isError).toBeFalsy();
+expect(result.json.data.length).toBeGreaterThan(0);
+
+// A tool outside the user's roles is refused, not run
+const refused = await session.callTool('delete_user', { id });
+expect(refused.isError).toBe(true);
+
+// Any other JSON-RPC request; returns the whole message, protocol errors included
+const reply = await session.request('prompts/list');
+
+// End the session server-side
+await session.close();
+```
+
+| Member                               | Description                                                              |
+| ------------------------------------ | ------------------------------------------------------------------------ |
+| `sessionId`                          | `mcp-session-id` the server assigned                                     |
+| `initializeResult`                   | Result of `initialize` (`serverInfo`, `capabilities`, `protocolVersion`) |
+| `listTools()`                        | `tools/list`, returns the tools array                                    |
+| `callTool(name, args?)`              | `tools/call`, returns the `CallToolResult` plus `json`                   |
+| `request(method, params?, options?)` | Any request in the session, returns the JSON-RPC message                 |
+| `close()`                            | `DELETE` with the session id                                             |
+
+### `mcp(message, options?)`
+
+Sends a single JSON-RPC message and returns `{ message, response, sessionId }`. Use it for the HTTP-level cases a
+session hides:
+
+```typescript
+// No token → 401
+await testHelper.mcp({ id: 1, method: 'initialize', params: {} }, { statusCode: 401 });
+
+// Another user's session id → 404 (not 403: confirming the id exists would be an oracle)
+await testHelper.mcp(
+  { id: 2, method: 'tools/list' },
+  { sessionId: adminSession.sessionId, statusCode: 404, token: userToken },
+);
+```
+
+### TestMcpOptions
+
+| Option             | Type                               | Default                         | Description                                     |
+| ------------------ | ---------------------------------- | ------------------------------- | ----------------------------------------------- |
+| `token`            | `string`                           | -                               | Bearer token, the same one `rest()` takes       |
+| `cookies`          | `string \| Record<string, string>` | -                               | Cookie authentication, same modes as `rest()`   |
+| `sessionId`        | `string`                           | -                               | `mcp-session-id` header (`mcp()` only)          |
+| `statusCode`       | `number`                           | `200`, `202` for a notification | Expected HTTP status (`mcp()` only)             |
+| `path`             | `string`                           | `'/ai/mcp'`                     | Endpoint, for a project with its own MCP module |
+| `headers`          | `Record<string, string>`           | -                               | Additional headers                              |
+| `log` / `logError` | `boolean`                          | `false`                         | Same as `rest()`                                |
+
+`mcpSession()` additionally takes `clientInfo` and `protocolVersion` for the `initialize` request.
+`TestHelper.parseMcpMessage(response)` is the parser behind both, for tests that send requests themselves.

package/src/test/test.helper.ts

@@ -197,6 +197,156 @@ export interface TestDownloadOptions {
   token?: string;
 }
 
+/**
+ * Options for MCP requests (`testHelper.mcp()` / `testHelper.mcpSession()`)
+ */
+export interface TestMcpOptions {
+  /**
+   * Cookie-based authentication, same three modes as {@link TestRestOptions.cookies}
+   */
+  cookies?: Record<string, string> | string;
+
+  /**
+   * Additional request headers, merged over the MCP defaults (`Accept`, `Content-Type`, `mcp-session-id`)
+   */
+  headers?: Record<string, string>;
+
+  log?: boolean;
+  logError?: boolean;
+
+  /**
+   * MCP endpoint path. Default: `/ai/mcp`, the built-in MCP server of the AI module
+   */
+  path?: string;
+
+  /**
+   * Value of the `mcp-session-id` header. Omit it for `initialize`, which opens a session.
+   */
+  sessionId?: string;
+
+  /**
+   * Expected HTTP status. Default: 200 for a request, 202 for a notification (a message without `id`)
+   */
+  statusCode?: number;
+
+  /**
+   * Bearer token: the user's normal session token or JWT, the same one `rest()` and `graphQl()` take
+   */
+  token?: string;
+}
+
+/**
+ * Options for `testHelper.mcpSession()`
+ */
+export interface TestMcpSessionOptions extends Omit<TestMcpOptions, 'sessionId' | 'statusCode'> {
+  /**
+   * `clientInfo` sent with `initialize`. Default: `{ name: 'nest-server-test-helper', version: '1.0.0' }`
+   */
+  clientInfo?: { name: string; version: string };
+
+  /**
+   * Protocol version requested in `initialize`. Default: `2025-03-26`
+   */
+  protocolVersion?: string;
+}
+
+/**
+ * One JSON-RPC message as the MCP transport returns it. For an answer that is not JSON-RPC
+ * (e.g. the JSON body of a 404 for an unknown session), the parsed body.
+ */
+export interface TestMcpMessage {
+  [key: string]: any;
+  error?: any;
+  id?: null | number | string;
+  jsonrpc?: '2.0';
+  result?: any;
+}
+
+/**
+ * Response of `testHelper.mcp()`
+ */
+export interface TestMcpResponse {
+  /**
+   * The JSON-RPC message from the SSE `data:` line or the JSON body; `null` for a notification (202, no body)
+   */
+  message: null | TestMcpMessage;
+
+  /**
+   * Full supertest response: status, headers, raw text
+   */
+  response: any;
+
+  /**
+   * `mcp-session-id` response header, set by `initialize`
+   */
+  sessionId?: string;
+}
+
+/**
+ * Result of `session.callTool()`: the MCP `CallToolResult` plus its first text content parsed as JSON
+ */
+export interface TestMcpToolResult {
+  [key: string]: any;
+  content: { [key: string]: any; text?: string; type: string }[];
+  isError?: boolean;
+
+  /**
+   * `content[0].text` parsed as JSON, or `undefined` when it is no JSON. The built-in MCP server returns a
+   * tool's own result this way (`{ data, success }`), and an error result as plain text.
+   */
+  json?: any;
+}
+
+/**
+ * MCP tool descriptor from `tools/list`
+ */
+export interface TestMcpTool {
+  [key: string]: any;
+  description?: string;
+  inputSchema?: any;
+  name: string;
+}
+
+/**
+ * An initialized MCP session, returned by `testHelper.mcpSession()`
+ */
+export interface TestMcpSession {
+  /**
+   * `tools/call`. Expects a JSON-RPC result (a refused or failing tool is a result with `isError: true`,
+   * not a protocol error) and returns it with `json` parsed from the first text content.
+   */
+  callTool(name: string, args?: Record<string, unknown>): Promise<TestMcpToolResult>;
+
+  /**
+   * Ends the session server-side (`DELETE` with the session id)
+   */
+  close(): Promise<void>;
+
+  /**
+   * Result of `initialize`: `serverInfo`, `capabilities`, `protocolVersion`
+   */
+  initializeResult: any;
+
+  /**
+   * `tools/list`. Expects a JSON-RPC result and returns its `tools`.
+   */
+  listTools(): Promise<TestMcpTool[]>;
+
+  /**
+   * Any JSON-RPC request in this session. Returns the whole message, so a test can assert a protocol `error`.
+   */
+  request(
+    method: string,
+    params?: Record<string, unknown>,
+    options?: Pick<TestMcpOptions, 'log' | 'logError' | 'statusCode'>,
+  ): Promise<null | TestMcpMessage>;
+
+  /**
+   * `mcp-session-id` the server assigned
+   */
+  sessionId: string;
+}
+
 /**
  * Test helper
  */
@@ -476,6 +626,119 @@ export class TestHelper {
     return undefined;
   }
 
+  /**
+   * Send one JSON-RPC message to an MCP endpoint (Streamable HTTP transport, default `/ai/mcp`).
+   *
+   * The transport answers a request as an SSE stream (`event: message` + `data: {…}`) and a notification
+   * with 202 and no body. This method sets the `Accept` header both need, sends the session id when given,
+   * checks the HTTP status like `rest()` does, and parses the JSON-RPC message out of the stream, so a test
+   * reads `message.result` instead of splitting SSE lines itself.
+   *
+   * For a whole conversation (initialize, then tools), use {@link mcpSession}.
+   *
+   * @example
+   * // An MCP endpoint without a token answers 401
+   * await testHelper.mcp({ id: 1, method: 'initialize', params: {} }, { statusCode: 401 });
+   */
+  async mcp(message: Record<string, unknown>, options: TestMcpOptions = {}): Promise<TestMcpResponse> {
+    const isNotification = message.id === undefined;
+    const response = await this.rest(options.path ?? '/ai/mcp', {
+      cookies: options.cookies,
+      headers: {
+        Accept: 'application/json, text/event-stream',
+        'Content-Type': 'application/json',
+        ...(options.sessionId ? { 'mcp-session-id': options.sessionId } : {}),
+        ...options.headers,
+      },
+      log: options.log,
+      logError: options.logError,
+      method: 'POST',
+      payload: { jsonrpc: '2.0', ...message },
+      returnResponse: true,
+      statusCode: options.statusCode ?? (isNotification ? 202 : 200),
+      token: options.token,
+    });
+    return {
+      message: TestHelper.parseMcpMessage(response),
+      response,
+      sessionId: response?.headers?.['mcp-session-id'],
+    };
+  }
+
+  /**
+   * Open an MCP session the way every MCP client does (`initialize`, then `notifications/initialized`)
+   * and return helpers for the calls a test makes: `listTools()`, `callTool()`, `request()`, `close()`.
+   *
+   * The session belongs to the user of `token` (or `cookies`): the built-in server filters `tools/list`
+   * and `tools/call` by that user's roles, so open one session per user a test compares.
+   *
+   * @example
+   * const session = await testHelper.mcpSession({ token: userToken });
+   * const names = (await session.listTools()).map(tool => tool.name);
+   * expect(names).not.toContain('delete_user');
+   *
+   * const refused = await session.callTool('delete_user', { id });
+   * expect(refused.isError).toBe(true);
+   */
+  async mcpSession(options: TestMcpSessionOptions = {}): Promise<TestMcpSession> {
+    const { clientInfo, protocolVersion, ...base } = options;
+    const path = base.path ?? '/ai/mcp';
+
+    const init = await this.mcp(
+      {
+        id: 1,
+        method: 'initialize',
+        params: {
+          capabilities: {},
+          clientInfo: clientInfo ?? { name: 'nest-server-test-helper', version: '1.0.0' },
+          protocolVersion: protocolVersion ?? '2025-03-26',
+        },
+      },
+      base,
+    );
+    expect(init.message?.error).toBeUndefined();
+    expect(init.sessionId).toBeTruthy();
+    const sessionId = init.sessionId;
+    await this.mcp({ method: 'notifications/initialized' }, { ...base, sessionId });
+
+    let nextId = 2;
+    const request: TestMcpSession['request'] = async (method, params, requestOptions = {}) => {
+      const reply = await this.mcp(
+        { id: nextId++, method, ...(params ? { params } : {}) },
+        { ...base, ...requestOptions, sessionId },
+      );
+      return reply.message;
+    };
+
+    return {
+      callTool: async (name, args = {}) => {
+        const reply = await request('tools/call', { arguments: args, name });
+        expect(reply?.error).toBeUndefined();
+        const result = reply?.result ?? { content: [] };
+        return { ...result, json: TestHelper.parseJsonOrUndefined(result.content?.[0]?.text) };
+      },
+      close: async () => {
+        await this.rest(path, {
+          cookies: base.cookies,
+          headers: { ...base.headers, 'mcp-session-id': sessionId },
+          log: base.log,
+          logError: base.logError,
+          method: 'DELETE',
+          returnResponse: true,
+          token: base.token,
+        });
+      },
+      initializeResult: init.message?.result,
+      listTools: async () => {
+        const reply = await request('tools/list');
+        expect(reply?.error).toBeUndefined();
+        return reply?.result?.tools ?? [];
+      },
+      request,
+      sessionId,
+    };
+  }
+
   /**
    * Send REST request
    */
@@ -929,6 +1192,46 @@ export class TestHelper {
     return value;
   }
 
+  /**
+   * Parse the JSON-RPC message out of an MCP response: the first `data:` line that carries a `result` or
+   * an `error` in an SSE stream (a server may send notifications before the response), or the JSON body
+   * otherwise. Returns `null` for an empty body (a notification's 202).
+   */
+  static parseMcpMessage(response: { headers?: Record<string, any>; text?: string }): null | TestMcpMessage {
+    const text = response?.text ?? '';
+    if (!text.trim()) {
+      return null;
+    }
+    const contentType = String(response?.headers?.['content-type'] ?? '');
+    if (contentType.includes('text/event-stream') || /^(event|data|id):/m.test(text)) {
+      for (const line of text.split(/\r?\n/)) {
+        if (!line.startsWith('data:')) {
+          continue;
+        }
+        const parsed = TestHelper.parseJsonOrUndefined(line.slice(5).trim());
+        if (parsed && (parsed.result !== undefined || parsed.error !== undefined)) {
+          return parsed;
+        }
+      }
+      return null;
+    }
+    return TestHelper.parseJsonOrUndefined(text) ?? null;
+  }
+
+  /**
+   * `JSON.parse`, or `undefined` for input that is no JSON
+   */
+  static parseJsonOrUndefined(text: string | undefined): any {
+    if (typeof text !== 'string') {
+      return undefined;
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      return undefined;
+    }
+  }
+
   /**
    * Convert JWT into to object
    * @param token