x402trace 0.1.0

package/dist/decoder/redact.js

@@ -0,0 +1,22 @@
+const REDACTED = "[REDACTED]";
+/**
+ * Redact the EIP-3009 signature from a payment payload.
+ *
+ * Per the X402-11 ticket: "Redact private keys / signatures by default;
+ * expose with --log-secrets flag." The signature itself is not strictly
+ * a secret (it's broadcast on-chain in the eventual settlement tx), but
+ * v0.1 redacts it by default to avoid surprising users who pipe their
+ * JSONL into pastebins / share with teammates. Operators who want the
+ * full signature flip the flag explicitly.
+ */
+export function redactPaymentPayload(payment, logSecrets) {
+    if (logSecrets)
+        return payment;
+    return {
+        ...payment,
+        payload: {
+            ...payment.payload,
+            signature: REDACTED,
+        },
+    };
+}

package/dist/decoder/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * X402-11 decoder types.
+ *
+ * These shapes are the boundary between raw HTTP capture (proxy) and
+ * structured downstream consumers (reconciliation, future inspect /
+ * doctor tools). The JSON schema mirrors `src/decoder/schema.md` —
+ * keep them in sync.
+ */
+/** Protocol surface. v0.1 is locked to v1 per ADR-001; v2 is detected
+ *  but not deeply parsed. */
+export type X402Version = 1 | 2;
+export interface PaymentRequirements {
+    readonly scheme: string;
+    readonly network: string;
+    readonly maxAmountRequired: string;
+    readonly resource: string;
+    readonly description?: string;
+    readonly mimeType?: string;
+    readonly payTo: string;
+    readonly maxTimeoutSeconds?: number;
+    readonly asset: string;
+    readonly outputSchema?: unknown;
+    readonly extra?: {
+        readonly name?: string;
+        readonly version?: string;
+    };
+}
+export interface PaymentAuthorization {
+    readonly from: string;
+    readonly to: string;
+    readonly value: string;
+    readonly validAfter: string;
+    readonly validBefore: string;
+    readonly nonce: string;
+}
+export interface PaymentPayload {
+    readonly x402Version: X402Version;
+    readonly scheme: string;
+    readonly network: string;
+    readonly payload: {
+        /** Either the literal signature or "[REDACTED]" depending on logSecrets flag. */
+        readonly signature: string;
+        readonly authorization: PaymentAuthorization;
+    };
+}
+export interface FacilitatorResponse {
+    readonly success?: boolean;
+    readonly isValid?: boolean;
+    readonly invalidReason?: string;
+    readonly errorReason?: string;
+    readonly transaction?: string;
+    readonly network?: string;
+    readonly payer?: string;
+}
+/**
+ * Discriminated union of events the decoder emits. Each corresponds to
+ * a row in ARCHITECTURE.md § JSONL record format. `t` is ISO 8601; `id`
+ * is the proxy's exchange id (so downstream tools can join).
+ */
+export type DecodedEvent = {
+    readonly event: "exchange.challenge";
+    readonly t: string;
+    readonly id: string;
+    readonly x402Version: X402Version;
+    readonly challenge: PaymentRequirements;
+    readonly raw402Error?: string;
+} | {
+    readonly event: "exchange.payment";
+    readonly t: string;
+    readonly id: string;
+    readonly x402Version: X402Version;
+    readonly payment: PaymentPayload;
+} | {
+    readonly event: "exchange.settlement";
+    readonly t: string;
+    readonly id: string;
+    readonly settlement: FacilitatorResponse;
+} | {
+    readonly event: "decoder.error";
+    readonly t: string;
+    readonly id?: string;
+    readonly stage: "challenge" | "payment" | "settlement";
+    readonly message: string;
+};
+/** Output format for the human/json logger. */
+export type LogFormat = "human" | "json";

package/dist/decoder/types.js

