@absol-labs/agent 0.11.0 → 0.12.0-rc.2

package/src/x402-buyer/pay.ts

@@ -0,0 +1,555 @@
+import type { MetrikNetwork } from "@absol-labs/sdk";
+import {
+  findStreamForAuthorization,
+  payWithX402,
+  X402PaymentRefusedError,
+  type PayWithX402Options,
+  type PayWithX402Result,
+  type SignedTransferAuthorization,
+  type X402PayerSigner,
+  type X402QuoteSummary,
+} from "@absol-labs/sdk/x402";
+import { decodePaymentSignatureHeader } from "@x402/core/http";
+import { createPublicClient, getAddress, http, type PublicClient } from "viem";
+
+import {
+  checkMandate,
+  verifySignedMandate,
+  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)                 |
+ *
+ * An UPFRONT ("minimum charge") opener quote is mapped the same way, with
+ * `budgetUsdc = price` — the WHOLE payment, of which `upfrontAmount` is
+ * non-refundable (paid to the seller at settlement) and only the rest is
+ * escrowed. So the per-stream and total caps always count the upfront part as
+ * spent, and nothing a refund returns is ever credited back. Its size is also
+ * capped separately, before signing, by the SDK's `maxUpfrontAmount` (default
+ * 0.10 USDC; pass {@link PayX402WithMandateInput.maxUpfrontAmount} to tighten
+ * it, `0n` to refuse every upfront charge).
+ *
+ * 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 {
+  readonly reason:
+    | NonNullable<MandateDecision["reason"]>
+    | "not-an-opener-quote";
+  readonly quote: X402QuoteSummary | null;
+
+  constructor(
+    reason: X402MandateDeniedError["reason"],
+    quote: X402QuoteSummary | null,
+    detail?: string,
+  ) {
+    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: X402QuoteSummary,
+): HireRequest | { readonly refused: string } {
+  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),
+  };
+}
+
+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;
+  /**
+   * Ceiling on the NON-REFUNDABLE upfront part of an upfront-opener quote, base
+   * units (the SDK's `maxUpfrontAmount`). Default the SDK's 0.10 USDC; `0n`
+   * refuses any upfront charge. Never above the price ceiling in effect.
+   */
+  readonly maxUpfrontAmount?: bigint;
+  /** 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 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}`;
+  /**
+   * `true` when the chain shows (or the signed quote implies) an UPFRONT-ONLY
+   * payment: no stream, the whole price was a non-refundable charge, nothing
+   * to recover.
+   */
+  readonly upfrontOnly: boolean;
+
+  constructor(context: {
+    readonly state: X402PostSignatureState;
+    readonly approved: HireRequest;
+    readonly quote: X402QuoteSummary;
+    readonly authorization: SignedTransferAuthorization | null;
+    readonly streamId: `0x${string}` | null;
+    readonly upfrontOnly?: boolean;
+    readonly cause: unknown;
+  }) {
+    const upfrontOnly =
+      context.upfrontOnly === true || context.quote.upfrontOnly === true;
+    const what =
+      context.state === "used"
+        ? upfrontOnly
+          ? "the payment SETTLED (the authorization was used) as an UPFRONT-ONLY charge: the whole price went to the seller, no stream was opened and there is nothing to refund"
+          : `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);
+    this.upfrontOnly = upfrontOnly;
+  }
+
+  /** Only an authorization that provably can never move funds frees its reservation. */
+  get releasable(): boolean {
+    return this.state === "unused-expired";
+  }
+}
+
+function headerValue(
+  headers: RequestInit["headers"] | undefined,
+  name: string,
+): string | null {
+  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: string,
+): SignedTransferAuthorization | null {
+  try {
+    const payload = decodePaymentSignatureHeader(header) as {
+      payload?: { authorization?: Record<string, string> };
+    };
+    const auth = payload.payload?.authorization;
+    if (auth === undefined) return null;
+    return {
+      from: getAddress(auth.from as string),
+      to: getAddress(auth.to as string),
+      value: BigInt(auth.value as string),
+      validAfter: BigInt(auth.validAfter as string),
+      validBefore: BigInt(auth.validBefore as string),
+      nonce: auth.nonce as `0x${string}`,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export interface PayX402WithMandateResult extends PayWithX402Result {
+  /** The stream-open request the mandate approved (null if nothing was paid). */
+  readonly approved: HireRequest | null;
+}
+
+function smaller(a: bigint, b: bigint | undefined): bigint {
+  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: PayX402WithMandateInput,
+): Promise<PayX402WithMandateResult> {
+  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,
+  );
+  // A negative maxUpfrontAmount is refused by the SDK (InvalidInputError)
+  // before the seller is contacted.
+
+  // 3. The per-quote mandate check, before signing.
+  let denial: X402MandateDeniedError | null = null;
+  let approved: HireRequest | null = null;
+  let approvedQuote: X402QuoteSummary | null = 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: SignedTransferAuthorization | null = null;
+  const baseFetch =
+    input.sdkOptions?.fetch ?? globalThis.fetch.bind(globalThis);
+  const capturingFetch = (async (
+    resource: string | URL | Request,
+    init?: RequestInit,
+  ) => {
+    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);
+  }) as typeof fetch;
+  const pay = input.payImpl ?? payWithX402;
+  let result: PayWithX402Result;
+  try {
+    result = await pay(input.url, input.init, {
+      ...input.sdkOptions,
+      fetch: capturingFetch,
+      signer: input.signer,
+      network: input.network,
+      maxAmount,
+      maxRatePerSecond,
+      ...(input.maxUpfrontAmount === undefined
+        ? {}
+        : { maxUpfrontAmount: smaller(input.maxUpfrontAmount, maxAmount) }),
+      ...(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: PayX402WithMandateInput,
+  context: {
+    readonly error: unknown;
+    readonly approved: HireRequest;
+    readonly quote: X402QuoteSummary;
+    readonly sentAuthorization: SignedTransferAuthorization | null;
+  },
+): Promise<X402PostSignatureError> {
+  const sdkError = context.error as {
+    readonly authorization?: SignedTransferAuthorization;
+    readonly authorizationUsed?: boolean | null;
+    readonly streamId?: string;
+  };
+  const authorization =
+    sdkError.authorization ?? context.sentAuthorization ?? null;
+  let used: boolean | null =
+    typeof sdkError.authorizationUsed === "boolean"
+      ? sdkError.authorizationUsed
+      : null;
+  let upfrontOnly =
+    (sdkError as { readonly upfrontOnly?: boolean }).upfrontOnly === true;
+  let streamId: `0x${string}` | null =
+    typeof sdkError.streamId === "string" &&
+    /^0x[0-9a-fA-F]{64}$/.test(sdkError.streamId)
+      ? (sdkError.streamId as `0x${string}`)
+      : null;
+
+  const reader =
+    input.chainReader ??
+    input.sdkOptions?.publicClient ??
+    (createPublicClient({
+      transport: input.sdkOptions?.transport ?? http(input.network.rpcUrls[0]),
+    }) as unknown as PublicClient);
+
+  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 as PublicClient,
+        });
+        streamId = recovery.streamId;
+        // An upfront-only payment opens no stream: the opener's
+        // UpfrontCharged (streamId 0), read on-chain, proves it was used.
+        if (recovery.upfrontOnly) upfrontOnly = true;
+      } catch {
+        streamId = null;
+      }
+      if (streamId !== null || upfrontOnly) used = true;
+    }
+  }
+
+  const nowSeconds = BigInt(Math.floor(Date.now() / 1000));
+  const state: X402PostSignatureState =
+    streamId !== null || upfrontOnly || 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,
+    upfrontOnly,
+    cause: context.error,
+  });
+}
+
+const authorizationStateAbi = [
+  {
+    type: "function",
+    name: "authorizationState",
+    stateMutability: "view",
+    inputs: [
+      { name: "authorizer", type: "address" },
+      { name: "nonce", type: "bytes32" },
+    ],
+    outputs: [{ name: "", type: "bool" }],
+  },
+] as const;