@flareapp/node 0.1.0

package/.oxlintrc.json

@@ -0,0 +1,7 @@
+{
+    "$schema": "../../node_modules/oxlint/configuration_schema.json",
+    "extends": ["../../.oxlintrc.json"],
+    "env": {
+        "node": true
+    }
+}

package/.release-it.json

@@ -0,0 +1,13 @@
+{
+    "git": {
+        "tagName": "@flareapp/node@${version}",
+        "tagAnnotation": "Release @flareapp/node@${version}",
+        "commitMessage": "chore: release @flareapp/node@${version}",
+        "requireBranch": "main",
+        "requireCleanWorkingDir": true,
+        "push": true
+    },
+    "npm": { "publish": true },
+    "github": { "release": false },
+    "hooks": { "before:release": "node ../../scripts/check-deps-published.mjs && npm test --if-present" }
+}

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# @flareapp/node changelog
+
+## 0.1.0 — 2026-05-28
+
+Initial release. Standalone Node.js SDK.
+
+- `flare.runWithContext({ method, path, url, headers, body }, fn)` opens an
+  AsyncLocalStorage-backed scope for a single request. Glows, custom context,
+  user identity, and entry point are all isolated.
+- `flare.setUser({ id, email, username, ipAddress })` attaches identity to the
+  active scope. Mirrors Sentry's split between user identity and request context.
+- Process listeners attached on `flare.light(key)` based on
+  `uncaughtExceptionMode` and `unhandledRejectionMode` (each `off`, `report`,
+  or `report-and-exit`; default `report-and-exit`). Listener state reconciles
+  dynamically when `configureNode(...)` is called later.
+- Default header denylist redacts `authorization`, `cookie`, `set-cookie`,
+  `x-api-key`, CSRF tokens, and forwarding headers. Custom allowlist and
+  denylist available via `configureNode`.
+- Request body capture is off by default; opt in via
+  `configureNode({ captureRequestBody: true })`. JSON and form-urlencoded
+  content types accepted; 16 KB cap; circular references and PII keys redacted.
+- Requires Node >=22.

package/README.md