@@ -0,0 +1,9 @@
+/**
+ * X402-11 decoder types.
+ *
+ * These shapes are the boundary between raw HTTP capture (proxy) and
+ * structured downstream consumers (reconciliation, future inspect /
+ * doctor tools). The JSON schema mirrors `src/decoder/schema.md` —
+ * keep them in sync.
+ */
+export {};

package/dist/proxy/event-bus.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Minimal pub-sub for in-process consumers (decoder, reconciler) to
+ * subscribe to the live event stream. The JSONL sink is a separate
+ * concern that does not go through this bus.
+ *
+ * A subscriber receives events from the moment it subscribes onward —
+ * no replay. If a subscriber falls behind, events are queued in memory
+ * up to `maxQueue` (default 1024), then the oldest is dropped and an
+ * internal "dropped" counter is incremented (visible via `droppedFor`).
+ */
+export interface EventBus<T> {
+    emit(event: T): void;
+    subscribe(maxQueue?: number): AsyncIterable<T> & {
+        unsubscribe(): void;
+    };
+    droppedFor(iterable: AsyncIterable<T>): number;
+}
+export declare function createEventBus<T>(): EventBus<T>;

package/dist/proxy/event-bus.js

@@ -0,0 +1,75 @@
+/**
+ * Minimal pub-sub for in-process consumers (decoder, reconciler) to
+ * subscribe to the live event stream. The JSONL sink is a separate
+ * concern that does not go through this bus.
+ *
+ * A subscriber receives events from the moment it subscribes onward —
+ * no replay. If a subscriber falls behind, events are queued in memory
+ * up to `maxQueue` (default 1024), then the oldest is dropped and an
+ * internal "dropped" counter is incremented (visible via `droppedFor`).
+ */
+export function createEventBus() {
+    const subscribers = new Set();
+    const iterableToSub = new WeakMap();
+    return {
+        emit(event) {
+            for (const sub of subscribers) {
+                const resolver = sub.resolvers.shift();
+                if (resolver) {
+                    resolver({ value: event, done: false });
+                    continue;
+                }
+                if (sub.queue.length >= sub.maxQueue) {
+                    sub.queue.shift();
+                    sub.dropped += 1;
+                }
+                sub.queue.push(event);
+            }
+        },
+        subscribe(maxQueue = 1024) {
+            const sub = {
+                queue: [],
+                maxQueue,
+                resolvers: [],
+                done: false,
+                dropped: 0,
+            };
+            subscribers.add(sub);
+            const iterable = {
+                [Symbol.asyncIterator]: () => ({
+                    next() {
+                        if (sub.queue.length > 0) {
+                            return Promise.resolve({ value: sub.queue.shift(), done: false });
+                        }
+                        if (sub.done) {
+                            return Promise.resolve({ value: undefined, done: true });
+                        }
+                        return new Promise((resolve) => sub.resolvers.push(resolve));
+                    },
+                    return() {
+                        sub.done = true;
+                        subscribers.delete(sub);
+                        for (const resolver of sub.resolvers) {
+                            resolver({ value: undefined, done: true });
+                        }
+                        sub.resolvers.length = 0;
+                        return Promise.resolve({ value: undefined, done: true });
+                    },
+                }),
+                unsubscribe() {
+                    sub.done = true;
+                    subscribers.delete(sub);
+                    for (const resolver of sub.resolvers) {
+                        resolver({ value: undefined, done: true });
+                    }
+                    sub.resolvers.length = 0;
+                },
+            };
+            iterableToSub.set(iterable, sub);
+            return iterable;
+        },
+        droppedFor(iterable) {
+            return iterableToSub.get(iterable)?.dropped ?? 0;
+        },
+    };
+}

package/dist/proxy/id.d.ts

@@ -0,0 +1,6 @@
+import type { ExchangeId } from "./types.js";
+/**
+ * Generate a unique exchange id. ULIDs would be sort-friendlier; UUIDv4
+ * is plenty for v0.1 (the JSONL `t` timestamp gives ordering).
+ */
+export declare function newExchangeId(): ExchangeId;

