@aifinpay/agent 1.8.4 → 2.0.0-rc.13

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,70 @@ 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
@@ -123,7 +176,10 @@ 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. "
@@ -134,6 +190,9 @@ export function parseGatewayUrl(url, allowedOrigins = DEFAULT_GATEWAY_ORIGINS) {
             + "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) {
         throw new Aifp1Error(`${url} has no merchant slug — a gateway URL looks like https://gateway.aifinpay.io/{slug}/path`);
@@ -229,7 +288,9 @@ 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); });
@@ -344,6 +405,40 @@ function resolveScope(opts, challenge) {
         resource: scope === "prefix" ? prefixHint(challenge.resource) : challenge.resource,
     };
 }
+function validateCanonicalQuoteEconomics(quote) {
+    try {
+        const s = quote.settlement;
+        const gross = BigInt(s.gross_units);
+        const payer = BigInt(s.payer_total_units);
+        const total = BigInt(s.total_units);
+        const merchant = BigInt(s.merchant_units);
+        const protocol = BigInt(s.protocol_fee_units);
+        const creator = BigInt(s.creator_units);
+        const expectedProtocol = gross / 100n;
+        // 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");
+        }
+    }
+    catch {
+        throw new Aifp1QuoteError(`quote ${quote.quote_id} does not implement canonical AIFP-1 gross economics (payer 100%, merchant 99%, protocol 1%, creator 0%)`);
+    }
+}
 /** Is this response the AIFP-1 paywall asking for money? */
 function isAifp1Challenge(body) {
     const b = body;
@@ -367,7 +462,13 @@ 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.
@@ -384,6 +485,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, {
@@ -392,13 +495,29 @@ 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
@@ -440,6 +559,9 @@ export async function aifp1Fetch(deps, url, init = {}, opts = {}) {
     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.
@@ -454,27 +576,80 @@ 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) {
             throw new Aifp1QuoteError(`quote ${quote.quote_id} is for merchant ${quote.merchant_id} but ${site} refused as ${challenge.merchant_id} — refusing to pay`);
         }
+        validateCanonicalQuoteEconomics(quote);
+        const quoteExpiryMs = Date.parse(quote.expires_at);
+        if (!Number.isFinite(quoteExpiryMs) || quoteExpiryMs <= Date.now()) {
+            throw new Aifp1QuoteError(`quote ${quote.quote_id} is expired or has invalid expires_at`);
+        }
         // 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);
@@ -511,33 +686,71 @@ export async function aifp1Fetch(deps, url, init = {}, opts = {}) {
                 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 the fee-inclusive rounding the splitter does on each leg and a
+            // 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`);
             }
-            const txRef = await deps.settle({
-                merchantWallet: quote.pay_to.polygon,
-                totalWei: BigInt(native.total_wei),
-                // 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,
-            });
+            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) {
+                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`);
+            }
+            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 = {
@@ -552,13 +765,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,
@@ -574,7 +780,26 @@ 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,
             });
@@ -596,19 +821,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
@@ -642,11 +867,28 @@ 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",
@@ -655,27 +897,52 @@ async function submitPayment(deps, apiBase, quote, txRef, asset, opts) {
                 },
                 body: JSON.stringify({
                     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