@metalntwx/metal-pay 0.2.0 → 0.3.0

package/src/mandates/vi/credential.ts

@@ -0,0 +1,477 @@
+// Verifiable Intent v0.1 credentials under Metal's L1 profile, as Mandate
+// Ingestion reads them. L1 is the issuer's credential under Metal's own `vct`,
+// binding the principal's key (`cnf.jwk`) to the principal's Metal account
+// (`sub`). L2 is the principal's autonomous-mode mandate pair: one open
+// checkout mandate and one open payment mandate, both naming the agent key in
+// `cnf.jwk`. What Mandate Binding enforces comes from the payment mandate;
+// the rest is descriptive and never enforced.
+//
+// Conventions fixed here for the chain:
+// - the payee is the Metal address in the payee object's `id`;
+// - the payment instrument is `{"type":"metal.mip20","id":<token>,…}`, a MIP20
+//   token from `INSTRUMENTS`, and amounts are integer minor units of its
+//   currency, `unitsPerMinor` token base units each;
+// - `agent_recurrence` dates are UTC: a `YYYY-MM-DD` start is 00:00:00Z of that
+//   day and a `YYYY-MM-DD` end is 23:59:59Z of that day, both inclusive; an
+//   RFC 3339 date-time with a `Z` or numeric offset is that instant; a
+//   date-time without an offset is refused;
+// - the budget is the L2's lifetime total: VI v0.1's `budget` caps spend
+//   over the whole mandate pair and never resets.
+
+import { type Address, type Hex, bytesToHex, getAddress, isAddress } from "viem";
+import type { AgentKey, Constraints, Terms } from "../binding.js";
+import { type Json, type JsonObject, jcs } from "../jcs.js";
+import { namesAddress } from "../l3a.js";
+import { USDZ } from "../../networks.js";
+import {
+  type P256Jwk,
+  type SdJwt,
+  compactJson,
+  decodeDisclosure,
+  decodeSdJwt,
+  fromB64url,
+  hashAscii,
+  jwkThumbprint,
+  jwkThumbprintBytes,
+  parseP256Jwk,
+  sha256Hex,
+  verifySdJwtSignature,
+} from "./sd-jwt.js";
+
+export type Credential = { format: "verifiable-intent"; version: "0.1"; layer1: string; layer2: string };
+
+/** Metal's L1 profile: the `vct` verifiers pass to the VI reference as `expected_l1_vct`. */
+export const METAL_L1_VCT = "https://credentials.metal.example/mandate";
+export const CHECKOUT_VCT = "mandate.checkout.open.1";
+export const PAYMENT_VCT = "mandate.payment.open.1";
+export const INSTRUMENT_TYPE = "metal.mip20";
+const ZERO_HASH: Hex = `0x${"00".repeat(32)}`;
+
+/**
+ * The payment instruments ingestion accepts: a MIP20 token, the ISO 4217
+ * currency its credential amounts are stated in, and the token's base units
+ * per minor unit. `*USDZ` (18 decimals) is dollar-denominated, 10^16 per cent.
+ */
+export const INSTRUMENTS = [{ token: USDZ.address as Address, currency: "USD", unitsPerMinor: 10n ** BigInt(USDZ.decimals - 2) }] as const;
+
+/** An issuer whose L1 credentials a verifier accepts: its `iss`, and the key its L1 header `kid` names. */
+export interface TrustedIssuer {
+  iss: string;
+  kid: string;
+  jwk: P256Jwk;
+}
+
+export type CredentialFailure =
+  | "MalformedCredential"
+  | "MalformedLayer"
+  | "UntrustedIssuer"
+  | "IssuerSignature"
+  | "PrincipalSignature"
+  | "SdHash"
+  | "Expired"
+  | "NotYetValid"
+  | "WrongAccount"
+  | "UndisclosedClaim"
+  | "MalformedMandate"
+  | "MissingConstraint"
+  | "Unenforceable";
+
+export class CredentialError extends Error {
+  constructor(
+    readonly reason: CredentialFailure,
+    detail: string,
+  ) {
+    super(`${reason}: ${detail}`);
+    this.name = "CredentialError";
+  }
+}
+
+function fail(reason: CredentialFailure, detail: string): never {
+  throw new CredentialError(reason, detail);
+}
+
+function isObject(value: Json | undefined): value is JsonObject {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function obj(value: Json | undefined, what: string, reason: CredentialFailure = "MalformedMandate"): JsonObject {
+  return isObject(value) ? value : fail(reason, `${what} must be an object`);
+}
+
+function list(value: Json | undefined, what: string): Json[] {
+  return Array.isArray(value) ? value : fail("MalformedMandate", `${what} must be an array`);
+}
+
+function str(o: JsonObject, key: string, reason: CredentialFailure = "MalformedMandate"): string {
+  const value = o[key];
+  return typeof value === "string" ? value : fail(reason, `${key} must be a string`);
+}
+
+function int(o: JsonObject, key: string, reason: CredentialFailure = "MalformedMandate"): number {
+  const value = o[key];
+  return typeof value === "number" && Number.isSafeInteger(value) ? value : fail(reason, `${key} must be an integer`);
+}
+
+function positive(o: JsonObject, key: string, what: string): bigint {
+  const value = o[key];
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0
+    ? BigInt(value)
+    : fail("MalformedMandate", `${what}.${key} must be a positive integer`);
+}
+
+function address(value: string, what: string): Address {
+  return isAddress(value, { strict: false }) ? getAddress(value) : fail("MalformedMandate", `${what} is not an address`);
+}
+
+export function parseCredential(json: unknown): Credential {
+  if (json === null || typeof json !== "object" || Array.isArray(json)) fail("MalformedCredential", "credential must be an object");
+  const keys = Object.keys(json).sort().join(",");
+  if (keys !== "format,layer1,layer2,version") fail("MalformedCredential", `expected format, version, layer1, layer2; got ${keys}`);
+  const { format, version, layer1, layer2 } = json as Record<string, unknown>;
+  if (format !== "verifiable-intent") fail("MalformedCredential", "format must be verifiable-intent");
+  if (version !== "0.1") fail("MalformedCredential", "version must be 0.1");
+  if (typeof layer1 !== "string" || typeof layer2 !== "string") fail("MalformedCredential", "layer1 and layer2 must be strings");
+  return { format, version, layer1, layer2 };
+}
+
+/** hash(C): SHA-256 over the RFC 8785 form of the whole credential. */
+export function hashCredential(c: Credential): Hex {
+  return sha256Hex(Buffer.from(jcs(c), "utf8"));
+}
+
+function p256Jwk(value: Json | undefined, what: string, reason: CredentialFailure): P256Jwk {
+  try {
+    return parseP256Jwk(obj(value, what, reason), what);
+  } catch (error) {
+    return fail(reason, error instanceof Error ? error.message : String(error));
+  }
+}
+
+/** A P-256 JWK as the typed agent key a mandate binds. */
+export function agentKeyOfJwk(jwk: P256Jwk): AgentKey {
+  return { x: bytesToHex(fromB64url(jwk.x)), y: bytesToHex(fromB64url(jwk.y)) };
+}
+
+/** The issuer key identifier `bind` records: the RFC 7638 thumbprint as 32 bytes. */
+export function issuerKeyId(jwk: P256Jwk): Hex {
+  return bytesToHex(jwkThumbprintBytes(jwk));
+}
+
+function decodeLayer(serialized: string, name: string, typ: string): SdJwt {
+  let sdJwt: SdJwt;
+  try {
+    sdJwt = decodeSdJwt(serialized);
+  } catch (error) {
+    return fail("MalformedLayer", `${name}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (sdJwt.header.alg !== "ES256" || sdJwt.header.typ !== typ) fail("MalformedLayer", `${name} header must be ES256 ${typ}`);
+  if (sdJwt.payload._sd_alg !== undefined && sdJwt.payload._sd_alg !== "sha-256") fail("MalformedLayer", `${name} _sd_alg must be sha-256`);
+  return sdJwt;
+}
+
+type Layers = { l1: SdJwt; l2: SdJwt };
+
+function decodeLayers(c: Credential): Layers {
+  const l1 = decodeLayer(c.layer1, "layer1", "sd+jwt");
+  if (l1.payload.vct !== METAL_L1_VCT) fail("MalformedLayer", `layer1 vct must be Metal's profile, ${METAL_L1_VCT}`);
+  return { l1, l2: decodeLayer(c.layer2, "layer2", "kb-sd-jwt+kb") };
+}
+
+type Disclosed = { encoded: string; value: Json[] };
+
+function disclosuresByHash(sdJwt: SdJwt, name: string): Map<string, Disclosed> {
+  const committed = new Set(Array.isArray(sdJwt.payload._sd) ? sdJwt.payload._sd : []);
+  const byHash = new Map<string, Disclosed>();
+  for (const encoded of sdJwt.disclosures) {
+    const hash = hashAscii(encoded);
+    if (!committed.has(hash)) fail("UndisclosedClaim", `${name} carries a disclosure absent from _sd`);
+    try {
+      byHash.set(hash, { encoded, value: decodeDisclosure(encoded) });
+    } catch (error) {
+      fail("MalformedLayer", `${name}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return byHash;
+}
+
+/**
+ * The payment mandate's constraints Mandate Binding evaluates, each with the
+ * members it may carry. `frequency` in `agent_recurrence` only guides timing
+ * in VI and is kept as descriptive. Anything else (a `min`, a merchant-managed
+ * `recurrence`, an unknown type or member) would narrow the agent's authority
+ * in a way the chain does not enforce, so ingestion refuses the credential.
+ */
+const EVALUABLE: Record<string, readonly string[]> = {
+  "mandate.payment.amount_range": ["type", "currency", "max"],
+  "mandate.payment.budget": ["type", "currency", "max"],
+  "mandate.payment.allowed_payees": ["type", "allowed"],
+  "mandate.payment.agent_recurrence": ["type", "frequency", "start_date", "end_date", "max_occurrences"],
+  "mandate.payment.reference": ["type", "conditional_transaction_id"],
+};
+
+const REQUIRED = ["mandate.payment.amount_range", "mandate.payment.budget", "mandate.payment.agent_recurrence"];
+
+function paymentConstraints(payment: JsonObject): Map<string, JsonObject> {
+  const byType = new Map<string, JsonObject>();
+  for (const c of list(payment.constraints, "payment constraints")) {
+    const constraint = obj(c, "a payment constraint");
+    const type = typeof constraint.type === "string" ? constraint.type : fail("MalformedMandate", "a constraint has no type");
+    const members = EVALUABLE[type] ?? fail("Unenforceable", `${type} is not a constraint Mandate Binding evaluates`);
+    const extra = Object.keys(constraint).filter((k) => !members.includes(k));
+    if (extra.length > 0) fail("Unenforceable", `${type} carries ${extra.join(", ")}, which Mandate Binding does not evaluate`);
+    if (byType.has(type)) fail("MalformedMandate", `more than one ${type} constraint`);
+    byType.set(type, constraint);
+  }
+  for (const type of REQUIRED) if (!byType.has(type)) fail("MissingConstraint", `a standing allowance must state ${type}`);
+  return byType;
+}
+
+const DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+
+/** A recurrence date as inclusive Unix seconds under the UTC convention in the header comment. */
+export function recurrenceBound(value: string, edge: "start" | "end"): bigint {
+  const date = DATE.exec(value);
+  if (date !== null) {
+    const ms = Date.UTC(Number(date[1]), Number(date[2]) - 1, Number(date[3]));
+    if (new Date(ms).toISOString().slice(0, 10) !== value) fail("MalformedMandate", `${value} is not a calendar date`);
+    return BigInt(ms / 1000 + (edge === "end" ? 86_399 : 0));
+  }
+  if (DATE_TIME.test(value)) {
+    // `Date.parse` moves a day past its month's end, or an hour of 24, to the
+    // next day; a bound is the instant the credential states or nothing.
+    const ms = Date.parse(value);
+    const [y, mo, d] = value.slice(0, 10).split("-").map(Number) as [number, number, number];
+    const sameDay = new Date(Date.UTC(y, mo - 1, d)).toISOString().slice(0, 10) === value.slice(0, 10);
+    if (Number.isNaN(ms) || !sameDay || Number(value.slice(11, 13)) > 23) fail("MalformedMandate", `${value} is not a date-time`);
+    return BigInt(edge === "start" ? Math.ceil(ms / 1000) : Math.floor(ms / 1000));
+  }
+  return fail("MalformedMandate", `agent_recurrence dates must be YYYY-MM-DD or an RFC 3339 date-time with an offset, not ${value}`);
+}
+
+/** The largest occurrence count, bound when `agent_recurrence` states no `max_occurrences`. */
+export const UNCAPPED_OCCURRENCES = 2n ** 256n - 1n;
+
+/** What a mandate binds from a credential, and what it keeps aside. */
+export interface MandateTerms {
+  /** L1 `sub`: the principal's Metal account. */
+  principal: Address;
+  agentKey: AgentKey;
+  agentJwk: P256Jwk & { kid: string };
+  constraints: Constraints;
+  terms: Terms;
+  /** L2's base JWT, which every L3a `sd_hash` covers. */
+  l2Base: string;
+  /** The L2 payment mandate disclosure, as serialised. */
+  paymentDisclosure: string;
+  /** The L2 checkout mandate disclosure, as serialised. */
+  checkoutDisclosure: string;
+  /** SHA-256 of the L2 checkout view a payee is given (`base ~ checkout disclosure ~ item disclosures ~`): every signed offer's `sd_hash`. */
+  checkoutSdHash: Hex;
+  /** Each allowed payee's L2 disclosure, as serialised, by account. */
+  payeeDisclosures: ReadonlyMap<Address, string>;
+  /** Fields no chain enforces, kept for disputes. */
+  descriptive: Record<string, Json>;
+}
+
+/**
+ * The most bytes a payee object or the payment instrument may serialise to.
+ * Every payment rebuilds its L3a around them, and a payment the facilitator
+ * relays has 1,000,000 gas: a 537-byte payee object measured 824,960 gas for
+ * a direct payment on Metal, a 1 KB one 933,217 and a 4 KB one 1,494,925.
+ */
+export const MAX_TERM_OBJECT_BYTES = 512;
+
+function bounded(serialised: string, what: string): string {
+  const bytes = Buffer.byteLength(serialised, "utf8");
+  return bytes <= MAX_TERM_OBJECT_BYTES ? serialised : fail("MalformedMandate", `${what} is ${bytes} bytes; at most ${MAX_TERM_OBJECT_BYTES}, so every payment fits the facilitator's gas`);
+}
+
+// A payee object or instrument is written into every L3a as L2 serialises it.
+// The reference writes each disclosure with json.dumps; requiring the decoded
+// disclosure to re-serialise to the same bytes makes the compact form of any
+// object inside it the reference's bytes for that object.
+function referenceSerialised(d: Disclosed, what: string): void {
+  if (compactJson(d.value) !== Buffer.from(fromB64url(d.encoded)).toString("utf8")) {
+    fail("MalformedMandate", `${what} is not serialised as the Verifiable Intent reference serialises it`);
+  }
+}
+
+function resolveTerms({ l1, l2 }: Layers, c: Credential): MandateTerms {
+  const l2Disclosures = disclosuresByHash(l2, "layer2");
+  const refHash = (ref: Json): string => {
+    const hash = obj(ref, "disclosure reference")["..."];
+    return typeof hash === "string" ? hash : fail("MalformedMandate", 'a disclosure reference must be {"...": hash}');
+  };
+  const resolve = (ref: Json): Disclosed => {
+    const entry = l2Disclosures.get(refHash(ref)) ?? fail("UndisclosedClaim", "a disclosure reference does not resolve");
+    if (entry.value.length !== 2) fail("MalformedMandate", "a referenced disclosure must be an array element");
+    return entry;
+  };
+  const valueOf = (d: Disclosed, what: string) => obj(d.value[1], what);
+
+  const delegates = list(l2.payload.delegate_payload, "delegate_payload");
+  if (delegates.length !== 2) fail("MalformedMandate", "delegate_payload must reference one checkout and one payment mandate");
+  const byVct = new Map(
+    delegates.map((ref) => {
+      const d = resolve(ref);
+      return [valueOf(d, "a delegated mandate").vct, { hash: refHash(ref), d }];
+    }),
+  );
+  const checkout = byVct.get(CHECKOUT_VCT) ?? fail("MalformedMandate", `delegate_payload lacks ${CHECKOUT_VCT}`);
+  const payment = byVct.get(PAYMENT_VCT) ?? fail("MalformedMandate", `delegate_payload lacks ${PAYMENT_VCT}`);
+  const checkoutMandate = valueOf(checkout.d, "the checkout mandate");
+  const paymentMandate = valueOf(payment.d, "the payment mandate");
+  referenceSerialised(payment.d, "the payment mandate disclosure");
+
+  const constraints = paymentConstraints(paymentMandate);
+  const get = (type: string) => constraints.get(type) as JsonObject;
+  if (str(get("mandate.payment.reference") ?? fail("MalformedMandate", "no mandate.payment.reference constraint"), "conditional_transaction_id") !== checkout.hash) {
+    fail("MalformedMandate", "the payment mandate's reference does not name the checkout mandate");
+  }
+
+  // A payment mandate without allowed_payees lets the agent pay any address;
+  // an empty list is not that (the format forbids reading it so), it is a mandate that pays nobody.
+  const payeeDisclosures = new Map<Address, string>();
+  const allowedPayees = get("mandate.payment.allowed_payees") as JsonObject | undefined;
+  const payees = (allowedPayees === undefined ? [] : list(allowedPayees.allowed, "allowed_payees")).map((ref) => {
+    const d = resolve(ref);
+    referenceSerialised(d, "a payee disclosure");
+    const object = valueOf(d, "a payee");
+    const account = address(str(object, "id"), "a payee id");
+    if (payeeDisclosures.has(account)) fail("MalformedMandate", `allowed_payees names ${account} twice`);
+    payeeDisclosures.set(account, d.encoded);
+    const serialised = bounded(compactJson(object), `the payee object for ${account}`);
+    if (!namesAddress(serialised, account)) fail("MalformedMandate", `the payee object for ${account} must name it in exactly one id member`);
+    return { account, object: serialised };
+  });
+  if (allowedPayees !== undefined && payees.length === 0) fail("MalformedMandate", "allowed_payees is empty");
+
+  const checkoutJwk = obj(obj(checkoutMandate.cnf, "checkout cnf").jwk, "checkout cnf.jwk");
+  const paymentJwk = obj(obj(paymentMandate.cnf, "payment cnf").jwk, "payment cnf.jwk");
+  const agentJwk = { ...p256Jwk(paymentJwk, "payment cnf.jwk", "MalformedMandate"), kid: str(paymentJwk, "kid") };
+  if (agentJwk.kid !== jwkThumbprint(agentJwk)) fail("MalformedMandate", "the mandate key's kid is not its RFC 7638 thumbprint");
+  if (jcs(checkoutJwk) !== jcs(paymentJwk)) fail("MalformedMandate", "the checkout and payment mandates name different mandate keys");
+  if (l2.payload.aud !== agentJwk.kid) fail("MalformedMandate", "layer2 aud is not the mandate key's kid");
+  if (/["\\]|[^\x20-\x7e]/.test(agentJwk.kid)) fail("MalformedMandate", "the mandate key's kid is not printable ASCII");
+
+  const instrumentObject = obj(paymentMandate.payment_instrument, "payment_instrument");
+  if (instrumentObject.type !== INSTRUMENT_TYPE) fail("MalformedMandate", `payment_instrument.type must be ${INSTRUMENT_TYPE}`);
+  const token = address(str(instrumentObject, "id"), "payment_instrument.id");
+  const instrument = INSTRUMENTS.find((i) => i.token.toLowerCase() === token.toLowerCase()) ?? fail("MalformedMandate", `payment_instrument.id ${token} is not a known token`);
+  if (!namesAddress(bounded(compactJson(instrumentObject), "payment_instrument"), token)) fail("MalformedMandate", "payment_instrument must name its token in exactly one id member");
+  const amountRange = get("mandate.payment.amount_range");
+  const budget = get("mandate.payment.budget");
+  for (const [name, c] of [["amount_range", amountRange], ["budget", budget]] as const) {
+    if (c.currency !== instrument.currency) fail("MalformedMandate", `${name} currency must be ${instrument.currency}`);
+  }
+  const recurrence = get("mandate.payment.agent_recurrence");
+  const recurrenceStart = recurrenceBound(str(recurrence, "start_date"), "start");
+  const recurrenceEnd = recurrenceBound(str(recurrence, "end_date"), "end");
+  if (recurrenceStart > recurrenceEnd) fail("MalformedMandate", "agent_recurrence ends before it starts");
+  const maxOccurrences = recurrence.max_occurrences === undefined ? UNCAPPED_OCCURRENCES : positive(recurrence, "max_occurrences", "agent_recurrence");
+
+  const iat = int(l2.payload, "iat", "MalformedLayer");
+  const exp = int(l2.payload, "exp", "MalformedLayer");
+  if (exp <= iat) fail("MalformedLayer", "layer2 exp must follow iat");
+  const principal = address(str(l1.payload, "sub", "MalformedLayer"), "layer1 sub");
+  const l2Base = c.layer2.split("~")[0] as string;
+  const paymentDisclosure = payment.d.encoded;
+
+  const itemsOf = (c: Json) => (isObject(c) && c.type === "mandate.checkout.line_items" ? c.items ?? null : null);
+  // The checkout view: the checkout disclosure, then each acceptable item the
+  // checkout mandate references by disclosure, in its own order.
+  const itemDisclosures: string[] = [];
+  for (const c of list(checkoutMandate.constraints ?? [], "checkout constraints")) {
+    for (const entry of list(itemsOf(c) ?? [], "line items")) {
+      for (const ref of list(obj(entry, "a line item").acceptable_items ?? [], "acceptable_items")) {
+        if (isObject(ref) && typeof ref["..."] === "string") itemDisclosures.push(resolve(ref).encoded);
+      }
+    }
+  }
+  const checkoutDisclosure = checkout.d.encoded;
+  const checkoutSdHash = sha256Hex(Buffer.from([l2Base, checkoutDisclosure, ...itemDisclosures].join("~") + "~", "ascii"));
+  return {
+    principal,
+    agentKey: agentKeyOfJwk(agentJwk),
+    agentJwk,
+    constraints: {
+      token: instrument.token,
+      perPaymentCap: positive(amountRange, "max", "amount_range") * instrument.unitsPerMinor,
+      budget: positive(budget, "max", "budget") * instrument.unitsPerMinor,
+      expiry: BigInt(Math.min(exp, int(l1.payload, "exp", "MalformedLayer"))),
+      recurrenceStart,
+      recurrenceEnd,
+      maxOccurrences,
+    },
+    terms: {
+      kid: agentJwk.kid,
+      instrument: compactJson(instrumentObject),
+      currency: instrument.currency,
+      unitsPerMinor: instrument.unitsPerMinor,
+      payees: payees.map(({ account, object }) => ({
+        account,
+        object,
+        sdHash: sha256Hex(Buffer.from(`${l2Base}~${paymentDisclosure}~${payeeDisclosures.get(account)}~`, "ascii")),
+      })),
+      openSdHash: allowedPayees === undefined ? sha256Hex(Buffer.from(`${l2Base}~${paymentDisclosure}~`, "ascii")) : ZERO_HASH,
+    },
+    l2Base,
+    paymentDisclosure,
+    checkoutDisclosure,
+    checkoutSdHash,
+    payeeDisclosures,
+    descriptive: {
+      issuer: l1.payload.iss ?? null,
+      promptSummary: checkoutMandate.prompt_summary ?? null,
+      lineItems: list(checkoutMandate.constraints ?? [], "checkout constraints").map(itemsOf).find((i) => i !== null) ?? null,
+      frequency: recurrence.frequency ?? null,
+      instrument: instrumentObject,
+      payees: payees.map(({ object }) => JSON.parse(object) as Json),
+      issuedAt: iat,
+    },
+  };
+}
+
+/**
+ * The terms a credential states, without verifying its signatures: the
+ * principal, the agent key, the constraints Mandate Binding enforces and the
+ * rebuild terms. Throws `CredentialError` naming the first failure.
+ */
+export function extractTerms(c: Credential): MandateTerms {
+  return resolveTerms(decodeLayers(c), c);
+}
+
+/**
+ * Verifies a credential off chain as the VI reference does under Metal's L1
+ * profile: L1 under a trusted issuer's key (its `iss` and header `kid` select
+ * the key), L1's `sub` the account being bound, L2 under the principal key L1
+ * binds, L2's `sd_hash` binding L1, both layers valid at `now`, and terms
+ * Mandate Binding can enforce. Returns the issuer and the terms.
+ */
+export async function verifyCredential(
+  c: Credential,
+  opts: { trustedIssuers: readonly TrustedIssuer[]; account: Address; now?: number },
+): Promise<{ issuer: TrustedIssuer; terms: MandateTerms }> {
+  const now = opts.now ?? Math.floor(Date.now() / 1000);
+  const layers = decodeLayers(c);
+  const { l1, l2 } = layers;
+  const iss = str(l1.payload, "iss", "MalformedLayer");
+  const kid = l1.header.kid;
+  const issuer = opts.trustedIssuers.find((i) => i.iss === iss && i.kid === kid) ?? fail("UntrustedIssuer", `no trusted issuer ${iss} with key ${String(kid)}`);
+  if (!(await verifySdJwtSignature(l1, issuer.jwk))) fail("IssuerSignature", "layer1 does not verify under the issuer key");
+  const principalJwk = p256Jwk(obj(l1.payload.cnf, "layer1 cnf", "MalformedLayer").jwk, "layer1 cnf.jwk", "MalformedLayer");
+  if (!(await verifySdJwtSignature(l2, principalJwk))) fail("PrincipalSignature", "layer2 does not verify under layer1 cnf.jwk");
+  if (str(l2.payload, "sd_hash", "SdHash") !== hashAscii(c.layer1)) fail("SdHash", "layer2 sd_hash does not bind layer1");
+  for (const [name, payload] of [["layer1", l1.payload], ["layer2", l2.payload]] as const) {
+    if (now > int(payload, "exp", "MalformedLayer")) fail("Expired", `${name} expired`);
+    if (now < int(payload, "iat", "MalformedLayer")) fail("NotYetValid", `${name} issued in the future`);
+  }
+  const terms = resolveTerms(layers, c);
+  if (terms.principal.toLowerCase() !== opts.account.toLowerCase()) fail("WrongAccount", `layer1 sub ${terms.principal} is not the account ${opts.account}`);
+  // What binding refuses as a mandate nothing could ever be paid under.
+  const { recurrenceStart, recurrenceEnd, expiry } = terms.constraints;
+  if (recurrenceStart > expiry) fail("MalformedMandate", "agent_recurrence starts after the mandate expires");
+  if (recurrenceEnd < BigInt(now)) fail("Expired", "the agent_recurrence window has ended");
+  return { issuer, terms };
+}

package/src/mandates/vi/issue.ts

@@ -0,0 +1,118 @@
+// Issuing a Verifiable Intent v0.1 credential under Metal's L1 profile, laid
+// out as the VI reference lays out an autonomous-mode credential: the
+// developer path's self-issued credential, and the test fixtures. A PSP
+// issuing for its customers produces the same layers with its own keys.
+
+import { randomBytes } from "node:crypto";
+import { type Address, getAddress } from "viem";
+import type { Json, JsonObject } from "../jcs.js";
+import { METAL_L1_VCT, CHECKOUT_VCT, type Credential, INSTRUMENTS, INSTRUMENT_TYPE, PAYMENT_VCT, type TrustedIssuer } from "./credential.js";
+import { type Es256Key, type P256Jwk, b64url, createDisclosure, hashAscii, jwkThumbprint, signSdJwt } from "./sd-jwt.js";
+
+export interface CredentialParams {
+  /** The issuer's `iss` and signing key; on the developer path, the developer's own. */
+  issuer: { iss: string; key: Es256Key };
+  /** The principal's Metal account: L1 `sub`, and the account the mandate binds on. */
+  principal: Address;
+  /** The principal's device key, which signs L2. */
+  principalKey: Es256Key;
+  agentKey: P256Jwk;
+  /** Decimal amounts in the instrument's currency, e.g. "10.00". */
+  perPaymentCap: string;
+  budget: string;
+  /** The addresses the agent may pay; none lets it pay any address within the other limits. */
+  payees: readonly { address: Address; name: string; website: string }[];
+  /** `agent_recurrence`: dates as `YYYY-MM-DD` (UTC days) or RFC 3339 date-times with an offset. */
+  recurrence: { frequency: string; startDate: string; endDate: string; maxOccurrences?: number };
+  expiresAt: number;
+  issuedAt?: number;
+  description: string;
+}
+
+export function trustedIssuer(issuer: CredentialParams["issuer"]): TrustedIssuer {
+  return { iss: issuer.iss, kid: issuer.key.kid, jwk: issuer.key.publicJwk };
+}
+
+// "10.00" to integer minor units; more fractional digits than the currency has is an error.
+function minorUnits(value: string, what: string): number {
+  const digits = 2;
+  const match = /^(\d+)(?:\.(\d+))?$/.exec(value);
+  if (match === null || (match[2] ?? "").length > digits) throw new Error(`${what} must be a decimal amount with at most ${digits} decimals`);
+  const units = Number(match[1]) * 10 ** digits + Number((match[2] ?? "").padEnd(digits, "0") || "0");
+  if (!Number.isSafeInteger(units) || units <= 0) throw new Error(`${what} must be positive`);
+  return units;
+}
+
+export async function createCredential(params: CredentialParams): Promise<Credential> {
+  const iat = params.issuedAt ?? Math.floor(Date.now() / 1000);
+  if (params.expiresAt <= iat) throw new Error("expiresAt must follow issuedAt");
+  const [instrument] = INSTRUMENTS;
+  const { kty, crv, x, y } = params.agentKey;
+  const jwk = { kty, crv, x, y, kid: jwkThumbprint(params.agentKey) };
+  const subject = getAddress(params.principal);
+
+  const layer1 = await signSdJwt(
+    { alg: "ES256", typ: "sd+jwt", kid: params.issuer.key.kid },
+    { iss: params.issuer.iss, sub: subject, iat, exp: params.expiresAt, vct: METAL_L1_VCT, cnf: { jwk: params.principalKey.publicJwk }, _sd: [], _sd_alg: "sha-256" },
+    [],
+    params.issuer.key.privateJwk,
+  );
+
+  const merchantDisclosures = params.payees.map((p) => createDisclosure({ id: getAddress(p.address), name: p.name, website: p.website }));
+  const merchantRefs: Json[] = merchantDisclosures.map((d) => ({ "...": hashAscii(d) }));
+  // A mandate with no payees omits allowed_merchants and allowed_payees: the format reads an empty
+  // allowlist as nobody, and an absent one as anyone.
+  const listed = merchantRefs.length > 0;
+  const checkout: JsonObject = {
+    vct: CHECKOUT_VCT,
+    cnf: { jwk },
+    constraints: [
+      ...(listed ? [{ type: "mandate.checkout.allowed_merchants", allowed: merchantRefs }] : []),
+      // The reference requires a line_items constraint on every open checkout mandate; an empty
+      // acceptable_items list is the spec's wildcard, so any item from the allowed payees.
+      { type: "mandate.checkout.line_items", items: [{ id: "line-1", acceptable_items: [], quantity: 1 }], match_mode: "minimum" },
+    ],
+    prompt_summary: params.description,
+  };
+  const checkoutDisclosure = createDisclosure(checkout);
+  const { frequency, startDate, endDate, maxOccurrences } = params.recurrence;
+  const payment: JsonObject = {
+    vct: PAYMENT_VCT,
+    cnf: { jwk },
+    constraints: [
+      { type: "mandate.payment.amount_range", currency: instrument.currency, max: minorUnits(params.perPaymentCap, "perPaymentCap") },
+      ...(listed ? [{ type: "mandate.payment.allowed_payees", allowed: merchantRefs }] : []),
+      { type: "mandate.payment.budget", currency: instrument.currency, max: minorUnits(params.budget, "budget") },
+      {
+        type: "mandate.payment.agent_recurrence",
+        frequency,
+        start_date: startDate,
+        end_date: endDate,
+        ...(maxOccurrences === undefined ? {} : { max_occurrences: maxOccurrences }),
+      },
+      { type: "mandate.payment.reference", conditional_transaction_id: hashAscii(checkoutDisclosure) },
+    ],
+    payment_instrument: { type: INSTRUMENT_TYPE, id: instrument.token, description: "*USDZ on Metal" },
+  };
+  const paymentDisclosure = createDisclosure(payment);
+  const l2Disclosures = [...merchantDisclosures, checkoutDisclosure, paymentDisclosure];
+
+  const layer2 = await signSdJwt(
+    { alg: "ES256", typ: "kb-sd-jwt+kb", kid: params.principalKey.kid },
+    {
+      nonce: b64url(randomBytes(16)),
+      aud: jwk.kid,
+      iat,
+      sd_hash: hashAscii(layer1),
+      delegate_payload: [{ "...": hashAscii(checkoutDisclosure) }, { "...": hashAscii(paymentDisclosure) }],
+      _sd_alg: "sha-256",
+      _sd: l2Disclosures.map(hashAscii),
+      iss: subject,
+      exp: params.expiresAt,
+    },
+    l2Disclosures,
+    params.principalKey.privateJwk,
+  );
+
+  return { format: "verifiable-intent", version: "0.1", layer1, layer2 };
+}