@absol-labs/agent 0.10.0 → 0.12.0-rc.1

package/dist/x402-buyer/guarded-fetch.js

@@ -0,0 +1,147 @@
+import { lookup as dnsLookup } from "node:dns/promises";
+import { isIP } from "node:net";
+/** A request the guard refused; nothing was sent. */
+export class OutboundRequestRefusedError extends Error {
+    constructor(reason) {
+        super(`outbound request refused: ${reason}`);
+        this.name = "OutboundRequestRefusedError";
+    }
+}
+const defaultLookup = async (hostname) => await dnsLookup(hostname, { all: true, verbatim: true });
+function ipv4ToInt(address) {
+    return address.split(".").reduce((acc, part) => acc * 256 + Number(part), 0);
+}
+const BLOCKED_V4 = [
+    ["0.0.0.0", 8],
+    ["10.0.0.0", 8],
+    ["100.64.0.0", 10],
+    ["127.0.0.0", 8],
+    ["169.254.0.0", 16],
+    ["172.16.0.0", 12],
+    ["192.0.0.0", 24],
+    ["192.0.2.0", 24],
+    ["192.168.0.0", 16],
+    ["198.18.0.0", 15],
+    ["198.51.100.0", 24],
+    ["203.0.113.0", 24],
+    ["224.0.0.0", 4],
+    ["240.0.0.0", 4],
+];
+function blockedV4(address) {
+    const value = ipv4ToInt(address);
+    return BLOCKED_V4.some(([base, bits]) => {
+        const mask = bits === 0 ? 0 : (~0 << (32 - bits)) >>> 0;
+        return (value & mask) >>> 0 === (ipv4ToInt(base) & mask) >>> 0;
+    });
+}
+function blockedV6(raw) {
+    const address = raw.toLowerCase().replace(/^\[|\]$/g, "");
+    if (address === "::" || address === "::1")
+        return true;
+    // IPv4-mapped / -compatible: judge the embedded IPv4 address.
+    const mapped = /^(?:::ffff:|::)(\d+\.\d+\.\d+\.\d+)$/.exec(address);
+    if (mapped?.[1] !== undefined)
+        return blockedV4(mapped[1]);
+    const hexMapped = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(address);
+    if (hexMapped?.[1] !== undefined && hexMapped[2] !== undefined) {
+        const hi = parseInt(hexMapped[1], 16);
+        const lo = parseInt(hexMapped[2], 16);
+        return blockedV4(`${hi >> 8}.${hi & 255}.${lo >> 8}.${lo & 255}`);
+    }
+    const first = parseInt(address.split(":")[0] || "0", 16);
+    return ((first & 0xfe00) === 0xfc00 || // fc00::/7 unique local
+        (first & 0xffc0) === 0xfe80 || // fe80::/10 link-local
+        (first & 0xffc0) === 0xfec0 || // fec0::/10 site-local (deprecated)
+        (first & 0xff00) === 0xff00 || // ff00::/8 multicast
+        address.startsWith("64:ff9b:") || // NAT64 (embeds IPv4)
+        address.startsWith("2001:db8:") // documentation
+    );
+}
+/** Whether an IP literal is in a range an outbound x402 request must not reach. */
+export function isBlockedAddress(address) {
+    const bare = address.replace(/^\[|\]$/g, "");
+    const family = isIP(bare);
+    if (family === 4)
+        return blockedV4(bare);
+    if (family === 6)
+        return blockedV6(bare);
+    return true; // not an IP: never "safe" by default
+}
+function hostAllowed(hostname, allowed) {
+    const host = hostname.toLowerCase();
+    return allowed.some((entry) => {
+        const rule = entry.trim().toLowerCase();
+        if (rule.startsWith("*."))
+            return host.endsWith(rule.slice(1));
+        return host === rule;
+    });
+}
+/** Validate one URL against the guard; throws {@link OutboundRequestRefusedError}. */
+export async function assertOutboundUrlAllowed(raw, options = {}) {
+    let url;
+    try {
+        url = new URL(String(raw));
+    }
+    catch {
+        throw new OutboundRequestRefusedError(`"${String(raw)}" is not a URL`);
+    }
+    const allowPrivate = options.allowPrivateNetworks === true;
+    if (url.protocol !== "https:" &&
+        !(url.protocol === "http:" && allowPrivate)) {
+        throw new OutboundRequestRefusedError(`${url.protocol} is not allowed (https only)`);
+    }
+    if (url.username !== "" || url.password !== "") {
+        throw new OutboundRequestRefusedError("credentials in the URL");
+    }
+    const hostname = url.hostname.replace(/^\[|\]$/g, "");
+    if (options.allowedHosts !== undefined &&
+        options.allowedHosts.length > 0 &&
+        !hostAllowed(hostname, options.allowedHosts)) {
+        throw new OutboundRequestRefusedError(`${hostname} is not in METRIK_AGENT_X402_ALLOWED_HOSTS`);
+    }
+    if (allowPrivate)
+        return url;
+    if (isIP(hostname) !== 0) {
+        if (isBlockedAddress(hostname)) {
+            throw new OutboundRequestRefusedError(`${hostname} is a loopback, private, link-local or reserved address`);
+        }
+        return url;
+    }
+    if (hostname === "localhost" || hostname.endsWith(".localhost")) {
+        throw new OutboundRequestRefusedError(`${hostname} is loopback`);
+    }
+    let addresses;
+    try {
+        addresses = await (options.lookup ?? defaultLookup)(hostname);
+    }
+    catch {
+        throw new OutboundRequestRefusedError(`${hostname} did not resolve`);
+    }
+    if (addresses.length === 0) {
+        throw new OutboundRequestRefusedError(`${hostname} did not resolve`);
+    }
+    const blocked = addresses.find((entry) => isBlockedAddress(entry.address));
+    if (blocked !== undefined) {
+        throw new OutboundRequestRefusedError(`${hostname} resolves to ${blocked.address}, a loopback, private, link-local or reserved address`);
+    }
+    return url;
+}
+/**
+ * A `fetch` that applies {@link assertOutboundUrlAllowed} to every request and
+ * never follows a redirect.
+ */
+export function createGuardedFetch(options = {}) {
+    const base = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const guarded = async (input, init) => {
+        const target = input instanceof Request ? input.url : input;
+        await assertOutboundUrlAllowed(target, options);
+        const response = await base(input, { ...init, redirect: "manual" });
+        if (response.type === "opaqueredirect" ||
+            (response.status >= 300 && response.status < 400)) {
+            throw new OutboundRequestRefusedError(`${new URL(String(target)).host} answered with a redirect (${response.status}), which is never followed`);
+        }
+        return response;
+    };
+    return guarded;
+}
+//# sourceMappingURL=guarded-fetch.js.map

