midline-agent 0.3.0 → 0.4.1

package/dist/esm/redact.js

@@ -0,0 +1,224 @@
+/**
+ * Shared by the Node agent and the browser SDK, so nothing here may touch a
+ * Node-only global (Buffer, process) — TextEncoder and URLSearchParams exist in both.
+ *
+ * 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 = [
+    [/-----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) {
+    return key.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+export class Redactor {
+    constructor(extraFields = [], extraHeaders = []) {
+        this.extraKeys = extraFields.map(normalizeKey).filter(Boolean);
+        this.headerNames = new Set([...DEFAULT_SENSITIVE_HEADERS, ...extraHeaders].map((name) => name.toLowerCase()));
+    }
+    isSensitiveKey(key) {
+        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, maxLength = 2048) {
+        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, key, delimiter) => {
+                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) => 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, depth = 0, seen = new WeakSet()) {
+        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();
+        // Buffer is a Uint8Array, so this also covers it without naming a Node-only global.
+        if (ArrayBuffer.isView(input)) {
+            return `[Binary ${input.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 = {};
+        let count = 0;
+        for (const [key, nested] of Object.entries(input)) {
+            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) {
+        if (!headers)
+            return undefined;
+        const out = {};
+        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) {
+        if (!search)
+            return undefined;
+        const out = {};
+        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, contentType, maxBytes) {
+        if (raw === undefined || raw === null || maxBytes <= 0)
+            return {};
+        const type = (contentType || "").toLowerCase();
+        if (typeof raw === "object" && !ArrayBuffer.isView(raw)) {
+            return this.fit(this.value(raw), maxBytes);
+        }
+        const text = ArrayBuffer.isView(raw)
+            ? new TextDecoder().decode(raw)
+            : 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]}` };
+    }
+    fit(value, maxBytes) {
+        const serialized = JSON.stringify(value) ?? "";
+        if (new TextEncoder().encode(serialized).length <= maxBytes) {
+            return { body: value };
+        }
+        return this.cut(serialized, maxBytes);
+    }
+    cut(text, maxBytes) {
+        const bytes = new TextEncoder().encode(text);
+        if (bytes.length <= maxBytes) {
+            return { body: text };
+        }
+        // Slicing bytes can split a multi-byte character; the replacement char is harmless here.
+        return { body: new TextDecoder().decode(bytes.subarray(0, maxBytes)), truncated: true };
+    }
+}

package/dist/esm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/redact.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Shared by the Node agent and the browser SDK, so nothing here may touch a
+ * Node-only global (Buffer, process) — TextEncoder and URLSearchParams exist in both.
+ *
  * 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.
  *

package/dist/redact.js

@@ -1,5 +1,8 @@
 "use strict";
 /**
+ * Shared by the Node agent and the browser SDK, so nothing here may touch a
+ * Node-only global (Buffer, process) — TextEncoder and URLSearchParams exist in both.
+ *
  * 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.
  *
@@ -120,7 +123,8 @@ class Redactor {
             return undefined;
         if (input instanceof Date)
             return Number.isNaN(input.getTime()) ? null : input.toISOString();
-        if (Buffer.isBuffer(input) || ArrayBuffer.isView(input)) {
+        // Buffer is a Uint8Array, so this also covers it without naming a Node-only global.
+        if (ArrayBuffer.isView(input)) {
             return `[Binary ${input.byteLength} bytes]`;
         }
         if (typeof input !== "object")
@@ -184,10 +188,12 @@ class Redactor {
         if (raw === undefined || raw === null || maxBytes <= 0)
             return {};
         const type = (contentType || "").toLowerCase();
-        if (typeof raw === "object" && !Buffer.isBuffer(raw)) {
+        if (typeof raw === "object" && !ArrayBuffer.isView(raw)) {
             return this.fit(this.value(raw), maxBytes);
         }
-        const text = Buffer.isBuffer(raw) ? raw.toString("utf8") : String(raw);
+        const text = ArrayBuffer.isView(raw)
+            ? new TextDecoder().decode(raw)
+            : String(raw);
         if (type.includes("json")) {
             try {
                 return this.fit(this.value(JSON.parse(text)), maxBytes);
@@ -206,18 +212,18 @@ class Redactor {
     }
     fit(value, maxBytes) {
         const serialized = JSON.stringify(value) ?? "";
-        if (Buffer.byteLength(serialized) <= maxBytes) {
+        if (new TextEncoder().encode(serialized).length <= maxBytes) {
             return { body: value };
         }
         return this.cut(serialized, maxBytes);
     }
     cut(text, maxBytes) {
-        const bytes = Buffer.from(text);
+        const bytes = new TextEncoder().encode(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 };
+        return { body: new TextDecoder().decode(bytes.subarray(0, maxBytes)), truncated: true };
     }
 }
 exports.Redactor = Redactor;

package/dist/socket-transport.d.ts

@@ -0,0 +1,58 @@
+/** Mirrors midline-core-api/src/realtime/ingest-protocol.ts's IngestAck. Duplicated,
+ * not shared: the two are separate packages, kept in sync by wire convention. */
+export type IngestAckErrorCode = "unauthorized" | "forbidden" | "rate_limited" | "bad_request" | "too_large" | "internal_error";
+export interface IngestAckOk {
+    ok: true;
+    accepted: number;
+    rejected: number;
+}
+export interface IngestAckError {
+    ok: false;
+    code: IngestAckErrorCode;
+    message: string;
+    retryAfterMs?: number;
+}
+export type IngestAck = IngestAckOk | IngestAckError;
+export interface SocketTransportOptions {
+    apiKey: string;
+    /** Full trust store for the Midline endpoint, or undefined for Node's default. */
+    ca?: Array<string | Buffer>;
+    connectTimeoutMs: number;
+    /** Per-emit ack timeout. */
+    timeoutMs: number;
+    /** Reconnection backoff bounds, derived from the agent's own flush/backoff config (see agent.ts). */
+    reconnectionDelayMs: number;
+    reconnectionDelayMaxMs: number;
+    /** Nothing queued for this long -> disconnect; reconnects lazily on the next send(). */
+    idleDisconnectMs: number;
+    userAgent: string;
+}
+/** A transport failure with a stable `code`, matching what agent.ts's errorCode()/describe() expect. */
+export declare class TransportError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Owns one socket.io-client connection to the ingest gateway: connects lazily on
+ * first send, lets socket.io-client's own reconnection/backoff handle transport
+ * drops, and disconnects after a sustained idle period (autoUnref also unrefs the
+ * underlying socket, so — as with the old HTTP transport — telemetry alone never
+ * keeps the process alive; the idle disconnect is extra hygiene on top of that,
+ * not the only thing standing between this and a hung process).
+ */
+export declare class SocketTransport {
+    private readonly origin;
+    private readonly options;
+    private socket;
+    private connecting;
+    private idleTimer;
+    constructor(origin: URL, options: SocketTransportOptions);
+    /** Sends one batch, connecting first if needed. Resolves with the server's ack or throws. */
+    send(events: Array<Record<string, unknown>>): Promise<IngestAck>;
+    destroy(): void;
+    private ensureConnected;
+    private createSocket;
+    private emit;
+    private scheduleIdleDisconnect;
+    private clearIdleTimer;
+}

