x402trace 0.1.0

package/dist/cli/replay.js

@@ -0,0 +1,193 @@
+/**
+ * Offline JSONL replay. Reads a log written by `x402trace proxy
+ * --reconcile`, reconstructs the four event streams the engine cares
+ * about (proxy `exchange.closed`, decoder `exchange.payment`, chain
+ * `chain.transfer`), and feeds them into a fresh engine.
+ *
+ * The engine runs on a *virtual clock* driven by each line's `t`
+ * field so the `not_settled` sweep fires at the right virtual moment
+ * even though the whole file replays in milliseconds.
+ *
+ * Per [ARCHITECTURE.md § JSONL record format](../../ARCHITECTURE.md#jsonl-record-format):
+ * "the file IS the API." This reader is the consumer side of that
+ * contract.
+ */
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+import { createReconciliationEngine } from "../reconciliation/engine.js";
+/**
+ * Replay the whole file, collect every emitted `ReconciliationResult`.
+ *
+ * Returns once the file is exhausted and the engine has been ticked
+ * once past the final virtual timestamp so any still-pending entry
+ * past `watchTimeoutMs` fires `not_settled`.
+ */
+export async function replayLog(opts) {
+    let virtualNow = 0;
+    const engine = createReconciliationEngine({
+        watchTimeoutMs: opts.watchTimeoutMs ?? 60_000,
+        // setInterval clamps at int32 max (~24.8d); pick a value well
+        // inside that window. Replay drives the sweep manually via `tick()`
+        // so the timer should never actually fire during a replay run.
+        sweepIntervalMs: 2_147_483_647,
+        now: () => virtualNow,
+    });
+    const results = [];
+    const resultsSub = engine.results();
+    const resultsTask = (async () => {
+        for await (const r of resultsSub)
+            results.push(r);
+    })();
+    let linesTotal = 0;
+    let linesSkipped = 0;
+    let proxyClosed = 0;
+    let decoderPayments = 0;
+    let chainTransfers = 0;
+    const stream = createReadStream(opts.logPath, { encoding: "utf8" });
+    const rl = createInterface({ input: stream, crlfDelay: Infinity });
+    for await (const rawLine of rl) {
+        linesTotal++;
+        const line = rawLine.trim();
+        if (!line) {
+            linesSkipped++;
+            continue;
+        }
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            linesSkipped++;
+            continue;
+        }
+        if (typeof record.event !== "string" || typeof record.t !== "string") {
+            linesSkipped++;
+            continue;
+        }
+        const ts = Date.parse(record.t);
+        if (Number.isFinite(ts)) {
+            // Advance virtual time monotonically. If lines are out of order
+            // we stay at the highest seen — never rewind.
+            if (ts > virtualNow)
+                virtualNow = ts;
+            engine.tick();
+        }
+        switch (record.event) {
+            case "exchange.closed": {
+                engine.ingestProxyEvent(record);
+                proxyClosed++;
+                break;
+            }
+            case "exchange.payment": {
+                engine.ingestDecoderEvent(record);
+                decoderPayments++;
+                break;
+            }
+            case "chain.transfer": {
+                const transfer = reviveChainTransfer(record);
+                if (transfer) {
+                    engine.ingestChainTransfer(transfer);
+                    chainTransfers++;
+                }
+                else {
+                    linesSkipped++;
+                }
+                break;
+            }
+            default: {
+                // exchange.opened / exchange.challenge / exchange.settlement /
+                // reconcile.result / proxy.error / decoder.error: not needed
+                // for offline reconciliation (the engine joins on closed +
+                // payment only). Don't count these as skipped errors.
+                break;
+            }
+        }
+    }
+    // Drive the sweep one last time at the final timestamp + slack so
+    // anything still pending past the watch window fires `not_settled`.
+    virtualNow += (opts.watchTimeoutMs ?? 60_000) + 1;
+    engine.tick();
+    await engine.close();
+    resultsSub.unsubscribe();
+    await resultsTask;
+    return {
+        counts: {
+            linesTotal,
+            linesSkipped,
+            proxyClosed,
+            decoderPayments,
+            chainTransfers,
+            results: results.length,
+        },
+        results,
+    };
+}
+/**
+ * `chain.transfer` lines store `bigint` fields as strings (JSON has no
+ * bigint). Resurrect them so the engine's match function sees real
+ * `bigint`s.
+ */
+function reviveChainTransfer(record) {
+    const txHash = record.txHash;
+    const from = record.from;
+    const to = record.to;
+    const tokenAddress = record.tokenAddress;
+    if (typeof txHash !== "string" ||
+        typeof from !== "string" ||
+        typeof to !== "string" ||
+        typeof tokenAddress !== "string") {
+        return null;
+    }
+    const blockNumber = toBigint(record.blockNumber);
+    const value = toBigint(record.value);
+    if (blockNumber === null || value === null)
+        return null;
+    const blockTimestamp = typeof record.blockTimestamp === "number"
+        ? record.blockTimestamp
+        : Number(record.blockTimestamp);
+    if (!Number.isFinite(blockTimestamp))
+        return null;
+    const nonce = typeof record.authorizationNonce === "string"
+        ? record.authorizationNonce
+        : undefined;
+    return {
+        txHash: txHash,
+        blockNumber,
+        blockTimestamp,
+        from: from,
+        to: to,
+        value,
+        tokenAddress: tokenAddress,
+        ...(nonce ? { authorizationNonce: nonce } : {}),
+    };
+}
+function toBigint(value) {
+    if (typeof value === "bigint")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return BigInt(value);
+    if (typeof value === "string" && /^-?\d+$/.test(value)) {
+        try {
+            return BigInt(value);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/** Test seam: serialise a ChainTransfer to its JSONL-stored shape. */
+export function chainTransferToJsonl(transfer, t = new Date().toISOString()) {
+    return {
+        event: "chain.transfer",
+        t,
+        txHash: transfer.txHash,
+        blockNumber: transfer.blockNumber.toString(),
+        blockTimestamp: transfer.blockTimestamp,
+        from: transfer.from,
+        to: transfer.to,
+        value: transfer.value.toString(),
+        tokenAddress: transfer.tokenAddress,
+        ...(transfer.authorizationNonce ? { authorizationNonce: transfer.authorizationNonce } : {}),
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * X402-14 binary entry. `package.json` `bin.x402trace` points at
+ * `dist/cli.js` (the compiled form of this file). Pure shim: wire real
+ * `process` handles to `runCli` and translate its return value to
+ * `process.exit`.
+ *
+ * Keep this file dependency-light — actual command logic lives under
+ * `src/cli/`. The reason for the split is that `runCli` is testable in
+ * isolation (with injected stdout/stderr/env/waitForShutdown) while
+ * `process.exit` cannot be safely called from a vitest worker.
+ */
+import { runCli } from "./cli/index.js";
+void runCli(process.argv.slice(2), {
+    stdout: process.stdout,
+    stderr: process.stderr,
+    env: process.env,
+}).then((code) => {
+    process.exit(code);
+});

package/dist/decoder/decoder.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Streaming decoder. Consumes raw `ProxyEvent`s from the proxy and emits
+ * structured `DecodedEvent`s. Pure-function-ish: holds no I/O state,
+ * just a small in-memory map of partially-known exchanges so it can
+ * correlate header data across the open/close pair.
+ */
+import type { ProxyEvent } from "../proxy/types.js";
+import type { DecodedEvent } from "./types.js";
+export interface DecoderOptions {
+    /** When false (default), signatures in payment payloads are replaced with "[REDACTED]". */
+    readonly logSecrets?: boolean;
+}
+export interface Decoder {
+    /**
+     * Decode a single raw proxy event. Returns 0–N structured events.
+     * Caller is responsible for sinking them (event bus, JSONL, stdout).
+     */
+    decode(event: ProxyEvent): DecodedEvent[];
+}
+export declare function createDecoder(opts?: DecoderOptions): Decoder;

package/dist/decoder/decoder.js

@@ -0,0 +1,118 @@
+import { detectVersion, findPaymentHeader, findSettlementHeader, parseChallengeBody, parsePaymentHeader, parseSettlementHeader, } from "./parse.js";
+import { redactPaymentPayload } from "./redact.js";
+export function createDecoder(opts = {}) {
+    const logSecrets = opts.logSecrets ?? false;
+    return {
+        decode(event) {
+            const out = [];
+            if (event.event === "exchange.opened") {
+                // Look for a v1 X-PAYMENT or v2 PAYMENT-SIGNATURE in the request headers.
+                const hit = findPaymentHeader(event.request.headers);
+                if (hit) {
+                    const parsed = parsePaymentHeader(hit.value, hit.version);
+                    if (parsed.ok) {
+                        out.push({
+                            event: "exchange.payment",
+                            t: event.t,
+                            id: event.id,
+                            x402Version: hit.version,
+                            payment: redactPaymentPayload(parsed.value, logSecrets),
+                        });
+                    }
+                    else {
+                        out.push({
+                            event: "decoder.error",
+                            t: event.t,
+                            id: event.id,
+                            stage: "payment",
+                            message: parsed.message,
+                        });
+                    }
+                }
+                return out;
+            }
+            if (event.event === "exchange.closed") {
+                // 402: parse the response body as a challenge.
+                if (event.response.status === 402 && event.response.body !== undefined) {
+                    const parsed = parseChallengeBody(event.response.body);
+                    if (parsed.ok) {
+                        out.push({
+                            event: "exchange.challenge",
+                            t: event.t,
+                            id: event.id,
+                            x402Version: parsed.value.x402Version,
+                            challenge: parsed.value.requirements,
+                            ...(parsed.value.error ? { raw402Error: parsed.value.error } : {}),
+                        });
+                    }
+                    else {
+                        out.push({
+                            event: "decoder.error",
+                            t: event.t,
+                            id: event.id,
+                            stage: "challenge",
+                            message: parsed.message,
+                        });
+                    }
+                }
+                // Settlement: look for X-PAYMENT-RESPONSE / PAYMENT-RESPONSE header.
+                const settlementHit = findSettlementHeader(event.response.headers);
+                if (settlementHit) {
+                    const parsed = parseSettlementHeader(settlementHit.value);
+                    if (parsed.ok) {
+                        out.push({
+                            event: "exchange.settlement",
+                            t: event.t,
+                            id: event.id,
+                            settlement: parsed.value,
+                        });
+                    }
+                    else {
+                        out.push({
+                            event: "decoder.error",
+                            t: event.t,
+                            id: event.id,
+                            stage: "settlement",
+                            message: parsed.message,
+                        });
+                    }
+                }
+                else if (event.outcome.kind === "paid" &&
+                    "rawPaymentResponseHeader" in event.outcome &&
+                    event.outcome.rawPaymentResponseHeader) {
+                    // Proxy already extracted the header; decode from there as a fallback.
+                    const parsed = parseSettlementHeader(event.outcome.rawPaymentResponseHeader);
+                    if (parsed.ok) {
+                        out.push({
+                            event: "exchange.settlement",
+                            t: event.t,
+                            id: event.id,
+                            settlement: parsed.value,
+                        });
+                    }
+                }
+                // Side note: the proxy already classified outcome via `event.outcome`
+                // (paid | rejected | upstream_timeout | unknown). The decoder
+                // doesn't re-emit it — downstream tools can read either signal.
+                // Use detectVersion as a soft-validation hint; not directly emitted
+                // but useful in future extensions.
+                void detectVersion(event.response.headers);
+                return out;
+            }
+            if (event.event === "proxy.error") {
+                // Pass through as a decoder error; the proxy already wrote its
+                // own proxy.error event to JSONL, so this is just for live
+                // subscribers that only listen on the decoder bus.
+                out.push({
+                    event: "decoder.error",
+                    t: event.t,
+                    ...(event.id ? { id: event.id } : {}),
+                    stage: "payment",
+                    message: `upstream/proxy error: ${event.message}`,
+                });
+                return out;
+            }
+            return out;
+        },
+    };
+}

package/dist/decoder/format.d.ts

@@ -0,0 +1,9 @@
+import type { DecodedEvent } from "./types.js";
+/**
+ * Human-readable single-line summary of a decoded event. Designed for
+ * `pnpm proxy` / `x402trace proxy` stdout where compactness matters.
+ * Full structure goes to JSONL.
+ */
+export declare function formatHuman(event: DecodedEvent): string;
+/** JSON-line representation. Pure JSON.stringify with stable key order via field-by-field copy. */
+export declare function formatJson(event: DecodedEvent): string;

package/dist/decoder/format.js

@@ -0,0 +1,50 @@
+/**
+ * Human-readable single-line summary of a decoded event. Designed for
+ * `pnpm proxy` / `x402trace proxy` stdout where compactness matters.
+ * Full structure goes to JSONL.
+ */
+export function formatHuman(event) {
+    const stamp = `[${event.t}]`;
+    switch (event.event) {
+        case "exchange.challenge": {
+            const r = event.challenge;
+            const amt = r.maxAmountRequired;
+            const errSuffix = event.raw402Error ? ` (error=${event.raw402Error})` : "";
+            return `${stamp} 402 challenge id=${short(event.id)} v${event.x402Version} ${r.scheme}/${r.network} amount=${amt} payTo=${shortAddr(r.payTo)} asset=${shortAddr(r.asset)}${errSuffix}`;
+        }
+        case "exchange.payment": {
+            const auth = event.payment.payload.authorization;
+            return `${stamp} X-PAYMENT id=${short(event.id)} v${event.x402Version} from=${shortAddr(auth.from)} → to=${shortAddr(auth.to)} value=${auth.value} nonce=${short(auth.nonce)} validBefore=${auth.validBefore}`;
+        }
+        case "exchange.settlement": {
+            const s = event.settlement;
+            const status = s.success === true
+                ? "✓ success"
+                : s.isValid === false
+                    ? `✗ invalid: ${s.invalidReason ?? "?"}`
+                    : s.errorReason
+                        ? `✗ error: ${s.errorReason}`
+                        : "?";
+            const tx = s.transaction ? ` tx=${short(s.transaction)}` : "";
+            return `${stamp} settlement id=${short(event.id)} ${status}${tx}`;
+        }
+        case "decoder.error": {
+            const idStr = event.id ? ` id=${short(event.id)}` : "";
+            return `${stamp} decoder.error stage=${event.stage}${idStr} message="${event.message}"`;
+        }
+    }
+}
+/** JSON-line representation. Pure JSON.stringify with stable key order via field-by-field copy. */
+export function formatJson(event) {
+    return JSON.stringify(event);
+}
+function short(value, head = 8) {
+    if (value.length <= head + 4)
+        return value;
+    return `${value.slice(0, head)}…`;
+}
+function shortAddr(value) {
+    if (!value.startsWith("0x") || value.length < 12)
+        return value;
+    return `${value.slice(0, 6)}…${value.slice(-4)}`;
+}

package/dist/decoder/index.d.ts

@@ -0,0 +1,5 @@
+export { createDecoder, type Decoder, type DecoderOptions } from "./decoder.js";
+export { formatHuman, formatJson } from "./format.js";
+export { redactPaymentPayload } from "./redact.js";
+export { detectVersion, findPaymentHeader, findSettlementHeader, parseChallengeBody, parsePaymentHeader, parseSettlementHeader, type ParseResult, } from "./parse.js";
+export { type DecodedEvent, type FacilitatorResponse, type LogFormat, type PaymentAuthorization, type PaymentPayload, type PaymentRequirements, type X402Version, } from "./types.js";

package/dist/decoder/index.js

@@ -0,0 +1,5 @@
+export { createDecoder } from "./decoder.js";
+export { formatHuman, formatJson } from "./format.js";
+export { redactPaymentPayload } from "./redact.js";
+export { detectVersion, findPaymentHeader, findSettlementHeader, parseChallengeBody, parsePaymentHeader, parseSettlementHeader, } from "./parse.js";
+export {} from "./types.js";

package/dist/decoder/parse.d.ts

@@ -0,0 +1,53 @@
+import type { FacilitatorResponse, PaymentPayload, PaymentRequirements, X402Version } from "./types.js";
+interface ParseError {
+    readonly ok: false;
+    readonly message: string;
+}
+interface ParseOk<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+export type ParseResult<T> = ParseOk<T> | ParseError;
+/**
+ * Detect the x402 protocol version from headers + body. Returns 1
+ * (default) when no clear v2 marker is present.
+ */
+export declare function detectVersion(headers: Record<string, string>, body?: unknown): X402Version;
+/**
+ * Find the (request) payment header value, preferring v1 then v2.
+ */
+export declare function findPaymentHeader(headers: Record<string, string>): {
+    name: string;
+    value: string;
+    version: X402Version;
+} | null;
+/**
+ * Find the (response) settlement header value.
+ */
+export declare function findSettlementHeader(headers: Record<string, string>): {
+    name: string;
+    value: string;
+    version: X402Version;
+} | null;
+/**
+ * Parse a 402 response body (raw text) into a v1 / v2 challenge.
+ * Returns the first `accepts[]` entry — v0.1 picks the head; downstream
+ * tools can extend.
+ */
+export declare function parseChallengeBody(rawBody: string): ParseResult<{
+    requirements: PaymentRequirements;
+    x402Version: X402Version;
+    error?: string;
+}>;
+/**
+ * Parse a base64-encoded X-PAYMENT / PAYMENT-SIGNATURE header value
+ * into a typed `PaymentPayload`. Uses the x402 SDK for v1 fast-path
+ * and falls back to a hand-rolled shape check for v2.
+ */
+export declare function parsePaymentHeader(headerValue: string, version: X402Version): ParseResult<PaymentPayload>;
+/**
+ * Parse a base64-encoded X-PAYMENT-RESPONSE / PAYMENT-RESPONSE header
+ * value into a `FacilitatorResponse`.
+ */
+export declare function parseSettlementHeader(headerValue: string): ParseResult<FacilitatorResponse>;
+export {};

package/dist/decoder/parse.js

@@ -0,0 +1,179 @@
+/**
+ * Pure parsers from raw HTTP signal → typed x402 structures.
+ *
+ * Per CLAUDE.md hard rule 4 ("Don't reproduce code from x402 SDKs.
+ * Use them as dependencies."), we use the `x402` package's
+ * `exact.evm.decodePayment` for the v1 X-PAYMENT header. The v2
+ * `PAYMENT-SIGNATURE` header is base64-encoded JSON of a similar
+ * shape; the SDK's v1-only decoder rejects it, so we add a
+ * minimal forward-compatible parser inline. v0.1 produces the same
+ * normalized `PaymentPayload` shape for both surfaces.
+ */
+import { exact } from "x402/schemes";
+const PAYMENT_HEADER_V1 = "x-payment";
+const PAYMENT_HEADER_V2 = "payment-signature";
+const SETTLEMENT_HEADER_V1 = "x-payment-response";
+const SETTLEMENT_HEADER_V2 = "payment-response";
+/**
+ * Detect the x402 protocol version from headers + body. Returns 1
+ * (default) when no clear v2 marker is present.
+ */
+export function detectVersion(headers, body) {
+    if (headers[PAYMENT_HEADER_V2] || headers[SETTLEMENT_HEADER_V2])
+        return 2;
+    if (body &&
+        typeof body === "object" &&
+        "x402Version" in body &&
+        body.x402Version === 2) {
+        return 2;
+    }
+    return 1;
+}
+/**
+ * Find the (request) payment header value, preferring v1 then v2.
+ */
+export function findPaymentHeader(headers) {
+    if (headers[PAYMENT_HEADER_V1]) {
+        return { name: PAYMENT_HEADER_V1, value: headers[PAYMENT_HEADER_V1], version: 1 };
+    }
+    if (headers[PAYMENT_HEADER_V2]) {
+        return { name: PAYMENT_HEADER_V2, value: headers[PAYMENT_HEADER_V2], version: 2 };
+    }
+    return null;
+}
+/**
+ * Find the (response) settlement header value.
+ */
+export function findSettlementHeader(headers) {
+    if (headers[SETTLEMENT_HEADER_V1]) {
+        return { name: SETTLEMENT_HEADER_V1, value: headers[SETTLEMENT_HEADER_V1], version: 1 };
+    }
+    if (headers[SETTLEMENT_HEADER_V2]) {
+        return { name: SETTLEMENT_HEADER_V2, value: headers[SETTLEMENT_HEADER_V2], version: 2 };
+    }
+    return null;
+}
+/**
+ * Parse a 402 response body (raw text) into a v1 / v2 challenge.
+ * Returns the first `accepts[]` entry — v0.1 picks the head; downstream
+ * tools can extend.
+ */
+export function parseChallengeBody(rawBody) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawBody);
+    }
+    catch (err) {
+        return { ok: false, message: `challenge body is not JSON: ${err.message}` };
+    }
+    if (!parsed || typeof parsed !== "object") {
+        return { ok: false, message: "challenge body is not an object" };
+    }
+    const obj = parsed;
+    const x402Version = obj.x402Version === 2 ? 2 : 1;
+    if (!Array.isArray(obj.accepts) || obj.accepts.length === 0) {
+        return { ok: false, message: "challenge body missing accepts[]" };
+    }
+    const first = obj.accepts[0];
+    if (!first || typeof first !== "object") {
+        return { ok: false, message: "challenge accepts[0] is not an object" };
+    }
+    const r = first;
+    for (const k of ["scheme", "network", "maxAmountRequired", "resource", "payTo", "asset"]) {
+        if (typeof r[k] !== "string") {
+            return { ok: false, message: `challenge accepts[0].${k} missing or wrong type` };
+        }
+    }
+    return {
+        ok: true,
+        value: {
+            requirements: first,
+            x402Version,
+            ...(obj.error ? { error: obj.error } : {}),
+        },
+    };
+}
+function decodeBase64Json(value) {
+    let decoded;
+    try {
+        decoded = Buffer.from(value, "base64").toString("utf8");
+    }
+    catch (err) {
+        return { ok: false, message: `not valid base64: ${err.message}` };
+    }
+    try {
+        return { ok: true, value: JSON.parse(decoded) };
+    }
+    catch (err) {
+        return { ok: false, message: `base64 decode is not JSON: ${err.message}` };
+    }
+}
+function shapeCheckPaymentPayload(parsed) {
+    if (!parsed || typeof parsed !== "object") {
+        return { ok: false, message: "payment payload is not an object" };
+    }
+    const obj = parsed;
+    if (obj.scheme !== "exact" && typeof obj.scheme !== "string") {
+        return { ok: false, message: "payment payload missing scheme" };
+    }
+    if (typeof obj.network !== "string") {
+        return { ok: false, message: "payment payload missing network" };
+    }
+    const payload = obj.payload;
+    if (!payload || typeof payload !== "object") {
+        return { ok: false, message: "payment payload.payload missing" };
+    }
+    if (typeof payload.signature !== "string") {
+        return { ok: false, message: "payment payload.signature missing" };
+    }
+    const auth = payload.authorization;
+    if (!auth || typeof auth !== "object") {
+        return { ok: false, message: "payment payload.authorization missing" };
+    }
+    for (const k of ["from", "to", "value", "validAfter", "validBefore", "nonce"]) {
+        if (typeof auth[k] !== "string") {
+            return { ok: false, message: `payment payload.authorization.${k} missing` };
+        }
+    }
+    return { ok: true, value: parsed };
+}
+/**
+ * Parse a base64-encoded X-PAYMENT / PAYMENT-SIGNATURE header value
+ * into a typed `PaymentPayload`. Uses the x402 SDK for v1 fast-path
+ * and falls back to a hand-rolled shape check for v2.
+ */
+export function parsePaymentHeader(headerValue, version) {
+    if (version === 1) {
+        try {
+            const decoded = exact.evm.decodePayment(headerValue);
+            return shapeCheckPaymentPayload(decoded);
+        }
+        catch (err) {
+            // Fall through to manual decode — some captured fixtures may not be
+            // perfectly schema-conforming and we still want to surface what we can.
+            const fallback = decodeBase64Json(headerValue);
+            if (!fallback.ok) {
+                return { ok: false, message: `v1 SDK decode failed: ${err.message}` };
+            }
+            return shapeCheckPaymentPayload(fallback.value);
+        }
+    }
+    // v2: hand-rolled.
+    const decoded = decodeBase64Json(headerValue);
+    if (!decoded.ok)
+        return decoded;
+    return shapeCheckPaymentPayload(decoded.value);
+}
+/**
+ * Parse a base64-encoded X-PAYMENT-RESPONSE / PAYMENT-RESPONSE header
+ * value into a `FacilitatorResponse`.
+ */
+export function parseSettlementHeader(headerValue) {
+    const decoded = decodeBase64Json(headerValue);
+    if (!decoded.ok)
+        return decoded;
+    if (!decoded.value || typeof decoded.value !== "object") {
+        return { ok: false, message: "settlement payload is not an object" };
+    }
+    return { ok: true, value: decoded.value };
+}

package/dist/decoder/redact.d.ts

@@ -0,0 +1,12 @@
+import type { PaymentPayload } from "./types.js";
+/**
+ * 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 declare function redactPaymentPayload(payment: PaymentPayload, logSecrets: boolean): PaymentPayload;