@forum-labs/payfetch 1.0.0

package/dist/src/core/pipeline.js

@@ -0,0 +1,795 @@
+import { APPROVAL_ELICIT_TIMEOUT_S, CLIENT_VERSION, GUARD_SEND_QUERY, INTEGRATION_HEADER, guardBudgetMs, KNOWN_ASSETS, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, POLICY_VERSION, X_PAYMENT_HEADER, X_PAYMENT_RESPONSE_HEADER, } from "./constants.js";
+import { guardDayKey, utcDate, } from "./ledger.js";
+import { budgetExhausted, elicitUnsupportedFallback, guardBlocked, guardUnavailable, guardWarn, preapproved, } from "./notes.js";
+import { matchesAnyHost } from "./policy.js";
+import { deliverBody, transportFetch, } from "./transport.js";
+import { parse402Challenge, parseChallenge } from "../payer/parse402.js";
+import { parseSettlementResponse, quoteWithRejections, selectQuote, } from "../payer/x402.js";
+const defaultDelay = (ms) => new Promise((r) => {
+    const t = setTimeout(r, ms);
+    t.unref?.();
+});
+function hex(bytes) {
+    let s = "";
+    for (const b of bytes)
+        s += b.toString(16).padStart(2, "0");
+    return s;
+}
+function uuid4FromBytes(b) {
+    const h = hex(b.subarray(0, 16)).split("");
+    h[12] = "4";
+    const variant = (parseInt(h[16], 16) & 0x3) | 0x8;
+    h[16] = variant.toString(16);
+    const s = h.join("");
+    return `${s.slice(0, 8)}-${s.slice(8, 12)}-${s.slice(12, 16)}-${s.slice(16, 20)}-${s.slice(20, 32)}`;
+}
+export class PayfetchEngine {
+    #cfg;
+    #deps;
+    #delay;
+    guards = [];
+    constructor(cfg) {
+        this.#cfg = cfg;
+        this.#deps = cfg.deps;
+        this.#delay = cfg.delay ?? defaultDelay;
+    }
+    newReceiptId() {
+        return uuid4FromBytes(this.#deps.random());
+    }
+    capsOf(policy) {
+        return {
+            dailyUsd: policy.caps.dailyUsd,
+            perHostDailyUsd: policy.caps.perHostDailyUsd,
+            totalUsd: policy.caps.totalUsd,
+        };
+    }
+    transportIo() {
+        return {
+            ...this.#cfg.transportIo,
+            now: this.#deps.now,
+            log: this.#deps.log,
+            fs: this.#cfg.fs,
+        };
+    }
+    async fetch(url, init, opts) {
+        return this.run(url, init ?? {}, opts ?? {}, false);
+    }
+    async quote(url, init) {
+        const { receipt } = await this.run(url, init ?? {}, { dryRun: true }, true);
+        return { decision: this.decisionFromReceipt(receipt), receipt };
+    }
+    async status() {
+        this.#cfg.budget.sweepExpired();
+        const pol = this.#cfg.policyProvider();
+        const caps = pol.ok ? this.capsOf(pol.policy) : { dailyUsd: 0, perHostDailyUsd: 0, totalUsd: null };
+        const now = this.#deps.now();
+        const date = utcDate(now);
+        const state = this.#cfg.budget.state;
+        const dayKeyStr = `day:${date}`;
+        const daySpent = state.counters[dayKeyStr] ?? 0;
+        const totalSpent = state.counters["total"] ?? 0;
+        const perHost = {};
+        for (const [k, v] of Object.entries(state.counters)) {
+            const m = /^host:(.+):(\d{4}-\d{2}-\d{2})$/.exec(k);
+            if (m && m[2] === date) {
+                const host = m[1];
+                const rem = this.#cfg.budget.remaining(caps, host);
+                perHost[host] = { spentUsd: v, remainingUsd: rem.hostRemainingUsd };
+            }
+        }
+        const remaining = this.#cfg.budget.remaining(caps, "");
+        const recent = this.#cfg.ledger
+            .readAllReceipts()
+            .filter((r) => r.payment !== null)
+            .sort((a, b) => b.ts - a.ts)
+            .slice(0, 10)
+            .map((r) => ({
+            receiptId: r.receiptId,
+            host: r.host,
+            amountUsd: r.payment?.settledAmountUsd ?? r.quote?.amountUsd ?? null,
+            outcome: r.outcome,
+            ts: r.ts,
+        }));
+        return {
+            date,
+            day: { spentUsd: daySpent, remainingUsd: remaining.dayRemainingUsd },
+            total: { spentUsd: totalSpent, remainingUsd: remaining.totalRemainingUsd },
+            perHost,
+            holds: state.holds.map((h) => ({
+                holdId: h.holdId,
+                amountUsd: h.amountUsd,
+                host: h.host,
+                validBeforeTs: h.validBeforeTs,
+            })),
+            autoDenied: this.#cfg.budget.autoDeniedHosts(),
+            recentPayments: recent,
+        };
+    }
+    receipts(q) {
+        const limit = Math.min(Math.max(q.limit ?? 50, 1), 200);
+        let rs = this.#cfg.ledger.readAllReceipts();
+        if (q.sinceTs !== undefined)
+            rs = rs.filter((r) => r.ts >= q.sinceTs);
+        if (q.host !== undefined)
+            rs = rs.filter((r) => r.host === q.host);
+        if (q.outcome !== undefined)
+            rs = rs.filter((r) => r.outcome === q.outcome);
+        rs.sort((a, b) => b.ts - a.ts);
+        return rs.slice(0, limit);
+    }
+    listApprovals() {
+        return this.#cfg.budget.listApprovals();
+    }
+    queueCapableNow() {
+        const p = this.#cfg.policyProvider();
+        if (!p.ok)
+            return false;
+        const a = p.policy.approval;
+        return a.mode === "queue" || (a.mode === "elicit" && a.elicitFallback === "queue");
+    }
+    resolveApproval(approvalId, approve) {
+        if (!this.#cfg.approverEnabled)
+            return { ok: false, error: "approver_not_enabled" };
+        if (approve && this.queueCapableNow()) {
+            return { ok: false, error: "queue_self_approval_forbidden" };
+        }
+        const g = this.#cfg.budget.resolvePending(approvalId, approve);
+        return g ? { ok: true } : { ok: false, error: "approval_not_found" };
+    }
+    async run(url, init, opts, quoteMode) {
+        const deps = this.#deps;
+        const receiptId = this.newReceiptId();
+        const verdictPath = [];
+        const notes = [];
+        if (this.#cfg.testMode)
+            notes.push("test_mode");
+        this.#cfg.budget.sweepExpired();
+        const pol = this.#cfg.policyProvider();
+        if (!pol.ok) {
+            return this.finish(this.baseReceipt(receiptId, url, init, "", "policy_denied", verdictPath, notes, null, {
+                dayRemainingUsd: 0,
+                hostRemainingUsd: 0,
+                totalRemainingUsd: null,
+            }, { denyCode: "policy_config_invalid", notesExtra: [pol.error] }), null);
+        }
+        const policy = pol.policy;
+        const caps = this.capsOf(policy);
+        const method = (init.method ?? "GET").toUpperCase();
+        const userHeaders = stripReservedHeaders(init.headers);
+        const body = typeof init.body === "string" ? init.body : null;
+        const responseMode = opts.responseMode ?? "inline";
+        const dry = quoteMode || Boolean(opts.dryRun);
+        const io = this.transportIo();
+        const leg1 = await transportFetch(url, { method, headers: userHeaders, body }, policy, io);
+        for (const n of leg1.notes)
+            notes.push(n);
+        if (!leg1.ok) {
+            const budgets = this.#cfg.budget.remaining(caps, leg1.finalHost);
+            const outcome = "fetch_error";
+            const receipt = this.baseReceipt(receiptId, url, init, leg1.finalHost, outcome, verdictPath, notes, null, budgets, { http: this.httpBlock(leg1) });
+            return this.finish(receipt, null);
+        }
+        const finalHost = leg1.finalHost;
+        const budgetsAtDecision = this.#cfg.budget.remaining(caps, finalHost);
+        if (leg1.status !== 402) {
+            const delivered = deliverBody(leg1.rawBody ?? new Uint8Array(0), responseMode, {
+                fs: io.fs,
+                downloadPath: this.#cfg.ledger.downloadPath(receiptId),
+            });
+            if (delivered.mode === "inline" && delivered.truncated)
+                notes.push("body_truncated");
+            const receipt = this.baseReceipt(receiptId, url, init, finalHost, "free", verdictPath, notes, null, budgetsAtDecision, { http: this.httpBlock(leg1) });
+            return this.finish(receipt, this.materialize(leg1, delivered));
+        }
+        const challenge = parse402Challenge(leg1.rawBody ?? new Uint8Array(0), leg1.headers?.get(PAYMENT_REQUIRED_HEADER) ?? null);
+        verdictPath.push("parse");
+        if (challenge.malformed) {
+            return this.deny(receiptId, url, init, finalHost, verdictPath, notes, null, budgetsAtDecision, "malformed_402", ["malformed_402"], "policy_denied", leg1);
+        }
+        verdictPath.push("quotes");
+        const payer = this.detectPayer(challenge);
+        const { quotes, rejected } = this.quoteAndReject(challenge, payer);
+        if (quotes.length === 0) {
+            const rejNotes = tallyNotes(rejected);
+            return this.deny(receiptId, url, init, finalHost, verdictPath, notes, null, budgetsAtDecision, "unsupported_terms", ["unsupported_terms", ...rejNotes], "policy_denied", leg1, rejected);
+        }
+        verdictPath.push("select");
+        const quote = selectQuote(quotes);
+        if (quote === null) {
+            return this.deny(receiptId, url, init, finalHost, verdictPath, notes, null, budgetsAtDecision, "unsupported_terms", ["unsupported_terms"], "policy_denied", leg1, rejected);
+        }
+        if (this.#cfg.testMode && quote.network === "base") {
+            return this.deny(receiptId, url, init, finalHost, verdictPath, notes, quote, budgetsAtDecision, "test_mode", ["test_mode"], "policy_denied", leg1, rejected);
+        }
+        verdictPath.push("deny_list");
+        if (matchesAnyHost(finalHost, policy.deny)) {
+            return this.deny(receiptId, url, init, finalHost, verdictPath, notes, quote, budgetsAtDecision, "host_denied", ["host_denied"], "policy_denied", leg1, rejected);
+        }
+        verdictPath.push("allow_list");
+        if (policy.mode === "allowlist" && !matchesAnyHost(finalHost, policy.allow)) {
+            return this.deny(receiptId, url, init, finalHost, verdictPath, notes, quote, budgetsAtDecision, "host_not_allowlisted", ["host_not_allowlisted"], "policy_denied", leg1, rejected);
+        }
+        verdictPath.push("auto_deny");
+        if (policy.autoDeny.enabled && this.#cfg.budget.isAutoDenied(finalHost)) {
+            return this.deny(receiptId, url, init, finalHost, verdictPath, notes, quote, budgetsAtDecision, "host_auto_denied", ["host_auto_denied"], "policy_denied", leg1, rejected);
+        }
+        verdictPath.push("per_call");
+        const effectivePerCall = Math.min(policy.caps.perCallUsd, opts.maxAmountUsd ?? Number.POSITIVE_INFINITY);
+        if (microUsd(quote.amountUsd) > microUsd(effectivePerCall)) {
+            return this.deny(receiptId, url, init, finalHost, verdictPath, notes, quote, budgetsAtDecision, "per_call_cap_exceeded", ["per_call_cap_exceeded"], "policy_denied", leg1, rejected);
+        }
+        verdictPath.push("guards");
+        const guardInput = {
+            url: guardUrl(leg1.finalUrl),
+            host: finalHost,
+            quote,
+            context: {
+                tokenAddress: opts.tokenAddress,
+                chain: opts.chain,
+            },
+            dryRun: dry,
+        };
+        const guardResults = [];
+        for (const guard of this.guards) {
+            const cfg = guard.id === "trust" ? policy.guards.trust : policy.guards.safety;
+            if (!cfg.enabled)
+                continue;
+            if (!guard.applies(guardInput))
+                continue;
+            const res = await this.runGuard(guard, { ...guardInput, config: cfg }, guardBudgetMs(cfg.mode));
+            guardResults.push(res);
+            if (res.verdict === "block") {
+                notes.push(guardBlocked(res.id));
+                return this.denyGuardBlocked(receiptId, url, init, finalHost, verdictPath, notes, quote, budgetsAtDecision, leg1, rejected, guardResults, "danger");
+            }
+            if (res.verdict === "warn")
+                notes.push(guardWarn(res.id));
+            if (res.verdict === "unavailable") {
+                notes.push(guardUnavailable(res.id));
+                const disposition = resolveUnavailable(cfg, res);
+                if (disposition === "block") {
+                    return this.denyGuardBlocked(receiptId, url, init, finalHost, verdictPath, notes, quote, budgetsAtDecision, leg1, rejected, guardResults, guardBlockReasonFor(res));
+                }
+                if (disposition === "warn")
+                    notes.push(guardWarn(res.id));
+            }
+        }
+        verdictPath.push("dry_run");
+        if (dry) {
+            const receipt = this.baseReceipt(receiptId, url, init, finalHost, "dry_run", verdictPath, notes, quote, budgetsAtDecision, { rejectedQuotes: rejected, guards: guardResults, http: this.httpBlock(leg1) });
+            return this.finish(receipt, null);
+        }
+        verdictPath.push("approval");
+        let approvedBy = null;
+        if (microUsd(quote.amountUsd) > microUsd(policy.approval.thresholdUsd)) {
+            const appr = await this.runApproval(policy, finalHost, quote, guardResults, budgetsAtDecision, receiptId);
+            for (const n of appr.notes)
+                notes.push(n);
+            if (appr.kind === "denied") {
+                const receipt = this.baseReceipt(receiptId, url, init, finalHost, appr.outcome, verdictPath, notes, quote, budgetsAtDecision, { rejectedQuotes: rejected, guards: guardResults, http: this.httpBlock(leg1),
+                    approval: { mode: policy.approval.mode, approvedBy: null } });
+                return this.finish(receipt, null);
+            }
+            approvedBy = appr.approvedBy;
+        }
+        const approvalBlock = approvedBy !== null ? { mode: policy.approval.mode, approvedBy } : null;
+        verdictPath.push("reserve");
+        const reservation = this.#cfg.budget.reserve({
+            holdId: receiptId,
+            amountUsd: quote.amountUsd,
+            host: finalHost,
+            caps,
+        });
+        if (!reservation.ok) {
+            return this.deny(receiptId, url, init, finalHost, verdictPath, notes, quote, budgetsAtDecision, `budget_exhausted:${reservation.which}`, [budgetExhausted(reservation.which)], "policy_denied", leg1, rejected, guardResults, approvalBlock);
+        }
+        verdictPath.push("pay");
+        return this.executePayment(receiptId, url, leg1.finalUrl, init, method, userHeaders, body, finalHost, quote, payer, policy, verdictPath, notes, rejected, guardResults, budgetsAtDecision, responseMode, approvalBlock);
+    }
+    async executePayment(receiptId, url, finalUrl, init, method, userHeaders, body, finalHost, quote, payer, policy, verdictPath, notes, rejected, guardResults, budgets, responseMode, approval) {
+        const deps = this.#deps;
+        const budget = this.#cfg.budget;
+        let proof;
+        try {
+            proof = await payer.buildPayment(quote, deps.signer, deps);
+        }
+        catch (err) {
+            budget.release(receiptId);
+            deps.log("payment.build_failed", { host: finalHost, message: scrub(err.message) });
+            const receipt = this.baseReceipt(receiptId, url, init, finalHost, "fetch_error", verdictPath, notes, quote, budgets, { rejectedQuotes: rejected, guards: guardResults, approval });
+            return this.finish(receipt, null);
+        }
+        budget.setHoldValidBefore(receiptId, proof.validBeforeTs);
+        const payerAddress = await deps.signer.address();
+        const io = this.transportIo();
+        const retry = await transportFetch(finalUrl, { method, headers: { ...userHeaders, ...proof.headers }, body }, policy, io, { followRedirects: false });
+        for (const n of retry.notes)
+            if (!notes.includes(n))
+                notes.push(n);
+        const cls = classifyTerminal(retry, quote);
+        if (cls.note)
+            notes.push(cls.note);
+        if (cls.holdDisposition === "settle") {
+            budget.settle(receiptId, cls.settledAmountUsd ?? quote.amountUsd);
+        }
+        if (policy.autoDeny.enabled) {
+            const strikeCls = strikeClassFor(cls.outcome);
+            if (strikeCls)
+                budget.recordStrike(finalHost, strikeCls);
+        }
+        let response = null;
+        if (cls.outcome === "paid_delivered" && retry.ok) {
+            const delivered = deliverBody(retry.rawBody ?? new Uint8Array(0), responseMode, {
+                fs: io.fs,
+                downloadPath: this.#cfg.ledger.downloadPath(receiptId),
+            });
+            if (delivered.mode === "inline" && delivered.truncated)
+                notes.push("body_truncated");
+            response = this.materialize(retry, delivered);
+        }
+        const receipt = this.baseReceipt(receiptId, url, init, finalHost, cls.outcome, verdictPath, notes, quote, budgets, {
+            rejectedQuotes: rejected,
+            guards: guardResults,
+            approval,
+            http: retry.ok ? this.httpBlock(retry) : null,
+            payment: {
+                payerAddress,
+                nonce: proof.nonce,
+                validBeforeTs: proof.validBeforeTs,
+                settledAmountUsd: cls.holdDisposition === "settle" ? cls.settledAmountUsd ?? quote.amountUsd : null,
+                txRef: cls.txRef,
+                settlementConfirmed: cls.settlementConfirmed,
+            },
+        });
+        return this.finish(receipt, response);
+    }
+    async runGuard(guard, input, budgetMs) {
+        const start = this.#deps.now();
+        const TIMEOUT = Symbol("guard_timeout");
+        try {
+            const res = await Promise.race([
+                guard.check(input, this.#deps),
+                this.#delay(budgetMs).then(() => TIMEOUT),
+            ]);
+            if (res === TIMEOUT)
+                return this.guardUnavailableResult(guard.id, start, "timeout");
+            return res;
+        }
+        catch (err) {
+            this.#deps.log("guard.crash", { id: guard.id, message: scrub(err.message) });
+            return this.guardUnavailableResult(guard.id, start, "crash");
+        }
+    }
+    guardUnavailableResult(id, start, reason) {
+        return { id, verdict: "unavailable", detail: { reason }, latencyMs: this.#deps.now() - start, costUsd: 0 };
+    }
+    async runApproval(policy, host, quote, guardResults, budgets, receiptId) {
+        const mode = policy.approval.mode;
+        if (mode === "deny") {
+            return { kind: "denied", outcome: "approval_denied", notes: ["approval_mode_deny"] };
+        }
+        const preNote = preApprovedNote(policy, host, quote);
+        if (preNote) {
+            return { kind: "approved", approvedBy: "config", notes: [preNote] };
+        }
+        if (mode === "queue") {
+            return this.queueApproval(host, quote, receiptId, []);
+        }
+        if (this.#deps.elicit === null) {
+            return this.elicitUnavailable(policy, host, quote, receiptId, "elicit_unsupported");
+        }
+        const req = {
+            host,
+            resource: quote.resource,
+            amountUsd: quote.amountUsd,
+            networkLabel: quote.network,
+            assetLabel: assetLabel(quote.asset),
+            guards: guardResults,
+            remainingBudgets: budgets,
+        };
+        let decision;
+        try {
+            decision = await Promise.race([
+                this.#deps.elicit(req),
+                this.#delay(APPROVAL_ELICIT_TIMEOUT_S * 1000).then(() => ({ __timeout: true })),
+            ]);
+        }
+        catch {
+            return this.elicitUnavailable(policy, host, quote, receiptId, "elicit_cancelled");
+        }
+        if ("__timeout" in decision) {
+            return { kind: "denied", outcome: "approval_timeout", notes: ["approval_timeout"] };
+        }
+        if (decision.cancelled) {
+            return this.elicitUnavailable(policy, host, quote, receiptId, "elicit_cancelled");
+        }
+        if (!decision.approved) {
+            return { kind: "denied", outcome: "approval_denied", notes: [] };
+        }
+        return { kind: "approved", approvedBy: "elicit", notes: [] };
+    }
+    elicitUnavailable(policy, host, quote, receiptId, cause) {
+        const fb = policy.approval.elicitFallback;
+        const fbNote = elicitUnsupportedFallback(fb);
+        if (fb === "queue") {
+            return this.queueApproval(host, quote, receiptId, [cause, fbNote]);
+        }
+        return { kind: "denied", outcome: "approval_denied", notes: [cause, fbNote] };
+    }
+    queueApproval(host, quote, receiptId, extraNotes) {
+        const grant = this.#cfg.budget.findGrant(host, quote.amountUsd);
+        if (grant) {
+            this.#cfg.budget.consumeGrant(grant.approvalId);
+            return { kind: "approved", approvedBy: "queue", notes: extraNotes };
+        }
+        this.#cfg.budget.addPendingApproval({
+            approvalId: receiptId,
+            host,
+            amountUsd: quote.amountUsd,
+            createdTs: this.#deps.now(),
+            resource: quote.resource,
+        });
+        return { kind: "denied", outcome: "approval_queued", notes: extraNotes };
+    }
+    liveGuardBudgetUsd(id) {
+        const pol = this.#cfg.policyProvider();
+        if (!pol.ok)
+            return 0;
+        return id === "trust"
+            ? pol.policy.guards.trust.dailyBudgetUsd
+            : pol.policy.guards.safety.dailyBudgetUsd;
+    }
+    makeGuardFetch(id, budgetUsd, baseUrl) {
+        const resolveBudget = typeof budgetUsd === "function" ? budgetUsd : () => budgetUsd;
+        return async (url, reqInit, opts) => {
+            const budget = resolveBudget();
+            if (budget <= 0 || opts?.dryRun)
+                return this.#deps.fetch(url, reqInit);
+            let host;
+            try {
+                host = new URL(url).hostname;
+            }
+            catch {
+                return this.#deps.fetch(url, reqInit);
+            }
+            const baseHost = baseUrl ? safeHostname(baseUrl) : null;
+            if (baseHost && host !== baseHost)
+                return this.#deps.fetch(url, reqInit);
+            return this.payGuardFetch(id, budget, host, url, reqInit);
+        };
+    }
+    async payGuardFetch(id, budgetUsd, host, url, reqInit) {
+        const deps = this.#deps;
+        const resp = await deps.fetch(url, { ...reqInit, redirect: "manual" });
+        if (resp.status !== 402)
+            return resp;
+        const bytes = new Uint8Array(await resp.arrayBuffer());
+        const challenge = parseChallenge(bytes);
+        const { quotes } = quoteWithRejections(challenge);
+        const quote = selectQuote(quotes);
+        const as402 = () => new Response(bytes, { status: 402, headers: resp.headers });
+        if (!quote)
+            return as402();
+        if (this.#cfg.testMode && quote.network === "base")
+            return as402();
+        const pol = this.#cfg.policyProvider();
+        if (!pol.ok)
+            return as402();
+        const caps = this.capsOf(pol.policy);
+        const receiptId = this.newReceiptId();
+        const day = utcDate(deps.now());
+        const reservation = this.#cfg.budget.reserve({
+            holdId: receiptId,
+            amountUsd: quote.amountUsd,
+            host,
+            caps,
+            extra: [{ key: guardDayKey(id, day), cap: budgetUsd, which: `guard:${id}` }],
+        });
+        if (!reservation.ok)
+            return as402();
+        let proof;
+        try {
+            proof = await this.#cfg.payers[0].buildPayment(quote, deps.signer, deps);
+        }
+        catch {
+            this.#cfg.budget.release(receiptId);
+            return as402();
+        }
+        this.#cfg.budget.setHoldValidBefore(receiptId, proof.validBeforeTs);
+        const payerAddress = await deps.signer.address();
+        const method = (reqInit.method ?? "GET").toUpperCase();
+        const userHeaders = stripReservedHeaders(reqInit.headers);
+        const bodyStr = typeof reqInit.body === "string" ? reqInit.body : null;
+        const retry = await deps.fetch(url, {
+            method,
+            headers: { ...userHeaders, ...proof.headers },
+            body: bodyStr ?? undefined,
+            redirect: "manual",
+        });
+        const retryBytes = new Uint8Array(await retry.clone().arrayBuffer());
+        const settlementHeader = readSettlementHeader(retry.headers);
+        const settlement = settlementHeader ? parseSettlementResponse(settlementHeader) : null;
+        const cls = classifyFromParts(retry.status, settlement, quote);
+        if (cls.holdDisposition === "settle") {
+            this.#cfg.budget.settle(receiptId, cls.settledAmountUsd ?? quote.amountUsd);
+        }
+        const budgets = this.#cfg.budget.remaining(caps, host);
+        const receipt = {
+            schema: "p3f.receipt.v1",
+            receiptId,
+            ts: deps.now(),
+            clientVersion: CLIENT_VERSION,
+            policyVersion: POLICY_VERSION,
+            test: this.#cfg.testMode,
+            url,
+            method,
+            host,
+            outcome: cls.outcome,
+            denyCode: null,
+            verdictPath: ["guard_spend"],
+            quote,
+            rejectedQuotes: null,
+            guards: [],
+            approval: null,
+            payment: {
+                payerAddress,
+                nonce: proof.nonce,
+                validBeforeTs: proof.validBeforeTs,
+                settledAmountUsd: cls.holdDisposition === "settle" ? cls.settledAmountUsd ?? quote.amountUsd : null,
+                txRef: cls.txRef,
+                settlementConfirmed: cls.settlementConfirmed,
+            },
+            budgets: {
+                dayRemainingUsd: budgets.dayRemainingUsd,
+                hostRemainingUsd: budgets.hostRemainingUsd,
+                totalRemainingUsd: budgets.totalRemainingUsd,
+            },
+            http: {
+                status: retry.status,
+                contentType: retry.headers.get("content-type"),
+                bodyBytes: retryBytes.length,
+                bodySha256: null,
+                truncated: false,
+                totalMs: 0,
+            },
+            notes: this.#cfg.testMode ? ["test_mode", ...(cls.note ? [cls.note] : [])] : cls.note ? [cls.note] : [],
+        };
+        this.#cfg.ledger.append(receipt);
+        return new Response(retryBytes, { status: retry.status, headers: retry.headers });
+    }
+    detectPayer(challenge) {
+        const p = this.#cfg.payers.find((x) => x.detects(challenge));
+        return p ?? this.#cfg.payers[0];
+    }
+    quoteAndReject(challenge, payer) {
+        if (payer.rail === "x402")
+            return quoteWithRejections(challenge);
+        return { quotes: payer.quotes(challenge), rejected: {} };
+    }
+    httpBlock(t) {
+        return {
+            status: t.status,
+            contentType: t.contentType,
+            bodyBytes: t.bodyBytes,
+            bodySha256: t.bodySha256,
+            truncated: t.hardCapped,
+            totalMs: t.totalMs,
+        };
+    }
+    materialize(t, delivered) {
+        const headers = t.headers ?? new Headers();
+        if (delivered.mode === "file") {
+            return new Response(null, { status: t.status ?? 200, headers });
+        }
+        return new Response(delivered.text, { status: t.status ?? 200, headers });
+    }
+    deny(receiptId, url, init, host, verdictPath, notes, quote, budgets, denyCode, denyNotes, outcome, leg1, rejected, guards, approval) {
+        for (const n of denyNotes)
+            if (!notes.includes(n))
+                notes.push(n);
+        const receipt = this.baseReceipt(receiptId, url, init, host, outcome, verdictPath, notes, quote, budgets, {
+            denyCode,
+            rejectedQuotes: rejected ?? null,
+            guards: guards ?? [],
+            http: this.httpBlock(leg1),
+            approval: approval ?? null,
+        });
+        return this.finish(receipt, null);
+    }
+    denyGuardBlocked(receiptId, url, init, host, verdictPath, notes, quote, budgets, leg1, rejected, guards, reason) {
+        const receipt = this.baseReceipt(receiptId, url, init, host, "guard_blocked", verdictPath, notes, quote, budgets, {
+            denyCode: "guard_blocked",
+            rejectedQuotes: rejected,
+            guards,
+            http: this.httpBlock(leg1),
+            guardBlockReason: reason,
+        });
+        return this.finish(receipt, null);
+    }
+    baseReceipt(receiptId, url, init, host, outcome, verdictPath, notes, quote, budgets, extra = {}) {
+        const method = (init.method ?? "GET").toUpperCase();
+        const finalNotes = [...notes];
+        for (const n of extra.notesExtra ?? [])
+            finalNotes.push(n);
+        return {
+            schema: "p3f.receipt.v1",
+            receiptId,
+            ts: this.#deps.now(),
+            clientVersion: CLIENT_VERSION,
+            policyVersion: POLICY_VERSION,
+            test: this.#cfg.testMode,
+            url,
+            method,
+            host,
+            outcome,
+            denyCode: extra.denyCode ?? null,
+            guardBlockReason: extra.guardBlockReason ?? null,
+            verdictPath: [...verdictPath],
+            quote,
+            rejectedQuotes: extra.rejectedQuotes ?? null,
+            guards: extra.guards ?? [],
+            approval: extra.approval ?? null,
+            payment: extra.payment ?? null,
+            budgets: {
+                dayRemainingUsd: budgets.dayRemainingUsd,
+                hostRemainingUsd: budgets.hostRemainingUsd,
+                totalRemainingUsd: budgets.totalRemainingUsd,
+            },
+            http: extra.http ?? null,
+            notes: finalNotes,
+        };
+    }
+    finish(receipt, response) {
+        this.#cfg.ledger.append(receipt);
+        return { response, receipt };
+    }
+    decisionFromReceipt(r) {
+        const decision = r.outcome === "dry_run" ? "would_pay" : r.outcome === "free" ? "free" : "would_deny";
+        return {
+            outcome: r.outcome,
+            denyCode: r.denyCode,
+            decision,
+            quote: r.quote,
+            rejectedQuotes: r.rejectedQuotes,
+            guards: r.guards,
+            remainingBudgets: {
+                dayRemainingUsd: r.budgets.dayRemainingUsd,
+                hostRemainingUsd: r.budgets.hostRemainingUsd,
+                totalRemainingUsd: r.budgets.totalRemainingUsd,
+            },
+            notes: r.notes,
+        };
+    }
+}
+export function classifyTerminal(retry, quote) {
+    if (!retry.ok) {
+        if (retry.error === "private_target_blocked" || retry.error === "insecure_redirect") {
+            return { outcome: "fetch_error", holdDisposition: "keep", settlementConfirmed: false, settledAmountUsd: null, txRef: null, note: null };
+        }
+        return { outcome: "unknown_settlement", holdDisposition: "keep", settlementConfirmed: false, settledAmountUsd: null, txRef: null, note: null };
+    }
+    const settlement = retry.headers
+        ? parseSettlementFromHeaders(retry.headers)
+        : null;
+    return classifyFromParts(retry.status ?? 0, settlement, quote);
+}
+function readSettlementHeader(headers) {
+    return headers.get(PAYMENT_RESPONSE_HEADER) ?? headers.get(X_PAYMENT_RESPONSE_HEADER);
+}
+function parseSettlementFromHeaders(headers) {
+    const v = readSettlementHeader(headers);
+    if (!v)
+        return null;
+    return parseSettlementResponse(v);
+}
+export function classifyFromParts(status, settlement, _quote) {
+    const confirmed = settlement?.success === true;
+    const txRef = settlement?.transaction ?? null;
+    const is2xx = status >= 200 && status < 300;
+    if (is2xx) {
+        if (confirmed) {
+            return { outcome: "paid_delivered", holdDisposition: "settle", settlementConfirmed: true, settledAmountUsd: null, txRef, note: null };
+        }
+        return { outcome: "paid_delivered", holdDisposition: "settle", settlementConfirmed: false, settledAmountUsd: null, txRef, note: "settlement_unconfirmed" };
+    }
+    if (confirmed) {
+        return { outcome: "paid_not_delivered", holdDisposition: "settle", settlementConfirmed: true, settledAmountUsd: null, txRef, note: null };
+    }
+    if (status >= 500) {
+        return { outcome: "unknown_settlement", holdDisposition: "keep", settlementConfirmed: false, settledAmountUsd: null, txRef: null, note: null };
+    }
+    return { outcome: "payment_rejected", holdDisposition: "keep", settlementConfirmed: false, settledAmountUsd: null, txRef: null, note: null };
+}
+function strikeClassFor(o) {
+    if (o === "paid_not_delivered" || o === "payment_rejected")
+        return "confirmed";
+    if (o === "unknown_settlement")
+        return "soft";
+    return null;
+}
+function isDegradedScreen(res) {
+    return res.verdict === "unavailable" && res.detail?.reason === "degraded_screen";
+}
+function resolveUnavailable(cfg, res) {
+    if (cfg.mode !== "enforce")
+        return "proceed";
+    if (isDegradedScreen(res) && "onDegraded" in cfg)
+        return cfg.onDegraded;
+    return cfg.onUnavailable;
+}
+function guardBlockReasonFor(res) {
+    if (res.verdict === "block")
+        return "danger";
+    const reason = typeof res.detail?.reason === "string" ? res.detail.reason : "";
+    if (reason === "degraded_screen")
+        return "degraded";
+    if (reason === "timeout")
+        return "timeout";
+    return "unavailable";
+}
+function preApprovedNote(policy, host, quote) {
+    const a = policy.approval;
+    if (matchesAnyHost(host, a.preApprovedHosts))
+        return preapproved("host");
+    if (a.preApprovedUpToUsd !== null && microUsd(quote.amountUsd) <= microUsd(a.preApprovedUpToUsd)) {
+        return preapproved("cap");
+    }
+    return null;
+}
+function microUsd(x) {
+    return Number.isFinite(x) ? Math.round(x * 1_000_000) : Number.POSITIVE_INFINITY;
+}
+export function stripReservedHeaders(headers) {
+    const reserved = new Set([
+        X_PAYMENT_HEADER.toLowerCase(),
+        X_PAYMENT_RESPONSE_HEADER.toLowerCase(),
+        INTEGRATION_HEADER.toLowerCase(),
+    ]);
+    const out = {};
+    if (!headers)
+        return out;
+    const h = new Headers(headers);
+    h.forEach((value, key) => {
+        if (!reserved.has(key.toLowerCase()))
+            out[key] = value;
+    });
+    return out;
+}
+function guardUrl(fullUrl) {
+    if (GUARD_SEND_QUERY)
+        return fullUrl;
+    try {
+        const u = new URL(fullUrl);
+        return `${u.origin}${u.pathname}`;
+    }
+    catch {
+        return fullUrl;
+    }
+}
+function assetLabel(asset) {
+    const known = KNOWN_ASSETS.find((a) => a.address.toLowerCase() === asset.toLowerCase());
+    return known?.label ?? asset;
+}
+function safeHostname(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return "";
+    }
+}
+function tallyNotes(rejected) {
+    const out = [];
+    for (const reason of Object.keys(rejected)) {
+        if (reason === "unsupported_scheme_upto")
+            out.push("unsupported_scheme_upto");
+        else if (reason === "unknown_asset")
+            out.push("unknown_asset");
+        else if (reason === "unsupported_network")
+            out.push("unsupported_network");
+    }
+    return out;
+}
+function scrub(s) {
+    return s.replace(/0x[0-9a-fA-F]{40,}/g, "0x<redacted>");
+}