@@ -0,0 +1,158 @@
+# @flareapp/node
+
+Node.js SDK for [flareapp.io](https://flareapp.io). Capture uncaught
+exceptions, unhandled rejections, and explicit `flare.report(err)` calls in
+your Node servers. Per-request context isolation via AsyncLocalStorage.
+
+> **Status: unstable (0.x).** This package is pre-1.0 and its API may change
+> between minor releases. Pin an exact version in production
+> (`"@flareapp/node": "0.1.0"`). The 2.x packages (`@flareapp/js` and the
+> framework integrations) are stable and unaffected.
+
+Requires Node 22 or newer.
+
+## Install
+
+```bash
+npm install @flareapp/node
+```
+
+## Quick start
+
+```ts
+import { flare } from '@flareapp/node';
+
+flare.light('your-flare-api-key');
+```
+
+That's it. Crashes and unhandled rejections are reported automatically (the
+default behavior is to report, flush, and exit with code 1).
+
+## Per-request context
+
+In an HTTP server, wrap each request handler with `runWithContext` so the
+SDK has request data attached to any error reported during that request:
+
+```ts
+import http from 'node:http';
+import { flare } from '@flareapp/node';
+
+flare.light('your-flare-api-key');
+
+http.createServer((req, res) => {
+    flare.runWithContext({ method: req.method, path: req.url, headers: req.headers }, () => {
+        // your handler logic
+    });
+}).listen(3000);
+```
+
+When your authentication middleware resolves a user, attach it:
+
+```ts
+flare.setUser({ id: user.id, email: user.email });
+```
+
+You can also patch the request context after it was first set:
+
+```ts
+flare.mergeContext({ url: resolvedAbsoluteUrl });
+```
+
+## Framework wiring
+
+> **Async errors and request context.** A report only carries request context
+> (`http.request.*`, `url.path`, user) when it is created while the request's
+> `runWithContext` scope is active. `AsyncLocalStorage` propagates that scope
+> across `await`, but a report fired from a framework's _global_ error handler
+> only stays in scope if that handler runs inside the request's async chain.
+> When in doubt, report inside `runWithContext`. The patterns below are verified
+> by `e2e/node-frameworks/context.spec.ts` against the versions noted.
+
+### Express
+
+```ts
+import express from 'express';
+import { flare } from '@flareapp/node';
+
+flare.light('your-key');
+
+const app = express();
+app.use((req, res, next) => {
+    flare.runWithContext({ method: req.method, path: req.originalUrl, headers: req.headers }, () => next());
+});
+// ... your routes
+app.use((err, req, res, next) => {
+    flare.report(err);
+    res.status(500).send('Internal Server Error');
+});
+```
+
+### Fastify
+
+```ts
+import Fastify from 'fastify';
+import { flare } from '@flareapp/node';
+
+flare.light('your-key');
+
+const app = Fastify();
+app.addHook('onRequest', (req, _reply, done) => {
+    flare.runWithContext({ method: req.method, path: req.url, headers: req.headers }, () => done());
+});
+app.setErrorHandler((err, _req, reply) => {
+    flare.report(err);
+    reply.status(500).send({ error: 'Internal Server Error' });
+});
+```
+
+### Hono
+
+```ts
+import { Hono } from 'hono';
+import { flare } from '@flareapp/node';
+
+flare.light('your-key');
+
+const app = new Hono();
+app.use('*', async (c, next) => {
+    await flare.runWithContext(
+        { method: c.req.method, path: c.req.path, headers: Object.fromEntries(c.req.raw.headers) },
+        () => next(),
+    );
+});
+app.onError((err, c) => {
+    flare.report(err);
+    return c.text('Internal Server Error', 500);
+});
+```
+
+Verified with Express 5, Fastify 5, Hono 4. Express 4 does not catch async
+route errors at all (they surface as `unhandledRejection`); use Express 5 or
+report inside `runWithContext`.
+
+## Configuration
+
+```ts
+flare.configureNode({
+    uncaughtExceptionMode: 'report-and-exit', // 'off' | 'report' | 'report-and-exit'
+    unhandledRejectionMode: 'report-and-exit',
+    shutdownTimeoutMs: 2000,
+    captureRequestBody: false,
+    bodyMaxBytes: 16_384,
+    headerDenylist: /^x-private-/i, // unioned with the default denylist
+    headerAllowlist: undefined,
+});
+```
+
+## Security: header and body capture defaults
+
+Headers are emitted as `http.request.header.<lowercase-name>`. The default
+denylist redacts `authorization`, `cookie`, `set-cookie`, `x-api-key`,
+`proxy-authorization`, `x-csrf-token`, `x-xsrf-token`, `x-auth-token`,
+`forwarded`, and `x-forwarded-for|user`. Values for denylisted headers are
+replaced with `[redacted]`.
+
+Body capture is off by default. When enabled, only `application/json` and
+`application/x-www-form-urlencoded` content types are captured. PII keys
+(`password`, `token`, `secret`, etc.) are redacted in the captured body. Body
+is truncated to 16 KB by default.

package/package.json