package/dist/proxy/id.js

@@ -0,0 +1,8 @@
+import { randomUUID } from "node:crypto";
+/**
+ * Generate a unique exchange id. ULIDs would be sort-friendlier; UUIDv4
+ * is plenty for v0.1 (the JSONL `t` timestamp gives ordering).
+ */
+export function newExchangeId() {
+    return randomUUID();
+}

package/dist/proxy/index.d.ts

@@ -0,0 +1,5 @@
+export { createProxy, type ProxyHandle, type ProxyOptions } from "./proxy.js";
+export { isLikelyX402Exchange, type CapturedRequest, type CapturedResponse, type ExchangeId, type ExchangeOutcome, type ProxyEvent, } from "./types.js";
+export { createEventBus, type EventBus } from "./event-bus.js";
+export { JsonlSink } from "./jsonl-sink.js";
+export { newExchangeId } from "./id.js";

package/dist/proxy/index.js

@@ -0,0 +1,5 @@
+export { createProxy } from "./proxy.js";
+export { isLikelyX402Exchange, } from "./types.js";
+export { createEventBus } from "./event-bus.js";
+export { JsonlSink } from "./jsonl-sink.js";
+export { newExchangeId } from "./id.js";

package/dist/proxy/jsonl-sink.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Append-only JSONL writer. One event per line, terminated with `\n`.
+ *
+ * Per ARCHITECTURE.md § JSONL record format: "the file IS the API."
+ * No buffering beyond Node's default stream buffer; rely on the OS to
+ * flush. On `close()` we await the drain.
+ */
+export declare class JsonlSink {
+    private stream;
+    private path;
+    constructor(path: string);
+    open(): Promise<void>;
+    /** Append one JSON-serialised event followed by a newline. */
+    append(event: unknown): void;
+    close(): Promise<void>;
+    /** Absolute path of the log file. */
+    get filePath(): string;
+}

package/dist/proxy/jsonl-sink.js

@@ -0,0 +1,44 @@
+import { createWriteStream } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+/**
+ * Append-only JSONL writer. One event per line, terminated with `\n`.
+ *
+ * Per ARCHITECTURE.md § JSONL record format: "the file IS the API."
+ * No buffering beyond Node's default stream buffer; rely on the OS to
+ * flush. On `close()` we await the drain.
+ */
+export class JsonlSink {
+    stream = null;
+    path;
+    constructor(path) {
+        this.path = resolve(path);
+    }
+    async open() {
+        await mkdir(dirname(this.path), { recursive: true });
+        this.stream = createWriteStream(this.path, { flags: "a", encoding: "utf8" });
+        await new Promise((resolveOpen, reject) => {
+            this.stream.once("open", () => resolveOpen());
+            this.stream.once("error", reject);
+        });
+    }
+    /** Append one JSON-serialised event followed by a newline. */
+    append(event) {
+        if (!this.stream)
+            throw new Error("JsonlSink: open() must be called before append()");
+        this.stream.write(JSON.stringify(event) + "\n");
+    }
+    async close() {
+        if (!this.stream)
+            return;
+        const s = this.stream;
+        this.stream = null;
+        await new Promise((resolveClose, reject) => {
+            s.end((err) => (err ? reject(err) : resolveClose()));
+        });
+    }
+    /** Absolute path of the log file. */
+    get filePath() {
+        return this.path;
+    }
+}

package/dist/proxy/proxy.d.ts

