midline-agent 0.1.9 → 0.2.0

package/dist/middleware.js

@@ -3,52 +3,103 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.midlineMiddleware = midlineMiddleware;
 const agent_1 = require("./agent");
 const breadcrumbs_1 = require("./breadcrumbs");
-function midlineMiddleware() {
-    return (req, res, next) => {
-        const start = Date.now();
-        let logged = false;
-        const logRequest = () => {
-            if (logged)
-                return;
-            logged = true;
-            const duration = Date.now() - start;
-            const statusCode = res.statusCode || 200;
+const config_1 = require("./config");
+const context_1 = require("./context");
+const tap_1 = require("./tap");
+/**
+ * Records every request that passes through. Mount it before your routes.
+ *
+ * It only listens: nothing here reads the request stream, delays `next()`, or
+ * changes the response. Recording happens on `finish`/`close`, after the response
+ * has been handed to the socket.
+ */
+function midlineMiddleware(options = {}) {
+    const captureOverride = options.capture ? (0, config_1.resolveCapture)(options.capture) : undefined;
+    return function midline(req, res, next) {
+        try {
+            observe(req, res, options, captureOverride);
+        }
+        catch {
+            // Monitoring must never be the reason a request fails.
+        }
+        next();
+    };
+}
+function observe(req, res, options, captureOverride) {
+    const agent = options.agent ?? agent_1.MidlineAgent.current;
+    if (!agent || !agent.active || options.ignore?.(req)) {
+        return;
+    }
+    const capture = captureOverride ?? agent.capture;
+    const context = (0, context_1.createRequestContext)(req.headers);
+    (0, context_1.setRequestContext)(req, context);
+    const started = process.hrtime.bigint();
+    // originalUrl survives router rewrites of req.url; read it now, not at finish.
+    const url = req.originalUrl ?? req.url ?? "/";
+    const responseTap = capture.responseBody ? tapResponse(res, capture.maxBodyBytes) : undefined;
+    let recorded = false;
+    const record = () => {
+        if (recorded)
+            return;
+        recorded = true;
+        try {
+            const aborted = !res.writableFinished;
+            const statusCode = aborted && !res.headersSent ? 499 : res.statusCode;
+            const routePath = req.route?.path;
+            const encoding = (0, tap_1.headerValue)(res.getHeader("content-encoding"));
             (0, breadcrumbs_1.addBreadcrumb)({
                 type: "http",
-                message: `${req.method} ${req.path} -> ${statusCode}`,
+                message: `${req.method} ${url.split("?")[0]} -> ${statusCode}`,
                 timestamp: new Date().toISOString(),
             });
-            agent_1.MidlineAgent.addEvent({
-                type: "request",
-                timestamp: new Date().toISOString(),
-                path: req.path,
+            agent.recordHttp({
+                integration: req.originalUrl !== undefined ? "express" : "node-http",
+                context,
                 method: req.method,
-                statusCode: statusCode,
-                duration,
-                ip: req.ip || req.socket.remoteAddress,
-                userAgent: req.headers["user-agent"]
+                url,
+                statusCode,
+                durationMs: Number(process.hrtime.bigint() - started) / 1e6,
+                ip: req.ip ?? req.socket?.remoteAddress,
+                userAgent: (0, tap_1.headerValue)(req.headers["user-agent"]),
+                routeTemplate: typeof routePath === "string" ? `${req.baseUrl ?? ""}${routePath}` : undefined,
+                aborted,
+                capture,
+                request: {
+                    headers: capture.headers ? req.headers : undefined,
+                    contentType: (0, tap_1.headerValue)(req.headers["content-type"]),
+                    // Whatever a body parser already produced. The raw stream is never read here.
+                    body: capture.requestBody ? req.body : undefined,
+                },
+                response: {
+                    headers: capture.headers ? res.getHeaders() : undefined,
+                    contentType: (0, tap_1.headerValue)(res.getHeader("content-type")),
+                    body: responseTap && !(0, tap_1.isCompressed)(encoding) ? responseTap.body : undefined,
+                    bodyBytes: responseTap?.bytes,
+                    truncated: responseTap?.truncated,
+                },
             });
-        };
-        // Override multiple response methods to ensure we catch all responses
-        const originalSend = res.send.bind(res);
-        const originalJson = res.json.bind(res);
-        const originalEnd = res.end.bind(res);
-        res.send = function (body) {
-            logRequest();
-            return originalSend(body);
-        };
-        res.json = function (body) {
-            logRequest();
-            return originalJson(body);
-        };
-        res.end = function (chunk, encoding) {
-            logRequest();
-            return originalEnd(chunk, encoding);
-        };
-        // Also listen for the 'finish' event as a fallback
-        res.once('finish', () => {
-            logRequest();
-        });
-        next();
+        }
+        catch {
+            // See above.
+        }
+    };
+    res.once("finish", record);
+    res.once("close", record);
+}
+/** Wraps write/end with every argument passed through untouched, callbacks included. */
+function tapResponse(res, limit) {
+    const tap = new tap_1.BodyTap(limit);
+    const write = res.write;
+    const end = res.end;
+    res.write = function (...args) {
+        tap.push(args[0], typeof args[1] === "string" ? args[1] : undefined);
+        return write.apply(this, args);
+    };
+    res.end = function (...args) {
+        if (typeof args[0] !== "function") {
+            tap.push(args[0], typeof args[1] === "string" ? args[1] : undefined);
+        }
+        return end.apply(this, args);
     };
+    return tap;
 }

package/dist/proxy.d.ts

@@ -0,0 +1,70 @@
+import * as http from "http";
+import { MidlineAgent } from "./agent";
+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;
+}
+export declare function resolveTarget(target: string | undefined): 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 declare function createMidlineProxy(options?: MidlineProxyOptions): MidlineProxy;
+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 declare function startMidlineProxy(options?: StartProxyOptions): Promise<http.Server & {
+    proxy: MidlineProxy;
+}>;
+export declare function proxyAddress(server: http.Server): string;

package/dist/proxy.js

@@ -0,0 +1,383 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTarget = resolveTarget;
+exports.createMidlineProxy = createMidlineProxy;
+exports.startMidlineProxy = startMidlineProxy;
+exports.proxyAddress = proxyAddress;
+const http = __importStar(require("http"));
+const https = __importStar(require("https"));
+const agent_1 = require("./agent");
+const config_1 = require("./config");
+const context_1 = require("./context");
+const tap_1 = require("./tap");
+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, code) {
+        super(message);
+        this.code = code;
+    }
+}
+function resolveTarget(target) {
+    if (!target) {
+        throw new config_1.ConfigError("no destination: pass `target` or set TARGET_API_URL (e.g. http://localhost:4000)");
+    }
+    let url;
+    try {
+        url = new URL(target);
+    }
+    catch {
+        throw new config_1.ConfigError(`target "${target}" is not a valid URL`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new config_1.ConfigError(`target must be http:// or https:// (got ${url.protocol}//)`);
+    }
+    if (url.username || url.password) {
+        throw new config_1.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.
+ */
+function createMidlineProxy(options = {}) {
+    const target = resolveTarget(options.target ?? (0, config_1.env)("TARGET_API_URL"));
+    const extraCa = (0, config_1.loadCa)(options.targetCa ?? (0, config_1.env)("TARGET_API_CA"), "targetCa / TARGET_API_CA");
+    if (extraCa && target.protocol !== "https:") {
+        throw new config_1.ConfigError("targetCa / TARGET_API_CA is set but the target is not https://");
+    }
+    const timeoutMs = options.timeoutMs ?? (0, config_1.envInt)("TARGET_API_TIMEOUT_MS") ?? 30000;
+    const connectTimeoutMs = options.connectTimeoutMs ?? 5000;
+    const retries = Math.max(0, Math.min(options.retries ?? (0, config_1.envInt)("TARGET_API_RETRIES") ?? 0, 5));
+    const maxRequestBodyBytes = options.maxRequestBodyBytes ?? 10 * 1024 * 1024;
+    const captureOverride = options.capture ? (0, config_1.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: (0, config_1.trustStore)(extraCa) })
+        : new http.Agent({ keepAlive: true });
+    let lastNotice = "";
+    const warn = (signature, message) => {
+        if (signature === lastNotice)
+            return;
+        lastNotice = signature;
+        try {
+            (options.onError ?? console.warn)(message);
+        }
+        catch {
+            // ignore
+        }
+    };
+    const handler = function midlineProxy(req, res) {
+        const started = process.hrtime.bigint();
+        const context = (0, context_1.createRequestContext)(req.headers);
+        const agent = options.agent ?? agent_1.MidlineAgent.current;
+        const capture = captureOverride ?? agent?.capture ?? (0, config_1.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 tap_1.BodyTap(capture.maxBodyBytes) : undefined;
+        const responseTap = capture.responseBody ? new tap_1.BodyTap(capture.maxBodyBytes) : undefined;
+        let upstreamResponse;
+        let failure;
+        let recorded = false;
+        const record = () => {
+            if (recorded)
+                return;
+            recorded = true;
+            if (!agent?.active)
+                return;
+            const responseEncoding = (0, tap_1.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: (0, tap_1.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: (0, tap_1.headerValue)(req.headers["content-type"]),
+                    body: requestTap && requestTap.bytes > 0 && !(0, tap_1.isCompressed)((0, tap_1.headerValue)(req.headers["content-encoding"])) ? requestTap.body : undefined,
+                    bodyBytes: requestTap?.bytes,
+                    truncated: requestTap?.truncated,
+                },
+                response: {
+                    headers: capture.headers && upstreamResponse ? upstreamResponse.headers : undefined,
+                    contentType: (0, tap_1.headerValue)(upstreamResponse?.headers["content-type"]),
+                    body: responseTap && responseTap.bytes > 0 && !(0, tap_1.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) => {
+            let connectTimer;
+            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.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) => {
+                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) => {
+                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);
+    };
+    Object.defineProperty(handler, "target", { value: target, enumerable: true });
+    handler.close = () => upstreamAgent.destroy();
+    return handler;
+}
+async function startMidlineProxy(options = {}) {
+    const agent = options.agent ?? agent_1.MidlineAgent.current ?? agent_1.MidlineAgent.init(options.midline ?? {});
+    const proxy = createMidlineProxy({ ...options, agent });
+    const server = http.createServer(proxy);
+    server.proxy = proxy;
+    server.on("close", () => proxy.close());
+    const port = options.port ?? (0, config_1.envInt)("MIDLINE_PROXY_PORT") ?? 8080;
+    const host = options.host ?? (0, config_1.env)("MIDLINE_PROXY_HOST") ?? "127.0.0.1";
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    return server;
+}
+function proxyAddress(server) {
+    const address = server.address();
+    const host = address.family === "IPv6" ? `[${address.address}]` : address.address;
+    return `http://${host}:${address.port}`;
+}
+function forwardHeaders(req, target, context, options) {
+    const out = stripHopByHop(req.headers);
+    const trustForwarded = options.trustForwardedHeaders === true;
+    const clientIp = req.socket.remoteAddress ?? "";
+    const incomingFor = (0, tap_1.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.encrypted ? "https" : "http";
+    out["x-forwarded-for"] = trustForwarded && incomingFor ? `${incomingFor}, ${clientIp}` : clientIp;
+    out["x-forwarded-proto"] = (trustForwarded && (0, tap_1.headerValue)(req.headers["x-forwarded-proto"])) || proto;
+    out["x-forwarded-host"] = (trustForwarded && (0, tap_1.headerValue)(req.headers["x-forwarded-host"])) || (0, tap_1.headerValue)(req.headers.host) || "";
+    out["x-request-id"] = context.requestId;
+    out["x-correlation-id"] = context.correlationId;
+    return out;
+}
+function stripHopByHop(headers) {
+    const named = new Set(String(headers.connection ?? "")
+        .split(",")
+        .map((token) => token.trim().toLowerCase())
+        .filter(Boolean));
+    const out = {};
+    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, trustForwarded) {
+    if (trustForwarded) {
+        const forwarded = (0, tap_1.headerValue)(req.headers["x-forwarded-for"])?.split(",")[0]?.trim();
+        if (forwarded)
+            return forwarded;
+    }
+    return req.socket.remoteAddress;
+}
+function respondError(res, status, error, message, context) {
+    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, err, target) {
+    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/dist/redact.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 declare const REDACTED = "[REDACTED]";
+/** Always redacted by name, even if a user-supplied list somehow unmatched them. */
+export declare const DEFAULT_SENSITIVE_HEADERS: string[];
+export declare function normalizeKey(key: string): string;
+export declare class Redactor {
+    private readonly extraKeys;
+    private readonly headerNames;
+    constructor(extraFields?: string[], extraHeaders?: string[]);
+    isSensitiveKey(key: string): boolean;
+    /** Masks credentials embedded in free text: bearer tokens, JWTs, key formats, URL userinfo and query params. */
+    string(value: string, maxLength?: number): string;
+    /** Deep copy with sensitive keys and values masked. Bounded in depth, breadth and string length. */
+    value(input: unknown, depth?: number, seen?: WeakSet<object>): unknown;
+    headers(headers: Record<string, unknown> | undefined): Record<string, string> | undefined;
+    query(search: string): Record<string, string | string[]> | undefined;
+    /**
+     * 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;
+    };
+    private fit;
+    private cut;
+}