@aifinpay/agent 2.0.0-rc.7 → 2.0.1

package/dist/aifp1.js

@@ -34,7 +34,10 @@
 // the whole protocol without an RPC endpoint.
 // ──────────────────────────────────────────────────────────────────────────
 import { createHash } from "node:crypto";
+import { keccak256, stringToHex } from "viem";
 import { AiFinPayError } from "./errors.js";
+import { SettlementConfirmationPendingError } from "./settlement.js";
+import { settlementHttp, SettlementHttpError } from "./settlementHttp.js";
 // ── Errors ────────────────────────────────────────────────────────────────
 //
 // Specific classes rather than one message, because the recoveries differ: a
@@ -55,20 +58,72 @@ export class Aifp1SettlementUnsupportedError extends Aifp1Error {
  * Carries the tx hash because that is the only thing standing between the
  * caller and a lost payment: the quote is still settleable through
  * `POST /v1/pay` by hand with the same Idempotency-Key, and without the hash
- * in the error there is nothing to retry with.
+ * in the error there is nothing to retry with. `recovery` additionally preserves
+ * the quote nonce and issuer domain needed to sign a fresh receipt claim.
  */
 export class Aifp1PayError extends Aifp1Error {
     txRef;
     quoteId;
-    constructor(msg, txRef, quoteId) {
+    recovery;
+    constructor(msg, txRef, quoteId, recovery) {
         super(msg);
         this.txRef = txRef;
         this.quoteId = quoteId;
+        this.recovery = recovery;
     }
 }
+/** Recover an already settled Polygon payment. Never sends an on-chain transaction. */
+export function recoverAifp1Payment(recovery, signer, options = {}) {
+    return submitPayment({ ...signer, agentId: signer.payerAddress, fetchImpl: signer.fetchImpl ?? fetch }, recovery.apiBaseUrl, recovery.quote, recovery.txRef, recovery.asset, { paymentIssuer: recovery.paymentIssuer, ...options });
+}
 /** The gateway rejected a receipt we believed covered the request. */
 export class Aifp1ReceiptRejectedError extends Aifp1Error {
 }
+export function describeQuote(q) {
+    const ns = q.native_settlement;
+    const pay = ns ? { amount: formatUnits(ns.total_wei, ns.decimals), asset: ns.asset } : null;
+    // Fee as basis points, from the split the quote already carries. Stated so the
+    // agent sees the rate, not just the total — the same reason the 402 does.
+    let feeBps = null;
+    try {
+        const total = BigInt(q.settlement.gross_units);
+        const merchant = BigInt(q.settlement.merchant_units);
+        if (total > 0n)
+            feeBps = Number(((total - merchant) * 10000n) / total);
+    }
+    catch {
+        /* leave null rather than guess */
+    }
+    const where = q.scope === "merchant"
+        ? `anything on ${q.merchant_id}`
+        : q.scope === "prefix"
+            ? `any path under ${q.resource}`
+            : q.resource;
+    const payPart = pay ? `${pay.amount} ${pay.asset}` : `$${q.amount}`;
+    const headline = `Pay ${payPart} ($${q.amount}) for ${q.requests} request${q.requests === 1 ? "" : "s"} ` +
+        `to ${where}` +
+        (feeBps != null ? ` (incl. ${(feeBps / 100).toFixed(2)}% fee)` : "") +
+        `, valid until ${q.expires_at}.`;
+    return {
+        headline,
+        amount_usd: q.amount,
+        pay,
+        requests: q.requests,
+        unit_quota: q.unit_quota,
+        scope: q.scope,
+        resource: q.resource,
+        expires_at: q.expires_at,
+        fee_bps: feeBps,
+    };
+}
+/** wei/lamports → a decimal string with the asset's own decimals, no float. */
+function formatUnits(raw, decimals) {
+    const n = BigInt(raw);
+    const base = 10n ** BigInt(decimals);
+    const whole = n / base;
+    const frac = (n % base).toString().padStart(decimals, "0").replace(/0+$/, "");
+    return frac ? `${whole}.${frac}` : `${whole}`;
+}
 // ── Scope, ported from the server ─────────────────────────────────────────
 //
 // backend/aifp/scope.js decides whether a receipt covers a request, and this
@@ -96,7 +151,9 @@ export function scopeCovers(scope, resource, path) {
  * and a single-segment path → "/" (the whole site).
  */
 export function prefixHint(path) {
-    const segs = String(path || "/").split("/").filter(Boolean);
+    const segs = String(path || "/")
+        .split("/")
+        .filter(Boolean);
     return segs.length > 1 ? `/${segs[0]}/` : "/";
 }
 /**
@@ -123,16 +180,22 @@ export function prefixHint(path) {
  * treated as "allow all", because that is the shape a config bug takes.
  */
 export const DEFAULT_GATEWAY_ORIGINS = ["https://gateway.aifinpay.io"];
-export function parseGatewayUrl(url, allowedOrigins = DEFAULT_GATEWAY_ORIGINS) {
+export function parseGatewayUrl(url, allowedOrigins = DEFAULT_GATEWAY_ORIGINS, resourcePathMode = "gateway") {
+    if (resourcePathMode !== "gateway" && resourcePathMode !== "direct") {
+        throw new Aifp1Error("resourcePathMode must be 'gateway' or 'direct'");
+    }
     const u = new URL(url);
     if (!allowedOrigins.length) {
-        throw new Aifp1Error("no allowed gateway origins configured — refusing to pay any host. "
-            + "Pass gatewayOrigins explicitly for a self-hosted gateway.");
+        throw new Aifp1Error("no allowed gateway origins configured — refusing to pay any host. " +
+            "Pass gatewayOrigins explicitly for a self-hosted gateway.");
     }
     if (!allowedOrigins.includes(u.origin)) {
-        throw new Aifp1Error(`${u.origin} is not a known AiFinPay gateway (allowed: ${allowedOrigins.join(", ")}). `
-            + "Refusing to settle: a 402 is unauthenticated, so paying an unrecognised host "
-            + "means paying whoever answered.");
+        throw new Aifp1Error(`${u.origin} is not a known AiFinPay gateway (allowed: ${allowedOrigins.join(", ")}). ` +
+            "Refusing to settle: a 402 is unauthenticated, so paying an unrecognised host " +
+            "means paying whoever answered.");
+    }
+    if (resourcePathMode === "direct") {
+        return { site: u.origin, slug: "", restPath: u.pathname };
     }
     const segments = u.pathname.split("/").filter(Boolean);
     if (segments.length === 0) {
@@ -185,9 +248,7 @@ export function jwtExpiryMs(jwt) {
  * A random key would satisfy the header requirement and none of the above.
  */
 export function idempotencyKeyFor(p) {
-    const digest = createHash("sha256")
-        .update(`aifp1|${p.quoteId}|${p.asset}|${p.chain}|${p.txRef}`)
-        .digest("hex");
+    const digest = createHash("sha256").update(`aifp1|${p.quoteId}|${p.asset}|${p.chain}|${p.txRef}`).digest("hex");
     return `aifp1-${digest}`; // 70 chars — well under the server's 200 limit
 }
 /**
@@ -229,10 +290,14 @@ export class Aifp1ReceiptCache {
     async coalesce(site, buy) {
         const running = this.inflight.get(site);
         if (running) {
-            await running.catch(() => { });
+            // The winner may already have paid. Share its failure and recovery
+            // context; swallowing it would let every waiter buy another batch.
+            await running;
             return "retry";
         }
-        const p = buy().finally(() => { this.inflight.delete(site); });
+        const p = buy().finally(() => {
+            this.inflight.delete(site);
+        });
         this.inflight.set(site, p);
         return p;
     }
@@ -254,11 +319,11 @@ export class Aifp1ReceiptCache {
      */
     find(site, restPath, merchantId) {
         const now = Date.now();
-        return this.entries.find((e) => e.site === site
-            && (merchantId === undefined || e.merchantId === merchantId)
-            && e.remaining > 0
-            && e.expiresAt - EXPIRY_MARGIN_MS > now
-            && scopeCovers(e.scope, e.resource, restPath));
+        return this.entries.find((e) => e.site === site &&
+            (merchantId === undefined || e.merchantId === merchantId) &&
+            e.remaining > 0 &&
+            e.expiresAt - EXPIRY_MARGIN_MS > now &&
+            scopeCovers(e.scope, e.resource, restPath));
     }
     put(entry) {
         this.entries.push(entry);
@@ -278,7 +343,16 @@ export class Aifp1ReceiptCache {
         const now = Date.now();
         return this.entries.filter((e) => e.expiresAt > now);
     }
-    get size() { return this.entries.length; }
+    /**
+     * Redacted view for dashboards and MCP tools: everything except the bearer
+     * `jwt` (a credential — only the paying agent holds it). Safe to log.
+     */
+    summary() {
+        return this.list().map(({ jwt: _jwt, ...rest }) => rest);
+    }
+    get size() {
+        return this.entries.length;
+    }
 }
 /** Default batch size: 1000 billing units — the $0.10 floor, and the size the
  *  gateway's own how_to_pay examples suggest (routes/gateway.js). If an
@@ -295,7 +369,7 @@ export class Aifp1ReceiptCache {
  * dollars. Fixing the constant would have fixed today and broken the next
  * re-price, so the count is derived instead.
  */
-const DEFAULT_BATCH_USD = 0.10;
+const DEFAULT_BATCH_USD = 0.1;
 /** Used only when a 402 omits base_unit_price_usd — matches $0.10 at $0.0005. */
 const FALLBACK_UNITS = 200;
 /** Units to buy so the batch is worth about DEFAULT_BATCH_USD. */
@@ -354,13 +428,25 @@ function validateCanonicalQuoteEconomics(quote) {
         const protocol = BigInt(s.protocol_fee_units);
         const creator = BigInt(s.creator_units);
         const expectedProtocol = gross / 100n;
-        if (s.fee_on_top !== false
-            || gross <= 0n
-            || payer !== gross
-            || total !== gross
-            || creator !== 0n
-            || protocol !== expectedProtocol
-            || merchant !== gross - expectedProtocol) {
+        // Older backend clients consume this unfortunately named breakdown. It
+        // cannot be dropped during a rolling upgrade. Only accept it as inclusive
+        // when the explicit semantics and every leg agree with the canonical data.
+        const legacy = s.fee_on_top;
+        const matches = (value, expected) => typeof value === "string" && /^\d+$/.test(value) && BigInt(value) === expected;
+        const inclusiveLegacy = s.settlement_semantics === "gross-inclusive" &&
+            legacy !== null &&
+            typeof legacy === "object" &&
+            !Array.isArray(legacy) &&
+            matches(legacy.provider, merchant) &&
+            matches(legacy.treasury, protocol) &&
+            matches(legacy.creator, creator);
+        if ((s.fee_on_top !== false && !inclusiveLegacy) ||
+            gross <= 0n ||
+            payer !== gross ||
+            total !== gross ||
+            creator !== 0n ||
+            protocol !== expectedProtocol ||
+            merchant !== gross - expectedProtocol) {
             throw new Error("split mismatch");
         }
     }
@@ -371,8 +457,7 @@ function validateCanonicalQuoteEconomics(quote) {
 /** Is this response the AIFP-1 paywall asking for money? */
 function isAifp1Challenge(body) {
     const b = body;
-    return !!b && b.protocol === "AIFP-1" && typeof b.merchant_id === "string"
-        && typeof b.resource === "string";
+    return !!b && b.protocol === "AIFP-1" && typeof b.merchant_id === "string" && typeof b.resource === "string";
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /** Billing units the gateway says are left, or null when it did not say. */
@@ -391,16 +476,22 @@ function quotaRemaining(resp) {
  * already has.
  */
 export async function aifp1Fetch(deps, url, init = {}, opts = {}) {
-    const { site, restPath } = parseGatewayUrl(url, opts.gatewayOrigins ?? DEFAULT_GATEWAY_ORIGINS);
+    if (opts.maxAmountUsd !== undefined && (!Number.isFinite(opts.maxAmountUsd) || opts.maxAmountUsd <= 0)) {
+        throw new Aifp1QuoteError("maxAmountUsd must be a positive finite USD amount");
+    }
+    const direct = opts.resourcePathMode === "direct";
+    let { site, restPath } = parseGatewayUrl(url, opts.gatewayOrigins ?? DEFAULT_GATEWAY_ORIGINS, opts.resourcePathMode);
+    let directMerchant;
     // A paid flow sends the request twice, so the body has to survive being sent
     // twice. A stream cannot, and finding that out after paying would mean money
     // moved for a request that can no longer be made.
-    if (init.body !== undefined && init.body !== null
-        && typeof init.body === "object"
-        && typeof init.body.getReader === "function") {
-        throw new Aifp1Error("aifp1Fetch cannot use a stream body: a paywalled request is sent twice "
-            + "(once to learn the price, once with the receipt) and a stream can only "
-            + "be read once. Pass a string, Buffer, or URLSearchParams.");
+    if (init.body !== undefined &&
+        init.body !== null &&
+        typeof init.body === "object" &&
+        typeof init.body.getReader === "function") {
+        throw new Aifp1Error("aifp1Fetch cannot use a stream body: a paywalled request is sent twice " +
+            "(once to learn the price, once with the receipt) and a stream can only " +
+            "be read once. Pass a string, Buffer, or URLSearchParams.");
     }
     const send = (receiptJwt) => {
         // new Headers() rather than a spread: RequestInit.headers is legally a
@@ -408,6 +499,8 @@ export async function aifp1Fetch(deps, url, init = {}, opts = {}) {
         // silently dropping every header the caller set, including their auth.
         const headers = new Headers(init.headers);
         headers.set("AIFP-Agent-Id", deps.agentId);
+        if (direct)
+            headers.delete("AIFP-Receipt");
         if (receiptJwt)
             headers.set("AIFP-Receipt", receiptJwt);
         return deps.fetchImpl(url, {
@@ -416,13 +509,32 @@ export async function aifp1Fetch(deps, url, init = {}, opts = {}) {
             // The receipt is a bearer token. fetch follows redirects by default and
             // only strips authorization/cookie/host on a cross-origin hop — a custom
             // header rides along, so one 302 from a merchant upstream would hand the
-            // batch to another host. Stop at the redirect and let the caller decide.
-            ...(receiptJwt ? { redirect: "manual" } : {}),
+            // batch to another host. Direct probes also stop here: a redirect must
+            // not turn an untrusted origin's 402 into an authorized purchase.
+            ...(receiptJwt || direct ? { redirect: "manual" } : {}),
         });
     };
     // 1. Spend a batch we already own, if one covers this path.
-    const held = deps.cache.find(site, restPath);
-    const resp = await send(held?.jwt);
+    let held = direct ? undefined : deps.cache.find(site, restPath);
+    let resp = await send(held?.jwt);
+    if (direct && resp.status === 402) {
+        // A direct origin can serve several merchants. Learn this resource's
+        // merchant before attaching a bearer receipt, even for a cached batch.
+        const probe = await resp
+            .clone()
+            .json()
+            .catch(() => null);
+        if (isAifp1Challenge(probe)) {
+            if (probe.resource !== restPath) {
+                throw new Aifp1QuoteError("direct AIFP-1 challenge resource must match the full URL pathname");
+            }
+            directMerchant = probe.merchant_id;
+            site = `direct:${JSON.stringify([site, directMerchant])}`;
+            held = deps.cache.find(site, restPath);
+            if (held)
+                resp = await send(held.jwt);
+        }
+    }
     if (held) {
         // Absent header, not "zero left": the gateway sets AIFP-Quota-Remaining
         // only on a metered paid call, and `Number(null)` is 0 — reading it
@@ -446,12 +558,17 @@ export async function aifp1Fetch(deps, url, init = {}, opts = {}) {
             // away a paid receipt and settles a second one on the next call.
             //
             // The gateway labels its own answers: {"error":"AIFP-403", ...}.
-            const detail = await resp.clone().text().catch(() => "");
+            const detail = await resp
+                .clone()
+                .text()
+                .catch(() => "");
             let ours = false;
             try {
                 ours = JSON.parse(detail)?.error === "AIFP-403";
             }
-            catch { /* upstream body, not ours */ }
+            catch {
+                /* upstream body, not ours */
+            }
             if (!ours)
                 return resp; // the merchant's 403, receipt intact
             deps.cache.evict(held);
@@ -461,9 +578,15 @@ export async function aifp1Fetch(deps, url, init = {}, opts = {}) {
     }
     // 402 — but only AIFP-1 is ours. x402 and anything else passes through
     // untouched; call() owns those flows.
-    const challenge = await resp.clone().json().catch(() => null);
+    const challenge = await resp
+        .clone()
+        .json()
+        .catch(() => null);
     if (!isAifp1Challenge(challenge))
         return resp;
+    if (direct && (challenge.merchant_id !== directMerchant || challenge.resource !== restPath)) {
+        throw new Aifp1QuoteError("direct AIFP-1 resource or merchant changed during receipt verification");
+    }
     // The batch we were spending is spent (or expired) — the gateway just said
     // so. Forget it before quoting the next one, or find() would keep handing
     // back a receipt that cannot pay for anything.
@@ -478,16 +601,27 @@ export async function aifp1Fetch(deps, url, init = {}, opts = {}) {
     // spend it, and if it does not they buy their own, which is a different
     // batch rather than a duplicate.
     const buyBatch = async () => {
+        if (typeof deps.signPaymentAuthorization !== "function" || !/^0x[0-9a-fA-F]{40}$/.test(deps.payerAddress || "")) {
+            throw new Aifp1QuoteError("a settlement wallet signer is required to receive a payment receipt");
+        }
         // 2. Quote.
         const apiBase = (opts.apiBaseUrl ?? DEFAULT_API_BASE).replace(/\/$/, "");
         const { scope, resource } = resolveScope(opts, challenge);
         const quote = await requestQuote(deps, apiBase, {
             merchant_id: challenge.merchant_id,
+            payer: deps.payerAddress,
             ...(resource !== undefined ? { resource } : {}),
             scope,
             units: opts.units ?? defaultUnitsFor(challenge),
             agent_id: deps.agentId,
-        });
+        }, opts.apiTimeoutMs);
+        if (quote.payer && quote.payer.toLowerCase() !== deps.payerAddress.toLowerCase()) {
+            throw new Aifp1QuoteError("quote names a different paying wallet");
+        }
+        if (quote.payment_authorization && quote.payment_authorization.scheme !== "wallet-signature-v1") {
+            throw new Aifp1QuoteError("unsupported receipt authorization scheme");
+        }
+        trustedPaymentIssuer(quote, opts.paymentIssuer);
         // The merchant we are about to pay must be the merchant that refused us.
         // Cheap, and the failure it catches is the one worth catching.
         if (quote.merchant_id !== challenge.merchant_id) {
@@ -500,10 +634,59 @@ export async function aifp1Fetch(deps, url, init = {}, opts = {}) {
         }
         // 3. Budget. The quote states the batch total in USD, so both caps are
         // checked against the real figure, before anything is signed.
-        const amountUsd = Number(quote.amount);
+        let amountUsd = Number(quote.amount);
         if (!Number.isFinite(amountUsd) || amountUsd < 0) {
             throw new Aifp1QuoteError(`quote ${quote.quote_id} has an unusable amount "${quote.amount}"`);
         }
+        if (opts.settlementPin) {
+            const price = opts.nativeUsdPrice;
+            const age = price ? Date.now() - price.observedAtMs : NaN;
+            if (!price ||
+                !Number.isFinite(price.usd) ||
+                price.usd <= 0 ||
+                !Number.isFinite(age) ||
+                age < -5_000 ||
+                age > 60_000) {
+                throw new Aifp1QuoteError("a fresh independent nativeUsdPrice is required before native payment; quote-provided FX is not trusted");
+            }
+            const native = quote.native_settlement;
+            if (!native || !/^[0-9]{1,78}$/.test(native.total_wei)) {
+                throw new Aifp1QuoteError("quote has no valid native debit to check against the independent price");
+            }
+            const debitUsd = (Number(BigInt(native.total_wei)) / 1e18) * price.usd;
+            if (!Number.isFinite(debitUsd) ||
+                debitUsd <= 0 ||
+                Math.abs(debitUsd - amountUsd) > Math.max(0.02 * amountUsd, 1e-6)) {
+                throw new Aifp1QuoteError("native debit disagrees with the independent USD price");
+            }
+            // Reserve and charge the larger amount, so rounding/FX tolerance cannot
+            // turn into a cumulative bypass of the user's daily USD budget.
+            amountUsd = Math.max(amountUsd, debitUsd);
+            const call = quote.settlement_call;
+            const args = call?.args;
+            if (native.asset !== "POL" || native.decimals !== 18 || !quote.accepted_assets.includes("POL")) {
+                throw new Aifp1QuoteError("native receipt settlement requires accepted POL with 18 decimals");
+            }
+            if (!call ||
+                call.chain !== "polygon" ||
+                call.splitter_version !== "1.3" ||
+                call.contract?.toLowerCase() !== opts.settlementPin.splitter.toLowerCase() ||
+                call.asset !== "POL" ||
+                call.function !== "payNative((bytes32,address,uint256,address,uint256,string))" ||
+                call.arg_encoding !== "tuple" ||
+                call.value_wei !== native.total_wei ||
+                args?.payment_id?.toLowerCase() !== keccak256(stringToHex(quote.quote_id)).toLowerCase() ||
+                args?.merchant?.toLowerCase() !== quote.pay_to.polygon?.toLowerCase() ||
+                args?.gross_amount !== native.total_wei ||
+                args?.order_id !== quote.quote_id ||
+                args?.valid_until !== Math.floor(quoteExpiryMs / 1000) ||
+                args?.ip_creator?.toLowerCase() !== "0x0000000000000000000000000000000000000000") {
+                throw new Aifp1QuoteError("quote settlement_call does not match the reviewed v1.3 payment; refusing a payment the receipt verifier cannot accept");
+            }
+        }
+        if (opts.maxAmountUsd !== undefined && amountUsd > opts.maxAmountUsd) {
+            throw new Aifp1QuoteError(`quote ${quote.quote_id} costs $${amountUsd}, above maxAmountUsd $${opts.maxAmountUsd}`);
+        }
         if (!deps.checkPerCall(amountUsd))
             return null;
         const reservation = await deps.reserveDaily(amountUsd);
@@ -514,13 +697,13 @@ export async function aifp1Fetch(deps, url, init = {}, opts = {}) {
             // 4. Settle on-chain, then exchange the tx for a receipt.
             const native = quote.native_settlement;
             if (!native) {
-                throw new Aifp1SettlementUnsupportedError(`quote ${quote.quote_id} carries no native_settlement — the backend had no live POL rate, `
-                    + `and the deployed B2BSplitter has no ERC-20 entrypoint, so this SDK cannot settle `
-                    + `${quote.accepted_assets.join("/")}. Retry when a POL rate is available or settle the quote yourself.`);
+                throw new Aifp1SettlementUnsupportedError(`quote ${quote.quote_id} carries no native_settlement — the backend had no live POL rate, ` +
+                    `and the deployed B2BSplitter has no ERC-20 entrypoint, so this SDK cannot settle ` +
+                    `${quote.accepted_assets.join("/")}. Retry when a POL rate is available or settle the quote yourself.`);
             }
             if (!quote.accepted_chains.includes("polygon") || !quote.pay_to.polygon) {
-                throw new Aifp1SettlementUnsupportedError(`quote ${quote.quote_id} does not accept polygon (accepts ${quote.accepted_chains.join(", ")}) — `
-                    + `AIFP-1 settlement verification is Polygon-only server-side (aifp/verify-settlement.js)`);
+                throw new Aifp1SettlementUnsupportedError(`quote ${quote.quote_id} does not accept polygon (accepts ${quote.accepted_chains.join(", ")}) — ` +
+                    `AIFP-1 settlement verification is Polygon-only server-side (aifp/verify-settlement.js)`);
             }
             // The caps above were checked in USD; the wallet is about to be debited in
             // wei. Nothing tied the two together, so a quote could pass a $0.10 cap and
@@ -533,60 +716,88 @@ export async function aifp1Fetch(deps, url, init = {}, opts = {}) {
             // numbers must agree, and if they do not, the safe reading is not "trust
             // the USD" — it is that this quote is not what it says it is.
             const quotedRate = Number(native.rate_usd);
-            const weiUsd = Number.isFinite(quotedRate) && quotedRate > 0
-                ? (Number(BigInt(native.total_wei)) / 1e18) * quotedRate
-                : NaN;
+            const weiUsd = Number.isFinite(quotedRate) && quotedRate > 0 ? (Number(BigInt(native.total_wei)) / 1e18) * quotedRate : NaN;
             if (!Number.isFinite(weiUsd)) {
-                throw new Aifp1QuoteError(`quote ${quote.quote_id} states total_wei ${native.total_wei} at rate "${native.rate_usd}" — `
-                    + `unusable, and the caps were checked against $${amountUsd}`);
+                throw new Aifp1QuoteError(`quote ${quote.quote_id} states total_wei ${native.total_wei} at rate "${native.rate_usd}" — ` +
+                    `unusable, and the caps were checked against $${amountUsd}`);
             }
             // 2% covers native conversion rounding and a
             // rate printed to six places; anything wider is a disagreement, not drift.
             if (Math.abs(weiUsd - amountUsd) > Math.max(0.02 * amountUsd, 1e-6)) {
-                throw new Aifp1QuoteError(`quote ${quote.quote_id} would debit ${native.total_wei} wei ≈ $${weiUsd.toFixed(6)} `
-                    + `but states $${amountUsd} — refusing to sign a payment the budget caps did not see`);
+                throw new Aifp1QuoteError(`quote ${quote.quote_id} would debit ${native.total_wei} wei ≈ $${weiUsd.toFixed(6)} ` +
+                    `but states $${amountUsd} — refusing to sign a payment the budget caps did not see`);
             }
             const nativeGross = BigInt(native.gross_wei ?? native.total_wei);
             const nativeMerchant = BigInt(native.merchant_wei);
             const nativeTreasury = BigInt(native.treasury_wei);
             const nativeCreator = BigInt(native.creator_wei);
-            if (native.settlement_semantics !== "gross-inclusive"
-                || BigInt(native.payer_total_wei ?? native.total_wei) !== nativeGross
-                || BigInt(native.total_wei) !== nativeGross
-                || nativeCreator !== 0n
-                || nativeTreasury !== nativeGross / 100n
-                || nativeMerchant !== nativeGross - nativeTreasury) {
+            if (native.settlement_semantics !== "gross-inclusive" ||
+                BigInt(native.payer_total_wei ?? native.total_wei) !== nativeGross ||
+                BigInt(native.total_wei) !== nativeGross ||
+                nativeCreator !== 0n ||
+                nativeTreasury !== nativeGross / 100n ||
+                nativeMerchant !== nativeGross - nativeTreasury) {
                 throw new Aifp1QuoteError(`quote ${quote.quote_id} native settlement does not match canonical AIFP-1 gross split`);
             }
             const validUntil = BigInt(native.valid_until ?? Math.floor(quoteExpiryMs / 1000));
             if (validUntil !== BigInt(Math.floor(quoteExpiryMs / 1000))) {
                 throw new Aifp1QuoteError(`quote ${quote.quote_id} valid_until does not match expires_at`);
             }
-            const txRef = await deps.settle({
-                merchantWallet: quote.pay_to.polygon,
-                grossWei: nativeGross,
-                merchantWei: nativeMerchant,
-                treasuryWei: nativeTreasury,
-                creatorWei: nativeCreator,
-                validUntil,
-                // The binding the server verifies on-chain: the Payment event's orderId
-                // must equal the quote id, or /v1/pay answers order_id_mismatch.
-                orderId: quote.quote_id,
-            });
+            let txRef;
+            try {
+                txRef = await deps.settle({
+                    merchantWallet: quote.pay_to.polygon,
+                    grossWei: nativeGross,
+                    merchantWei: nativeMerchant,
+                    treasuryWei: nativeTreasury,
+                    creatorWei: nativeCreator,
+                    validUntil,
+                    // The binding the server verifies on-chain: the Payment event's orderId
+                    // must equal the quote id, or /v1/pay answers order_id_mismatch.
+                    orderId: quote.quote_id,
+                });
+            }
+            catch (error) {
+                if (error instanceof SettlementConfirmationPendingError && error.stage === "settlement") {
+                    // Treat unknown confirmation as spent until reconciliation. Releasing
+                    // the reservation here would let a retry spend the same budget again.
+                    settled = true;
+                    const recovery = {
+                        apiBaseUrl: apiBase,
+                        quote,
+                        txRef: error.txHash,
+                        asset: native.asset,
+                        paymentIssuer: opts.paymentIssuer,
+                    };
+                    try {
+                        if (typeof reservation === "string")
+                            await deps.commit(reservation, amountUsd);
+                    }
+                    catch {
+                        throw new Aifp1PayError("payment broadcast; confirmation and budget reconciliation required", error.txHash, quote.quote_id, recovery);
+                    }
+                    throw new Aifp1PayError("payment broadcast; recover its confirmation and receipt without paying again", error.txHash, quote.quote_id, recovery);
+                }
+                throw error;
+            }
             // Money has moved. The reservation becomes settled spend here and not one
             // line later — everything below can still fail, and none of those failures
             // give the funds back.
             settled = true;
-            if (typeof reservation === "string")
-                await deps.commit(reservation, amountUsd);
-            const paid = await submitPayment(deps, apiBase, quote, txRef, native.asset, opts);
-            // 5. Retry the original request with the receipt.
-            const receiptResp = await send(paid.receipt);
-            if (receiptResp.status === 402) {
-                const body = await receiptResp.clone().text().catch(() => "");
-                throw new Aifp1ReceiptRejectedError(`gateway still answered 402 for ${restPath} with a freshly settled receipt `
-                    + `${paid.receipt_id} (tx ${txRef}): ${body.slice(0, 300)}`);
+            try {
+                if (typeof reservation === "string")
+                    await deps.commit(reservation, amountUsd);
+            }
+            catch {
+                throw new Aifp1PayError("payment settled; budget reconciliation and receipt recovery required", txRef, quote.quote_id, {
+                    apiBaseUrl: apiBase,
+                    quote,
+                    txRef,
+                    asset: native.asset,
+                    paymentIssuer: opts.paymentIssuer,
+                });
             }
+            const paid = await submitPayment(deps, apiBase, quote, txRef, native.asset, opts);
             // 6. Keep the batch. This is the whole point of the design: the next call
             // this receipt covers costs a header, not a transaction.
             const entry = {
@@ -601,13 +812,6 @@ export async function aifp1Fetch(deps, url, init = {}, opts = {}) {
                 expiresAt: Date.parse(paid.expires_at),
                 amountUsd,
             };
-            // The gateway's own count if it gave one; otherwise the batch minus the
-            // weight of the route that refused us, which is the only figure we can
-            // justify locally.
-            const remaining = quotaRemaining(receiptResp);
-            entry.remaining = remaining !== null
-                ? remaining
-                : Math.max(0, paid.unit_quota - challenge.unit_weight);
             // Cache unconditionally. This used to be guarded on a finite expiresAt,
             // which meant an unparseable expires_at silently binned a batch that had
             // just been settled on-chain — money spent, JWT existing nowhere else,
@@ -623,9 +827,35 @@ export async function aifp1Fetch(deps, url, init = {}, opts = {}) {
                 // and answers 402 the moment the receipt really is spent or stale.
                 entry.expiresAt = jwtExpiryMs(paid.receipt) ?? Number.POSITIVE_INFINITY;
             }
+            // Store the purchased access BEFORE contacting the merchant again. A
+            // transport failure here must not discard a paid batch and buy it twice.
             deps.cache.put(entry);
+            let receiptResp;
+            try {
+                receiptResp = await send(paid.receipt);
+            }
+            catch {
+                throw new Aifp1PayError("payment settled and receipt cached; content request failed, retry without paying again", txRef, quote.quote_id, {
+                    apiBaseUrl: apiBase,
+                    quote,
+                    txRef,
+                    asset: native.asset,
+                    paymentIssuer: opts.paymentIssuer,
+                });
+            }
+            if (receiptResp.status === 402) {
+                throw new Aifp1ReceiptRejectedError(`gateway still answered 402 for ${restPath} with settled receipt ${paid.receipt_id} (tx ${txRef}); recover the existing payment`);
+            }
+            // The gateway's own count if it gave one; otherwise the batch minus the
+            // weight of the route that refused us, which is the only figure we can
+            // justify locally.
+            const remaining = quotaRemaining(receiptResp);
+            entry.remaining = remaining !== null ? remaining : Math.max(0, paid.unit_quota - challenge.unit_weight);
             deps.onPaid?.({
-                merchantId: paid.merchant_id, amountUsd, txRef, receiptId: paid.receipt_id,
+                merchantId: paid.merchant_id,
+                amountUsd,
+                txRef,
+                receiptId: paid.receipt_id,
             });
             return receiptResp;
         }
@@ -645,19 +875,19 @@ export async function aifp1Fetch(deps, url, init = {}, opts = {}) {
     return buyBatch();
 }
 // ── /v1/quote ─────────────────────────────────────────────────────────────
-async function requestQuote(deps, apiBase, body) {
+async function requestQuote(deps, apiBase, body, timeoutMs) {
     let r;
+    let text;
     try {
-        r = await deps.fetchImpl(`${apiBase}/v1/quote`, {
+        ({ response: r, text } = await settlementHttp(deps.fetchImpl, `${apiBase}/v1/quote`, {
             method: "POST",
             headers: { "content-type": "application/json", "AIFP-Agent-Id": deps.agentId },
             body: JSON.stringify(body),
-        });
+        }, timeoutMs));
     }
     catch (e) {
         throw new Aifp1QuoteError(`POST ${apiBase}/v1/quote failed: ${e.message}`);
     }
-    const text = await r.text();
     if (!r.ok) {
         // The server's own detail is the useful part — a scope refused for a
         // non-flat-rated tier, a batch under the minimum, an owner policy — and
@@ -691,11 +921,43 @@ async function submitPayment(deps, apiBase, quote, txRef, asset, opts) {
     const chain = "polygon";
     const idempotencyKey = idempotencyKeyFor({ quoteId: quote.quote_id, chain, asset, txRef });
     const deadline = Date.now() + (opts.settlementConfirmMs ?? DEFAULT_SETTLEMENT_CONFIRM_MS);
+    const recovery = {
+        apiBaseUrl: apiBase,
+        quote,
+        txRef,
+        asset,
+        paymentIssuer: opts.paymentIssuer,
+    };
+    const failure = (message) => new Aifp1PayError(message, txRef, quote.quote_id, recovery);
     let lastDetail = "";
     for (let attempt = 0;; attempt++) {
+        if (attempt > 0 && Date.now() >= deadline)
+            throw failure("payment confirmation deadline elapsed; recover the existing transaction");
+        const expiresAt = Math.floor(Date.now() / 1000) + 240;
+        const payer = deps.payerAddress.toLowerCase();
+        // Construct this locally; never sign an arbitrary server-provided message.
+        const message = paymentAuthorizationMessage({
+            quote,
+            apiBase,
+            chain,
+            txRef,
+            asset,
+            idempotencyKey,
+            payer,
+            expiresAt,
+            issuer: opts.paymentIssuer,
+        });
+        let signature;
+        try {
+            signature = await deps.signPaymentAuthorization(message);
+        }
+        catch (e) {
+            throw failure(`payment already settled; wallet could not sign receipt authorization: ${e.message}`);
+        }
         let r;
+        let text;
         try {
-            r = await deps.fetchImpl(`${apiBase}/v1/pay`, {
+            ({ response: r, text } = await settlementHttp(deps.fetchImpl, `${apiBase}/v1/pay`, {
                 method: "POST",
                 headers: {
                     "content-type": "application/json",
@@ -703,28 +965,65 @@ async function submitPayment(deps, apiBase, quote, txRef, asset, opts) {
                     "AIFP-Agent-Id": deps.agentId,
                 },
                 body: JSON.stringify({
-                    quote_id: quote.quote_id, chain, asset, tx_ref: txRef, agent_id: deps.agentId,
+                    quote_id: quote.quote_id,
+                    chain,
+                    asset,
+                    tx_ref: txRef,
+                    agent_id: deps.agentId,
+                    payment_authorization: { payer, expires_at: expiresAt, signature },
                 }),
-            });
+            }, Math.max(1, Math.min(opts.apiTimeoutMs ?? 15_000, deadline - Date.now()))));
         }
         catch (e) {
-            throw new Aifp1PayError(`POST ${apiBase}/v1/pay failed after settling: ${e.message}`, txRef, quote.quote_id);
+            if (Date.now() >= deadline || (e instanceof SettlementHttpError && e.code !== "request_timeout")) {
+                throw failure(`POST ${apiBase}/v1/pay failed after settling: ${e.message}`);
+            }
+            await sleep(Math.min(1000 * 2 ** attempt, 8000, Math.max(0, deadline - Date.now())));
+            continue;
         }
-        const text = await r.text();
         if (r.ok) {
-            const paid = JSON.parse(text);
+            let paid;
+            try {
+                paid = JSON.parse(text);
+            }
+            catch {
+                throw failure(`/v1/pay returned invalid JSON after settlement`);
+            }
             if (!paid.receipt) {
-                throw new Aifp1PayError(`/v1/pay → 200 without a receipt: ${text.slice(0, 300)}`, txRef, quote.quote_id);
+                throw failure(`/v1/pay → 200 without a receipt: ${text.slice(0, 300)}`);
             }
             return paid;
         }
         lastDetail = text.slice(0, 400);
-        // 425 is the only status worth retrying: the chain has not caught up with
-        // us yet. Everything else is a verdict.
-        if (r.status !== 425 || Date.now() >= deadline) {
-            throw new Aifp1PayError(`POST /v1/pay → ${r.status} after on-chain settlement ${txRef} for quote ${quote.quote_id}: ${lastDetail}`, txRef, quote.quote_id);
+        // A 503 after settlement may mean accounting is unavailable, or that a
+        // committed response was lost. Retry issuance, never the transfer.
+        if (![425, 503].includes(r.status) || Date.now() >= deadline) {
+            throw failure(`POST /v1/pay → ${r.status} after on-chain settlement ${txRef} for quote ${quote.quote_id}: ${lastDetail}`);
         }
-        await sleep(Math.min(1000 * 2 ** attempt, 8000));
+        await sleep(Math.min(1000 * 2 ** attempt, 8000, Math.max(0, deadline - Date.now())));
+    }
+}
+/** Fixed, domain-separated receipt claim; sign with the wallet that settled. */
+export function paymentAuthorizationMessage(p) {
+    return JSON.stringify([
+        "AiFinPay receipt authorization v1",
+        trustedPaymentIssuer(p.quote, p.issuer),
+        p.quote.quote_id,
+        p.quote.nonce,
+        p.quote.merchant_id,
+        p.quote.network_mode || "live",
+        p.chain,
+        p.txRef,
+        p.asset || "",
+        p.idempotencyKey,
+        p.payer,
+        p.expiresAt,
+    ]);
+}
+function trustedPaymentIssuer(quote, configured = "https://api.aifinpay.io") {
+    if (quote.payment_authorization?.domain && quote.payment_authorization.domain !== configured) {
+        throw new Aifp1QuoteError("receipt authorization domain does not match the trusted paymentIssuer");
     }
+    return configured;
 }
 //# sourceMappingURL=aifp1.js.map