@@ -0,0 +1,21 @@
+import { type Server } from "node:http";
+import { type EventBus } from "./event-bus.js";
+import type { ProxyEvent } from "./types.js";
+export interface ProxyOptions {
+    /** Base URL of the upstream service (e.g. `https://api.example.com`). */
+    readonly upstream: string;
+    /** Listen port. 0 = OS-assigned (used by tests). Default 8402. */
+    readonly port?: number;
+    /** Path to the JSONL log file. If undefined, no file is written. */
+    readonly logPath?: string;
+    /** Per-request upstream timeout. Default 30_000 ms. */
+    readonly upstreamTimeoutMs?: number;
+}
+export interface ProxyHandle {
+    readonly server: Server;
+    readonly url: string;
+    readonly events: EventBus<ProxyEvent>;
+    readonly logPath: string | null;
+    close(): Promise<void>;
+}
+export declare function createProxy(opts: ProxyOptions): Promise<ProxyHandle>;

package/dist/proxy/proxy.js

@@ -0,0 +1,238 @@
+import { createServer } from "node:http";
+import { newExchangeId } from "./id.js";
+import { createEventBus } from "./event-bus.js";
+import { JsonlSink } from "./jsonl-sink.js";
+const HOP_BY_HOP_HEADERS = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+    "host", // we rewrite Host to match the upstream
+]);
+function isLikelyTextContentType(contentType) {
+    if (!contentType)
+        return true; // empty body = treat as text
+    const lower = contentType.toLowerCase();
+    return (lower.startsWith("text/") ||
+        lower.includes("application/json") ||
+        lower.includes("application/x-www-form-urlencoded") ||
+        lower.includes("+json") ||
+        lower.includes("+xml") ||
+        lower.startsWith("application/xml"));
+}
+function isValidUtf8(buf) {
+    try {
+        const decoder = new TextDecoder("utf-8", { fatal: true });
+        decoder.decode(buf);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function bodyToCapture(body, contentType) {
+    if (body.length === 0)
+        return { body: "" };
+    if (isLikelyTextContentType(contentType) && isValidUtf8(body)) {
+        return { body: body.toString("utf8") };
+    }
+    return { bodyBase64: body.toString("base64") };
+}
+function collectHeaders(raw) {
+    const out = {};
+    for (const [name, value] of Object.entries(raw)) {
+        if (Array.isArray(value))
+            out[name] = value.join(", ");
+        else if (typeof value === "string")
+            out[name] = value;
+    }
+    return out;
+}
+async function readNodeBody(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+function classifyOutcome(res, receivedAt) {
+    if (res.status >= 200 && res.status < 300) {
+        const header = res.headers["x-payment-response"] ?? res.headers["payment-response"];
+        return {
+            kind: "paid",
+            status: res.status,
+            receivedAt,
+            ...(header ? { rawPaymentResponseHeader: header } : {}),
+        };
+    }
+    if (res.status === 402) {
+        return {
+            kind: "rejected",
+            status: res.status,
+            receivedAt,
+            ...(res.body !== undefined ? { rawBody: res.body } : {}),
+        };
+    }
+    return { kind: "unknown", status: res.status, receivedAt };
+}
+function stripHopByHop(headers) {
+    const out = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (!HOP_BY_HOP_HEADERS.has(name.toLowerCase()))
+            out[name] = value;
+    }
+    return out;
+}
+export async function createProxy(opts) {
+    const upstream = new URL(opts.upstream);
+    const upstreamTimeoutMs = opts.upstreamTimeoutMs ?? 30_000;
+    const events = createEventBus();
+    let sink = null;
+    if (opts.logPath) {
+        sink = new JsonlSink(opts.logPath);
+        await sink.open();
+    }
+    const emit = (event) => {
+        events.emit(event);
+        sink?.append(event);
+    };
+    const server = createServer(async (req, res) => {
+        const id = newExchangeId();
+        const startedAt = Date.now();
+        const startedAtIso = new Date(startedAt).toISOString();
+        let capturedReq = null;
+        try {
+            const reqHeaders = collectHeaders(req.headers);
+            const reqBodyBuf = await readNodeBody(req);
+            const reqContentType = reqHeaders["content-type"];
+            capturedReq = {
+                method: (req.method ?? "GET").toUpperCase(),
+                path: req.url ?? "/",
+                headers: reqHeaders,
+                ...bodyToCapture(reqBodyBuf, reqContentType),
+            };
+            emit({
+                event: "exchange.opened",
+                t: startedAtIso,
+                id,
+                upstreamUrl: opts.upstream,
+                request: capturedReq,
+            });
+            // Build upstream URL by appending the client's path to the upstream base.
+            const upstreamUrl = new URL(capturedReq.path.replace(/^\/+/, ""), upstream.origin + upstream.pathname.replace(/\/?$/, "/"));
+            // Forward request to upstream.
+            const fwdHeaders = stripHopByHop(capturedReq.headers);
+            const init = {
+                method: capturedReq.method,
+                headers: fwdHeaders,
+                signal: AbortSignal.timeout(upstreamTimeoutMs),
+            };
+            if (capturedReq.method !== "GET" && capturedReq.method !== "HEAD" && reqBodyBuf.length > 0) {
+                init.body = reqBodyBuf;
+            }
+            let upstreamResp;
+            try {
+                upstreamResp = await fetch(upstreamUrl.toString(), init);
+            }
+            catch (err) {
+                const isTimeout = err instanceof Error && err.name === "TimeoutError";
+                const receivedAt = new Date().toISOString();
+                const durationMs = Date.now() - startedAt;
+                const outcome = isTimeout
+                    ? { kind: "upstream_timeout", afterMs: durationMs, observedAt: receivedAt }
+                    : { kind: "unknown", status: 0, receivedAt };
+                emit({
+                    event: "exchange.closed",
+                    t: receivedAt,
+                    id,
+                    response: { status: 502, headers: { "content-type": "text/plain" }, body: "Bad Gateway" },
+                    outcome,
+                    durationMs,
+                });
+                emit({
+                    event: "proxy.error",
+                    t: receivedAt,
+                    id,
+                    message: err instanceof Error ? err.message : String(err),
+                    stack: err instanceof Error ? err.stack : undefined,
+                });
+                res.statusCode = 502;
+                res.setHeader("content-type", "text/plain");
+                res.end("Bad Gateway");
+                return;
+            }
+            // Read upstream response.
+            const respHeaders = {};
+            upstreamResp.headers.forEach((value, key) => {
+                respHeaders[key.toLowerCase()] = value;
+            });
+            const respBodyBuf = Buffer.from(await upstreamResp.arrayBuffer());
+            const respContentType = respHeaders["content-type"];
+            const capturedRes = {
+                status: upstreamResp.status,
+                headers: respHeaders,
+                ...bodyToCapture(respBodyBuf, respContentType),
+            };
+            const receivedAt = new Date().toISOString();
+            const durationMs = Date.now() - startedAt;
+            const outcome = classifyOutcome(capturedRes, receivedAt);
+            emit({
+                event: "exchange.closed",
+                t: receivedAt,
+                id,
+                response: capturedRes,
+                outcome,
+                durationMs,
+            });
+            // Forward back to client.
+            res.statusCode = capturedRes.status;
+            for (const [name, value] of Object.entries(stripHopByHop(respHeaders))) {
+                res.setHeader(name, value);
+            }
+            res.end(respBodyBuf);
+        }
+        catch (err) {
+            const t = new Date().toISOString();
+            emit({
+                event: "proxy.error",
+                t,
+                id,
+                message: err instanceof Error ? err.message : String(err),
+                stack: err instanceof Error ? err.stack : undefined,
+            });
+            if (!res.headersSent) {
+                res.statusCode = 500;
+                res.setHeader("content-type", "text/plain");
+                res.end("Proxy Error");
+            }
+            else {
+                res.end();
+            }
+        }
+    });
+    await new Promise((resolveListen, reject) => {
+        server.once("error", reject);
+        server.listen(opts.port ?? 8402, () => {
+            server.off("error", reject);
+            resolveListen();
+        });
+    });
+    const address = server.address();
+    const url = `http://localhost:${address.port}`;
+    return {
+        server,
+        url,
+        events,
+        logPath: sink?.filePath ?? null,
+        async close() {
+            await new Promise((resolveClose, reject) => {
+                server.close((err) => (err ? reject(err) : resolveClose()));
+            });
+            await sink?.close();
+        },
+    };
+}

package/dist/proxy/types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * X402-10 proxy core types.
+ *
+ * The proxy is deliberately dumb: it captures raw HTTP and emits typed
+ * events. No x402 protocol parsing happens here — that's the decoder's
+ * job (X402-11). These shapes are the JSONL-on-disk format per
+ * ARCHITECTURE.md § JSONL record format; downstream readers depend on
+ * them being stable.
+ */
+/** Stable identifier for a single client request / upstream response pair. */
+export type ExchangeId = string;
+export interface CapturedRequest {
+    /** HTTP method, uppercase. */
+    readonly method: string;
+    /** Path + query the client asked for (e.g. `/api/weather?x=1`). */
+    readonly path: string;
+    /** Lowercase header name → value. Multi-value headers are joined with `, `. */
+    readonly headers: Readonly<Record<string, string>>;
+    /**
+     * Request body. Empty string when no body or GET/HEAD.
+     * If non-UTF8 or binary, `bodyBase64` is set instead.
+     */
+    readonly body?: string;
+    readonly bodyBase64?: string;
+}
+export interface CapturedResponse {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body?: string;
+    readonly bodyBase64?: string;
+}
+/**
+ * Classification of what happened to a proxied exchange. Kept coarse so
+ * the proxy never has to understand x402 protocol semantics — the
+ * discriminant is determined from HTTP status + presence of payment
+ * headers only.
+ */
+export type ExchangeOutcome = {
+    readonly kind: "paid";
+    readonly status: number;
+    readonly receivedAt: string;
+    /** Raw value of X-PAYMENT-RESPONSE if upstream returned one. Decoder parses. */
+    readonly rawPaymentResponseHeader?: string;
+} | {
+    readonly kind: "rejected";
+    readonly status: number;
+    readonly receivedAt: string;
+    /** Raw response body (text). Decoder extracts errorReason if x402-shaped. */
+    readonly rawBody?: string;
+} | {
+    readonly kind: "upstream_timeout";
+    readonly afterMs: number;
+    readonly observedAt: string;
+} | {
+    readonly kind: "unknown";
+    readonly status: number;
+    readonly receivedAt: string;
+};
+/**
+ * Discriminated union of every event the proxy emits.
+ * `t` is ISO 8601, `event` is the discriminant.
+ */
+export type ProxyEvent = {
+    readonly event: "exchange.opened";
+    readonly t: string;
+    readonly id: ExchangeId;
+    readonly upstreamUrl: string;
+    readonly request: CapturedRequest;
+} | {
+    readonly event: "exchange.closed";
+    readonly t: string;
+    readonly id: ExchangeId;
+    readonly response: CapturedResponse;
+    readonly outcome: ExchangeOutcome;
+    readonly durationMs: number;
+} | {
+    readonly event: "proxy.error";
+    readonly t: string;
+    readonly id?: ExchangeId;
+    readonly message: string;
+    readonly stack?: string;
+};
+/**
+ * Heuristic: is this request/response pair x402-related at all?
+ *
+ * v0.1 detection rule (pure HTTP signals, no x402 parsing):
+ * - Request has an `X-PAYMENT` or `PAYMENT-SIGNATURE` header, OR
+ * - Response has a `402` status, OR
+ * - Response has an `X-PAYMENT-RESPONSE` or `PAYMENT-RESPONSE` header.
+ *
+ * The proxy logs every request/response regardless; this heuristic is
+ * used downstream by the decoder/reconciler to skip non-x402 traffic
+ * cheaply.
+ */
+export declare function isLikelyX402Exchange(req: CapturedRequest, res: CapturedResponse | undefined): boolean;