package/dist/x402-buyer/guarded-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guarded-fetch.js","sourceRoot":"","sources":["../../src/x402-buyer/guarded-fetch.ts"],"names":[],"mappings":"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"}

package/dist/x402-buyer/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@absol-labs/agent/x402-buyer` — the BUYER side of Metrik x402: pay an x402
+ * v2 endpoint through `@absol-labs/sdk/x402`'s `payWithX402` with every SDK
+ * protection intact, gated by a spend mandate (`checkMandate()`) before
+ * anything is signed. Kept out of the root barrel so consumers that never use
+ * x402 do not load `@x402/*`. See docs/x402.md.
+ */
+export * from "./pay.js";
+export * from "./guarded-fetch.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/x402-buyer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/x402-buyer/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC"}

package/dist/x402-buyer/index.js

@@ -0,0 +1,10 @@
+/**
+ * `@absol-labs/agent/x402-buyer` — the BUYER side of Metrik x402: pay an x402
+ * v2 endpoint through `@absol-labs/sdk/x402`'s `payWithX402` with every SDK
+ * protection intact, gated by a spend mandate (`checkMandate()`) before
+ * anything is signed. Kept out of the root barrel so consumers that never use
+ * x402 do not load `@x402/*`. See docs/x402.md.
+ */
+export * from "./pay.js";
+export * from "./guarded-fetch.js";
+//# sourceMappingURL=index.js.map

package/dist/x402-buyer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/x402-buyer/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC"}

package/dist/x402-buyer/pay.d.ts