@@ -0,0 +1,54 @@
+{
+    "name": "@flareapp/node",
+    "version": "0.1.0",
+    "description": "Node.js SDK for flareapp.io",
+    "homepage": "https://flareapp.io",
+    "bugs": {
+        "url": "https://github.com/spatie/flare-client-js/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/spatie/flare-client-js.git"
+    },
+    "license": "MIT",
+    "author": {
+        "name": "Spatie",
+        "email": "info@spatie.be"
+    },
+    "main": "./dist/index.cjs",
+    "module": "./dist/index.mjs",
+    "types": "./dist/index.d.cts",
+    "exports": {
+        ".": {
+            "import": {
+                "types": "./dist/index.d.mts",
+                "default": "./dist/index.mjs"
+            },
+            "require": {
+                "types": "./dist/index.d.cts",
+                "default": "./dist/index.cjs"
+            }
+        }
+    },
+    "engines": {
+        "node": ">=22"
+    },
+    "scripts": {
+        "prepublishOnly": "npm run build",
+        "build": "tsdown src/index.ts --format cjs,esm --dts --env.FLARE_JS_CLIENT_VERSION=$(node -p \"require('./package.json').version\") --clean",
+        "test": "vitest run",
+        "typescript": "tsc --noEmit",
+        "release": "release-it"
+    },
+    "dependencies": {
+        "@flareapp/core": "2.2.0"
+    },
+    "devDependencies": {
+        "tsdown": "^0.20.3",
+        "typescript": "^5.7.0",
+        "vitest": "^4.0.18"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/src/Flare.ts

@@ -0,0 +1,224 @@
+import { Api, Flare as CoreFlare } from '@flareapp/core';
+
+import { DEFAULT_BODY_CONTENT_TYPES, DEFAULT_BODY_KEY_DENYLIST } from './context/body';
+import { makeNodeContextCollector } from './context/collectNode';
+import { DEFAULT_HEADER_DENYLIST, resolveHeaderDenylist } from './context/headers';
+import { buildFatalCallbacks } from './process/fatal';
+import { ProcessHandlerManager } from './process/handlers';
+import { AsyncLocalStorageScopeProvider } from './scope/AsyncLocalStorageScopeProvider';
+import type { NodeScope } from './scope/NodeScope';
+import { DiskFileReader } from './stacktrace/DiskFileReader';
+import type { NodeOptions, RequestContext, ResolvedNodeOptions, User } from './types';
+
+const NODE_SDK_NAME = '@flareapp/node';
+const NODE_SDK_VERSION =
+    typeof process !== 'undefined' && process.env?.FLARE_JS_CLIENT_VERSION !== undefined
+        ? process.env.FLARE_JS_CLIENT_VERSION
+        : '?';
+
+/**
+ * Strip the `g` and `y` flags from a user-supplied regex.
+ *
+ * `RegExp.prototype.test()` and `.exec()` keep `lastIndex` state when either of
+ * these flags is set, which means reusing the same regex across many keys (as
+ * the header denylist and body redaction do) silently skips matches after the
+ * first hit. Reconstructing the regex without those flags gives stateless
+ * matching while preserving everything else (`i`, `m`, `s`, `u`, source).
+ */
+function sanitizeRegex(re: RegExp): RegExp {
+    const safeFlags = re.flags.replace(/[gy]/g, '');
+    return new RegExp(re.source, safeFlags);
+}
+
+const DEFAULT_NODE_OPTIONS: ResolvedNodeOptions = {
+    uncaughtExceptionMode: 'report-and-exit',
+    unhandledRejectionMode: 'report-and-exit',
+    shutdownTimeoutMs: 2000,
+    headerDenylist: DEFAULT_HEADER_DENYLIST,
+    headerAllowlist: null,
+    replaceDefaultHeaderDenylist: false,
+    captureRequestBody: false,
+    bodyMaxBytes: 16_384,
+    bodyAllowedContentTypes: DEFAULT_BODY_CONTENT_TYPES,
+    bodyKeyDenylist: DEFAULT_BODY_KEY_DENYLIST,
+};
+
+/**
+ * Node.js-specific `Flare` singleton, exposed from `@flareapp/node` as `flare`.
+ *
+ * Subclasses core's `Flare` and wires the Node-only seams in its constructor:
+ *
+ * - `AsyncLocalStorageScopeProvider` so each `runWithContext(...)` callback
+ *   gets its own `NodeScope` (glows, attributes, user, entry-point, request),
+ *   isolated from concurrent requests.
+ * - `makeNodeContextCollector(...)` to project the current `NodeScope` and
+ *   process info into report attributes (http.request.*, url.path, etc).
+ * - `DiskFileReader` to read source files for stack-trace snippets via
+ *   `node:fs/promises` instead of the browser's `fetch`.
+ * - `ProcessHandlerManager` to attach/detach `uncaughtException` and
+ *   `unhandledRejection` listeners based on the current `NodeOptions`.
+ *
+ * Also adds Node-only API surface on top of core: `configureNode(...)`,
+ * `runWithContext(...)`, `mergeContext(...)`, `setUser(...)`, `getContext()`,
+ * `removeProcessListeners()`. Inherited core methods (`light`, `configure`,
+ * `addContext`, `glow`, etc.) return `this`, so chaining keeps the
+ * `NodeFlare` type and `configureNode(...)` stays callable mid-chain.
+ */
+export class NodeFlare extends CoreFlare {
+    private nodeOptions: ResolvedNodeOptions = { ...DEFAULT_NODE_OPTIONS };
+    private isLit = false;
+    private nodeScopeProvider: AsyncLocalStorageScopeProvider;
+    private handlerManager: ProcessHandlerManager;
+
+    constructor() {
+        const scopeProvider = new AsyncLocalStorageScopeProvider();
+        // The collector closes over `() => this.nodeOptions` (a getter, not a
+        // value) so subsequent `configureNode(...)` calls take effect on
+        // future reports without reinjecting the collector.
+        const collector = makeNodeContextCollector(scopeProvider, () => this.nodeOptions);
+        super(new Api(), collector, new DiskFileReader(), scopeProvider);
+        this.nodeScopeProvider = scopeProvider;
+        this.setSdkInfo({ name: NODE_SDK_NAME, version: NODE_SDK_VERSION });
+
+        const cbs = buildFatalCallbacks(this, () => this.nodeOptions);
+        this.handlerManager = new ProcessHandlerManager(cbs);
+    }
+
+    /**
+     * Set the API key (and optional debug flag), then reconcile process
+     * listeners with the current `nodeOptions`. Reconcile runs on EVERY call,
+     * not just the first, so `light()` is the right escape hatch to re-attach
+     * after `removeProcessListeners()`.
+     */
+    light(key?: string, debug?: boolean) {
+        super.light(key, debug);
+        this.isLit = true;
+        this.handlerManager.reconcile(this.nodeOptions);
+        return this;
+    }
+
+    /**
+     * Merge Node-only options (fatal-handler modes, header/body redaction
+     * config, shutdown timeout) into the active configuration. Safe to call
+     * before or after `light()`:
+     *
+     * - Before `light()`: options are stored; listeners are attached when
+     *   `light()` runs.
+     * - After `light()`: options are stored AND listeners are reconciled
+     *   immediately, so flipping a mode to `'off'` detaches the handler and
+     *   flipping it back to `'report'`/`'report-and-exit'` re-attaches.
+     *
+     * Regex options (`headerAllowlist`, `bodyAllowedContentTypes`,
+     * `bodyKeyDenylist`) are passed through `sanitizeRegex` to strip stateful
+     * `g`/`y` flags; without that, `RegExp.prototype.test` would skip matches
+     * across keys.
+     */
+    configureNode(partial: Partial<NodeOptions>): NodeFlare {
+        if (partial.headerDenylist !== undefined || partial.replaceDefaultHeaderDenylist !== undefined) {
+            this.nodeOptions.headerDenylist = resolveHeaderDenylist(
+                partial.headerDenylist ?? undefined,
+                partial.replaceDefaultHeaderDenylist ?? this.nodeOptions.replaceDefaultHeaderDenylist,
+            );
+            this.nodeOptions.replaceDefaultHeaderDenylist =
+                partial.replaceDefaultHeaderDenylist ?? this.nodeOptions.replaceDefaultHeaderDenylist;
+        }
+
+        if (partial.headerAllowlist !== undefined) {
+            this.nodeOptions.headerAllowlist =
+                partial.headerAllowlist === null ? null : sanitizeRegex(partial.headerAllowlist);
+        }
+
+        if (partial.uncaughtExceptionMode !== undefined) {
+            this.nodeOptions.uncaughtExceptionMode = partial.uncaughtExceptionMode;
+        }
+
+        if (partial.unhandledRejectionMode !== undefined) {
+            this.nodeOptions.unhandledRejectionMode = partial.unhandledRejectionMode;
+        }
+
+        if (partial.shutdownTimeoutMs !== undefined) {
+            this.nodeOptions.shutdownTimeoutMs = partial.shutdownTimeoutMs;
+        }
+
+        if (partial.captureRequestBody !== undefined) {
+            this.nodeOptions.captureRequestBody = partial.captureRequestBody;
+        }
+
+        if (partial.bodyMaxBytes !== undefined) {
+            this.nodeOptions.bodyMaxBytes = partial.bodyMaxBytes;
+        }
+
+        if (partial.bodyAllowedContentTypes !== undefined) {
+            this.nodeOptions.bodyAllowedContentTypes = sanitizeRegex(partial.bodyAllowedContentTypes);
+        }
+
+        if (partial.bodyKeyDenylist !== undefined) {
+            this.nodeOptions.bodyKeyDenylist = sanitizeRegex(partial.bodyKeyDenylist);
+        }
+
+        if (this.isLit) {
+            this.handlerManager.reconcile(this.nodeOptions);
+        }
+
+        return this;
+    }
+
+    /**
+     * Run `fn` inside a fresh `NodeScope` carrying the supplied request
+     * metadata. Inside `fn` (and any async work it awaits), `flare.glow(...)`,
+     * `flare.addContext(...)`, `flare.setUser(...)`, and `flare.report(...)`
+     * see a scope that is isolated from other concurrent requests.
+     *
+     * Mirrors a typical web-framework middleware: call once per request,
+     * wrapping the request handler, and the SDK will attribute any error
+     * reported inside the chain to the right request.
+     */
+    runWithContext<T>(request: RequestContext, fn: () => T): T {
+        return this.nodeScopeProvider.runWithContext(request, fn);
+    }
+
+    /**
+     * Patch the request metadata on the active scope after `runWithContext(...)`
+     * has already started. Useful when fields become known partway through a
+     * request (e.g., the resolved absolute URL after proxy headers are parsed).
+     *
+     * Outside any `runWithContext(...)` callback, this writes to the fallback
+     * scope; the patch is visible to subsequent reports issued from outside a
+     * request scope but is NOT inherited by future `runWithContext(...)` calls.
+     */
+    mergeContext(partial: Partial<RequestContext>): void {
+        this.nodeScopeProvider.mergeContext(partial);
+    }
+
+    /**
+     * Attach an authenticated user to the active scope. Inside a request scope
+     * this is per-request; outside it lands on the fallback scope. The fields
+     * are projected to OTel-style keys (`enduser.id`, `enduser.email`,
+     * `enduser.username`, `client.address`) by the Node context collector.
+     */
+    setUser(user: User | null): void {
+        this.nodeScopeProvider.setUser(user);
+    }
+
+    /**
+     * Returns the request scope when called inside `runWithContext(...)`, or
+     * `null` outside. Intentionally returns `null` (not the fallback scope)
+     * when no request is active, so callers can distinguish "we are inside a
+     * request" from "we are not". Primarily useful for debugging.
+     */
+    getContext(): NodeScope | null {
+        return this.nodeScopeProvider.getContext();
+    }
+
+    /**
+     * Detach the `uncaughtException` and `unhandledRejection` listeners
+     * without changing `nodeOptions`. Intended for tests and for graceful
+     * shutdown paths where you want to take ownership of process exit
+     * yourself.
+     *
+     * Calling `light()` afterwards re-attaches based on the current options.
+     */
+    removeProcessListeners(): void {
+        this.handlerManager.detach();
+    }
+}

package/src/context/body.ts

@@ -0,0 +1,185 @@
+import { DEFAULT_URL_DENYLIST } from '@flareapp/core';
+
+/**
+ * Content types accepted by default for body capture. JSON and
+ * URL-encoded forms cover the vast majority of API payloads while keeping
+ * the parser surface tiny. `\b` after the second alternative prevents
+ * accidental matches like `application/x-www-form-urlencoded-foo` (artificial
+ * but cheap to defend against). The leading `^` plus `\b` lets us match
+ * either bare types or types with `; charset=utf-8` style suffixes.
+ */
+export const DEFAULT_BODY_CONTENT_TYPES = /^application\/(json|x-www-form-urlencoded)\b/i;
+
+/**
+ * Keys whose values get replaced with `[redacted]` during body redaction.
+ * Reuses core's URL denylist so credentials, tokens, etc are caught with the
+ * same regex everywhere (less surface for users to keep in sync).
+ */
+export const DEFAULT_BODY_KEY_DENYLIST = DEFAULT_URL_DENYLIST;
+
+type BodyOptions = {
+    bodyAllowedContentTypes: RegExp;
+    bodyKeyDenylist: RegExp;
+    bodyMaxBytes: number;
+};
+
+/**
+ * Normalize, redact, serialize, and size-cap a request body for inclusion in
+ * a Flare report.
+ *
+ * Accepts four runtime shapes (whatever the user hands us via
+ * `runWithContext({ body, ... })`):
+ *
+ * - `string` — assumed to match the declared `contentType`. Must be JSON or
+ *   form-encoded text per `bodyAllowedContentTypes`; otherwise dropped.
+ * - `Buffer` — decoded as UTF-8 then treated like a string.
+ * - `URLSearchParams` — flattened to a plain `Record<string, string>`. No
+ *   content-type gate (the type is unambiguous from the shape).
+ * - Other `object` (POJO, array) — used as-is, no content-type gate. This is
+ *   the common middleware path (Express's `req.body`, Fastify's, etc).
+ *
+ * Anything else (`number`, `boolean`, class instance, stream) returns `null`
+ * and the body is not reported.
+ *
+ * After parsing:
+ *
+ * 1. **Redact.** Walk the value, replacing any property whose key matches
+ *    `bodyKeyDenylist` with `'[redacted]'`. Handles arrays, nested objects,
+ *    and circular references (`WeakSet`-tracked, emits `'[Circular]'` on
+ *    repeat sight).
+ * 2. **Stringify.** `JSON.stringify`; if it throws (BigInt, Symbol, etc),
+ *    drop the body entirely.
+ * 3. **Truncate.** Cap at `bodyMaxBytes` UTF-8 bytes (the option's named
+ *    semantic) INCLUDING the suffix. Truncation respects codepoint boundaries
+ *    so the result decodes cleanly with no replacement characters.
+ *
+ * Returns the final JSON string, or `null` when the body should not be
+ * reported (unknown shape, content-type miss, serialization failure).
+ */
+export function captureBody(body: unknown, contentType: string | undefined, opts: BodyOptions): string | null {
+    if (body === undefined || body === null) return null;
+
+    let parsed: unknown;
+    if (typeof body === 'string') {
+        if (!matchesContentType(contentType, opts.bodyAllowedContentTypes)) return null;
+        parsed = parseString(body, contentType);
+        if (parsed === undefined) return null;
+    } else if (Buffer.isBuffer(body)) {
+        if (!matchesContentType(contentType, opts.bodyAllowedContentTypes)) return null;
+        parsed = parseString(body.toString('utf8'), contentType);
+        if (parsed === undefined) return null;
+    } else if (body instanceof URLSearchParams) {
+        parsed = Object.fromEntries(body.entries());
+    } else if (Array.isArray(body) || isPlainObject(body)) {
+        parsed = body;
+    } else {
+        return null;
+    }
+
+    const redacted = redact(parsed, opts.bodyKeyDenylist);
+    let serialized: string;
+    try {
+        serialized = JSON.stringify(redacted);
+    } catch {
+        return null;
+    }
+    return truncateToByteLimit(serialized, opts.bodyMaxBytes);
+}
+
+const TRUNCATION_SUFFIX = '…[truncated]';
+const TRUNCATION_SUFFIX_BYTES = Buffer.byteLength(TRUNCATION_SUFFIX, 'utf8');
+
+/**
+ * Truncate a serialized string so the resulting UTF-8 byte length never
+ * exceeds `maxBytes`, including the appended truncation suffix.
+ *
+ * Walks backwards from the budget index while the byte at that position is a
+ * UTF-8 continuation byte (`10xxxxxx`), stopping at the first byte that
+ * starts a new codepoint. Slicing at that index leaves a buffer that decodes
+ * cleanly with no replacement characters.
+ */
+function truncateToByteLimit(serialized: string, maxBytes: number): string {
+    const buf = Buffer.from(serialized, 'utf8');
+    if (buf.length <= maxBytes) return serialized;
+    if (maxBytes <= TRUNCATION_SUFFIX_BYTES) {
+        // Budget too small to fit the suffix plus any payload. Emit the suffix
+        // truncated to the byte budget, respecting codepoint boundaries.
+        const suffixBuf = Buffer.from(TRUNCATION_SUFFIX, 'utf8');
+        let cut = maxBytes;
+        while (cut > 0 && (suffixBuf[cut] & 0xc0) === 0x80) cut--;
+        return suffixBuf.subarray(0, cut).toString('utf8');
+    }
+    let cut = maxBytes - TRUNCATION_SUFFIX_BYTES;
+    while (cut > 0 && (buf[cut] & 0xc0) === 0x80) cut--;
+    return buf.subarray(0, cut).toString('utf8') + TRUNCATION_SUFFIX;
+}
+
+/**
+ * Check whether a `content-type` header is on the allowlist. Normalizes to the
+ * bare media type first: strips any parameters (`; charset=utf-8`), trims, and
+ * lowercases, so the regex is tested against `application/json` rather than the
+ * full header. This lets a strict custom regex like `/^application\/json$/`
+ * still match `application/json; charset=utf-8`. Empty/missing is a hard miss.
+ */
+function matchesContentType(ct: string | undefined, allowed: RegExp): boolean {
+    if (!ct) return false;
+    const mediaType = ct.split(';')[0].trim().toLowerCase();
+    if (!mediaType) return false;
+    return allowed.test(mediaType);
+}
+
+/**
+ * Parse a serialized body string into a JS value, branching on the declared
+ * content type.
+ *
+ * - URL-encoded forms become a flat object so the same `redact` walker works.
+ * - Otherwise treat as JSON. Returns `undefined` (NOT `null`, which is a
+ *   legitimate JSON value) when parsing fails, so the caller can distinguish
+ *   "couldn't parse" from "parsed to literal null".
+ */
+function parseString(text: string, contentType?: string): unknown {
+    if (contentType && /x-www-form-urlencoded/i.test(contentType)) {
+        return Object.fromEntries(new URLSearchParams(text).entries());
+    }
+    try {
+        return JSON.parse(text);
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * True only for `Object.create(null)` or `{}`-shaped values. Excludes class
+ * instances (their prototype chain points somewhere other than Object.prototype
+ * or null), streams, FormData, ArrayBuffer views, Buffer, URLSearchParams,
+ * and other built-ins that happen to be `typeof === 'object'`.
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    if (value === null || typeof value !== 'object') return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || proto === Object.prototype;
+}
+
+/**
+ * Recursively walk `value`, replacing values for denylisted keys with
+ * `'[redacted]'` and substituting `'[Circular]'` for any object visited more
+ * than once.
+ *
+ * `seen` is a `WeakSet` of already-visited objects. Carried as a parameter
+ * (rather than a closure variable) so the same recursive call can pass it
+ * down without per-call allocation.
+ *
+ * Primitives and `null` pass through unchanged. Arrays preserve order;
+ * objects preserve keys.
+ */
+function redact(value: unknown, denylist: RegExp, seen: WeakSet<object> = new WeakSet()): unknown {
+    if (value === null || typeof value !== 'object') return value;
+    if (seen.has(value as object)) return '[Circular]';
+    seen.add(value as object);
+    if (Array.isArray(value)) return value.map((v) => redact(v, denylist, seen));
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = denylist.test(k) ? '[redacted]' : redact(v, denylist, seen);
+    }
+    return out;
+}