@bounded-sh/observe 0.1.0

package/dist/intercept/fetch.d.ts

@@ -0,0 +1,2 @@
+export declare function patchFetch(): void;
+export declare function unpatchFetch(): void;

package/dist/intercept/fetch.js

@@ -0,0 +1,534 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// intercept/fetch.ts -- globalThis.fetch (undici) interception (SPEC §3.1a).
+//
+// INVARIANTS (T-shim, binding):
+//   * The app's call ALWAYS goes through: any shim failure falls back to the
+//     original fetch with the original arguments; observation errors are
+//     swallowed and counted, never thrown.
+//   * Zero synchronous work beyond cheap metadata on the hot path; body
+//     parsing/classification happens on the pipeline tick.
+//   * X-Bounded-* headers NEVER egress: they are stripped here (and used as
+//     an attribution fallback when no AsyncLocalStorage context is present).
+//   * Self-traffic (the ingest host) is never captured (no feedback loop).
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.patchFetch = patchFetch;
+exports.unpatchFetch = unpatchFetch;
+const node_crypto_1 = require("node:crypto");
+const context_1 = require("../context");
+const escort_1 = require("../escort");
+const llm_prices_1 = require("../llm-prices");
+const state_1 = require("../state");
+const template_1 = require("../template");
+const BOUNDED_HEADER_RE = /^x-bounded-/i;
+const BODY_CAP = 32 * 1024;
+const RESP_JSON_CAP = 512 * 1024;
+/** Per (host|method) request-body samples retained for shape field names. */
+const SHAPE_BODY_SAMPLES = 5;
+let realFetch;
+const shapeBodyBudget = new Map();
+function aliasHost(host) {
+    return state_1.state.config?.aliasHosts?.[host] ?? host;
+}
+function noteBoundedHeader(acc, name, value) {
+    const n = name.toLowerCase();
+    if (n === "x-bounded-actor")
+        acc.id = value;
+    else if (n === "x-bounded-actor-kind")
+        acc.kind = value;
+    else if (n === "x-bounded-on-behalf-of")
+        acc.onBehalfOf = value;
+}
+function headerActorToContext(acc) {
+    if (!acc.id)
+        return undefined;
+    const kind = acc.kind === "human" || acc.kind === "agent" || acc.kind === "service" ? acc.kind : "unknown";
+    const ctx = { id: acc.id.slice(0, 256), kind };
+    if (acc.onBehalfOf)
+        ctx.onBehalfOf = acc.onBehalfOf.slice(0, 256);
+    return ctx;
+}
+/** Strip X-Bounded-* from a Headers instance IN PLACE; collect their values. */
+function stripHeadersInstance(h, acc) {
+    const doomed = [];
+    h.forEach((value, name) => {
+        if (BOUNDED_HEADER_RE.test(name)) {
+            noteBoundedHeader(acc, name, value);
+            doomed.push(name);
+        }
+    });
+    for (const name of doomed)
+        h.delete(name);
+}
+/** Return a cleaned copy of a HeadersInit, or undefined if nothing to strip. */
+function cleanHeadersInit(headers, acc) {
+    if (!headers)
+        return undefined;
+    if (headers instanceof Headers) {
+        let found = false;
+        headers.forEach((_v, name) => {
+            if (BOUNDED_HEADER_RE.test(name))
+                found = true;
+        });
+        if (!found)
+            return undefined;
+        const copy = new Headers(headers);
+        stripHeadersInstance(copy, acc);
+        return copy;
+    }
+    if (Array.isArray(headers)) {
+        let found = false;
+        for (const pair of headers) {
+            if (Array.isArray(pair) && typeof pair[0] === "string" && BOUNDED_HEADER_RE.test(pair[0])) {
+                found = true;
+                noteBoundedHeader(acc, pair[0], String(pair[1]));
+            }
+        }
+        if (!found)
+            return undefined;
+        return headers.filter((p) => !(Array.isArray(p) && BOUNDED_HEADER_RE.test(String(p[0]))));
+    }
+    if (typeof headers === "object") {
+        const obj = headers;
+        let found = false;
+        for (const k of Object.keys(obj)) {
+            if (BOUNDED_HEADER_RE.test(k)) {
+                found = true;
+                noteBoundedHeader(acc, k, String(obj[k]));
+            }
+        }
+        if (!found)
+            return undefined;
+        const copy = {};
+        for (const k of Object.keys(obj)) {
+            if (!BOUNDED_HEADER_RE.test(k))
+                copy[k] = obj[k];
+        }
+        return copy;
+    }
+    return undefined;
+}
+function headerFromInit(headers, name) {
+    try {
+        if (!headers)
+            return undefined;
+        if (headers instanceof Headers)
+            return headers.get(name) ?? undefined;
+        if (Array.isArray(headers)) {
+            for (const p of headers) {
+                if (Array.isArray(p) && String(p[0]).toLowerCase() === name)
+                    return String(p[1]);
+            }
+            return undefined;
+        }
+        if (typeof headers === "object") {
+            for (const k of Object.keys(headers)) {
+                if (k.toLowerCase() === name)
+                    return String(headers[k]);
+            }
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return undefined;
+}
+function bodyToText(body) {
+    if (typeof body === "string") {
+        return { text: body.slice(0, BODY_CAP), bytes: Buffer.byteLength(body) };
+    }
+    if (body instanceof URLSearchParams) {
+        const s = body.toString();
+        return { text: s.slice(0, BODY_CAP), bytes: Buffer.byteLength(s) };
+    }
+    if (body instanceof Uint8Array) {
+        return {
+            text: Buffer.from(body.buffer, body.byteOffset, Math.min(body.byteLength, BODY_CAP)).toString("utf8"),
+            bytes: body.byteLength,
+        };
+    }
+    if (body instanceof ArrayBuffer) {
+        return {
+            text: Buffer.from(body, 0, Math.min(body.byteLength, BODY_CAP)).toString("utf8"),
+            bytes: body.byteLength,
+        };
+    }
+    return { bytes: 0 }; // streams / FormData / Blob: metadata only
+}
+function shapeBodyAllowance(host, method) {
+    const key = `${host}|${method}`;
+    const used = shapeBodyBudget.get(key) ?? 0;
+    if (used >= SHAPE_BODY_SAMPLES)
+        return false;
+    if (shapeBodyBudget.size > 2_048 && !shapeBodyBudget.has(key))
+        return false;
+    shapeBodyBudget.set(key, used + 1);
+    return true;
+}
+function preprocess(input, init) {
+    // Resolve URL (absolute in Node fetch).
+    let url;
+    if (typeof input === "string")
+        url = new URL(input);
+    else if (input instanceof URL)
+        url = input;
+    else if (input && typeof input.url === "string")
+        url = new URL(input.url);
+    else
+        return undefined;
+    const rawHost = url.host;
+    const host = aliasHost(rawHost);
+    if (rawHost === state_1.state.ingestHost || host === state_1.state.ingestHost)
+        return undefined; // self
+    const isRequest = typeof input === "object" && input !== null && typeof input.url === "string";
+    const method = (init?.method ?? (isRequest ? input.method : undefined) ?? "GET").toUpperCase();
+    const acc = {};
+    let cleanedInit;
+    // Strip X-Bounded-* wherever they might live.
+    if (isRequest) {
+        try {
+            stripHeadersInstance(input.headers, acc);
+        }
+        catch {
+            /* immutable headers: values still never egress via init below */
+        }
+    }
+    if (init?.headers) {
+        const cleaned = cleanHeadersInit(init.headers, acc);
+        if (cleaned !== undefined)
+            cleanedInit = { ...init, headers: cleaned };
+    }
+    // Request metadata.
+    const effHeaders = init?.headers ?? (isRequest ? input.headers : undefined);
+    const contentType = headerFromInit(effHeaders, "content-type");
+    const contentLength = Number(headerFromInit(effHeaders, "content-length"));
+    const meta = {
+        host,
+        path: url.pathname,
+        method,
+        actor: (0, context_1.currentActor)() ?? headerActorToContext(acc),
+        bytesIn: Number.isFinite(contentLength) && contentLength > 0 ? contentLength : 0,
+        reqContentType: contentType,
+        wantsRespBody: false,
+        cleanedInit,
+        ts: Date.now(),
+    };
+    if (url.search && url.search.length > 1) {
+        meta.queryNames = [...url.searchParams.keys()].slice(0, 64);
+    }
+    // Body capture: manifest (recognizer) hosts always; otherwise a small
+    // per-route allowance so shape samples get field names.
+    const recognizedHost = state_1.state.manifest.captureHosts.has(host);
+    if (method !== "GET" && method !== "HEAD") {
+        const wantBody = recognizedHost || shapeBodyAllowance(host, method);
+        const body = init?.body;
+        if (wantBody && body !== undefined && body !== null) {
+            const { text, bytes } = bodyToText(body);
+            if (text !== undefined)
+                meta.reqBodyText = text;
+            if (meta.bytesIn === 0 && bytes > 0)
+                meta.bytesIn = bytes;
+        }
+        else if (wantBody && recognizedHost && isRequest && input.body) {
+            // Request-with-stream body: clone-read (async, off the hot path).
+            try {
+                const req = input.clone();
+                meta.reqBodyPromise = req
+                    .text()
+                    .then((t) => t.slice(0, BODY_CAP))
+                    .catch(() => undefined);
+                if (!meta.reqContentType)
+                    meta.reqContentType = input.headers.get("content-type") ?? undefined;
+            }
+            catch {
+                /* metadata only */
+            }
+        }
+    }
+    // Does the manifest want response fields for this route?
+    if (recognizedHost) {
+        meta.wantsRespBody = state_1.state.manifest.wantsResponseBody(host, method, (0, template_1.templatePath)(url.pathname));
+    }
+    return meta;
+}
+function finalize(meta, startMs, res) {
+    const durMs = performance.now() - startMs;
+    const status = res?.status ?? 0;
+    let bytesOut = 0;
+    try {
+        const cl = Number(res?.headers.get("content-length"));
+        if (Number.isFinite(cl) && cl > 0)
+            bytesOut = cl;
+    }
+    catch {
+        /* ignore */
+    }
+    const raw = {
+        ts: meta.ts,
+        host: meta.host,
+        path: meta.path,
+        queryNames: meta.queryNames,
+        method: meta.method,
+        status,
+        durMs,
+        bytesIn: meta.bytesIn,
+        bytesOut,
+        actor: meta.actor,
+        reqBodyText: meta.reqBodyText,
+        reqContentType: meta.reqContentType,
+    };
+    // Response JSON capture (recognized routes with responseFields only).
+    let respPromise;
+    if (res && meta.wantsRespBody) {
+        try {
+            const ct = res.headers.get("content-type") ?? "";
+            const cl = Number(res.headers.get("content-length"));
+            const sizeOk = !Number.isFinite(cl) || cl <= RESP_JSON_CAP;
+            if (ct.toLowerCase().includes("json") && sizeOk) {
+                const clone = res.clone();
+                respPromise = Promise.race([
+                    clone.json().then((j) => {
+                        raw.respJson = j;
+                    }),
+                    new Promise((resolve) => {
+                        const t = setTimeout(resolve, 10_000);
+                        t.unref?.();
+                    }),
+                ]).catch(() => undefined);
+            }
+        }
+        catch {
+            /* metadata only */
+        }
+    }
+    const enqueue = () => state_1.state.pipeline?.enqueueRaw(raw);
+    if (meta.reqBodyPromise || respPromise) {
+        const waits = [];
+        if (meta.reqBodyPromise) {
+            waits.push(meta.reqBodyPromise.then((t) => {
+                if (t !== undefined && raw.reqBodyText === undefined)
+                    raw.reqBodyText = t;
+            }));
+        }
+        if (respPromise)
+            waits.push(respPromise);
+        void Promise.allSettled(waits).then(enqueue);
+    }
+    else {
+        enqueue();
+    }
+}
+// --- Escort (Mode A, T9) -----------------------------------------------------
+/** Escort config for this call, or undefined. Zero work unless escort mode is
+ * on (hasEscorts); reads (GET/HEAD) are never escorted (U16). */
+function escortFor(meta) {
+    if (!state_1.state.manifest.hasEscorts)
+        return undefined;
+    if (meta.method === "GET" || meta.method === "HEAD")
+        return undefined;
+    return state_1.state.manifest.escort(meta.host, meta.method, (0, template_1.templatePath)(meta.path));
+}
+/** Merge headers (Request's own first, then init's) and add Idempotency-Key.
+ * Never mutates the app's original request/init — returns a fresh init. */
+function withIdempotencyKey(input, init, intentId) {
+    const h = new Headers();
+    if (input && typeof input === "object" && typeof input.url === "string") {
+        try {
+            input.headers.forEach((v, k) => h.set(k, v));
+        }
+        catch {
+            /* immutable headers: init headers below still carry through */
+        }
+    }
+    if (init?.headers) {
+        try {
+            new Headers(init.headers).forEach((v, k) => h.set(k, v));
+        }
+        catch {
+            /* ignore malformed headers */
+        }
+    }
+    h.set("Idempotency-Key", intentId);
+    return { ...(init ?? {}), headers: h };
+}
+/** Settle from the fired response (reads a CLONE off the hot path for the
+ * rail result id; never blocks the response returned to the app). */
+function reportSettleFromResponse(cfg, intentId, res, failOpen) {
+    const base = {
+        outcome: failOpen ? "fail_open" : "fired",
+        status: res.status,
+    };
+    if (failOpen)
+        base.failOpen = true;
+    try {
+        const ct = (res.headers.get("content-type") ?? "").toLowerCase();
+        if (ct.includes("json")) {
+            void res
+                .clone()
+                .json()
+                .then((j) => {
+                const id = j && typeof j.id === "string" ? j.id : undefined;
+                // llm-gateway rail (§4.3, Track H): price the ACTUAL usage-cost from the
+                // fired call's response so the enforcement worker can DECREASE the
+                // estCents reservation (release headroom). Metadata only — token counts
+                // + model echo, never message content. Any other rail: id-only settle.
+                let actualCents;
+                if (cfg.rail === "llm-gateway") {
+                    const usage = (0, llm_prices_1.usageFromResponse)(j);
+                    if (usage)
+                        actualCents = (0, llm_prices_1.actualCentsFromUsage)(usage).actualCents;
+                }
+                (0, escort_1.settleAsync)(cfg, intentId, { ...base, resultId: id, ...(actualCents !== undefined ? { actualCents } : {}) });
+            })
+                .catch(() => (0, escort_1.settleAsync)(cfg, intentId, base));
+            return;
+        }
+    }
+    catch {
+        /* fall through to id-less settle */
+    }
+    (0, escort_1.settleAsync)(cfg, intentId, base);
+}
+/** Fire the (verdict-approved) call from the app's own process with the
+ * Idempotency-Key, and emit the normal observe event for it. */
+async function fireEscorted(orig, input, effInit, meta, intentId) {
+    const idemInit = withIdempotencyKey(input, effInit, intentId);
+    const start = performance.now();
+    let res;
+    try {
+        res = await orig(input, idemInit);
+    }
+    catch (err) {
+        try {
+            finalize(meta, start, undefined); // observe the failed egress (status 0)
+        }
+        catch (e) {
+            (0, state_1.noteInternalError)("escort.finalize", e);
+        }
+        throw err;
+    }
+    try {
+        finalize(meta, start, res);
+    }
+    catch (e) {
+        (0, state_1.noteInternalError)("escort.finalize", e);
+    }
+    return res;
+}
+/** Orchestrate the escort round-trip for one matched call. Throws a rail-shaped
+ * local error on any non-fire verdict; fires from the app process otherwise. */
+async function runEscort(orig, input, effInit, meta, cfg) {
+    const intentId = (0, node_crypto_1.randomUUID)();
+    // Intent fields come from the request the app ALREADY built (no mutation).
+    let bodyText = meta.reqBodyText;
+    if (bodyText === undefined && meta.reqBodyPromise) {
+        bodyText = await meta.reqBodyPromise.catch(() => undefined);
+    }
+    const intent = (0, escort_1.buildIntentFields)(bodyText, meta.reqContentType, cfg);
+    let verdict;
+    try {
+        verdict = await (0, escort_1.requestVerdict)(cfg, intentId, intent, meta.actor);
+    }
+    catch {
+        // Verdict endpoint unreachable/timeout: apply failMode LOCALLY (U18).
+        if (cfg.failMode === "open") {
+            const res = await fireEscorted(orig, input, effInit, meta, intentId);
+            reportSettleFromResponse(cfg, intentId, res, true);
+            return res;
+        }
+        throw (0, escort_1.buildRailError)(cfg, { kind: "fail_closed", intentId });
+    }
+    if (verdict.verdict === "allowed") {
+        const res = await fireEscorted(orig, input, effInit, meta, intentId);
+        reportSettleFromResponse(cfg, intentId, res, false);
+        return res;
+    }
+    if (verdict.verdict === "pending_approval") {
+        throw (0, escort_1.buildRailError)(cfg, { kind: "pending_approval", intentId, approveUrl: verdict.approveUrl });
+    }
+    throw (0, escort_1.buildRailError)(cfg, {
+        kind: "declined",
+        intentId,
+        invariant: verdict.invariant,
+        reason: verdict.reason,
+    });
+}
+function patchFetch() {
+    if (typeof globalThis.fetch !== "function")
+        return;
+    if (globalThis.fetch.__bounded)
+        return;
+    const orig = globalThis.fetch.bind(globalThis);
+    realFetch = orig;
+    state_1.state.originalFetch = orig;
+    const patched = function fetch(input, init) {
+        if (!state_1.state.enabled)
+            return orig(input, init);
+        let meta;
+        let effInit = init;
+        try {
+            meta = preprocess(input, init);
+            if (meta?.cleanedInit)
+                effInit = meta.cleanedInit;
+        }
+        catch (err) {
+            (0, state_1.noteInternalError)("fetch.preprocess", err);
+            meta = undefined;
+            effInit = init;
+        }
+        // ESCORT (Mode A, T9): a matched escorted route makes ONE verdict round-trip,
+        // then fires from THIS process (or throws a rail-shaped local error). Non-
+        // escorted routes never reach here (escortFor is a boolean check when escort
+        // mode is off) — the observe hot path below is unchanged (U2).
+        if (meta) {
+            let cfg;
+            try {
+                cfg = escortFor(meta);
+            }
+            catch (err) {
+                (0, state_1.noteInternalError)("fetch.escortFor", err);
+                cfg = undefined;
+            }
+            if (cfg)
+                return runEscort(orig, input, effInit, meta, cfg);
+        }
+        const start = performance.now();
+        let p;
+        try {
+            p = orig(input, effInit);
+        }
+        catch (err) {
+            // Synchronous throw from fetch (bad args): record nothing, preserve it.
+            throw err;
+        }
+        if (!meta)
+            return p;
+        const m = meta;
+        return p.then((res) => {
+            try {
+                finalize(m, start, res);
+            }
+            catch (err) {
+                (0, state_1.noteInternalError)("fetch.finalize", err);
+            }
+            return res;
+        }, (err) => {
+            try {
+                finalize(m, start, undefined);
+            }
+            catch (e) {
+                (0, state_1.noteInternalError)("fetch.finalize", e);
+            }
+            throw err;
+        });
+    };
+    patched.__bounded = true;
+    globalThis.fetch = patched;
+}
+function unpatchFetch() {
+    if (realFetch && globalThis.fetch?.__bounded) {
+        globalThis.fetch = realFetch;
+    }
+    shapeBodyBudget.clear();
+}

package/dist/intercept/http.d.ts

@@ -0,0 +1,2 @@
+export declare function patchHttp(): void;
+export declare function unpatchHttp(): void;