@@ -0,0 +1,135 @@
+import type { MetrikNetwork } from "@absol-labs/sdk";
+import { payWithX402, type PayWithX402Options, type PayWithX402Result, type SignedTransferAuthorization, type X402PayerSigner, type X402QuoteSummary } from "@absol-labs/sdk/x402";
+import { type PublicClient } from "viem";
+import { type HireRequest, type MandateDecision, type SignedSpendMandate } from "../mandates/mandate.js";
+/**
+ * Buyer-side x402 payments under a spend mandate (metrik-agent#121).
+ *
+ * The golden rule of this package — no spend without a mandate — applies to an
+ * x402 payment exactly as it applies to `metrik open`, because a Metrik x402
+ * payment IS a stream open: the opener facilitator settles the payer's EIP-3009
+ * authorization with `factory.deployAndSettle`, which opens a `StreamEscrowV2`
+ * stream with `deposit = price`. So the payment is mapped onto the SAME
+ * {@link HireRequest} a stream open is checked as, from the quote's opener terms
+ * (which the SDK has already proven on-chain: `payTo == factory.predict(terms)`):
+ *
+ * | Mandate field          | x402 quote field                                 |
+ * | ---------------------- | ------------------------------------------------ |
+ * | `maxPerStreamUsdc`     | `amount` (the deposit; the price of the call)    |
+ * | `maxTotalUsdc`         | `spentSoFar + amount`                            |
+ * | `maxRatePerSecondUsdc` | `ratePerSecond` (how fast the seller can earn)   |
+ * | `maxDurationSeconds`   | `maxDuration` (the stream's window)              |
+ * | `allowedOperators`     | `operator` (who the stream pays)                 |
+ *
+ * The check runs inside the SDK's `onQuote` hook — after every SDK protection
+ * (scheme, network, USDC domain, EIP-3009 only, registered factory, on-chain
+ * `predict`, authorization lifetime) and BEFORE anything is signed — so a
+ * denied payment never produces a signature. It is enforced twice: the mandate's
+ * caps are also handed to the SDK as `maxAmount` / `maxRatePerSecond`. A quote
+ * that is not a Metrik opener payment (no operator/rate/duration terms) is
+ * refused: there would be no stream to bound and nothing to recover.
+ *
+ * The mandate itself (signature, expiry, revocation) is verified FIRST, before
+ * any request reaches the seller.
+ */
+/** A payment refused by the spend mandate. Nothing was signed. */
+export declare class X402MandateDeniedError extends Error {
+    readonly reason: NonNullable<MandateDecision["reason"]> | "not-an-opener-quote";
+    readonly quote: X402QuoteSummary | null;
+    constructor(reason: X402MandateDeniedError["reason"], quote: X402QuoteSummary | null, detail?: string);
+}
+/**
+ * The stream-open request an x402 quote would create, or a refusal reason when
+ * the quote does not carry Metrik opener terms.
+ */
+export declare function x402QuoteToHireRequest(quote: X402QuoteSummary): HireRequest | {
+    readonly refused: string;
+};
+export interface PayX402WithMandateInput {
+    readonly url: string | URL;
+    readonly init?: RequestInit;
+    /** The payer: signs the EIP-3009 authorization. Needs USDC, no gas. */
+    readonly signer: X402PayerSigner;
+    readonly network: MetrikNetwork;
+    readonly signedMandate: SignedSpendMandate;
+    /** USDC already spent under this mandate (the cumulative-cap input). */
+    readonly spentSoFarUsdc: bigint;
+    readonly nowSeconds: number;
+    readonly revokedMandateIds?: Iterable<`0x${string}`>;
+    /** An explicit price ceiling, tighter than the mandate (never looser). */
+    readonly maxAmount?: bigint;
+    /** An explicit rate ceiling, tighter than the mandate (never looser). */
+    readonly maxRatePerSecond?: bigint;
+    /** Refuse a quote the seller can fully earn in fewer verified seconds. */
+    readonly minDurationSeconds?: number;
+    /** Passed through to the SDK (transport, fetch, publicClient, ...). */
+    readonly sdkOptions?: Pick<PayWithX402Options, "publicClient" | "transport" | "fetch" | "allowInsecureHttp" | "maxAuthorizationSeconds" | "allowLegacyFactory">;
+    /** Test seam: the SDK payer. Default `payWithX402`. */
+    readonly payImpl?: typeof payWithX402;
+    /**
+     * Called once the mandate APPROVES a quote, BEFORE the SDK signs it. A
+     * caller that tracks cumulative spend reserves the payment here, so a
+     * failure after the signature is handed out can never leave it uncounted.
+     * Throwing refuses the quote (nothing is signed).
+     */
+    readonly onApproved?: (approval: {
+        readonly request: HireRequest;
+        readonly quote: X402QuoteSummary;
+    }) => void | Promise<void>;
+    /**
+     * Chain reads used after a post-signature failure (USDC
+     * `authorizationState`, the opener's `StreamOpenedFor` log). Default: the
+     * SDK options' `publicClient`, else a client over their `transport`, else
+     * the network's first RPC.
+     */
+    readonly chainReader?: Pick<PublicClient, "readContract" | "getLogs" | "getBlockNumber">;
+}
+/** What is known about a payment whose signature was handed out but that did not complete cleanly. */
+export type X402PostSignatureState = 
+/** The authorization was used: the money left the payer. */
+"used"
+/** It could not be established either way. Treat as used. */
+ | "possibly-used"
+/** Not used yet, but still valid until `validBefore`: a holder can still submit it. */
+ | "unused-but-valid"
+/** Not used and past `validBefore`: it can never move funds. */
+ | "unused-expired";
+/**
+ * The payment was APPROVED and its authorization signed and handed to the
+ * seller, then something failed (a malformed or missing PAYMENT-RESPONSE, a
+ * settlement the SDK could not confirm, a dropped connection). The money may
+ * have moved: {@link X402PostSignatureError.state} says what is known, and
+ * {@link X402PostSignatureError.releasable} is `true` only when the
+ * authorization provably can never be used. A spend reservation must be kept
+ * otherwise.
+ */
+export declare class X402PostSignatureError extends Error {
+    readonly state: X402PostSignatureState;
+    readonly approved: HireRequest;
+    readonly quote: X402QuoteSummary;
+    readonly authorization: SignedTransferAuthorization | null;
+    /** The stream the payment opened, when it could be identified. */
+    readonly streamId: `0x${string}` | null;
+    readonly opener: `0x${string}`;
+    constructor(context: {
+        readonly state: X402PostSignatureState;
+        readonly approved: HireRequest;
+        readonly quote: X402QuoteSummary;
+        readonly authorization: SignedTransferAuthorization | null;
+        readonly streamId: `0x${string}` | null;
+        readonly cause: unknown;
+    });
+    /** Only an authorization that provably can never move funds frees its reservation. */
+    get releasable(): boolean;
+}
+export interface PayX402WithMandateResult extends PayWithX402Result {
+    /** The stream-open request the mandate approved (null if nothing was paid). */
+    readonly approved: HireRequest | null;
+}
+/**
+ * Pay an x402 v2 endpoint through the SDK's `payWithX402`, gated by
+ * `checkMandate()`. Fail closed: a mandate that does not verify, a quote it
+ * denies, or a quote without opener terms is a hard stop with nothing signed.
+ */
+export declare function payX402WithMandate(input: PayX402WithMandateInput): Promise<PayX402WithMandateResult>;
+//# sourceMappingURL=pay.d.ts.map

