@metalntwx/metal-pay 0.2.0 → 0.3.0

package/src/mandates/index.ts

@@ -0,0 +1,121 @@
+export { ACCOUNT_BATCH_MODE, assertMetalAccount, authorizeMandateCall, metalAccountAbi, metalAccountCode, metalAccountFactoryAbi } from "./account.js";
+export {
+  FEE_PER_GAS,
+  MANDATE_SIGNATURE_TAG,
+  BINDING_GAS_PER_BYTE,
+  MANDATE_GAS,
+  REASONS,
+  REFUSALS,
+  bindCall,
+  decodeAgentKey,
+  describeRefusal,
+  encodeAgentKey,
+  mandateBindingAbi,
+  mandateReference,
+  pullCall,
+  reasonName,
+  referencePrefix,
+  refusalOf,
+  replaceCall,
+  revokeCall,
+  sameAgentKey,
+  type AgentKey,
+  type Binding,
+  type Constraints,
+  type L3aFields,
+  type MandateCall,
+  type Payee,
+  type Pull,
+  type ReasonName,
+  type Terms,
+} from "./binding.js";
+export { publicMessage, readBoundAgentKey, readCheck, readMandateState, redactUrls, sendMandateCall } from "./chain.js";
+export {
+  buildCheckoutJwt,
+  buildL3b,
+  checkoutHash,
+  lineItemOf,
+  readCheckoutJwt,
+  readL3b,
+  serializeL3b,
+  signCheckoutJwt,
+  signL3b,
+  signPayment,
+  verifyCheckoutMandate,
+  x402Offer,
+  type CheckoutExpectation,
+  type CheckoutJwt,
+  type L3bFields,
+  type ReadL3b,
+  type SignedL3b,
+  type SignedPayment,
+  type UnsignedL3b,
+} from "./checkout.js";
+export { MANDATE_EXTENSION_KEY, SIGNED_OFFER_REQUIRED, asksSignedOffer, mandateExtension, mandateRefOf, signedOfferOf, type MandateExtension } from "./extension.js";
+export { requireSignedOffer, type RequireSignedOfferConfig } from "./seller.js";
+export {
+  MANDATE_MAX_VALIDITY_SECONDS,
+  MANDATE_VALID_AFTER_LEAD_SECONDS,
+  MandateExactScheme,
+  createMandatePaymentClient,
+  type MandatePaymentClient,
+  type MandatePaymentClientConfig,
+  type MandateSchemeConfig,
+} from "./client.js";
+export { ingestCredential, type Ingested } from "./ingest.js";
+export { jcs, type Json, type JsonObject } from "./jcs.js";
+export {
+  buildL3a,
+  decodeMandateBlob,
+  encodeMandateBlob,
+  jsonString,
+  lowS,
+  mandateNonce,
+  namesAddress,
+  serializeL3a,
+  signL3a,
+  transactionIdOf,
+  verifyL3aSignature,
+  type SignedL3a,
+  type UnsignedL3a,
+} from "./l3a.js";
+export {
+  STEP_TITLES,
+  verifyMandate,
+  verifyMandatePayment,
+  type BoundMandate,
+  type MandateVerification,
+  type VerifiedPayment,
+  type VerifyMandateOptions,
+  type VerifyStep,
+} from "./verify.js";
+export {
+  CredentialError,
+  INSTRUMENTS,
+  METAL_L1_VCT,
+  MAX_TERM_OBJECT_BYTES,
+  UNCAPPED_OCCURRENCES,
+  agentKeyOfJwk,
+  extractTerms,
+  hashCredential,
+  issuerKeyId,
+  parseCredential,
+  recurrenceBound,
+  verifyCredential,
+  type Credential,
+  type CredentialFailure,
+  type MandateTerms,
+  type TrustedIssuer,
+} from "./vi/credential.js";
+export { createCredential, trustedIssuer, type CredentialParams } from "./vi/issue.js";
+export {
+  createEs256Key,
+  jwkThumbprint,
+  p256DigestSigner,
+  parseP256Jwk,
+  privateKeyHex,
+  type Es256Key,
+  type P256Jwk,
+  type P256PrivateJwk,
+  type SignDigest,
+} from "./vi/sd-jwt.js";

