@spendctl/proxy 0.0.0-stage → 0.2.0

package/dist/sidecar.js

@@ -0,0 +1,759 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { hasMppCredential, parseMpp, parseMppReceipt, signMpp, } from "@spendctl/adapter-mpp";
+import { parseX402, parseX402Settlement, signX402, X402_PAYMENT_HEADERS, } from "@spendctl/adapter-x402";
+import { ApprovalBroker, buildTrace, childBaggage, evaluate, FREE_PLAN, formatUsd, hostLabel, isSandbox, monthStartUtc, newId, nextMonthStartUtc, PRICING_URL, planUsage, renderTrace, TIER_LABELS, t, targetFromUrl, toCsv, toExportRow, toJson, traceFromHeaders, WINDOWS, } from "@spendctl/core";
+import { dashboardHtml, reviewHtml } from "./dashboard.js";
+import { sendWebhooks } from "./webhooks.js";
+const HOP_BY_HOP = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-authorization",
+    "proxy-authenticate",
+    "proxy-connection",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+    "host",
+    "content-length",
+]);
+const MAX_BODY_BYTES = 10 * 1024 * 1024;
+function json(body, status = 200, headers = {}) {
+    return new Response(`${JSON.stringify(body, (_, v) => (typeof v === "bigint" ? v.toString() : v), 2)}\n`, {
+        status,
+        headers: { "content-type": "application/json; charset=utf-8", ...headers },
+    });
+}
+function safeEqual(a, b) {
+    const left = Buffer.from(a);
+    const right = Buffer.from(b);
+    return left.length === right.length && timingSafeEqual(left, right);
+}
+function statusForOutcome(decision) {
+    if (decision.outcome === "deny")
+        return "denied";
+    if (decision.outcome === "approve")
+        return "pending_approval";
+    return "reserved";
+}
+/**
+ * The spendctl sidecar. `handle()` is a Fetch-API handler, so the same logic runs
+ * behind node:http (see `listen()`), Bun.serve, or a Workers-style runtime.
+ */
+export class Sidecar {
+    options;
+    broker;
+    circuits = new Map();
+    upstreamFetch;
+    /** `<month>:80` / `<month>:full` once each, so the log says it once. */
+    planWarnings = new Set();
+    constructor(options) {
+        this.options = options;
+        this.upstreamFetch = options.fetch ?? fetch;
+        this.broker = new ApprovalBroker(options.ledger, {
+            timeoutMs: options.config.approvals.timeoutMs,
+            notify: (approval, attempt) => {
+                this.emit({ type: "approval", approval, attempt, message: `approval ${approval.id} requested` });
+                if (options.config.approvals.webhooks.length === 0)
+                    return;
+                return sendWebhooks(options.config.approvals.webhooks, approval, attempt, {
+                    review: this.reviewLink(approval.id),
+                });
+            },
+        });
+    }
+    get config() {
+        return this.options.config;
+    }
+    get ledger() {
+        return this.options.ledger;
+    }
+    get plan() {
+        return this.options.plan ?? FREE_PLAN;
+    }
+    /** This month's governed-event count against the plan (for the CLI, the dashboard and the admin API). */
+    usage(now = Date.now()) {
+        return planUsage(this.plan, this.ledger, { now, sandbox: isSandbox(this.config) });
+    }
+    /**
+     * Free-tier hard stop (docs/PLANS.md): once the month's cap is reached, refuse before policy
+     * evaluation. Runs inside the ledger transaction so two requests cannot both pass as the last one.
+     * Nothing applies under the mock signer, and dry runs are not gated (they never count either).
+     */
+    planGate(now) {
+        const limit = this.plan.limits.eventsPerMonth;
+        if (limit === null || isSandbox(this.config))
+            return undefined;
+        const since = monthStartUtc(now);
+        const used = this.ledger.countGovernedSince(since);
+        this.warnPlan(used, limit, since);
+        if (used < limit)
+            return undefined;
+        const message = t("plan_events_exceeded", {
+            tier: TIER_LABELS[this.plan.tier],
+            limit: limit.toLocaleString("en-US"),
+            used: used.toLocaleString("en-US"),
+            since: new Date(since).toISOString().slice(0, 10),
+            resets: new Date(nextMonthStartUtc(now)).toISOString().slice(0, 10),
+            url: PRICING_URL,
+        });
+        return { outcome: "deny", reasons: [{ code: "plan_events_exceeded", outcome: "deny", message }] };
+    }
+    warnPlan(used, limit, since) {
+        const level = used >= limit ? "full" : used >= Math.ceil(limit * 0.8) ? "80" : undefined;
+        if (!level)
+            return;
+        const key = `${new Date(since).toISOString().slice(0, 7)}:${level}`;
+        if (this.planWarnings.has(key))
+            return;
+        this.planWarnings.add(key);
+        const label = TIER_LABELS[this.plan.tier];
+        this.emit({
+            type: "plan",
+            message: level === "full"
+                ? `${label} plan: ${limit.toLocaleString("en-US")} governed payments used this month; new payments are refused until the month rolls over (${PRICING_URL})`
+                : `${label} plan: ${used.toLocaleString("en-US")} of ${limit.toLocaleString("en-US")} governed payments used this month`,
+        });
+    }
+    emit(event) {
+        try {
+            this.options.onEvent?.(event);
+        }
+        catch {
+            // logging must never break payments
+        }
+    }
+    baseUrl() {
+        return (this.config.approvals.publicUrl ??
+            this.options.baseUrl ??
+            `http://${this.config.server.host}:${this.config.server.port}`).replace(/\/$/, "");
+    }
+    /** One-time-ish review token: HMAC of the approval id under the admin token. */
+    approvalToken(id) {
+        return createHmac("sha256", this.options.adminToken).update(`approval:${id}`).digest("hex").slice(0, 32);
+    }
+    reviewLink(id) {
+        return `${this.baseUrl()}/_spendctl/review/${id}?t=${this.approvalToken(id)}`;
+    }
+    // ---------------------------------------------------------------- routing
+    async handle(request) {
+        const url = new URL(request.url);
+        const explicitTarget = request.headers.get("x-spendctl-target");
+        if (!explicitTarget && url.pathname.startsWith("/_spendctl/"))
+            return this.api(request, url);
+        let target;
+        try {
+            target = new URL(explicitTarget ?? `${url.pathname.slice(1)}${url.search}`);
+            if (target.protocol !== "http:" && target.protocol !== "https:")
+                throw new Error("bad protocol");
+        }
+        catch {
+            return json({
+                error: "spendctl_bad_target",
+                message: "Send requests as http://<sidecar>/<absolute-url>, with an X-Spendctl-Target header, or through HTTP_PROXY.",
+            }, 400);
+        }
+        return this.gateway(request, target);
+    }
+    identifyAgent(request) {
+        let agent = request.headers.get("x-spendctl-agent") ?? undefined;
+        let token = request.headers.get("x-spendctl-token") ?? undefined;
+        const proxyAuth = request.headers.get("proxy-authorization");
+        if (proxyAuth?.toLowerCase().startsWith("basic ")) {
+            const decoded = Buffer.from(proxyAuth.slice(6), "base64").toString("utf8");
+            const sep = decoded.indexOf(":");
+            agent ??= sep === -1 ? decoded : decoded.slice(0, sep);
+            token ??= sep === -1 ? undefined : decoded.slice(sep + 1);
+        }
+        agent ??= this.config.defaultAgent;
+        if (!agent)
+            return { error: "No agent identity: set the X-Spendctl-Agent header or defaultAgent in spendctl.yaml." };
+        if (this.config.agentAuth === "token") {
+            const expected = this.options.agentTokens?.[agent];
+            if (!expected || !token || !safeEqual(expected, token))
+                return { error: `Invalid or missing token for agent "${agent}".` };
+        }
+        return { agent };
+    }
+    isAdmin(request) {
+        const header = request.headers.get("authorization") ?? "";
+        const token = header.toLowerCase().startsWith("bearer ") ? header.slice(7).trim() : "";
+        return token.length > 0 && safeEqual(token, this.options.adminToken);
+    }
+    // ---------------------------------------------------------------- gateway
+    async gateway(request, target) {
+        const identity = this.identifyAgent(request);
+        if (!identity.agent)
+            return json({ error: "spendctl_unauthorized", message: identity.error }, 407);
+        const agent = identity.agent;
+        const suppliedHeader = X402_PAYMENT_HEADERS.find((name) => request.headers.has(name)) ??
+            (hasMppCredential(request.headers) ? "Authorization: Payment" : undefined);
+        if (suppliedHeader) {
+            const reason = {
+                code: "agent_supplied_payment",
+                outcome: "deny",
+                message: t("agent_supplied_payment", { header: suppliedHeader }),
+            };
+            const attempt = this.recordOnly(agent, request.method, target, traceFromHeaders(request.headers), [reason]);
+            return this.refusal(attempt, 403);
+        }
+        let body;
+        if (request.method !== "GET" && request.method !== "HEAD") {
+            body = await request.arrayBuffer();
+            if (body.byteLength > MAX_BODY_BYTES)
+                return json({ error: "spendctl_body_too_large" }, 413);
+        }
+        const trace = traceFromHeaders(request.headers);
+        let first;
+        try {
+            first = await this.forward(request, target, body, {});
+        }
+        catch (error) {
+            return json({ error: "spendctl_upstream_error", message: error.message }, 502);
+        }
+        if (first.status !== 402)
+            return this.passthrough(first);
+        const finalUrl = first.url ? new URL(first.url) : target;
+        const text = await first.text();
+        const sources = [];
+        const options = [];
+        const x402 = parseX402(first.headers, text, this.config.assets);
+        if (x402) {
+            for (const option of x402.options) {
+                if (!this.options.evmSigner && option.signable) {
+                    option.signable = false;
+                    option.unsignableReason = "no EVM signer is configured";
+                }
+                sources.push({ kind: "x402", challenge: x402, local: option.index });
+                options.push({ ...option, index: options.length });
+            }
+        }
+        const providers = this.options.mppProviders ?? [];
+        const mpp = parseMpp(first.headers, providers, this.config.assets);
+        if (mpp) {
+            for (const option of mpp.options) {
+                sources.push({ kind: "mpp", challenge: mpp, local: option.index });
+                options.push({ ...option, index: options.length });
+            }
+        }
+        if (!x402 && !mpp) {
+            // Not a payment protocol we know: hand the 402 back untouched.
+            return this.passthrough(new Response(text, { status: 402, headers: first.headers }));
+        }
+        const challengeResponse = new Response(text, { status: 402, headers: first.headers });
+        return this.pay({ request, agent, target: finalUrl, body, trace, options, sources, challengeResponse });
+    }
+    async pay(ctx) {
+        const { agent, target, trace, options } = ctx;
+        const policy = this.config.agents[agent];
+        // An agent may ask for a dry run of a single request (it can only reduce what happens).
+        const dryRun = this.options.dryRun || policy?.mode === "dry-run" || ctx.request.headers.get("x-spendctl-dry-run") === "1";
+        const tgt = targetFromUrl(target);
+        const host = hostLabel(tgt);
+        const idempotencyKey = ctx.request.headers.get("idempotency-key") ?? undefined;
+        const approvalHeader = ctx.request.headers.get("x-spendctl-approval") ?? undefined;
+        const now = Date.now();
+        const attemptId = newId("pay");
+        let carriedApproval;
+        const decided = this.ledger.transaction(() => {
+            // Re-using a human approval from an earlier, non-held request. Checked under
+            // the lock so that one approval pays for exactly one retry.
+            let waived = new Set();
+            if (approvalHeader) {
+                const approval = this.ledger.getApproval(approvalHeader);
+                if (approval &&
+                    approval.status === "approved" &&
+                    approval.agent === agent &&
+                    approval.host === host &&
+                    approval.path === tgt.path) {
+                    const original = this.ledger.getAttempt(approval.attemptId);
+                    if (original && original.status === "expired" && this.ledger.attemptsForApproval(approval.id) <= 1) {
+                        carriedApproval = approval;
+                        waived = new Set(approval.reasons.map((reason) => reason.code));
+                    }
+                }
+            }
+            let decision = (dryRun ? undefined : this.planGate(now)) ??
+                evaluate({
+                    agentName: agent,
+                    agent: policy,
+                    target: tgt,
+                    options,
+                    trace,
+                    now,
+                    stats: this.ledger,
+                    waived,
+                    circuit: this.circuit(host),
+                });
+            if (decision.outcome !== "deny" && idempotencyKey) {
+                const previous = this.ledger.findByIdempotencyKey(agent, idempotencyKey, now - this.config.idempotencyWindowMs);
+                if (previous && previous.host === host && previous.path === tgt.path) {
+                    decision = {
+                        outcome: "deny",
+                        option: decision.option,
+                        reasons: [
+                            {
+                                code: "duplicate_request",
+                                outcome: "deny",
+                                message: t("duplicate_request", { key: idempotencyKey, attempt: previous.id }),
+                            },
+                        ],
+                    };
+                }
+            }
+            const status = dryRun ? "dry_run" : statusForOutcome(decision);
+            const attempt = this.newAttempt(attemptId, agent, ctx.request.method, tgt, trace, decision, status, idempotencyKey);
+            if (carriedApproval)
+                attempt.approvalId = carriedApproval.id;
+            this.ledger.insertAttempt(attempt);
+            return { decision, attempt };
+        });
+        let { decision, attempt } = decided;
+        this.emit({ type: "decision", attempt, message: `${attempt.id} ${decision.outcome}` });
+        if (dryRun)
+            return this.refusal(attempt, 402, { dryRun: true, wouldBe: decision.outcome });
+        if (decision.outcome === "deny")
+            return this.refusal(attempt, attempt.reasons.some((r) => r.code === "duplicate_request") ? 409 : 402);
+        if (decision.outcome === "approve") {
+            const approval = this.broker.create(attempt, decision.reasons.filter((reason) => reason.outcome === "approve"));
+            this.ledger.updateAttempt(attempt.id, { approvalId: approval.id });
+            attempt.approvalId = approval.id;
+            if (!this.config.approvals.hold) {
+                this.ledger.updateAttempt(attempt.id, { status: "expired" });
+                return this.refusal({ ...attempt, status: "pending_approval" }, 402, {
+                    approval: approval.id,
+                    hint: `Ask a human to run \`spendctl approve ${approval.id}\`, then retry with header X-Spendctl-Approval: ${approval.id}.`,
+                });
+            }
+            // Hold on the wire for at most `holdMax`: HTTP clients give up on a silent response
+            // (Node's fetch after 300 s), and a payment made for a requester that already left is
+            // a payment nobody receives.
+            const result = await this.broker.wait(approval.id, Math.min(this.config.approvals.holdMaxMs, this.config.approvals.timeoutMs), ctx.request.signal);
+            if (ctx.request.signal.aborted || result.status === "pending") {
+                // Same contract as retry mode: this attempt is spent, the approval stays as it is, and
+                // the agent retries with X-Spendctl-Approval once a human has approved.
+                this.ledger.updateAttempt(attempt.id, { status: "expired" });
+                const why = ctx.request.signal.aborted
+                    ? `requester disconnected while waiting; approval ${approval.id} is ${result.status}, nothing paid`
+                    : `still waiting after ${Math.round(this.config.approvals.holdMaxMs / 1000)}s; approval ${approval.id} stays pending`;
+                this.emit({ type: "decision", attempt: { ...attempt, status: "expired" }, message: `${attempt.id} ${why}` });
+                return this.refusal({ ...attempt, status: "pending_approval" }, 402, {
+                    approval: approval.id,
+                    hint: `Ask a human to run \`spendctl approve ${approval.id}\`, then retry with header X-Spendctl-Approval: ${approval.id}.`,
+                });
+            }
+            if (result.status !== "approved") {
+                const code = result.status === "expired" ? "approval_timeout" : "approval_denied";
+                const reason = {
+                    code,
+                    outcome: "deny",
+                    message: t(code, {
+                        timeout: `${Math.round(this.config.approvals.timeoutMs / 1000)}s`,
+                        note: result.note ? ` (${result.note})` : "",
+                    }),
+                };
+                const reasons = [reason, ...attempt.reasons];
+                this.ledger.updateAttempt(attempt.id, { status: "denied", outcome: "deny", reasons });
+                return this.refusal({ ...attempt, status: "denied", outcome: "deny", reasons }, 402);
+            }
+            // Re-check under the lock: other agents may have spent in the meantime.
+            const approvedCodes = new Set(result.reasons.map((reason) => reason.code));
+            const recheck = this.ledger.transaction(() => {
+                const again = evaluate({
+                    agentName: agent,
+                    agent: policy,
+                    target: tgt,
+                    options,
+                    trace,
+                    now: Date.now(),
+                    stats: this.ledger,
+                    waived: approvedCodes,
+                    circuit: this.circuit(host),
+                });
+                const status = again.outcome === "allow" ? "reserved" : "denied";
+                this.ledger.updateAttempt(attempt.id, {
+                    status,
+                    outcome: again.outcome === "allow" ? "approve" : "deny",
+                    reasons: again.reasons.length ? again.reasons : attempt.reasons,
+                });
+                return again;
+            });
+            if (recheck.outcome !== "allow") {
+                const refreshed = this.ledger.getAttempt(attempt.id) ?? attempt;
+                return this.refusal(refreshed, 402);
+            }
+            decision = recheck;
+            attempt = this.ledger.getAttempt(attempt.id) ?? attempt;
+        }
+        return this.signAndSend(ctx, attempt, decision.option);
+    }
+    async signAndSend(ctx, attempt, option) {
+        const source = ctx.sources[option.index];
+        if (!source)
+            throw new Error(`no source for option ${option.index}`);
+        let headers;
+        try {
+            if (source.kind === "x402") {
+                if (!this.options.evmSigner)
+                    throw new Error("no EVM signer configured");
+                const local = source.challenge.options[source.local];
+                const signed = await signX402(source.challenge, local, this.options.evmSigner, { paymentId: attempt.id });
+                headers = signed.headers;
+                if (signed.nonce && this.ledger.nonceUsed(signed.nonce))
+                    throw new Error("nonce collision; refusing to re-use a signature");
+                this.ledger.updateAttempt(attempt.id, { nonce: signed.nonce, payer: signed.payer });
+            }
+            else {
+                const local = source.challenge.options[source.local];
+                headers = (await signMpp(source.challenge, local, this.options.mppProviders ?? [], ctx.challengeResponse.clone())).headers;
+            }
+        }
+        catch (error) {
+            const message = error.message;
+            this.ledger.updateAttempt(attempt.id, { status: "failed", error: `signing failed: ${message}` });
+            this.emit({ type: "error", attempt, message });
+            return json({ error: "spendctl_signing_failed", attempt: attempt.id, message }, 502);
+        }
+        headers.baggage = childBaggage(ctx.request.headers.get("baggage"), ctx.trace, attempt.id);
+        let paid;
+        try {
+            paid = await this.forward(ctx.request, ctx.target, ctx.body, headers);
+        }
+        catch (error) {
+            // The signed payment left this process; we cannot know whether it settled.
+            this.finish(attempt, "unknown", { error: `paid request failed: ${error.message}` });
+            return json({
+                error: "spendctl_upstream_error",
+                attempt: attempt.id,
+                message: `The paid request failed (${error.message}). spendctl will not retry automatically to avoid paying twice.`,
+            }, 502);
+        }
+        if (source.kind === "x402") {
+            const settlement = parseX402Settlement(paid.headers);
+            if (paid.ok) {
+                this.finish(attempt, "settled", {
+                    txHash: settlement?.transaction,
+                    settledAtomic: settlement?.amount,
+                    receipt: settlement?.raw,
+                });
+            }
+            else if (settlement?.pending) {
+                this.finish(attempt, "unknown", {
+                    txHash: settlement.transaction,
+                    error: "settlement_pending",
+                    receipt: settlement.raw,
+                });
+            }
+            else if (paid.status === 402 || (settlement && !settlement.success)) {
+                this.finish(attempt, "failed", {
+                    error: settlement?.errorReason ?? "seller rejected the payment",
+                    receipt: settlement?.raw,
+                });
+            }
+            else {
+                this.finish(attempt, "unknown", { error: `seller answered ${paid.status} after payment` });
+            }
+        }
+        else {
+            const receipt = parseMppReceipt(paid);
+            if (paid.ok)
+                this.finish(attempt, "settled", { txHash: receipt?.reference, receipt: receipt?.raw });
+            else if (paid.status === 402)
+                this.finish(attempt, "failed", { error: "seller rejected the payment" });
+            else
+                this.finish(attempt, "unknown", { error: `seller answered ${paid.status} after payment` });
+        }
+        return this.passthrough(paid, attempt.id);
+    }
+    finish(attempt, status, patch) {
+        this.ledger.updateAttempt(attempt.id, { status, ...patch });
+        const updated = this.ledger.getAttempt(attempt.id) ?? { ...attempt, status, ...patch };
+        const host = attempt.host;
+        if (status === "settled") {
+            this.circuits.delete(host);
+            this.emit({ type: "settled", attempt: updated, message: `${attempt.id} settled` });
+        }
+        else {
+            const state = this.circuits.get(host) ?? { failures: 0, openUntil: 0 };
+            state.failures += 1;
+            if (state.failures >= this.config.circuitBreaker.failures)
+                state.openUntil = Date.now() + this.config.circuitBreaker.cooldownMs;
+            this.circuits.set(host, state);
+            this.emit({ type: "failed", attempt: updated, message: `${attempt.id} ${status}: ${patch.error ?? ""}` });
+        }
+    }
+    circuit(host) {
+        const state = this.circuits.get(host);
+        if (!state)
+            return undefined;
+        if (state.openUntil && state.openUntil <= Date.now()) {
+            // Half-open: allow one more try; a failure re-opens immediately.
+            state.openUntil = 0;
+            state.failures = this.config.circuitBreaker.failures - 1;
+        }
+        return { open: state.openUntil > Date.now(), failures: state.failures, until: state.openUntil };
+    }
+    newAttempt(id, agent, method, target, trace, decision, status, idempotencyKey) {
+        const option = decision.option;
+        const now = Date.now();
+        return {
+            id,
+            createdAt: now,
+            updatedAt: now,
+            agent,
+            method,
+            host: hostLabel(target),
+            path: target.path,
+            status,
+            outcome: decision.outcome,
+            reasons: decision.reasons,
+            protocol: option?.protocol,
+            protocolVersion: option?.protocolVersion,
+            scheme: option?.scheme,
+            network: option?.network,
+            asset: option?.asset,
+            assetSymbol: option?.assetSymbol,
+            decimals: option?.decimals,
+            amountAtomic: option?.amountAtomic,
+            usdMicros: option?.usdMicros,
+            payTo: option?.payTo,
+            idempotencyKey,
+            traceRoot: trace.root,
+            traceParent: trace.parent,
+            depth: trace.depth,
+        };
+    }
+    recordOnly(agent, method, target, trace, reasons) {
+        const attempt = this.newAttempt(newId("pay"), agent, method, targetFromUrl(target), trace, { outcome: "deny", reasons }, "denied");
+        this.ledger.insertAttempt(attempt);
+        this.emit({ type: "decision", attempt, message: `${attempt.id} deny` });
+        return attempt;
+    }
+    refusal(attempt, status, extra = {}) {
+        const primary = attempt.reasons[0];
+        const amount = attempt.usdMicros !== undefined ? formatUsd(attempt.usdMicros) : undefined;
+        const dry = extra.dryRun === true;
+        const message = dry
+            ? `Dry run: spendctl would ${extra.wouldBe === "allow" ? "pay" : extra.wouldBe === "approve" ? "ask a human to approve" : "refuse"} ${amount ?? ""} to ${attempt.host}${attempt.path}.${primary ? ` ${primary.message}` : ""}`
+            : attempt.status === "pending_approval"
+                ? `spendctl needs a human to approve ${amount ?? "this payment"} to ${attempt.host}${attempt.path}: ${primary?.message ?? ""}`
+                : `spendctl refused ${amount ? `to pay ${amount} to` : "a payment to"} ${attempt.host}${attempt.path}: ${primary?.message ?? "denied by policy"}`;
+        return json({
+            error: dry
+                ? "spendctl_dry_run"
+                : attempt.status === "pending_approval"
+                    ? "spendctl_approval_required"
+                    : "spendctl_denied",
+            message,
+            attempt: attempt.id,
+            decision: attempt.outcome,
+            amount,
+            reasons: attempt.reasons.map(({ code, message: text }) => ({ code, message: text })),
+            ...extra,
+        }, status, { "x-spendctl-attempt": attempt.id, "x-spendctl-decision": dry ? "dry-run" : attempt.status });
+    }
+    async forward(request, target, body, extra) {
+        const headers = new Headers();
+        request.headers.forEach((value, key) => {
+            const lower = key.toLowerCase();
+            if (HOP_BY_HOP.has(lower) || lower.startsWith("x-spendctl-"))
+                return;
+            headers.set(key, value);
+        });
+        for (const [key, value] of Object.entries(extra))
+            headers.set(key, value);
+        return this.upstreamFetch(target, {
+            method: request.method,
+            headers,
+            body: body && body.byteLength > 0 ? body : undefined,
+            redirect: "follow",
+            signal: AbortSignal.timeout(this.config.server.upstreamTimeoutMs),
+        });
+    }
+    passthrough(response, attemptId) {
+        const headers = new Headers(response.headers);
+        // fetch already decoded the body; the original framing headers no longer apply.
+        headers.delete("content-encoding");
+        headers.delete("content-length");
+        headers.delete("transfer-encoding");
+        if (attemptId) {
+            headers.set("x-spendctl-attempt", attemptId);
+            const attempt = this.ledger.getAttempt(attemptId);
+            if (attempt) {
+                headers.set("x-spendctl-decision", attempt.status);
+                if (attempt.usdMicros !== undefined)
+                    headers.set("x-spendctl-amount", formatUsd(attempt.usdMicros));
+            }
+        }
+        return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+    }
+    // ---------------------------------------------------------------- API
+    budget(agent) {
+        const policy = this.config.agents[agent];
+        if (!policy)
+            return undefined;
+        const now = Date.now();
+        const windows = Object.keys(WINDOWS)
+            .filter((window) => policy.budget[window] !== undefined)
+            .map((window) => {
+            const limit = policy.budget[window];
+            const spent = this.ledger.spentSince(agent, now - WINDOWS[window]);
+            return {
+                window,
+                limit: formatUsd(limit),
+                spent: formatUsd(spent),
+                remaining: formatUsd(limit > spent ? limit - spent : 0n),
+            };
+        });
+        return {
+            agent,
+            mode: this.options.dryRun ? "dry-run" : policy.mode,
+            perRequest: policy.budget.perRequest !== undefined ? formatUsd(policy.budget.perRequest) : null,
+            requireApprovalAbove: policy.requireApprovalAbove !== undefined ? formatUsd(policy.requireApprovalAbove) : null,
+            onBudgetExceeded: policy.onBudgetExceeded,
+            allow: policy.allow ?? ["*"],
+            windows,
+        };
+    }
+    async api(request, url) {
+        const path = url.pathname.replace(/\/+$/, "");
+        if (path === "/_spendctl/health")
+            return json({ ok: true, version: "0.2.0", plan: this.plan.tier });
+        // Browser review page for approval links (token-bound, POST to act).
+        const review = /^\/_spendctl\/review\/([\w-]+)$/.exec(path);
+        if (review)
+            return this.review(request, url, review[1]);
+        if (path.startsWith("/_spendctl/agent/")) {
+            const identity = this.identifyAgent(request);
+            if (!identity.agent)
+                return json({ error: "spendctl_unauthorized", message: identity.error }, 401);
+            const agent = identity.agent;
+            if (path === "/_spendctl/agent/budget") {
+                const budget = this.budget(agent);
+                return budget ? json(budget) : json({ error: "unknown_agent", message: t("unknown_agent", { agent }) }, 404);
+            }
+            if (path === "/_spendctl/agent/receipts") {
+                const limit = Math.min(Number(url.searchParams.get("limit") ?? 20) || 20, 200);
+                return json({ agent, receipts: this.ledger.listAttempts({ agent, limit }).map(toExportRow) });
+            }
+            const approvalMatch = /^\/_spendctl\/agent\/approvals\/([\w-]+)$/.exec(path);
+            if (approvalMatch) {
+                const approval = this.ledger.getApproval(approvalMatch[1]);
+                if (!approval || approval.agent !== agent)
+                    return json({ error: "not_found" }, 404);
+                return json({
+                    id: approval.id,
+                    status: approval.status,
+                    expiresAt: new Date(approval.expiresAt).toISOString(),
+                });
+            }
+            return json({ error: "not_found" }, 404);
+        }
+        if (path === "/_spendctl/dashboard") {
+            return new Response(dashboardHtml(), {
+                headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
+            });
+        }
+        if (!path.startsWith("/_spendctl/admin/"))
+            return json({ error: "not_found" }, 404);
+        if (!this.isAdmin(request))
+            return json({ error: "spendctl_admin_only", message: "Admin token required." }, 401);
+        if (path === "/_spendctl/admin/pending") {
+            this.broker.expireStale();
+            return json({ pending: this.broker.pending() });
+        }
+        if (path === "/_spendctl/admin/approvals")
+            return json({ approvals: this.ledger.listApprovals(undefined, 200) });
+        const decide = /^\/_spendctl\/admin\/approvals\/([\w-]+)\/(approve|deny)$/.exec(path);
+        if (decide && request.method === "POST") {
+            const body = (await request.json().catch(() => ({})));
+            return this.decideApproval(decide[1], decide[2], body.by ?? "admin-api", body.note);
+        }
+        if (path === "/_spendctl/admin/ledger") {
+            const limit = Math.min(Number(url.searchParams.get("limit") ?? 100) || 100, 10_000);
+            const agent = url.searchParams.get("agent") ?? undefined;
+            return json({ attempts: this.ledger.listAttempts({ agent, limit }).map(toExportRow) });
+        }
+        if (path === "/_spendctl/admin/export") {
+            const format = url.searchParams.get("format") === "json" ? "json" : "csv";
+            const since = url.searchParams.get("since");
+            const attempts = this.ledger.listAttempts({
+                agent: url.searchParams.get("agent") ?? undefined,
+                since: since ? Date.parse(since) : undefined,
+            });
+            const ordered = [...attempts].reverse();
+            return new Response(format === "json" ? toJson(ordered) : toCsv(ordered), {
+                headers: { "content-type": format === "json" ? "application/json" : "text/csv; charset=utf-8" },
+            });
+        }
+        const traceMatch = /^\/_spendctl\/admin\/trace\/([\w-]+)$/.exec(path);
+        if (traceMatch) {
+            const id = traceMatch[1];
+            const attempt = this.ledger.getAttempt(id);
+            if (!attempt)
+                return json({ error: "not_found" }, 404);
+            const root = attempt.traceRoot ?? attempt.id;
+            const tree = buildTrace(root, this.ledger.listAttempts({ traceRoot: root }));
+            return json({ root, text: tree ? renderTrace(tree) : "", nodes: tree });
+        }
+        if (path === "/_spendctl/admin/summary") {
+            return json({
+                agents: Object.keys(this.config.agents).map((name) => this.budget(name)),
+                pending: this.broker.pending().length,
+                recent: this.ledger.listAttempts({ limit: 50 }).map(toExportRow),
+                dryRun: Boolean(this.options.dryRun),
+                plan: this.usage(),
+            });
+        }
+        const resolve = /^\/_spendctl\/admin\/ledger\/([\w-]+)\/resolve$/.exec(path);
+        if (resolve && request.method === "POST") {
+            const body = (await request.json().catch(() => ({})));
+            if (body.status !== "settled" && body.status !== "failed")
+                return json({ error: "status must be settled or failed" }, 400);
+            const attempt = this.ledger.getAttempt(resolve[1]);
+            if (!attempt)
+                return json({ error: "not_found" }, 404);
+            if (attempt.status !== "unknown")
+                return json({ error: `attempt is ${attempt.status}, only unknown attempts can be resolved` }, 409);
+            this.ledger.updateAttempt(attempt.id, { status: body.status, txHash: body.txHash ?? attempt.txHash });
+            return json({ attempt: toExportRow(this.ledger.getAttempt(attempt.id)) });
+        }
+        return json({ error: "not_found" }, 404);
+    }
+    decideApproval(id, action, by, note) {
+        const existing = this.ledger.getApproval(id);
+        if (!existing)
+            return json({ error: "not_found", message: `No approval ${id}` }, 404);
+        if (existing.status !== "pending")
+            return json({ error: "already_decided", approval: existing }, 409);
+        if (existing.expiresAt <= Date.now()) {
+            const expired = this.broker.decide(id, "expired", "timeout");
+            return json({ error: "expired", approval: expired }, 409);
+        }
+        const approval = this.broker.decide(id, action === "approve" ? "approved" : "denied", by, note);
+        return json({ approval });
+    }
+    async review(request, url, id) {
+        const token = url.searchParams.get("t") ?? "";
+        if (!safeEqual(token, this.approvalToken(id)))
+            return json({ error: "invalid_link" }, 403);
+        const approval = this.ledger.getApproval(id);
+        if (!approval)
+            return json({ error: "not_found" }, 404);
+        if (request.method === "POST") {
+            const form = await request.formData().catch(() => undefined);
+            const action = form?.get("action") === "approve" ? "approve" : "deny";
+            const response = this.decideApproval(id, action, "review-link");
+            const decided = this.ledger.getApproval(id) ?? approval;
+            return new Response(reviewHtml(decided, this.ledger.getAttempt(decided.attemptId), url.toString(), response.status !== 200), {
+                status: response.status === 200 ? 200 : 409,
+                headers: { "content-type": "text/html; charset=utf-8" },
+            });
+        }
+        // GET never changes state (chat apps prefetch links).
+        return new Response(reviewHtml(approval, this.ledger.getAttempt(approval.attemptId), url.toString(), false), {
+            headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
+        });
+    }
+}
+//# sourceMappingURL=sidecar.js.map