package/dist/x402-buyer/pay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pay.d.ts","sourceRoot":"","sources":["../../src/x402-buyer/pay.ts"],"names":[],"mappings":"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"}

package/dist/x402-buyer/pay.js

@@ -0,0 +1,336 @@
+import { findStreamForAuthorization, payWithX402, X402PaymentRefusedError, } from "@absol-labs/sdk/x402";
+import { decodePaymentSignatureHeader } from "@x402/core/http";
+import { createPublicClient, getAddress, http } from "viem";
+import { checkMandate, verifySignedMandate, } from "../mandates/mandate.js";
+/**
+ * Buyer-side x402 payments under a spend mandate (metrik-agent#121).
+ *
+ * The golden rule of this package — no spend without a mandate — applies to an
+ * x402 payment exactly as it applies to `metrik open`, because a Metrik x402
+ * payment IS a stream open: the opener facilitator settles the payer's EIP-3009
+ * authorization with `factory.deployAndSettle`, which opens a `StreamEscrowV2`
+ * stream with `deposit = price`. So the payment is mapped onto the SAME
+ * {@link HireRequest} a stream open is checked as, from the quote's opener terms
+ * (which the SDK has already proven on-chain: `payTo == factory.predict(terms)`):
+ *
+ * | Mandate field          | x402 quote field                                 |
+ * | ---------------------- | ------------------------------------------------ |
+ * | `maxPerStreamUsdc`     | `amount` (the deposit; the price of the call)    |
+ * | `maxTotalUsdc`         | `spentSoFar + amount`                            |
+ * | `maxRatePerSecondUsdc` | `ratePerSecond` (how fast the seller can earn)   |
+ * | `maxDurationSeconds`   | `maxDuration` (the stream's window)              |
+ * | `allowedOperators`     | `operator` (who the stream pays)                 |
+ *
+ * The check runs inside the SDK's `onQuote` hook — after every SDK protection
+ * (scheme, network, USDC domain, EIP-3009 only, registered factory, on-chain
+ * `predict`, authorization lifetime) and BEFORE anything is signed — so a
+ * denied payment never produces a signature. It is enforced twice: the mandate's
+ * caps are also handed to the SDK as `maxAmount` / `maxRatePerSecond`. A quote
+ * that is not a Metrik opener payment (no operator/rate/duration terms) is
+ * refused: there would be no stream to bound and nothing to recover.
+ *
+ * The mandate itself (signature, expiry, revocation) is verified FIRST, before
+ * any request reaches the seller.
+ */
+/** A payment refused by the spend mandate. Nothing was signed. */
+export class X402MandateDeniedError extends Error {
+    reason;
+    quote;
+    constructor(reason, quote, detail) {
+        super(`x402 payment refused by the spend mandate: ${reason}${detail === undefined ? "" : ` (${detail})`}. Nothing was signed.`);
+        this.name = "X402MandateDeniedError";
+        this.reason = reason;
+        this.quote = quote;
+    }
+}
+/**
+ * The stream-open request an x402 quote would create, or a refusal reason when
+ * the quote does not carry Metrik opener terms.
+ */
+export function x402QuoteToHireRequest(quote) {
+    if (quote.operator === null ||
+        quote.ratePerSecond === null ||
+        quote.maxDuration === null) {
+        return {
+            refused: "the quote carries no Metrik opener terms (operator, ratePerSecond, maxDuration), so it would not open a recoverable stream",
+        };
+    }
+    if (quote.maxDuration > BigInt(Number.MAX_SAFE_INTEGER)) {
+        return { refused: `maxDuration ${quote.maxDuration} is out of range` };
+    }
+    return {
+        operator: quote.operator,
+        budgetUsdc: quote.amount,
+        ratePerSecondUsdc: quote.ratePerSecond,
+        maxDurationSeconds: Number(quote.maxDuration),
+    };
+}
+/**
+ * The payment was APPROVED and its authorization signed and handed to the
+ * seller, then something failed (a malformed or missing PAYMENT-RESPONSE, a
+ * settlement the SDK could not confirm, a dropped connection). The money may
+ * have moved: {@link X402PostSignatureError.state} says what is known, and
+ * {@link X402PostSignatureError.releasable} is `true` only when the
+ * authorization provably can never be used. A spend reservation must be kept
+ * otherwise.
+ */
+export class X402PostSignatureError extends Error {
+    state;
+    approved;
+    quote;
+    authorization;
+    /** The stream the payment opened, when it could be identified. */
+    streamId;
+    opener;
+    constructor(context) {
+        const what = context.state === "used"
+            ? `the payment SETTLED (the authorization was used)${context.streamId === null ? ", but its stream could not be identified" : ` into stream ${context.streamId}`}`
+            : context.state === "possibly-used"
+                ? "the payment MAY HAVE SETTLED: whether the authorization was used could not be established, so treat it as spent"
+                : context.state === "unused-but-valid"
+                    ? `the authorization has not been used, but it stays valid until ${context.authorization?.validBefore.toString() ?? "its validBefore"} and the seller still holds it — treat it as spent until then, or cancel it on USDC (cancelAuthorization)`
+                    : "the authorization was never used and has expired: nothing moved";
+        super(`x402 payment of ${context.approved.budgetUsdc.toString()} USDC base units to ${context.quote.payTo} did not complete cleanly: ${what}. Cause: ${context.cause instanceof Error ? context.cause.message : String(context.cause)}`, { cause: context.cause });
+        this.name = "X402PostSignatureError";
+        this.state = context.state;
+        this.approved = context.approved;
+        this.quote = context.quote;
+        this.authorization = context.authorization;
+        this.streamId = context.streamId;
+        this.opener = getAddress(context.quote.payTo);
+    }
+    /** Only an authorization that provably can never move funds frees its reservation. */
+    get releasable() {
+        return this.state === "unused-expired";
+    }
+}
+function headerValue(headers, name) {
+    if (headers === undefined)
+        return null;
+    if (headers instanceof Headers)
+        return headers.get(name);
+    if (Array.isArray(headers)) {
+        const hit = headers.find((pair) => pair[0]?.toLowerCase() === name);
+        return hit?.[1] ?? null;
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === name) {
+            return typeof value === "string" ? value : (value[0] ?? null);
+        }
+    }
+    return null;
+}
+/** The EIP-3009 authorization inside an x402 v2 PAYMENT-SIGNATURE header, if decodable. */
+function authorizationFromHeader(header) {
+    try {
+        const payload = decodePaymentSignatureHeader(header);
+        const auth = payload.payload?.authorization;
+        if (auth === undefined)
+            return null;
+        return {
+            from: getAddress(auth.from),
+            to: getAddress(auth.to),
+            value: BigInt(auth.value),
+            validAfter: BigInt(auth.validAfter),
+            validBefore: BigInt(auth.validBefore),
+            nonce: auth.nonce,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function smaller(a, b) {
+    return b !== undefined && b < a ? b : a;
+}
+/**
+ * Pay an x402 v2 endpoint through the SDK's `payWithX402`, gated by
+ * `checkMandate()`. Fail closed: a mandate that does not verify, a quote it
+ * denies, or a quote without opener terms is a hard stop with nothing signed.
+ */
+export async function payX402WithMandate(input) {
+    const mandate = input.signedMandate.mandate;
+    // 1. The mandate itself, before the seller is even contacted.
+    const verdict = await verifySignedMandate(input.signedMandate, {
+        nowSeconds: input.nowSeconds,
+        ...(input.revokedMandateIds === undefined
+            ? {}
+            : { revokedMandateIds: input.revokedMandateIds }),
+    });
+    if (!verdict.allowed) {
+        throw new X402MandateDeniedError(verdict.reason ?? "invalid-signature", null);
+    }
+    if (input.signedMandate.owner.toLowerCase() !==
+        input.signer.address.toLowerCase()) {
+        throw new X402MandateDeniedError("invalid-signature", null, `the mandate is owned by ${input.signedMandate.owner}, not the payer ${input.signer.address}`);
+    }
+    if (input.signedMandate.chainId !== input.network.chain.id) {
+        throw new X402MandateDeniedError("invalid-signature", null, `the mandate is for chain ${input.signedMandate.chainId}, not ${input.network.name} (${input.network.chain.id})`);
+    }
+    // 2. The SDK's own ceilings, never looser than the mandate.
+    const remaining = mandate.maxTotalUsdc - input.spentSoFarUsdc;
+    if (remaining <= 0n) {
+        throw new X402MandateDeniedError("exceeds-total-cap", null, "the mandate's total cap is already spent");
+    }
+    const maxAmount = smaller(smaller(mandate.maxPerStreamUsdc, remaining), input.maxAmount);
+    const maxRatePerSecond = smaller(mandate.maxRatePerSecondUsdc, input.maxRatePerSecond);
+    // 3. The per-quote mandate check, before signing.
+    let denial = null;
+    let approved = null;
+    let approvedQuote = null;
+    // The authorization exactly as it left this process, read from the
+    // PAYMENT-SIGNATURE header on the way out — so a post-signature failure can
+    // still be traced on-chain even when the SDK error does not carry it.
+    let sentAuthorization = null;
+    const baseFetch = input.sdkOptions?.fetch ?? globalThis.fetch.bind(globalThis);
+    const capturingFetch = (async (resource, init) => {
+        const header = headerValue(init?.headers, "payment-signature") ??
+            (resource instanceof Request
+                ? resource.headers.get("payment-signature")
+                : null);
+        if (header !== null) {
+            sentAuthorization = authorizationFromHeader(header) ?? sentAuthorization;
+        }
+        return await baseFetch(resource, init);
+    });
+    const pay = input.payImpl ?? payWithX402;
+    let result;
+    try {
+        result = await pay(input.url, input.init, {
+            ...input.sdkOptions,
+            fetch: capturingFetch,
+            signer: input.signer,
+            network: input.network,
+            maxAmount,
+            maxRatePerSecond,
+            ...(input.minDurationSeconds === undefined
+                ? {}
+                : { minDurationSeconds: input.minDurationSeconds }),
+            onQuote: async (quote) => {
+                const request = x402QuoteToHireRequest(quote);
+                if ("refused" in request) {
+                    denial = new X402MandateDeniedError("not-an-opener-quote", quote, request.refused);
+                    return false;
+                }
+                const decision = await checkMandate(input.signedMandate, request, input.spentSoFarUsdc, {
+                    nowSeconds: input.nowSeconds,
+                    ...(input.revokedMandateIds === undefined
+                        ? {}
+                        : { revokedMandateIds: input.revokedMandateIds }),
+                });
+                if (!decision.allowed) {
+                    denial = new X402MandateDeniedError(decision.reason ?? "invalid-signature", quote);
+                    return false;
+                }
+                // Reserve BEFORE the SDK signs: from here on the money can move.
+                // A reservation hook that fails refuses the quote.
+                await input.onApproved?.({ request, quote });
+                approved = request;
+                approvedQuote = quote;
+                denial = null;
+                return true;
+            },
+        });
+    }
+    catch (error) {
+        if (error instanceof X402PaymentRefusedError) {
+            // The SDK's own statement: nothing was signed or sent. A reservation
+            // made in onApproved can be released by the caller.
+            if (denial !== null)
+                throw denial;
+            throw error;
+        }
+        if (approved === null || approvedQuote === null)
+            throw error;
+        throw await classifyPostSignatureFailure(input, {
+            error,
+            approved,
+            quote: approvedQuote,
+            sentAuthorization,
+        });
+    }
+    return { ...result, approved: result.paid ? approved : null };
+}
+/**
+ * After a failure past the point of signing, establish what happened from the
+ * CHAIN, never from the seller: USDC `authorizationState(from, nonce)` and the
+ * opener's `StreamOpenedFor(streamId, payer, authorizationNonce, …)` log.
+ */
+async function classifyPostSignatureFailure(input, context) {
+    const sdkError = context.error;
+    const authorization = sdkError.authorization ?? context.sentAuthorization ?? null;
+    let used = typeof sdkError.authorizationUsed === "boolean"
+        ? sdkError.authorizationUsed
+        : null;
+    let streamId = typeof sdkError.streamId === "string" &&
+        /^0x[0-9a-fA-F]{64}$/.test(sdkError.streamId)
+        ? sdkError.streamId
+        : null;
+    const reader = input.chainReader ??
+        input.sdkOptions?.publicClient ??
+        createPublicClient({
+            transport: input.sdkOptions?.transport ?? http(input.network.rpcUrls[0]),
+        });
+    if (authorization !== null) {
+        if (used === null) {
+            try {
+                used = await reader.readContract({
+                    address: input.network.usdc.address,
+                    abi: authorizationStateAbi,
+                    functionName: "authorizationState",
+                    args: [authorization.from, authorization.nonce],
+                });
+            }
+            catch {
+                used = null;
+            }
+        }
+        if (streamId === null && used !== false) {
+            // The SDK's recovery: only a registered factory's opener
+            // (factory.isOpener read on-chain) can prove a stream for this nonce.
+            try {
+                const recovery = await findStreamForAuthorization({
+                    authorization,
+                    network: input.network,
+                    factory: context.quote.factory ?? null,
+                    publicClient: reader,
+                });
+                streamId = recovery.streamId;
+            }
+            catch {
+                streamId = null;
+            }
+            if (streamId !== null)
+                used = true;
+        }
+    }
+    const nowSeconds = BigInt(Math.floor(Date.now() / 1000));
+    const state = streamId !== null || used === true
+        ? "used"
+        : used === false && authorization !== null
+            ? authorization.validBefore <= nowSeconds
+                ? "unused-expired"
+                : "unused-but-valid"
+            : "possibly-used";
+    return new X402PostSignatureError({
+        state,
+        approved: context.approved,
+        quote: context.quote,
+        authorization,
+        streamId,
+        cause: context.error,
+    });
+}
+const authorizationStateAbi = [
+    {
+        type: "function",
+        name: "authorizationState",
+        stateMutability: "view",
+        inputs: [
+            { name: "authorizer", type: "address" },
+            { name: "nonce", type: "bytes32" },
+        ],
+        outputs: [{ name: "", type: "bool" }],
+    },
+];
+//# sourceMappingURL=pay.js.map