@metalntwx/metal-pay 0.2.0 → 0.3.0

package/src/mandates/checkout.ts

@@ -0,0 +1,368 @@
+// The agent's signed order: the checkout JWT the agent signs over the payee's
+// own offer, and the Verifiable Intent L3b (the checkout mandate) that
+// carries it to the payee. A seller that asks for one gets, with the
+// payment, proof that the agent was authorised for this offer; the L3a's
+// `transaction_id` is then the checkout JWT's hash, so the payment mandate
+// the chain verifies and the signed order the payee verifies name one offer.
+//
+//   checkout JWT   an ES256 JWS under the agent key: header
+//                  `{"alg":"ES256","typ":"JWT","kid":<agent kid>}`, payload the
+//                  offer in RFC 8785 form (the seller's x402 payment
+//                  requirements, or a payout instruction), with an `id` member
+//                  naming the payee's account
+//   checkout_hash  base64url(SHA-256(ASCII(checkout JWT)))
+//   L3b            `header.payload.signature~checkout disclosure~`, the
+//                  disclosure `{vct: "mandate.checkout.1", checkout_jwt,
+//                  checkout_hash, line_items: [{id, quantity: 1}]}`, `aud` the
+//                  payee, `sd_hash` over the L2 checkout view the payee is
+//                  given (`base ~ checkout disclosure ~ item disclosures ~`),
+//                  serialised as the VI reference serialises a `kb-sd-jwt`
+//
+// One line item per payment, `quantity: 1`, under the credential's wildcard
+// `line_items` constraint; its `id` names what was bought (the offer's
+// resource, else the payee). The payee verifies the L3b under the agent key
+// the mandate binds, against the offer it served; a verifier holding the
+// credential also checks the `sd_hash`.
+
+import { type Address, type Hex, concat, getAddress, hexToBytes, isAddressEqual, size } from "viem";
+import type { AgentKey, Terms } from "./binding.js";
+import { type Json, type JsonObject, jcs } from "./jcs.js";
+import { type SignedL3a, jsonString, lowS, signL3a, verifyL3aSignature } from "./l3a.js";
+import { type SignDigest, b64Ascii, b64url, fromB64url, hashAscii, sha256Hex } from "./vi/sd-jwt.js";
+
+const CHECKOUT_VCT = "mandate.checkout.1";
+
+/** The offer as the checkout JWT's payload text: RFC 8785, every character outside printable ASCII escaped as the reference escapes it. */
+export function checkoutOfferText(offer: JsonObject): string {
+  if (typeof offer.id !== "string") throw new Error("an offer names its payee in an id member");
+  return jcs(offer).replace(/[\u007f-\uffff]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+
+/** The checkout JWT's signing input under the agent key `kid`, and its digest. */
+export function buildCheckoutJwt(kid: string, offer: JsonObject): { signingInput: string; digest: Hex } {
+  const header = `{"alg":"ES256","typ":"JWT","kid":"${jsonString(kid, "kid")}"}`;
+  const signingInput = `${b64Ascii(header)}.${b64Ascii(checkoutOfferText(offer))}`;
+  return { signingInput, digest: sha256Hex(Buffer.from(signingInput, "ascii")) };
+}
+
+/** The checkout JWT the agent signs over `offer`, its `s` in the lower half of the curve order. */
+export async function signCheckoutJwt(kid: string, offer: JsonObject, signDigest: SignDigest): Promise<string> {
+  const { signingInput, digest } = buildCheckoutJwt(kid, offer);
+  const signature = await signDigest(digest);
+  if (size(signature) !== 64) throw new Error("an ES256 signature is r ‖ s, 64 bytes");
+  const r = `0x${signature.slice(2, 66)}` as Hex;
+  const s = lowS(`0x${signature.slice(66)}` as Hex);
+  return `${signingInput}.${b64url(hexToBytes(concat([r, s])))}`;
+}
+
+/** SHA-256 over the checkout JWT's ASCII: the L3b's `checkout_hash` and the L3a's `transaction_id`, as 32 bytes. */
+export function checkoutHash(jwt: string): Hex {
+  return sha256Hex(Buffer.from(jwt, "ascii"));
+}
+
+/** A checkout JWT read back: its signing input, agent kid, the offer and the signature. */
+export interface CheckoutJwt {
+  signingInput: string;
+  kid: string;
+  offer: JsonObject;
+  r: Hex;
+  s: Hex;
+}
+
+export function readCheckoutJwt(jwt: string): CheckoutJwt {
+  const segments = jwt.split(".");
+  if (segments.length !== 3) throw new Error("a checkout JWT has three segments");
+  const [h, p, sig] = segments as [string, string, string];
+  const header = JSON.parse(Buffer.from(fromB64url(h)).toString("utf8")) as Record<string, unknown>;
+  if (header.alg !== "ES256" || header.typ !== "JWT" || typeof header.kid !== "string") throw new Error("a checkout JWT is an ES256 JWT naming the mandate key");
+  const offer = JSON.parse(Buffer.from(fromB64url(p)).toString("utf8")) as unknown;
+  if (offer === null || typeof offer !== "object" || Array.isArray(offer)) throw new Error("a checkout JWT's payload is an object");
+  const signature = fromB64url(sig);
+  if (signature.length !== 64) throw new Error("a checkout JWT's signature is r ‖ s");
+  const r = `0x${Buffer.from(signature.subarray(0, 32)).toString("hex")}` as Hex;
+  const s = `0x${Buffer.from(signature.subarray(32)).toString("hex")}` as Hex;
+  return { signingInput: `${h}.${p}`, kid: header.kid, offer: offer as JsonObject, r, s };
+}
+
+/** The agent's own fields of an L3b, beside what the mandate and the offer fix. */
+export interface L3bFields {
+  nonce: string;
+  iss: string;
+  /** The checkout disclosure's salt, 16 bytes. */
+  checkoutSalt: Hex;
+  /** The one line item's id: what was bought. */
+  lineItemId: string;
+  r: Hex;
+  s: Hex;
+}
+
+/** An L3b without its signature: its serialisation's parts and the digest the agent signs. */
+export interface UnsignedL3b {
+  signingInput: string;
+  checkoutDisclosure: string;
+  /** SHA-256 of the signing input. */
+  digest: Hex;
+}
+
+/**
+ * The L3b for a checkout JWT under a mandate: `aud` the payee's account,
+ * `iat`/`exp` the payment's window, `sd_hash` the hash of the L2 checkout
+ * view the payee is given (`MandateTerms.checkoutSdHash`).
+ */
+export function buildL3b(args: {
+  kid: string;
+  payee: Address;
+  window: { validAfter: bigint; validBefore: bigint };
+  checkoutJwt: string;
+  checkoutSdHash: Hex;
+  fields: Omit<L3bFields, "r" | "s">;
+}): UnsignedL3b {
+  const { kid, payee, window, checkoutJwt, checkoutSdHash, fields } = args;
+  if (size(fields.checkoutSalt) !== 16) throw new Error("the checkout salt is 16 bytes");
+  if (!/^[A-Za-z0-9_.~+/=-]+$/.test(checkoutJwt) || checkoutJwt.split(".").length !== 3) throw new Error("the checkout JWT is a compact JWS");
+  const header = `{"alg":"ES256","typ":"kb-sd-jwt","kid":"${jsonString(kid, "kid")}"}`;
+  const checkoutDisclosure = b64Ascii(
+    `["${b64url(hexToBytes(fields.checkoutSalt))}",{"vct":"${CHECKOUT_VCT}","checkout_jwt":"${checkoutJwt}",` +
+      `"checkout_hash":"${b64url(hexToBytes(checkoutHash(checkoutJwt)))}","line_items":[{"id":"${jsonString(fields.lineItemId, "line item id")}","quantity":1}]}]`,
+  );
+  const payload =
+    `{"nonce":"${jsonString(fields.nonce, "nonce")}","aud":"${getAddress(payee)}","sd_hash":"${b64url(hexToBytes(checkoutSdHash))}",` +
+    `"iat":${window.validAfter},"delegate_payload":[{"...":"${hashAscii(checkoutDisclosure)}"}],` +
+    `"_sd_alg":"sha-256","iss":"${jsonString(fields.iss, "iss")}","exp":${window.validBefore}}`;
+  const signingInput = `${b64Ascii(header)}.${b64Ascii(payload)}`;
+  return { signingInput, checkoutDisclosure, digest: sha256Hex(Buffer.from(signingInput, "ascii")) };
+}
+
+/** The L3b's SD-JWT serialisation: `header.payload.signature~checkout disclosure~`. */
+export function serializeL3b(l3b: UnsignedL3b, r: Hex, s: Hex): string {
+  return `${l3b.signingInput}.${b64url(hexToBytes(concat([r, s])))}~${l3b.checkoutDisclosure}~`;
+}
+
+/** A checkout mandate, signed. */
+export interface SignedL3b {
+  fields: L3bFields;
+  serialized: string;
+  digest: Hex;
+  checkoutJwt: string;
+  /** The checkout JWT's hash: the L3a's `transaction_id`. */
+  checkoutHash: Hex;
+}
+
+/** Signs the checkout JWT over `offer` and the L3b that carries it. `s` is normalised whatever `signDigest` returns. */
+export async function signL3b(args: {
+  kid: string;
+  payee: Address;
+  offer: JsonObject;
+  lineItemId: string;
+  window: { validAfter: bigint; validBefore: bigint };
+  checkoutSdHash: Hex;
+  iss: string;
+  signDigest: SignDigest;
+}): Promise<SignedL3b> {
+  const checkoutJwt = await signCheckoutJwt(args.kid, args.offer, args.signDigest);
+  const fields = {
+    nonce: b64url(crypto.getRandomValues(new Uint8Array(16))),
+    iss: args.iss,
+    checkoutSalt: `0x${Buffer.from(crypto.getRandomValues(new Uint8Array(16))).toString("hex")}` as Hex,
+    lineItemId: args.lineItemId,
+  };
+  const l3b = buildL3b({ kid: args.kid, payee: args.payee, window: args.window, checkoutJwt, checkoutSdHash: args.checkoutSdHash, fields });
+  const signature = await args.signDigest(l3b.digest);
+  if (size(signature) !== 64) throw new Error("an ES256 signature is r ‖ s, 64 bytes");
+  const r = `0x${signature.slice(2, 66)}` as Hex;
+  const s = lowS(`0x${signature.slice(66)}` as Hex);
+  return { fields: { ...fields, r, s }, serialized: serializeL3b(l3b, r, s), digest: l3b.digest, checkoutJwt, checkoutHash: checkoutHash(checkoutJwt) };
+}
+
+/** An L3b read back: what the payee and the Open Verifier check. */
+export interface ReadL3b {
+  signingInput: string;
+  kid: string;
+  typ: unknown;
+  nonce: unknown;
+  aud: unknown;
+  iss: unknown;
+  iat: unknown;
+  exp: unknown;
+  sdHash: unknown;
+  delegateHash: unknown;
+  checkoutDisclosure: string;
+  checkoutJwt: string;
+  checkoutHash: unknown;
+  lineItems: unknown;
+  r: Hex;
+  s: Hex;
+}
+
+export function readL3b(serialized: string): ReadL3b {
+  const parts = serialized.split("~");
+  if (parts.length !== 3 || parts[2] !== "") throw new Error("an L3b is jwt~checkout disclosure~");
+  const [jwt, checkoutDisclosure] = parts as [string, string];
+  const segments = jwt.split(".");
+  if (segments.length !== 3) throw new Error("an L3b JWT has three segments");
+  const [h, p, sig] = segments as [string, string, string];
+  const header = JSON.parse(Buffer.from(fromB64url(h)).toString("utf8")) as Record<string, unknown>;
+  const payload = JSON.parse(Buffer.from(fromB64url(p)).toString("utf8")) as Record<string, unknown>;
+  const [, final] = JSON.parse(Buffer.from(fromB64url(checkoutDisclosure)).toString("utf8")) as [string, Record<string, unknown>];
+  if (typeof header.kid !== "string") throw new Error("an L3b names the mandate key");
+  if (final.vct !== CHECKOUT_VCT || typeof final.checkout_jwt !== "string") throw new Error(`the disclosure is not a ${CHECKOUT_VCT} with a checkout JWT`);
+  const signature = fromB64url(sig);
+  if (signature.length !== 64) throw new Error("an L3b's signature is r ‖ s");
+  const delegates = Array.isArray(payload.delegate_payload) ? (payload.delegate_payload as { "..."?: unknown }[]) : [];
+  return {
+    signingInput: `${h}.${p}`,
+    kid: header.kid,
+    typ: header.typ,
+    nonce: payload.nonce,
+    aud: payload.aud,
+    iss: payload.iss,
+    iat: payload.iat,
+    exp: payload.exp,
+    sdHash: payload.sd_hash,
+    delegateHash: delegates.length === 1 ? delegates[0]?.["..."] : undefined,
+    checkoutDisclosure,
+    checkoutJwt: final.checkout_jwt,
+    checkoutHash: final.checkout_hash,
+    lineItems: final.line_items,
+    r: `0x${Buffer.from(signature.subarray(0, 32)).toString("hex")}` as Hex,
+    s: `0x${Buffer.from(signature.subarray(32)).toString("hex")}` as Hex,
+  };
+}
+
+export interface CheckoutExpectation {
+  agent: AgentKey;
+  /** The agent key's kid, which the mandate binds. */
+  kid: string;
+  /** The payee's account: the L3b's `aud`, the offer's `id` and, where the offer states one, its `payTo`. */
+  payee: Address;
+  /** The offer the payee served, which the checkout JWT must carry verbatim. A verifier that did not serve it leaves it out, and the JWT's own offer stands. */
+  offer?: JsonObject;
+  /** The line item the offer stands for; the offer's own when omitted. */
+  lineItemId?: string;
+  /** The L2 checkout view's hash, checked when the verifier holds the credential. */
+  checkoutSdHash?: Hex;
+  /** The payment's window, which the checkout mandate's `iat` and `exp` must equal; without it, the mandate must be current at `now`. */
+  window?: { validAfter: bigint; validBefore: bigint };
+  now?: number;
+  /** The per-payment mandate's `transaction_id`, as 32 bytes, which must be the checkout hash. */
+  transactionId?: Hex;
+  /** The transfer's amount in base units, which the offer's `amount` must state where it states one. */
+  amount?: bigint;
+}
+
+/**
+ * The one check of a checkout mandate, as the reference's merchant rules
+ * say: the agent key the mandate binds signed it (`kid` and the signature),
+ * it is a `kb-sd-jwt` for this payee within its window, its one disclosure is
+ * the one it commits to, the checkout JWT is the agent's signature over the
+ * offer naming this payee (the one served, when the verifier served it),
+ * `checkout_hash` is that JWT's hash, and it buys one line item. With the
+ * credential's checkout view, the `sd_hash` too; with the per-payment
+ * mandate's `transaction_id` and the transfer's amount, that they are the
+ * checkout hash and the offer's amount. Each signature is verified once.
+ */
+export function verifyCheckoutMandate(serialized: string, expect: CheckoutExpectation): { ok: boolean; problems: string[] } {
+  try {
+    return checkCheckoutMandate(serialized, expect);
+  } catch (error) {
+    return { ok: false, problems: [`the checkout mandate is malformed: ${error instanceof Error ? error.message : String(error)}`] };
+  }
+}
+
+function checkCheckoutMandate(serialized: string, expect: CheckoutExpectation): { ok: boolean; problems: string[] } {
+  const problems: string[] = [];
+  let l3b: ReadL3b;
+  try {
+    l3b = readL3b(serialized);
+  } catch (error) {
+    return { ok: false, problems: [`the checkout mandate does not parse: ${error instanceof Error ? error.message : String(error)}`] };
+  }
+  if (l3b.typ !== "kb-sd-jwt") problems.push("the checkout mandate's typ is not kb-sd-jwt");
+  if (l3b.kid !== expect.kid) problems.push("the checkout mandate names another mandate key");
+  if (!verifyL3aSignature(expect.agent, sha256Hex(Buffer.from(l3b.signingInput, "ascii")), l3b.r, l3b.s)) problems.push("the checkout mandate is not signed by the mandate key");
+  if (typeof l3b.aud !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(l3b.aud) || !isAddressEqual(l3b.aud as Address, expect.payee)) problems.push("the checkout mandate is for another payee");
+  const now = expect.now ?? Math.floor(Date.now() / 1000);
+  if (!Number.isSafeInteger(l3b.iat) || !Number.isSafeInteger(l3b.exp) || (l3b.exp as number) <= (l3b.iat as number)) problems.push("the checkout mandate's window is malformed");
+  else if (expect.window !== undefined) {
+    if (BigInt(l3b.iat as number) !== expect.window.validAfter || BigInt(l3b.exp as number) !== expect.window.validBefore) problems.push("the checkout mandate's window is not the payment's");
+  } else if (now < (l3b.iat as number) - 300 || now > (l3b.exp as number) + 300) problems.push("the checkout mandate is outside its window");
+  if (l3b.delegateHash !== hashAscii(l3b.checkoutDisclosure)) problems.push("the checkout mandate does not commit to its disclosure");
+  if (expect.checkoutSdHash !== undefined && l3b.sdHash !== b64url(hexToBytes(expect.checkoutSdHash))) problems.push("the checkout mandate's sd_hash is not the mandate's checkout view");
+  if (l3b.checkoutHash !== b64url(hexToBytes(checkoutHash(l3b.checkoutJwt)))) problems.push("checkout_hash is not the checkout JWT's hash");
+  if (expect.transactionId !== undefined && expect.transactionId.toLowerCase() !== checkoutHash(l3b.checkoutJwt)) problems.push("the per-payment mandate's transaction_id is not the checkout hash");
+  let jwt: CheckoutJwt | undefined;
+  try {
+    jwt = readCheckoutJwt(l3b.checkoutJwt);
+  } catch (error) {
+    problems.push(`the checkout JWT does not parse: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  let lineItemId = expect.lineItemId;
+  if (jwt !== undefined) {
+    if (jwt.kid !== expect.kid || !verifyL3aSignature(expect.agent, sha256Hex(Buffer.from(jwt.signingInput, "ascii")), jwt.r, jwt.s)) problems.push("the checkout JWT is not signed by the mandate key");
+    if (expect.offer !== undefined && jwt.signingInput !== buildCheckoutJwt(expect.kid, expect.offer).signingInput) problems.push("the checkout JWT is not over the offer the payee served");
+    const offer = expect.offer ?? jwt.offer;
+    lineItemId ??= lineItemOf(offer);
+    if (typeof jwt.offer.id !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(jwt.offer.id) || !isAddressEqual(jwt.offer.id as Address, expect.payee)) problems.push("the offer does not name this payee");
+    if (typeof offer.payTo === "string" && !(/^0x[0-9a-fA-F]{40}$/.test(offer.payTo) && isAddressEqual(offer.payTo as Address, expect.payee))) problems.push("the offer's payTo is not the transfer's payee");
+    if (expect.amount !== undefined && typeof offer.amount === "string" && offer.amount !== expect.amount.toString()) problems.push("the offer's amount is not the transfer's");
+  }
+  const items = l3b.lineItems;
+  if (!Array.isArray(items) || items.length !== 1) problems.push("the checkout mandate must buy exactly one line item");
+  else {
+    const item: unknown = items[0];
+    if (item === null || typeof item !== "object" || Array.isArray(item)) problems.push("the line item is one unit of a named item");
+    else if (typeof (item as { id?: unknown }).id !== "string" || (item as { quantity?: unknown }).quantity !== 1) problems.push("the line item is one unit of a named item");
+    else if (lineItemId !== undefined && (item as { id: string }).id !== lineItemId) problems.push("the line item is not the offer's");
+  }
+  return { ok: problems.length === 0, problems };
+}
+
+/** A payment's two signatures by the agent key: the per-payment mandate, and the checkout mandate whose checkout hash it names. */
+export interface SignedPayment extends SignedL3a {
+  checkout: SignedL3b;
+}
+
+/**
+ * Signs a payment under a mandate: the checkout JWT over `offer` and the
+ * checkout mandate for the payee, then the per-payment mandate for the
+ * transfer with the checkout hash as its `transaction_id`, both over the
+ * same window.
+ */
+export async function signPayment(args: {
+  chainId: number;
+  ref: Hex;
+  token: Address;
+  terms: Terms;
+  to: Address;
+  value: bigint;
+  validAfter: bigint;
+  validBefore: bigint;
+  iss: string;
+  signDigest: SignDigest;
+  offer: JsonObject;
+  lineItemId: string;
+  checkoutSdHash: Hex;
+}): Promise<SignedPayment> {
+  const { offer, lineItemId, checkoutSdHash, ...transfer } = args;
+  const window = { validAfter: args.validAfter, validBefore: args.validBefore };
+  const checkout = await signL3b({ kid: args.terms.kid, payee: args.to, offer, lineItemId, window, checkoutSdHash, iss: args.iss, signDigest: args.signDigest });
+  const signed = await signL3a({ ...transfer, transactionId: checkout.checkoutHash });
+  return { ...signed, checkout };
+}
+
+/** The line item an offer stands for: an x402 seller's `extra.resource` when it names one, else the payee it pays. */
+export function lineItemOf(offer: JsonObject): string {
+  const extra = offer.extra;
+  const resource = extra !== null && typeof extra === "object" && !Array.isArray(extra) ? (extra as JsonObject).resource : undefined;
+  if (typeof resource === "string" && resource.length > 0) return resource;
+  return typeof offer.payTo === "string" ? offer.payTo : String(offer.id);
+}
+
+/** The offer an x402 payment is for: the payment requirements as served (members the server left unset dropped), naming the payee in `id`. */
+export function x402Offer(requirements: Record<string, Json | undefined>): JsonObject {
+  if (typeof requirements.payTo !== "string") throw new Error("x402 requirements name payTo");
+  const offer: JsonObject = { id: getAddress(requirements.payTo as Address) };
+  for (const [key, value] of Object.entries(requirements)) if (value !== undefined) offer[key] = value;
+  return offer;
+}
+

package/src/mandates/client.ts

@@ -0,0 +1,159 @@
+// Paying under a mandate: an `exact` client for an agent that pays from its
+// principal's account. Each payment is the agent's per-payment mandate, a
+// Verifiable Intent L3a in the profile Mandate Binding rebuilds, and that is
+// its only signature. The payload is a standard ERC-3009
+// `TransferWithAuthorization` whose `from` is the principal's account, whose
+// nonce is `bytes12(mandate reference) ‖ bytes20(SHA-256(L3a signing input))`,
+// whose window is the L3a's `iat` and `exp`, and whose signature is
+// `MNDT || abi.encode(Pull, L3a fields)`, the arguments of `pull` on the
+// principal's account. Sellers see an ordinary `exact` payment; Metal's
+// facilitator submits it as that `pull`, where Mandate Binding accepts or
+// refuses it. A seller that asks for the agent's signed order gets it in
+// the payload's `extensions`, and the per-payment mandate names its hash.
+//
+// `@x402/evm`'s `exact` client draws its own nonce and signs EIP-712 as
+// `from`, so this scheme builds the authorisation itself, as `@x402/evm`'s
+// `ExactEIP3009Payload`.
+
+import { x402Client } from "@x402/core/client";
+import type { PaymentPayloadResult, PaymentRequirements, SchemeNetworkClient } from "@x402/core/types";
+import type { ExactEIP3009Payload } from "@x402/evm";
+import { wrapFetchWithPayment } from "@x402/fetch";
+import { type Address, type Hex, getAddress } from "viem";
+import { type MetalPaymentClient, allowAsset, keepPaymentOnOrigin } from "../client.js";
+import { type MetalNetwork, type MetalNetworkName, USDZ, formatUsdz, resolveNetwork } from "../networks.js";
+import { mandateReference } from "./binding.js";
+import { type SignedPayment, lineItemOf, signPayment, x402Offer } from "./checkout.js";
+import { asksSignedOffer, mandateExtension } from "./extension.js";
+import type { Json } from "./jcs.js";
+import { type SignedL3a, encodeMandateBlob, signL3a, transactionIdOf } from "./l3a.js";
+import { type Credential, type MandateTerms, extractTerms, hashCredential } from "./vi/credential.js";
+import type { SignDigest } from "./vi/sd-jwt.js";
+
+/**
+ * The longest a per-payment mandate stays valid. An offer's
+ * `maxTimeoutSeconds` can only shorten it, so a seller cannot obtain one it
+ * may submit long after the agent chose to pay.
+ */
+export const MANDATE_MAX_VALIDITY_SECONDS = 600;
+
+/**
+ * How far before signing the window opens. MIP20 requires `now > validAfter`,
+ * and a facilitator simulates against the latest block, whose timestamp can
+ * trail the clock by a block or more.
+ */
+export const MANDATE_VALID_AFTER_LEAD_SECONDS = 5;
+
+export interface MandateSchemeConfig {
+  /** The credential the mandate was bound from: the principal, reference, token and rebuild terms derive from it. */
+  credential: Credential;
+  /** Signs an L3a's SHA-256 signing digest with the agent key: `p256DigestSigner`. */
+  signDigest: SignDigest;
+  /** Called with each per-payment mandate once it is signed, before the payment is sent; with the signed order when one was made. */
+  onSigned?: (payment: SignedL3a | SignedPayment) => void;
+  /** When to sign the seller's offer: when its offer asks (the default), for every payment, or never, which a seller that asks then refuses. */
+  signedOffer?: "when-asked" | "always" | "never";
+}
+
+function chainIdOf(network: string): number {
+  const match = /^eip155:(\d+)$/.exec(network);
+  if (!match) throw new Error(`not an EVM network: ${network}`);
+  return Number(match[1]);
+}
+
+/** The `exact` scheme for an agent paying under a mandate. */
+export class MandateExactScheme implements SchemeNetworkClient {
+  readonly scheme = "exact";
+  /** The account the payments come from. */
+  readonly principal: Address;
+  readonly reference: Hex;
+  readonly token: Address;
+  private readonly mandate: MandateTerms;
+
+  constructor(private readonly config: MandateSchemeConfig) {
+    this.mandate = extractTerms(config.credential);
+    this.principal = this.mandate.principal;
+    this.token = this.mandate.constraints.token;
+    this.reference = mandateReference(this.principal, this.mandate.agentKey, hashCredential(config.credential));
+  }
+
+  async createPaymentPayload(x402Version: number, requirements: PaymentRequirements): Promise<PaymentPayloadResult> {
+    const method = requirements.extra?.["assetTransferMethod"] ?? "eip3009";
+    if (method !== "eip3009") throw new Error(`a mandate pays by ERC-3009 only, not ${String(method)}`);
+    if (getAddress(requirements.asset) !== this.token) throw new Error(`asset ${requirements.asset} is not the mandate's token ${this.token}`);
+    if (BigInt(requirements.amount) % this.mandate.terms.unitsPerMinor !== 0n) {
+      throw new Error(`offer of ${formatUsdz(requirements.amount)} ${USDZ.symbol} is not a whole number of cents, which is all a mandate pays`);
+    }
+    const now = BigInt(Math.floor(Date.now() / 1000));
+    const transfer = {
+      chainId: chainIdOf(requirements.network),
+      ref: this.reference,
+      token: this.token,
+      terms: this.mandate.terms,
+      to: getAddress(requirements.payTo),
+      value: BigInt(requirements.amount),
+      validAfter: now - BigInt(MANDATE_VALID_AFTER_LEAD_SECONDS),
+      validBefore: now + BigInt(Math.min(requirements.maxTimeoutSeconds, MANDATE_MAX_VALIDITY_SECONDS)),
+      iss: this.mandate.terms.kid,
+      signDigest: this.config.signDigest,
+    };
+    const mode = this.config.signedOffer ?? "when-asked";
+    const withOffer = mode === "always" || (mode === "when-asked" && asksSignedOffer(requirements));
+    let signed: SignedL3a | SignedPayment;
+    let extensions: Record<string, unknown> | undefined;
+    if (withOffer) {
+      const offer = x402Offer(requirements as unknown as Record<string, Json | undefined>);
+      const payment = await signPayment({ ...transfer, offer, lineItemId: lineItemOf(offer), checkoutSdHash: this.mandate.checkoutSdHash });
+      signed = payment;
+      extensions = mandateExtension(this.reference, payment.checkout.serialized);
+    } else {
+      signed = await signL3a({ ...transfer, transactionId: transactionIdOf(requirements as unknown as Json) });
+    }
+    this.config.onSigned?.(signed);
+    const payload: ExactEIP3009Payload = {
+      authorization: {
+        from: this.principal,
+        to: signed.pull.to,
+        value: signed.pull.value.toString(),
+        validAfter: signed.pull.validAfter.toString(),
+        validBefore: signed.pull.validBefore.toString(),
+        nonce: signed.pull.nonce,
+      },
+      signature: encodeMandateBlob(signed.pull, signed.fields),
+    };
+    return { x402Version, payload, ...(extensions === undefined ? {} : { extensions }) };
+  }
+}
+
+export interface MandatePaymentClientConfig extends MandateSchemeConfig {
+  /** The one network this client pays on; offers for any other are refused. */
+  network: MetalNetworkName | MetalNetwork;
+  /** The fetch to wrap; `globalThis.fetch` by default. */
+  fetch?: typeof globalThis.fetch;
+}
+
+export interface MandatePaymentClient extends MetalPaymentClient {
+  /** The account the payments come from. */
+  principal: Address;
+  /** The mandate the payments are made under. */
+  reference: Hex;
+}
+
+/**
+ * One call to pay under a mandate. The client sets no limit of its own: the
+ * mandate bound on the principal's account decides, and Metal refuses a
+ * payment outside it at settlement.
+ */
+export function createMandatePaymentClient({ network, fetch = globalThis.fetch, ...config }: MandatePaymentClientConfig): MandatePaymentClient {
+  const resolved = resolveNetwork(network);
+  const scheme = new MandateExactScheme(config);
+  const client = new x402Client().register(resolved.network, scheme);
+  allowAsset(client, resolved.network, scheme.token);
+  return {
+    fetchWithPayment: wrapFetchWithPayment(keepPaymentOnOrigin(fetch), client),
+    client,
+    network: resolved,
+    principal: scheme.principal,
+    reference: scheme.reference,
+  };
+}

package/src/mandates/extension.ts

@@ -0,0 +1,48 @@
+// What a payment under a mandate carries in the x402 payload's `extensions`
+// field under `metal-mandate`, when the seller asked for the agent's signed
+// offer: the mandate reference and the signed order (a Verifiable Intent
+// checkout mandate, L3b). Neither is covered by the payer's signature: the
+// per-payment mandate the authorisation carries is the signature, and its
+// `transaction_id` is the signed order's `checkout_hash`, which ties the two.
+// A seller's offer asks for one with `extra.signedOffer: "required"`.
+
+import type { PaymentPayload, PaymentRequirements } from "@x402/core/types";
+
+export const MANDATE_EXTENSION_KEY = "metal-mandate";
+
+/** What a seller puts in a route's `extra` to be paid only with the agent's signed order. */
+export const SIGNED_OFFER_REQUIRED = { signedOffer: "required" } as const;
+
+export interface MandateExtension {
+  /** The mandate reference, `0x`-prefixed. */
+  ref: string;
+  /** The signed order, serialised. */
+  checkoutMandate: string;
+}
+
+/** The `extensions` entry for a payment under `ref` with its signed order. */
+export function mandateExtension(ref: string, checkoutMandate: string): Record<string, MandateExtension> {
+  return { [MANDATE_EXTENSION_KEY]: { ref, checkoutMandate } };
+}
+
+/** Whether an offer asks for the agent's signed order. */
+export function asksSignedOffer(requirements: Pick<PaymentRequirements, "extra">): boolean {
+  return requirements.extra?.["signedOffer"] === SIGNED_OFFER_REQUIRED.signedOffer;
+}
+
+function extensionOf(payload: Pick<PaymentPayload, "extensions">): Partial<MandateExtension> {
+  const value = payload.extensions?.[MANDATE_EXTENSION_KEY];
+  return value !== null && typeof value === "object" ? (value as Partial<MandateExtension>) : {};
+}
+
+/** The mandate reference a payment carries; empty when it carries none. */
+export function mandateRefOf(payload: Pick<PaymentPayload, "extensions">): string {
+  const { ref } = extensionOf(payload);
+  return typeof ref === "string" ? ref : "";
+}
+
+/** The signed order a payment carries; empty when it carries none. */
+export function signedOfferOf(payload: Pick<PaymentPayload, "extensions">): string {
+  const { checkoutMandate } = extensionOf(payload);
+  return typeof checkoutMandate === "string" ? checkoutMandate : "";
+}