package/dist/socket-transport.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocketTransport = exports.TransportError = void 0;
+const socket_io_client_1 = require("socket.io-client");
+const INGEST_NAMESPACE = "/ingest";
+const INGEST_EVENT = "ingest";
+/** A transport failure with a stable `code`, matching what agent.ts's errorCode()/describe() expect. */
+class TransportError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "TransportError";
+    }
+}
+exports.TransportError = TransportError;
+/**
+ * Owns one socket.io-client connection to the ingest gateway: connects lazily on
+ * first send, lets socket.io-client's own reconnection/backoff handle transport
+ * drops, and disconnects after a sustained idle period (autoUnref also unrefs the
+ * underlying socket, so — as with the old HTTP transport — telemetry alone never
+ * keeps the process alive; the idle disconnect is extra hygiene on top of that,
+ * not the only thing standing between this and a hung process).
+ */
+class SocketTransport {
+    constructor(origin, options) {
+        this.origin = origin;
+        this.options = options;
+        this.socket = null;
+        this.connecting = null;
+        this.idleTimer = null;
+    }
+    /** Sends one batch, connecting first if needed. Resolves with the server's ack or throws. */
+    async send(events) {
+        this.clearIdleTimer();
+        try {
+            await this.ensureConnected();
+            return await this.emit(events);
+        }
+        finally {
+            this.scheduleIdleDisconnect();
+        }
+    }
+    destroy() {
+        this.clearIdleTimer();
+        this.socket?.removeAllListeners();
+        this.socket?.disconnect();
+        this.socket = null;
+    }
+    ensureConnected() {
+        if (this.socket?.connected)
+            return Promise.resolve();
+        if (this.connecting)
+            return this.connecting;
+        if (!this.socket) {
+            this.socket = this.createSocket();
+        }
+        else if (!this.socket.active) {
+            // Cleanly disconnected earlier (our own idle timeout, or the server closed
+            // it): socket.io-client won't retry on its own, so ask it to.
+            this.socket.connect();
+        }
+        // Otherwise the existing socket is already reconnecting on its own; just wait below.
+        const socket = this.socket;
+        this.connecting = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                cleanup();
+                reject(new TransportError(`connection not established within ${this.options.connectTimeoutMs}ms`, "ECONNECT_TIMEOUT"));
+            }, this.options.connectTimeoutMs);
+            const onConnect = () => {
+                cleanup();
+                resolve();
+            };
+            const onError = (err) => {
+                cleanup();
+                reject(classifyConnectError(err));
+            };
+            const cleanup = () => {
+                clearTimeout(timer);
+                socket.off("connect", onConnect);
+                socket.off("connect_error", onError);
+            };
+            socket.once("connect", onConnect);
+            socket.once("connect_error", onError);
+        }).finally(() => {
+            this.connecting = null;
+        });
+        return this.connecting;
+    }
+    createSocket() {
+        const socket = (0, socket_io_client_1.io)(`${this.origin.origin}${INGEST_NAMESPACE}`, {
+            auth: { apiKey: this.options.apiKey },
+            transports: ["websocket"],
+            reconnection: true,
+            reconnectionAttempts: Infinity,
+            reconnectionDelay: this.options.reconnectionDelayMs,
+            reconnectionDelayMax: this.options.reconnectionDelayMaxMs,
+            randomizationFactor: 0.5,
+            timeout: this.options.connectTimeoutMs,
+            // Never the reason the process stays alive — same property the old HTTP
+            // transport's unref'd keep-alive sockets had.
+            autoUnref: true,
+            forceNew: true,
+            ca: this.options.ca,
+            extraHeaders: { "user-agent": this.options.userAgent },
+        });
+        return socket;
+    }
+    emit(events) {
+        const socket = this.socket;
+        if (!socket) {
+            return Promise.reject(new TransportError("not connected", "ENOTCONNECTED"));
+        }
+        return new Promise((resolve, reject) => {
+            socket.timeout(this.options.timeoutMs).emit(INGEST_EVENT, { events }, (err, ack) => {
+                if (err) {
+                    reject(new TransportError(`no response within ${this.options.timeoutMs}ms`, "ETIMEDOUT"));
+                }
+                else {
+                    resolve(ack);
+                }
+            });
+        });
+    }
+    scheduleIdleDisconnect() {
+        this.idleTimer = setTimeout(() => {
+            this.idleTimer = null;
+            this.socket?.disconnect();
+        }, this.options.idleDisconnectMs);
+        this.idleTimer.unref?.();
+    }
+    clearIdleTimer() {
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+    }
+}
+exports.SocketTransport = SocketTransport;
+/**
+ * `connect_error` from a plain `io()` connect-timeout has message "timeout" and
+ * no further detail. Anything else wraps the real Node error (ECONNREFUSED,
+ * ENOTFOUND, a TLS failure, ...) inside engine.io-client's TransportError, whose
+ * `.description` — for the websocket transport — is a `ws` ErrorEvent exposing
+ * the underlying error via its public `.error` getter (mirrors the DOM
+ * ErrorEvent.error field; see ws/lib/event-target.js). Verified empirically
+ * against the installed socket.io-client/ws versions, not assumed.
+ */
+function classifyConnectError(err) {
+    const anyErr = err;
+    if (anyErr?.message === "timeout") {
+        return new TransportError("connection timed out", "ECONNECT_TIMEOUT");
+    }
+    const inner = anyErr?.description?.error;
+    const code = inner?.code ?? "";
+    const message = inner?.message ?? anyErr?.message ?? "connection failed";
+    return new TransportError(message, code);
+}