package/src/mandates/ingest.ts

@@ -0,0 +1,42 @@
+// Mandate Ingestion: a Verifiable Intent credential verified off chain
+// against Metal's L1 profile and the caller's trusted issuers, its terms
+// extracted and hashed into what `bindCall` and `replaceCall` take.
+
+import type { Address, Hex } from "viem";
+import { type Binding, mandateReference } from "./binding.js";
+import { type Credential, type MandateTerms, type TrustedIssuer, hashCredential, issuerKeyId, verifyCredential } from "./vi/credential.js";
+
+export interface Ingested extends Binding {
+  credential: Credential;
+  /** The trusted issuer that attested it. */
+  issuer: TrustedIssuer;
+  /** The mandate reference binding will derive. */
+  reference: Hex;
+  /** Everything extracted, the descriptive fields among it. */
+  extracted: MandateTerms;
+}
+
+/**
+ * Verifies `credential` for binding on `account` against the trusted issuers
+ * at `now`, and extracts what the mandate binds. Throws `CredentialError`
+ * naming the failure; no binding is built for a credential that fails.
+ */
+export async function ingestCredential(
+  credential: Credential,
+  opts: { trustedIssuers: readonly TrustedIssuer[]; account: Address; now?: number },
+): Promise<Ingested> {
+  const { issuer, terms } = await verifyCredential(credential, opts);
+  const hashC = hashCredential(credential);
+  return {
+    credential,
+    issuer,
+    principal: terms.principal,
+    hashC,
+    issuerKey: issuerKeyId(issuer.jwk),
+    agentKey: terms.agentKey,
+    constraints: terms.constraints,
+    terms: terms.terms,
+    reference: mandateReference(terms.principal, terms.agentKey, hashC),
+    extracted: terms,
+  };
+}

package/src/mandates/jcs.ts

