midline-agent 0.1.9 → 0.2.0

package/src/proxy.ts

@@ -0,0 +1,435 @@
+import * as http from "http";
+import * as https from "https";
+import { AddressInfo } from "net";
+import { MidlineAgent } from "./agent";
+import { ConfigError, env, envInt, loadCa, resolveCapture, trustStore } from "./config";
+import { createRequestContext, RequestContext } from "./context";
+import { BodyTap, headerValue, isCompressed } from "./tap";
+import { CaInput, CaptureOptions, MidlineConfig } from "./types";
+
+export interface MidlineProxyOptions {
+  /**
+   * The destination API — the thing being monitored. `http://localhost:4000`,
+   * `https://staging.example.com`, `https://api.example.com`. Only its origin and
+   * path prefix are used; clients can never steer a request to another host.
+   * Env fallback: `TARGET_API_URL`.
+   */
+  target?: string;
+  /**
+   * Extra CAs to trust for the destination only (a private/internal CA). Added to
+   * the default trust store; verification is never switched off. Independent of
+   * the Midline server's `ca`. Env fallback: `TARGET_API_CA` (PEM or file path).
+   */
+  targetCa?: CaInput;
+  /** Time allowed for the destination to start responding, in ms. Default 30000. Env: `TARGET_API_TIMEOUT_MS`. */
+  timeoutMs?: number;
+  /** Time allowed to connect to the destination, in ms. Default 5000. */
+  connectTimeoutMs?: number;
+  /**
+   * Retries for requests that never reached the destination (refused, reset, DNS,
+   * connect timeout). Only GET, HEAD and OPTIONS without a body are retried — a
+   * write might have been applied. Default 0. Env: `TARGET_API_RETRIES`.
+   */
+  retries?: number;
+  /** Requests with a larger body get 413. Default 10 MiB. */
+  maxRequestBodyBytes?: number;
+  /** Send the client's Host header upstream instead of the destination's. Default false. */
+  preserveHost?: boolean;
+  /**
+   * Trust `X-Forwarded-*` from the client, e.g. when this proxy itself sits behind a
+   * load balancer. Default false, so clients cannot spoof their address.
+   */
+  trustForwardedHeaders?: boolean;
+  /** Overrides the agent's capture settings for proxied traffic. */
+  capture?: CaptureOptions;
+  /** Where events go. Defaults to `MidlineAgent.current`. Traffic is forwarded either way. */
+  agent?: MidlineAgent;
+  /** Receives proxy diagnostics. Defaults to console.warn. */
+  onError?: (message: string) => void;
+}
+
+export interface MidlineProxy {
+  (req: http.IncomingMessage, res: http.ServerResponse): void;
+  readonly target: URL;
+  /** Releases pooled upstream connections. */
+  close(): void;
+}
+
+const HOP_BY_HOP = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "proxy-connection",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+  "http2-settings",
+]);
+
+const RETRYABLE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+const RETRYABLE_CODES = new Set(["ECONNREFUSED", "ECONNRESET", "EPIPE", "ENOTFOUND", "EAI_AGAIN", "EHOSTUNREACH", "ENETUNREACH", "ECONNECT_TIMEOUT"]);
+const TIMEOUT_CODES = new Set(["ETIMEDOUT", "ECONNECT_TIMEOUT"]);
+
+class ProxyError extends Error {
+  constructor(message: string, readonly code: string) {
+    super(message);
+  }
+}
+
+export function resolveTarget(target: string | undefined): URL {
+  if (!target) {
+    throw new ConfigError("no destination: pass `target` or set TARGET_API_URL (e.g. http://localhost:4000)");
+  }
+  let url: URL;
+  try {
+    url = new URL(target);
+  } catch {
+    throw new ConfigError(`target "${target}" is not a valid URL`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new ConfigError(`target must be http:// or https:// (got ${url.protocol}//)`);
+  }
+  if (url.username || url.password) {
+    throw new ConfigError("target must not contain credentials");
+  }
+  url.search = "";
+  url.hash = "";
+  url.pathname = url.pathname.replace(/\/+$/, "");
+  return url;
+}
+
+/**
+ * A reverse proxy for the destination API: clients call it, it forwards to
+ * `target`, and every exchange is reported to Midline out of band.
+ *
+ * The Midline server is never in the request path. If it is down, slow or
+ * misconfigured, traffic keeps flowing and only telemetry is buffered.
+ */
+export function createMidlineProxy(options: MidlineProxyOptions = {}): MidlineProxy {
+  const target = resolveTarget(options.target ?? env("TARGET_API_URL"));
+  const extraCa = loadCa(options.targetCa ?? env("TARGET_API_CA"), "targetCa / TARGET_API_CA");
+  if (extraCa && target.protocol !== "https:") {
+    throw new ConfigError("targetCa / TARGET_API_CA is set but the target is not https://");
+  }
+
+  const timeoutMs = options.timeoutMs ?? envInt("TARGET_API_TIMEOUT_MS") ?? 30_000;
+  const connectTimeoutMs = options.connectTimeoutMs ?? 5000;
+  const retries = Math.max(0, Math.min(options.retries ?? envInt("TARGET_API_RETRIES") ?? 0, 5));
+  const maxRequestBodyBytes = options.maxRequestBodyBytes ?? 10 * 1024 * 1024;
+  const captureOverride = options.capture ? resolveCapture(options.capture) : undefined;
+  const isHttps = target.protocol === "https:";
+  // `pathname` of an http(s) URL is never empty, so a root target reads as "/". Joining
+  // that with "/users" would forward "//users".
+  const prefix = target.pathname === "/" ? "" : target.pathname;
+  const upstreamAgent = isHttps
+    ? new https.Agent({ keepAlive: true, ca: trustStore(extraCa) })
+    : new http.Agent({ keepAlive: true });
+
+  let lastNotice = "";
+  const warn = (signature: string, message: string) => {
+    if (signature === lastNotice) return;
+    lastNotice = signature;
+    try {
+      (options.onError ?? console.warn)(message);
+    } catch {
+      // ignore
+    }
+  };
+
+  const handler = function midlineProxy(req: http.IncomingMessage, res: http.ServerResponse): void {
+    const started = process.hrtime.bigint();
+    const context = createRequestContext(req.headers);
+    const agent = options.agent ?? MidlineAgent.current;
+    const capture = captureOverride ?? agent?.capture ?? resolveCapture(undefined);
+    const incomingUrl = req.url ?? "/";
+
+    // Origin-form only ("/path?query"). An absolute-form or authority-form request
+    // line would otherwise turn this into an open forward proxy.
+    const upstreamUrl = incomingUrl.startsWith("/") ? new URL(`${target.origin}${prefix}${incomingUrl}`) : null;
+    if (!upstreamUrl || upstreamUrl.origin !== target.origin) {
+      respondError(res, 400, "Bad Request", "Only origin-form request targets are accepted.", context);
+      return;
+    }
+
+    const requestTap = capture.requestBody ? new BodyTap(capture.maxBodyBytes) : undefined;
+    const responseTap = capture.responseBody ? new BodyTap(capture.maxBodyBytes) : undefined;
+    let upstreamResponse: http.IncomingMessage | undefined;
+    let failure: { status: number; code: string; message: string } | undefined;
+    let recorded = false;
+
+    const record = () => {
+      if (recorded) return;
+      recorded = true;
+      if (!agent?.active) return;
+      const responseEncoding = headerValue(upstreamResponse?.headers["content-encoding"]);
+      agent.recordHttp({
+        integration: "proxy",
+        context,
+        method: req.method,
+        url: incomingUrl,
+        statusCode: failure?.status ?? (res.headersSent ? res.statusCode : 499),
+        durationMs: Number(process.hrtime.bigint() - started) / 1e6,
+        ip: clientAddress(req, options.trustForwardedHeaders === true),
+        userAgent: headerValue(req.headers["user-agent"]),
+        aborted: !failure && !res.writableFinished,
+        // Origin and path only — a query string may carry credentials.
+        destination: { url: `${upstreamUrl.origin}${upstreamUrl.pathname}` },
+        errorCode: failure?.code,
+        errorMessage: failure?.message,
+        capture,
+        request: {
+          headers: capture.headers ? req.headers : undefined,
+          contentType: headerValue(req.headers["content-type"]),
+          body: requestTap && requestTap.bytes > 0 && !isCompressed(headerValue(req.headers["content-encoding"])) ? requestTap.body : undefined,
+          bodyBytes: requestTap?.bytes,
+          truncated: requestTap?.truncated,
+        },
+        response: {
+          headers: capture.headers && upstreamResponse ? upstreamResponse.headers : undefined,
+          contentType: headerValue(upstreamResponse?.headers["content-type"]),
+          body: responseTap && responseTap.bytes > 0 && !isCompressed(responseEncoding) ? responseTap.body : undefined,
+          bodyBytes: responseTap?.bytes,
+          truncated: responseTap?.truncated,
+        },
+      });
+    };
+    res.once("finish", record);
+    res.once("close", record);
+
+    const declaredLength = Number(req.headers["content-length"]);
+    if (Number.isFinite(declaredLength) && declaredLength > maxRequestBodyBytes) {
+      failure = { status: 413, code: "EBODY_TOO_LARGE", message: `request body of ${declaredLength} bytes exceeds ${maxRequestBodyBytes}` };
+      res.setHeader("connection", "close");
+      respondError(res, 413, "Payload Too Large", "Request body is too large.", context);
+      req.resume();
+      return;
+    }
+
+    const hasBody = (Number.isFinite(declaredLength) && declaredLength > 0) || req.headers["transfer-encoding"] !== undefined;
+    const canRetry = retries > 0 && !hasBody && RETRYABLE_METHODS.has((req.method ?? "GET").toUpperCase());
+    const headers = forwardHeaders(req, target, context, options);
+
+    let bodyBytes = 0;
+    let bodyTooLarge = false;
+
+    const attempt = (attemptNumber: number) => {
+      let connectTimer: NodeJS.Timeout | undefined;
+      const upstream = (isHttps ? https : http).request(upstreamUrl, {
+        method: req.method,
+        headers,
+        agent: upstreamAgent,
+      });
+
+      const responseTimer = setTimeout(() => {
+        upstream.destroy(new ProxyError(`destination did not respond within ${timeoutMs}ms`, "ETIMEDOUT"));
+      }, timeoutMs);
+
+      upstream.on("socket", (socket) => {
+        if ((socket as any).connecting) {
+          connectTimer = setTimeout(() => {
+            upstream.destroy(new ProxyError(`could not connect to the destination within ${connectTimeoutMs}ms`, "ECONNECT_TIMEOUT"));
+          }, connectTimeoutMs);
+          socket.once(isHttps ? "secureConnect" : "connect", () => clearTimeout(connectTimer));
+        }
+      });
+
+      upstream.on("response", (response) => {
+        clearTimeout(responseTimer);
+        if (connectTimer) clearTimeout(connectTimer);
+        upstreamResponse = response;
+        lastNotice = "";
+
+        res.writeHead(response.statusCode ?? 502, response.statusMessage, stripHopByHop(response.headers));
+        response.on("data", (chunk) => responseTap?.push(chunk));
+        response.on("error", () => res.destroy());
+        response.on("aborted", () => res.destroy());
+        response.pipe(res);
+      });
+
+      upstream.on("error", (err: any) => {
+        clearTimeout(responseTimer);
+        if (connectTimer) clearTimeout(connectTimer);
+        const code = String(err?.code ?? "EUPSTREAM");
+
+        // A destroyed request can report more than one error; answer the first.
+        if (failure) return;
+        if (upstreamResponse) {
+          // Failed mid-body: the status line is already out, so all that's left is to cut the connection.
+          res.destroy();
+          return;
+        }
+        if (bodyTooLarge) {
+          failure = { status: 413, code: "EBODY_TOO_LARGE", message: `request body exceeded ${maxRequestBodyBytes} bytes` };
+          res.setHeader("connection", "close");
+          respondError(res, 413, "Payload Too Large", "Request body is too large.", context);
+          return;
+        }
+        if (res.destroyed || res.writableEnded) {
+          // The client is gone; the close handler records it as aborted.
+          return;
+        }
+        if (canRetry && attemptNumber < retries && RETRYABLE_CODES.has(code)) {
+          setTimeout(() => attempt(attemptNumber + 1), Math.min(100 * 2 ** attemptNumber, 2000));
+          return;
+        }
+
+        const timedOut = TIMEOUT_CODES.has(code);
+        const status = timedOut ? 504 : 502;
+        failure = { status, code, message: describeUpstreamError(code, err, target) };
+        warn(code, `midline proxy: ${failure.message}`);
+        respondError(res, status, timedOut ? "Gateway Timeout" : "Bad Gateway", "The destination API is unavailable.", context);
+      });
+
+      // The client went away: stop the upstream work too.
+      res.once("close", () => {
+        if (!res.writableFinished) upstream.destroy();
+      });
+
+      if (!hasBody) {
+        upstream.end();
+        return;
+      }
+
+      req.on("data", (chunk: Buffer) => {
+        bodyBytes += chunk.length;
+        if (bodyBytes > maxRequestBodyBytes && !bodyTooLarge) {
+          bodyTooLarge = true;
+          req.unpipe(upstream);
+          upstream.destroy(new ProxyError("request body too large", "EBODY_TOO_LARGE"));
+          req.resume();
+          return;
+        }
+        requestTap?.push(chunk);
+      });
+      req.pipe(upstream);
+    };
+
+    attempt(0);
+  } as MidlineProxy;
+
+  Object.defineProperty(handler, "target", { value: target, enumerable: true });
+  (handler as { close: () => void }).close = () => upstreamAgent.destroy();
+  return handler;
+}
+
+export interface StartProxyOptions extends MidlineProxyOptions {
+  /** Default 8080. Env: `MIDLINE_PROXY_PORT`. */
+  port?: number;
+  /** Default 127.0.0.1 — set 0.0.0.0 explicitly to accept traffic from other machines. Env: `MIDLINE_PROXY_HOST`. */
+  host?: string;
+  /** Used to create an agent when `agent` isn't passed and none is initialised. */
+  midline?: MidlineConfig;
+}
+
+export async function startMidlineProxy(options: StartProxyOptions = {}): Promise<http.Server & { proxy: MidlineProxy }> {
+  const agent = options.agent ?? MidlineAgent.current ?? MidlineAgent.init(options.midline ?? {});
+  const proxy = createMidlineProxy({ ...options, agent });
+  const server = http.createServer(proxy) as http.Server & { proxy: MidlineProxy };
+  server.proxy = proxy;
+  server.on("close", () => proxy.close());
+
+  const port = options.port ?? envInt("MIDLINE_PROXY_PORT") ?? 8080;
+  const host = options.host ?? env("MIDLINE_PROXY_HOST") ?? "127.0.0.1";
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  return server;
+}
+
+export function proxyAddress(server: http.Server): string {
+  const address = server.address() as AddressInfo;
+  const host = address.family === "IPv6" ? `[${address.address}]` : address.address;
+  return `http://${host}:${address.port}`;
+}
+
+function forwardHeaders(
+  req: http.IncomingMessage,
+  target: URL,
+  context: RequestContext,
+  options: MidlineProxyOptions,
+): http.OutgoingHttpHeaders {
+  const out = stripHopByHop(req.headers);
+  const trustForwarded = options.trustForwardedHeaders === true;
+  const clientIp = req.socket.remoteAddress ?? "";
+  const incomingFor = headerValue(req.headers["x-forwarded-for"]);
+
+  if (!options.preserveHost) {
+    out.host = target.host;
+  }
+  // Already answered by this server; forwarding it would make the destination wait for a body it already has.
+  delete out.expect;
+
+  const proto = (req.socket as { encrypted?: boolean }).encrypted ? "https" : "http";
+  out["x-forwarded-for"] = trustForwarded && incomingFor ? `${incomingFor}, ${clientIp}` : clientIp;
+  out["x-forwarded-proto"] = (trustForwarded && headerValue(req.headers["x-forwarded-proto"])) || proto;
+  out["x-forwarded-host"] = (trustForwarded && headerValue(req.headers["x-forwarded-host"])) || headerValue(req.headers.host) || "";
+  out["x-request-id"] = context.requestId;
+  out["x-correlation-id"] = context.correlationId;
+  return out;
+}
+
+function stripHopByHop(headers: http.IncomingHttpHeaders): http.OutgoingHttpHeaders {
+  const named = new Set(
+    String(headers.connection ?? "")
+      .split(",")
+      .map((token) => token.trim().toLowerCase())
+      .filter(Boolean),
+  );
+  const out: http.OutgoingHttpHeaders = {};
+  for (const [name, value] of Object.entries(headers)) {
+    if (value === undefined || HOP_BY_HOP.has(name) || named.has(name)) continue;
+    out[name] = value;
+  }
+  return out;
+}
+
+function clientAddress(req: http.IncomingMessage, trustForwarded: boolean): string | undefined {
+  if (trustForwarded) {
+    const forwarded = headerValue(req.headers["x-forwarded-for"])?.split(",")[0]?.trim();
+    if (forwarded) return forwarded;
+  }
+  return req.socket.remoteAddress;
+}
+
+function respondError(res: http.ServerResponse, status: number, error: string, message: string, context: RequestContext): void {
+  if (res.headersSent) {
+    res.destroy();
+    return;
+  }
+  const body = JSON.stringify({ error, message, requestId: context.requestId });
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "content-length": Buffer.byteLength(body),
+    "x-request-id": context.requestId,
+  });
+  res.end(body);
+}
+
+function describeUpstreamError(code: string, err: any, target: URL): string {
+  const where = target.origin;
+  switch (code) {
+    case "ECONNREFUSED":
+      return `${where} refused the connection (is the destination API running?)`;
+    case "ENOTFOUND":
+    case "EAI_AGAIN":
+      return `cannot resolve ${target.hostname} (${code}) — check TARGET_API_URL`;
+    case "ETIMEDOUT":
+    case "ECONNECT_TIMEOUT":
+      return `${where}: ${err?.message ?? code}`;
+    case "DEPTH_ZERO_SELF_SIGNED_CERT":
+    case "SELF_SIGNED_CERT_IN_CHAIN":
+    case "UNABLE_TO_VERIFY_LEAF_SIGNATURE":
+    case "UNABLE_TO_GET_ISSUER_CERT_LOCALLY":
+    case "CERT_HAS_EXPIRED":
+    case "ERR_TLS_CERT_ALTNAME_INVALID":
+      return `${where} presented a certificate that could not be verified (${code}); verification stays on — if the destination uses a private CA, set targetCa / TARGET_API_CA`;
+    default:
+      return `${where}: ${err?.message ?? code} (${code})`;
+  }
+}