package/package.json

@@ -1,9 +1,29 @@
 {
   "name": "midline-agent",
-  "version": "0.3.0",
-  "description": "Midline — request & error monitoring with security detection",
+  "version": "0.4.1",
+  "description": "Midline — request, error and security monitoring for Node, and error, network and Web Vitals monitoring for browsers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "import": "./dist/esm/browser/index.js",
+      "default": "./dist/browser/index.js"
+    },
+    "./package.json": "./package.json",
+    "./dist/*": "./dist/*"
+  },
+  "typesVersions": {
+    "*": {
+      "browser": [
+        "dist/browser/index.d.ts"
+      ]
+    }
+  },
   "bin": {
     "midline-agent": "dist/cli.js"
   },
@@ -11,7 +31,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsc -p tsconfig.esm.json && node scripts/mark-esm.js",
     "prepare": "npm run build",
     "clean": "rm -rf dist",
     "test": "npm run build && node --test test/*.test.js"
@@ -24,7 +44,10 @@
     "security",
     "request",
     "errors",
-    "proxy"
+    "proxy",
+    "browser",
+    "web-vitals",
+    "frontend"
   ],
   "author": "Your Name",
   "license": "MIT",
@@ -32,9 +55,13 @@
     "@types/express": "^4.17.19",
     "@types/node": "^24.10.1",
     "express": "^4.18.2",
+    "socket.io": "^4.8.3",
     "typescript": "^5.1.3"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "socket.io-client": "^4.8.3"
   }
 }

package/scripts/mark-esm.js

@@ -0,0 +1,6 @@
+// dist/esm holds the browser build as ES modules. Marking the folder as a module
+// scope lets bundlers and Node treat those .js files as ESM without renaming them.
+const fs = require("fs");
+const path = require("path");
+
+fs.writeFileSync(path.join(__dirname, "..", "dist", "esm", "package.json"), '{ "type": "module" }\n');