@@ -0,0 +1,16 @@
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+export type JsonObject = { [key: string]: Json };
+
+/**
+ * RFC 8785. Numbers use ECMAScript Number serialization and keys sort by
+ * UTF-16 code units, both of which the RFC defines in terms of
+ * `JSON.stringify` and the default string ordering.
+ */
+export function jcs(value: Json): string {
+  if (typeof value === "number" && !Number.isFinite(value)) throw new Error("JCS cannot encode a non-finite number");
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") return JSON.stringify(value);
+  if (typeof value !== "object") throw new Error(`JCS cannot encode ${typeof value}`);
+  if (Array.isArray(value)) return `[${value.map(jcs).join(",")}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${jcs(value[k] as Json)}`).join(",")}}`;
+}

package/src/mandates/l3a.ts

@@ -0,0 +1,216 @@
+// The per-payment mandate: a Verifiable Intent L3a in the profile Mandate
+// Binding rebuilds, serialised byte for byte as the VI reference serialises
+// it (compact JSON in the reference's key order, the L2 payee object
+// verbatim), with `aud` the chain as `eip155:<chainId>`, `iat`/`exp` the
+// ERC-3009 window, and `transaction_id` the SHA-256 of the RFC 8785 form of
+// the seller's x402 payment requirements. The ERC-3009 nonce is
+// `bytes12(mandate reference) ‖ bytes20(SHA-256(signing input))`; the x402
+// payload's signature is `MNDT || abi.encode(Pull, L3a fields)`, which the
+// facilitator decodes into `pull`'s arguments.
+
+import { p256 } from "@noble/curves/nist";
+import {
+  type Address,
+  type Hex,
+  bytesToHex,
+  concat,
+  decodeAbiParameters,
+  encodeAbiParameters,
+  getAbiItem,
+  hexToBigInt,
+  hexToBytes,
+  isAddressEqual,
+  numberToHex,
+  size,
+  slice,
+  zeroAddress,
+} from "viem";
+import { type AgentKey, type L3aFields, type Pull, type Terms, mandateBindingAbi, referencePrefix } from "./binding.js";
+import { MANDATE_SIGNATURE_TAG } from "./binding.js";
+import { type Json, jcs } from "./jcs.js";
+import { type SignDigest, b64Ascii, b64url, hashAscii, sha256Hex } from "./vi/sd-jwt.js";
+
+const P256_N: bigint = 0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551n;
+const P256_HALF_N = P256_N / 2n;
+
+/** SHA-256 of the RFC 8785 form of the seller's x402 payment requirements, the L3a's `transaction_id`. */
+export function transactionIdOf(requirements: Json): Hex {
+  return sha256Hex(Buffer.from(jcs(requirements), "utf8"));
+}
+
+/** A JSON string's contents as the reference writes them unescaped: printable ASCII other than `"` and `\`. */
+export function jsonString(value: string, what: string): string {
+  if (value.length === 0 || !/^[\x20-\x7e]*$/.test(value) || /["\\]/.test(value)) {
+    throw new Error(`${what} must be printable ASCII without " or \\`);
+  }
+  return value;
+}
+
+/**
+ * Whether a compact JSON object has exactly one `"id":` member, the string
+ * `0x` and `account`'s 40 hex digits, and no `\u00XX` escape of a printable
+ * ASCII character (which could hide a second `id`), as Mandate Binding reads it.
+ */
+export function namesAddress(object: string, account: Address): boolean {
+  if (/\\u00[2-7]/.test(object) || /"id"\s+:/.test(object)) return false;
+  const members = object.split('"id":');
+  if (members.length !== 2) return false;
+  const match = /^"(0x[0-9a-fA-F]{40})"/.exec(members[1] as string);
+  return match !== null && isAddressEqual(match[1] as Address, account);
+}
+
+function b64(hex: Hex): string {
+  return b64url(hexToBytes(hex));
+}
+
+/** An L3a without its signature: the parts of its serialisation, and the digest the agent signs and the nonce carries. */
+export interface UnsignedL3a {
+  signingInput: string;
+  merchantDisclosure: string;
+  paymentDisclosure: string;
+  /** SHA-256 of the signing input. */
+  digest: Hex;
+}
+
+/** The payee object and `sd_hash` an L3a to `to` carries, as Mandate Binding resolves them; undefined when it cannot be for `to`. */
+function payeeTerms(terms: Terms, to: Address, fields: Pick<L3aFields, "payee" | "linkedPayee">) {
+  const bound = terms.payees.find((p) => isAddressEqual(p.account, to));
+  if (bound !== undefined) return { object: bound.object, sdHash: bound.sdHash, outside: false };
+  // The agent's own object opens with its id, so the one id member a parser reads is the one the chain checked.
+  if (!fields.payee.startsWith('{"id":"') || !namesAddress(fields.payee, to)) return undefined;
+  if (hexToBigInt(terms.openSdHash) !== 0n) return { object: fields.payee, sdHash: terms.openSdHash, outside: false };
+  const linked = terms.payees.find((p) => isAddressEqual(p.account, fields.linkedPayee));
+  return linked === undefined ? undefined : { object: fields.payee, sdHash: linked.sdHash, outside: true };
+}
+
+/**
+ * The L3a for the transfer `pull` under a mandate's rebuild `terms`, as
+ * Mandate Binding rebuilds it on `chainId`. Throws where Mandate Binding
+ * would find no L3a (a value that is not whole minor units, unwritable
+ * strings, a payee it cannot resolve).
+ */
+export function buildL3a(
+  chainId: number,
+  terms: Terms,
+  pull: Pick<Pull, "to" | "value" | "validAfter" | "validBefore">,
+  fields: Omit<L3aFields, "r" | "s">,
+): UnsignedL3a {
+  if (pull.value % terms.unitsPerMinor !== 0n) throw new Error(`${pull.value} is not a whole number of ${terms.currency} minor units`);
+  if (size(fields.merchantSalt) !== 16 || size(fields.paymentSalt) !== 16 || size(fields.transactionId) !== 32) {
+    throw new Error("salts are 16 bytes and transaction_id 32");
+  }
+  const payee = payeeTerms(terms, pull.to, fields);
+  if (payee === undefined) throw new Error(`no payee terms for ${pull.to}`);
+  const header = `{"alg":"ES256","typ":"kb-sd-jwt","kid":"${jsonString(terms.kid, "kid")}"}`;
+  const merchantDisclosure = b64Ascii(`["${b64(fields.merchantSalt)}",${payee.object}]`);
+  const paymentDisclosure = b64Ascii(
+    `["${b64(fields.paymentSalt)}",{"vct":"mandate.payment.1","transaction_id":"${b64(fields.transactionId)}",` +
+      `"payee":${payee.object},"payment_amount":{"currency":"${jsonString(terms.currency, "currency")}",` +
+      `"amount":${pull.value / terms.unitsPerMinor}},"payment_instrument":${terms.instrument}}]`,
+  );
+  const payload =
+    `{"nonce":"${jsonString(fields.nonce, "nonce")}","aud":"eip155:${chainId}","sd_hash":"${b64(payee.sdHash)}",` +
+    `"iat":${pull.validAfter},"delegate_payload":[{"...":"${hashAscii(merchantDisclosure)}"},{"...":"${hashAscii(paymentDisclosure)}"}],` +
+    `"_sd_alg":"sha-256","iss":"${jsonString(fields.iss, "iss")}","exp":${pull.validBefore}}`;
+  const signingInput = `${b64Ascii(header)}.${b64Ascii(payload)}`;
+  return { signingInput, merchantDisclosure, paymentDisclosure, digest: sha256Hex(Buffer.from(signingInput, "ascii")) };
+}
+
+/** `bytes12(mandate reference) ‖ bytes20(digest)`. */
+export function mandateNonce(ref: Hex, digest: Hex): Hex {
+  return concat([referencePrefix(ref), slice(digest, 0, 20)]).toLowerCase() as Hex;
+}
+
+/** The L3a's SD-JWT serialisation: `header.payload.signature~merchant disclosure~payment disclosure~`. */
+export function serializeL3a(l3a: UnsignedL3a, r: Hex, s: Hex): string {
+  return `${l3a.signingInput}.${b64url(hexToBytes(concat([r, s])))}~${l3a.merchantDisclosure}~${l3a.paymentDisclosure}~`;
+}
+
+/** `s` mapped into the lower half of the curve order, the one encoding Mandate Binding accepts. */
+export function lowS(s: Hex): Hex {
+  const value = hexToBigInt(s);
+  return numberToHex(value > P256_HALF_N ? P256_N - value : value, { size: 32 });
+}
+
+/** Whether `r ‖ s` is the agent key's low-s ES256 signature over the L3a whose signing digest is `digest`, as the precompile checks it. */
+export function verifyL3aSignature(key: AgentKey, digest: Hex, r: Hex, s: Hex): boolean {
+  if (hexToBigInt(s) > P256_HALF_N) return false;
+  try {
+    return p256.verify(hexToBytes(concat([r, s])), hexToBytes(digest), hexToBytes(concat(["0x04", key.x, key.y])), { prehash: false, lowS: true });
+  } catch {
+    return false;
+  }
+}
+
+/** A per-payment mandate, signed, with the authorisation it commits to. */
+export interface SignedL3a {
+  pull: Pull;
+  fields: L3aFields;
+  /** The L3a SD-JWT as the VI reference serialises it. */
+  serialized: string;
+  digest: Hex;
+}
+
+/**
+ * Builds and signs the agent's per-payment mandate for a transfer under a
+ * mandate: `ref` and `token` are the mandate's; a `to` the mandate does not
+ * list gets a payee object naming it (its CAIP-10 account as `website`),
+ * which under a mandate that names no payee is the payment's own object, and
+ * under one that does is linked through the first allowed payee so the chain
+ * can record its refusal. `s` is normalised whatever `signDigest` returns.
+ */
+export async function signL3a(args: {
+  chainId: number;
+  ref: Hex;
+  token: Address;
+  terms: Terms;
+  to: Address;
+  value: bigint;
+  validAfter: bigint;
+  validBefore: bigint;
+  transactionId: Hex;
+  iss: string;
+  signDigest: SignDigest;
+}): Promise<SignedL3a> {
+  const inSet = args.terms.payees.some((p) => isAddressEqual(p.account, args.to));
+  const open = hexToBigInt(args.terms.openSdHash) !== 0n;
+  const first = args.terms.payees[0];
+  if (!inSet && !open && first === undefined) throw new Error("the mandate has no payees");
+  const unsigned = {
+    nonce: b64url(crypto.getRandomValues(new Uint8Array(16))),
+    iss: args.iss,
+    merchantSalt: bytesToHex(crypto.getRandomValues(new Uint8Array(16))),
+    paymentSalt: bytesToHex(crypto.getRandomValues(new Uint8Array(16))),
+    transactionId: args.transactionId,
+    payee: inSet ? "" : `{"id":"${args.to}","name":"${args.to}","website":"eip155:${args.chainId}:${args.to}"}`,
+    linkedPayee: inSet || open ? zeroAddress : (first?.account ?? zeroAddress),
+  };
+  const l3a = buildL3a(args.chainId, args.terms, args, unsigned);
+  const signature = await args.signDigest(l3a.digest);
+  if (size(signature) !== 64) throw new Error("an ES256 signature is r ‖ s, 64 bytes");
+  const r = slice(signature, 0, 32);
+  const s = lowS(slice(signature, 32, 64));
+  const pull: Pull = {
+    token: args.token,
+    to: args.to,
+    value: args.value,
+    validAfter: args.validAfter,
+    validBefore: args.validBefore,
+    nonce: mandateNonce(args.ref, l3a.digest),
+  };
+  return { pull, fields: { ...unsigned, r, s }, serialized: serializeL3a(l3a, r, s), digest: l3a.digest };
+}
+
+const pullInputs = getAbiItem({ abi: mandateBindingAbi, name: "pull" }).inputs;
+
+/** The x402 payload's signature: `MNDT || abi.encode(Pull, L3a fields)`, the arguments of `pull`. */
+export function encodeMandateBlob(pull: Pull, fields: L3aFields): Hex {
+  return concat([MANDATE_SIGNATURE_TAG, encodeAbiParameters(pullInputs, [pull, fields])]);
+}
+
+/** The Pull and L3a fields an x402 payload's signature carries, as Mandate Binding's `check` and `pull` take them. */
+export function decodeMandateBlob(blob: Hex): { pull: Pull; fields: L3aFields } {
+  if (size(blob) < 4 || slice(blob, 0, 4) !== MANDATE_SIGNATURE_TAG) throw new Error("not a MetalAccount mandate signature");
+  const [pull, fields] = decodeAbiParameters(pullInputs, slice(blob, 4));
+  return { pull, fields };
+}

package/src/mandates/seller.ts

@@ -0,0 +1,91 @@
+// The seller's side of a signed order: a check, before the facilitator is
+// asked to verify, that a payment under a mandate carries the agent's signed
+// offer for this very offer, under the agent key the payer's account binds.
+
+import type { x402ResourceServer } from "@x402/core/server";
+import { type Address, type Hex, type PublicClient, createPublicClient, getAddress, http, isAddress, isHex, isAddressEqual } from "viem";
+import { accountFactoryFor, metalNetwork } from "../networks.js";
+import { assertMetalAccount } from "./account.js";
+import { referencePrefix } from "./binding.js";
+import { decodeMandateBlob } from "./l3a.js";
+import { readBoundAgentKey } from "./chain.js";
+import { lineItemOf, verifyCheckoutMandate, x402Offer } from "./checkout.js";
+import type { Json } from "./jcs.js";
+import { asksSignedOffer, mandateRefOf, signedOfferOf } from "./extension.js";
+
+/**
+ * Where the check reads the agent key a mandate binds on the payer's account,
+ * a viem client or the endpoint to make one for, and, for a factory other than
+ * the one `@metalntwx/metal-pay` names for the offer's network, the
+ * MetalAccountFactory whose clones are trusted.
+ */
+export type RequireSignedOfferConfig = { accountFactory?: Address } & ({ publicClient: PublicClient } | { rpcUrl: string });
+
+/**
+ * On a route whose offer asks for it (`extra.signedOffer: "required"`), a
+ * payment under a mandate must carry the agent's signed order, checked before
+ * the facilitator is asked: the payer's account binds the mandate the payment
+ * names, and the signed order is that mandate's key over the offer the
+ * server served, for this payee, buying its one line item (`extra.resource`
+ * when the route names one, else the payee). A refusal is a 402 whose reason
+ * names the check that failed, a payment that names no mandate included. A
+ * route that does not ask is left to the facilitator.
+ */
+export function requireSignedOffer(server: x402ResourceServer, config: RequireSignedOfferConfig): x402ResourceServer {
+  const publicClient = "publicClient" in config ? config.publicClient : createPublicClient({ transport: http(config.rpcUrl) });
+  const refuse = (reason: string) => ({ abort: true as const, reason });
+  // x402 treats a hook that throws as one that passed, so a check that cannot
+  // finish refuses the payment instead. The refusal reaches the payer, so it
+  // says nothing of the failure: a node's error can carry the endpoint's URL,
+  // and with it the endpoint's credential.
+  server.onBeforeVerify(async (context) => {
+    if (!asksSignedOffer(context.requirements)) return;
+    try {
+      return await checkSignedOffer(context);
+    } catch {
+      return refuse("the signed order could not be checked");
+    }
+  });
+  async function checkSignedOffer({ paymentPayload, requirements }: Parameters<Parameters<x402ResourceServer["onBeforeVerify"]>[0]>[0]) {
+    const ref = mandateRefOf(paymentPayload);
+    if (ref === "") return refuse("this offer is paid with the agent's signed order, which the payment lacks");
+    if (!isHex(ref) || ref.length !== 66) return refuse("the mandate reference is not 32 bytes");
+    const signedOffer = signedOfferOf(paymentPayload);
+    if (signedOffer === "") return refuse("the payment names a mandate but carries no signed order");
+    const payload = paymentPayload.payload as { signature?: unknown; authorization?: Record<string, unknown> };
+    const authorization = payload.authorization;
+    const from = authorization?.from;
+    if (typeof from !== "string" || !isAddress(from)) return refuse("the authorization names no payer account");
+    let accountFactory = config.accountFactory;
+    if (accountFactory === undefined) {
+      const network = metalNetwork(requirements.network);
+      if (network === undefined) return refuse(`${requirements.network} is not a Metal network, and no accountFactory was set`);
+      try { accountFactory = accountFactoryFor(network, undefined, "set accountFactory"); }
+      catch (error) { return refuse(error instanceof Error ? error.message : String(error)); }
+    }
+    try { await assertMetalAccount(publicClient, getAddress(from), accountFactory); }
+    catch { return refuse("the payer is not a MetalAccount of the trusted factory"); }
+    const bound = await readBoundAgentKey(publicClient, getAddress(from), ref as Hex);
+    if (bound === undefined) return refuse(`${from} binds no mandate ${ref}`);
+    const offer = x402Offer(requirements as unknown as Record<string, Json | undefined>);
+    let pull, fields;
+    try {
+      if (typeof payload.signature !== "string" || !isHex(payload.signature) || authorization === undefined) return refuse("the payment carries no mandate signature");
+      ({ pull, fields } = decodeMandateBlob(payload.signature));
+      if (String(authorization.nonce).slice(0, 26).toLowerCase() !== referencePrefix(ref as Hex).toLowerCase()) return refuse("the authorization nonce names another mandate");
+      if (pull.nonce.toLowerCase() !== String(authorization.nonce).toLowerCase()
+        || !isAddressEqual(pull.to, authorization.to as Address)
+        || !isAddressEqual(pull.to, requirements.payTo as Address)
+        || pull.value !== BigInt(String(authorization.value))
+        || pull.validAfter !== BigInt(String(authorization.validAfter))
+        || pull.validBefore !== BigInt(String(authorization.validBefore))
+        || !isAddressEqual(pull.token, requirements.asset as Address)) return refuse("the mandate signature does not describe the payment authorization");
+    } catch { return refuse("the payment carries a malformed mandate authorization"); }
+    // One check, each signature verified once: the signed order is this agent key's over the offer served, for this payee, and it is the order the payment names.
+    const check = verifyCheckoutMandate(signedOffer, {
+      agent: bound.agentKey, kid: bound.kid, payee: pull.to, offer, lineItemId: lineItemOf(offer), window: pull, transactionId: fields.transactionId, amount: pull.value,
+    });
+    return check.ok ? undefined : refuse(check.problems.join("; "));
+  }
+  return server;
+}