package/src/redact.ts

@@ -0,0 +1,231 @@
+/**
+ * Redaction happens in the host process, before an event is queued. Whatever is
+ * removed here never reaches a socket, a log line or the Midline server.
+ *
+ * Matching is on a normalised key — lower-cased with punctuation stripped — so
+ * `X-API-Key`, `api_key` and `apiKey` are all the same key.
+ */
+
+export const REDACTED = "[REDACTED]";
+
+/** Substrings: any key containing one of these is sensitive. */
+const SENSITIVE_KEY_PARTS = [
+  "password",
+  "passwd",
+  "passphrase",
+  "secret",
+  "token",
+  "apikey",
+  "accesskey",
+  "privatekey",
+  "authorization",
+  "cookie",
+  "session",
+  "credential",
+  "csrf",
+  "xsrf",
+  "signature",
+  "creditcard",
+  "cardnumber",
+  "cvv",
+  "cvc",
+  "ssn",
+  "socialsecurity",
+];
+
+/** Whole keys only — as substrings these would hit words like "author" or "spinner". */
+const SENSITIVE_KEYS_EXACT = new Set(["auth", "pwd", "pin", "otp", "sid", "jwt", "bearer"]);
+
+/** Always redacted by name, even if a user-supplied list somehow unmatched them. */
+export const DEFAULT_SENSITIVE_HEADERS = [
+  "authorization",
+  "proxy-authorization",
+  "cookie",
+  "set-cookie",
+  "x-api-key",
+  "api-key",
+  "x-auth-token",
+  "x-access-token",
+  "x-refresh-token",
+  "x-csrf-token",
+  "x-xsrf-token",
+  "x-amz-security-token",
+];
+
+const VALUE_PATTERNS: Array<[RegExp, string]> = [
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, REDACTED],
+  [/\b(Bearer|Basic|Digest|Token)\s+[A-Za-z0-9._~+\/=-]{8,}/gi, `$1 ${REDACTED}`],
+  [/\beyJ[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}/g, REDACTED],
+  [/\bak_[A-Fa-f0-9]{16,}\b/g, REDACTED],
+  [/\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{10,}\b/g, REDACTED],
+  [/\bAKIA[0-9A-Z]{16}\b/g, REDACTED],
+  [/(\b[a-z][a-z0-9+.-]*:\/\/)[^\s\/@:]+:[^\s\/@]+@/gi, `$1${REDACTED}@`],
+];
+
+/** `key=value` / `key: value` in query strings, log lines and error messages. */
+const KEY_VALUE_PAIR = /(^|[?&;,\s(\[{])([A-Za-z0-9_.%-]{1,64})(\s*[=:]\s*)("[^"]*"|'[^']*'|[^\s&#,;)\]}]+)/g;
+/** `"key": value` in JSON text, including JSON that was cut off mid-value. */
+const JSON_PAIR = /"([^"\\]{1,100})"\s*:\s*("(?:[^"\\]|\\.)*"?|-?\d+(?:\.\d+)?|true|false|null)/g;
+
+export function normalizeKey(key: string): string {
+  return key.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+export class Redactor {
+  private readonly extraKeys: string[];
+  private readonly headerNames: Set<string>;
+
+  constructor(extraFields: string[] = [], extraHeaders: string[] = []) {
+    this.extraKeys = extraFields.map(normalizeKey).filter(Boolean);
+    this.headerNames = new Set(
+      [...DEFAULT_SENSITIVE_HEADERS, ...extraHeaders].map((name) => name.toLowerCase()),
+    );
+  }
+
+  isSensitiveKey(key: string): boolean {
+    const normalized = normalizeKey(key);
+    if (!normalized) return false;
+    if (SENSITIVE_KEYS_EXACT.has(normalized)) return true;
+    if (SENSITIVE_KEY_PARTS.some((part) => normalized.includes(part))) return true;
+    return this.extraKeys.some((part) => normalized.includes(part));
+  }
+
+  /** Masks credentials embedded in free text: bearer tokens, JWTs, key formats, URL userinfo and query params. */
+  string(value: string, maxLength = 2048): string {
+    let out = value.length > maxLength * 4 ? value.slice(0, maxLength * 4) : value;
+    for (const [pattern, replacement] of VALUE_PATTERNS) {
+      out = out.replace(pattern, replacement);
+    }
+    if (out.includes("=") || out.includes(":")) {
+      out = out.replace(KEY_VALUE_PAIR, (match, sep: string, key: string, delimiter: string) => {
+        let decoded = key;
+        try {
+          decoded = decodeURIComponent(key);
+        } catch {
+          // keep the raw key
+        }
+        return this.isSensitiveKey(decoded) ? `${sep}${key}${delimiter}${REDACTED}` : match;
+      });
+    }
+    if (out.includes('"')) {
+      out = out.replace(JSON_PAIR, (match, key: string) =>
+        this.isSensitiveKey(key) ? `"${key}":"${REDACTED}"` : match,
+      );
+    }
+    // The ellipsis counts toward the limit: servers validate these lengths exactly.
+    return out.length > maxLength ? `${out.slice(0, Math.max(0, maxLength - 1))}…` : out;
+  }
+
+  /** Deep copy with sensitive keys and values masked. Bounded in depth, breadth and string length. */
+  value(input: unknown, depth = 0, seen: WeakSet<object> = new WeakSet()): unknown {
+    if (input === null || input === undefined) return input;
+    if (typeof input === "string") return this.string(input);
+    if (typeof input === "number" || typeof input === "boolean") return input;
+    if (typeof input === "bigint") return input.toString();
+    if (typeof input === "function" || typeof input === "symbol") return undefined;
+    if (input instanceof Date) return Number.isNaN(input.getTime()) ? null : input.toISOString();
+    if (Buffer.isBuffer(input) || ArrayBuffer.isView(input)) {
+      return `[Binary ${(input as ArrayBufferView).byteLength} bytes]`;
+    }
+    if (typeof input !== "object") return undefined;
+
+    if (seen.has(input)) return "[Circular]";
+    if (depth >= 8) return "[Truncated]";
+    seen.add(input);
+
+    if (Array.isArray(input)) {
+      const items = input.slice(0, 100).map((item) => this.value(item, depth + 1, seen));
+      if (input.length > 100) items.push(`[${input.length - 100} more]`);
+      return items;
+    }
+
+    const out: Record<string, unknown> = {};
+    let count = 0;
+    for (const [key, nested] of Object.entries(input as Record<string, unknown>)) {
+      if (count++ >= 200) {
+        out["[truncated]"] = "too many keys";
+        break;
+      }
+      out[key] = this.isSensitiveKey(key) ? REDACTED : this.value(nested, depth + 1, seen);
+    }
+    return out;
+  }
+
+  headers(headers: Record<string, unknown> | undefined): Record<string, string> | undefined {
+    if (!headers) return undefined;
+    const out: Record<string, string> = {};
+    for (const [rawName, rawValue] of Object.entries(headers)) {
+      if (rawValue === undefined) continue;
+      const name = rawName.toLowerCase();
+      if (this.headerNames.has(name) || this.isSensitiveKey(name)) {
+        out[name] = REDACTED;
+        continue;
+      }
+      const joined = Array.isArray(rawValue) ? rawValue.join(", ") : String(rawValue);
+      out[name] = this.string(joined, 1024);
+    }
+    return out;
+  }
+
+  query(search: string): Record<string, string | string[]> | undefined {
+    if (!search) return undefined;
+    const out: Record<string, string | string[]> = {};
+    const params = new URLSearchParams(search.startsWith("?") ? search.slice(1) : search);
+    for (const key of new Set(params.keys())) {
+      const values = params.getAll(key).map((value) =>
+        this.isSensitiveKey(key) ? REDACTED : this.string(value, 512),
+      );
+      out[key] = values.length === 1 ? values[0] : values;
+    }
+    return out;
+  }
+
+  /**
+   * Redacts a captured body. Structured content is parsed and redacted by key;
+   * text that cannot be parsed (usually because it was truncated) gets key/value
+   * pattern masking instead, so a cut-off JSON body still loses its passwords.
+   */
+  body(raw: unknown, contentType: string | undefined, maxBytes: number): { body?: unknown; truncated?: boolean; omitted?: string } {
+    if (raw === undefined || raw === null || maxBytes <= 0) return {};
+
+    const type = (contentType || "").toLowerCase();
+
+    if (typeof raw === "object" && !Buffer.isBuffer(raw)) {
+      return this.fit(this.value(raw), maxBytes);
+    }
+
+    const text = Buffer.isBuffer(raw) ? raw.toString("utf8") : String(raw);
+
+    if (type.includes("json")) {
+      try {
+        return this.fit(this.value(JSON.parse(text)), maxBytes);
+      } catch {
+        return this.cut(this.string(text, text.length), maxBytes);
+      }
+    }
+    if (type.includes("application/x-www-form-urlencoded")) {
+      return this.fit(this.query(text) ?? {}, maxBytes);
+    }
+    if (!type || type.startsWith("text/") || type.includes("xml") || type.includes("graphql")) {
+      return this.cut(this.string(text, maxBytes * 2), maxBytes);
+    }
+    return { omitted: `content-type ${type.split(";")[0]}` };
+  }
+
+  private fit(value: unknown, maxBytes: number): { body?: unknown; truncated?: boolean } {
+    const serialized = JSON.stringify(value) ?? "";
+    if (Buffer.byteLength(serialized) <= maxBytes) {
+      return { body: value };
+    }
+    return this.cut(serialized, maxBytes);
+  }
+
+  private cut(text: string, maxBytes: number): { body?: unknown; truncated?: boolean } {
+    const bytes = Buffer.from(text);
+    if (bytes.length <= maxBytes) {
+      return { body: text };
+    }
+    // Slicing bytes can split a multi-byte character; the replacement char is harmless here.
+    return { body: bytes.subarray(0, maxBytes).toString("utf8"), truncated: true };
+  }
+}