@metalntwx/metal-pay 0.2.0 → 0.3.0

package/src/mandates/vi/sd-jwt.ts

@@ -0,0 +1,189 @@
+// SD-JWT as Verifiable Intent v0.1 uses it: ES256 over the compact form,
+// SHA-256 disclosure digests, base64url throughout, JSON written as the
+// reference's Python `json.dumps(separators=(",", ":"))` writes it.
+
+import { createHash, randomBytes, webcrypto } from "node:crypto";
+import { p256 } from "@noble/curves/nist";
+import { type Hex, bytesToHex, concat, hexToBytes, numberToHex } from "viem";
+import type { Json, JsonObject } from "../jcs.js";
+
+export type P256Jwk = { kty: "EC"; crv: "P-256"; x: string; y: string };
+export type P256PrivateJwk = P256Jwk & { d: string };
+
+/** A P-256 key pair with the `kid` its signatures name. */
+export type Es256Key = { kid: string; publicJwk: P256Jwk; privateJwk: P256PrivateJwk };
+
+export type SdJwt = {
+  header: JsonObject;
+  payload: JsonObject;
+  /** `b64(header) "." b64(payload)` as serialised. */
+  signingInput: string;
+  signature: Uint8Array;
+  disclosures: string[];
+};
+
+export function b64url(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString("base64url");
+}
+
+export function fromB64url(text: string): Uint8Array {
+  if (!/^[A-Za-z0-9_-]*$/.test(text)) throw new Error("not base64url");
+  return new Uint8Array(Buffer.from(text, "base64url"));
+}
+
+export function sha256(bytes: Uint8Array | string): Uint8Array {
+  return new Uint8Array(createHash("sha256").update(bytes).digest());
+}
+
+export function sha256Hex(bytes: Uint8Array | string): Hex {
+  return bytesToHex(sha256(bytes));
+}
+
+/** base64url(SHA-256(ASCII text)): a disclosure's digest, and `sd_hash` over a serialised SD-JWT. */
+export function hashAscii(text: string): string {
+  return b64url(sha256(Buffer.from(text, "ascii")));
+}
+
+/** base64url of `text`'s ASCII bytes: a JWS segment or a disclosure. */
+export function b64Ascii(text: string): string {
+  return b64url(Buffer.from(text, "ascii"));
+}
+
+/** An EC P-256 public JWK, its coordinates 32 bytes each; throws naming `what` otherwise. */
+export function parseP256Jwk(value: unknown, what: string): P256Jwk {
+  const o = (typeof value === "object" && value !== null ? value : {}) as Record<string, unknown>;
+  const coordinate = (c: unknown): c is string => typeof c === "string" && /^[A-Za-z0-9_-]{43}$/.test(c) && fromB64url(c).length === 32;
+  if (o.kty !== "EC" || o.crv !== "P-256" || !coordinate(o.x) || !coordinate(o.y)) throw new Error(`${what} must be an EC P-256 public key`);
+  return { kty: "EC", crv: "P-256", x: o.x, y: o.y };
+}
+
+/**
+ * Python's `json.dumps(value, separators=(",", ":"))` with its default
+ * `ensure_ascii`: every character outside printable ASCII escaped as `\uXXXX`.
+ * The VI reference writes every JWT segment and disclosure this way and
+ * re-encodes decoded segments this way before checking a signature.
+ */
+export function compactJson(value: Json): string {
+  return JSON.stringify(value).replace(/[\u007f-￿]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+
+/** RFC 7638: SHA-256 over the required EC members in lexicographic order. */
+export function jwkThumbprintBytes({ crv, kty, x, y }: P256Jwk): Uint8Array {
+  return sha256(Buffer.from(JSON.stringify({ crv, kty, x, y }), "utf8"));
+}
+
+/** The RFC 7638 thumbprint, base64url: an agent key's `kid`. */
+export function jwkThumbprint(jwk: P256Jwk): string {
+  return b64url(jwkThumbprintBytes(jwk));
+}
+
+export function randomSalt(): string {
+  return b64url(randomBytes(16));
+}
+
+export function createDisclosure(value: Json, claimName?: string, salt: string = randomSalt()): string {
+  const entry: Json[] = claimName === undefined ? [salt, value] : [salt, claimName, value];
+  return b64url(Buffer.from(compactJson(entry), "ascii"));
+}
+
+export function decodeDisclosure(disclosure: string): Json[] {
+  const value: unknown = JSON.parse(Buffer.from(fromB64url(disclosure)).toString("utf8"));
+  if (!Array.isArray(value) || (value.length !== 2 && value.length !== 3) || typeof value[0] !== "string") {
+    throw new Error("disclosure is not [salt, value] or [salt, name, value]");
+  }
+  return value;
+}
+
+export function signingInputOf(header: JsonObject, payload: JsonObject): string {
+  return `${b64url(Buffer.from(compactJson(header), "ascii"))}.${b64url(Buffer.from(compactJson(payload), "ascii"))}`;
+}
+
+/** `jwt~d1~…~dn~`, the SD-JWT compact serialisation. */
+export function serializeSdJwt(signingInput: string, signature: Uint8Array, disclosures: readonly string[]): string {
+  return `${[`${signingInput}.${b64url(signature)}`, ...disclosures].join("~")}~`;
+}
+
+const ES256 = { name: "ECDSA", namedCurve: "P-256" } as const;
+const ES256_SIGN = { name: "ECDSA", hash: "SHA-256" } as const;
+
+export async function es256Sign(signingInput: string, privateJwk: P256PrivateJwk): Promise<Uint8Array> {
+  const key = await webcrypto.subtle.importKey("jwk", privateJwk, ES256, false, ["sign"]);
+  return new Uint8Array(await webcrypto.subtle.sign(ES256_SIGN, key, Buffer.from(signingInput, "ascii")));
+}
+
+export async function es256Verify(signingInput: string, signature: Uint8Array, publicJwk: P256Jwk): Promise<boolean> {
+  const { kty, crv, x, y } = publicJwk;
+  try {
+    const key = await webcrypto.subtle.importKey("jwk", { kty, crv, x, y }, ES256, false, ["verify"]);
+    return await webcrypto.subtle.verify(ES256_SIGN, key, Buffer.from(signature), Buffer.from(signingInput, "ascii"));
+  } catch {
+    return false;
+  }
+}
+
+export async function signSdJwt(header: JsonObject, payload: JsonObject, disclosures: string[], privateJwk: P256PrivateJwk): Promise<string> {
+  const signingInput = signingInputOf(header, payload);
+  return serializeSdJwt(signingInput, await es256Sign(signingInput, privateJwk), disclosures);
+}
+
+function jsonObject(segment: string): JsonObject {
+  const value: unknown = JSON.parse(Buffer.from(fromB64url(segment)).toString("utf8"));
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("JWT segment is not a JSON object");
+  return value as JsonObject;
+}
+
+export function decodeSdJwt(serialized: string): SdJwt {
+  if (!serialized.endsWith("~")) throw new Error("SD-JWT must end with ~");
+  const [jwt = "", ...disclosures] = serialized.slice(0, -1).split("~");
+  const segments = jwt.split(".");
+  if (segments.length !== 3) throw new Error("JWT must have three segments");
+  const [header = "", payload = "", signature = ""] = segments;
+  if (disclosures.some((d) => d.length === 0)) throw new Error("empty disclosure");
+  return {
+    header: jsonObject(header),
+    payload: jsonObject(payload),
+    signingInput: `${header}.${payload}`,
+    signature: fromB64url(signature),
+    disclosures,
+  };
+}
+
+/**
+ * The reference's signature check: re-encode the decoded header and payload
+ * compactly and verify over that, so a segment serialised any other way
+ * fails, as it does in the reference.
+ */
+export async function verifySdJwtSignature(sdJwt: SdJwt, publicJwk: P256Jwk): Promise<boolean> {
+  return es256Verify(signingInputOf(sdJwt.header, sdJwt.payload), sdJwt.signature, publicJwk);
+}
+
+/** A fresh P-256 key. An agent key's `kid` is its RFC 7638 thumbprint, the name a credential gives it. */
+export async function createEs256Key(kid?: string): Promise<Es256Key> {
+  const { privateKey } = await webcrypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]);
+  const { x, y, d } = await webcrypto.subtle.exportKey("jwk", privateKey);
+  if (x === undefined || y === undefined || d === undefined) throw new Error("webcrypto exported an incomplete P-256 JWK");
+  const publicJwk: P256Jwk = { kty: "EC", crv: "P-256", x, y };
+  return { kid: kid ?? jwkThumbprint(publicJwk), publicJwk, privateJwk: { ...publicJwk, d } };
+}
+
+/** The raw private scalar of an `Es256Key`, for `p256DigestSigner`. */
+export function privateKeyHex(key: Es256Key): Hex {
+  return bytesToHex(fromB64url(key.privateJwk.d));
+}
+
+/** Signs a 32-byte SHA-256 digest with a P-256 key, returning `r ‖ s`. */
+export type SignDigest = (digest: Hex) => Promise<Hex>;
+
+/**
+ * ES256 over a signing input whose SHA-256 is `digest`, as the P-256
+ * precompile verifies it (the digest is the message hash, not hashed again),
+ * with `s` in the lower half of the curve order.
+ */
+export function p256DigestSigner(privateKey: Hex): SignDigest {
+  const d = hexToBytes(privateKey);
+  if (d.length !== 32) throw new Error("a P-256 private key is 32 bytes");
+  return async (digest) => {
+    const signature = p256.sign(hexToBytes(digest), d, { prehash: false, lowS: true });
+    return concat([numberToHex(signature.r, { size: 32 }), numberToHex(signature.s, { size: 32 })]);
+  };
+}

package/src/networks.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { METAL_NETWORKS, rpcUrlFor } from "./networks.js";
+
+describe("rpcUrlFor", () => {
+  it("prefers the override, then the network's default RPC", () => {
+    expect(rpcUrlFor(METAL_NETWORKS.devnet, undefined, "set RPC")).toBe("http://127.0.0.1:8545");
+    expect(rpcUrlFor(METAL_NETWORKS.devnet, "http://override", "set RPC")).toBe("http://override");
+    expect(rpcUrlFor(METAL_NETWORKS.testnet, "http://override", "set RPC")).toBe("http://override");
+  });
+
+  it("says how to get an endpoint of your own on a network without a default", () => {
+    expect(() => rpcUrlFor(METAL_NETWORKS.testnet, undefined, "set METAL_RPC_URL")).toThrow(
+      new Error(`testnet needs an RPC endpoint of your own: sign up at https://console-testnet.metalntwx.com, create an endpoint, then set METAL_RPC_URL`),
+    );
+  });
+});

package/src/networks.ts

@@ -0,0 +1,152 @@
+import type { Network } from "@x402/core/types";
+import type { Address } from "viem";
+
+export type MetalNetworkName = "devnet" | "testnet";
+
+export interface MetalNetwork {
+  name: MetalNetworkName;
+  /** CAIP-2 identifier, the `network` field of every x402 message. */
+  network: Network;
+  chainId: number;
+  /**
+   * The default JSON-RPC endpoint, or, on a network where each user brings an
+   * endpoint of their own, the console that issues them.
+   */
+  rpc: { url: string } | { consoleUrl: string };
+  /**
+   * Metal's x402 facilitator for this network, the URL an `HTTPFacilitatorClient`
+   * verifies and settles through. On devnet it is the one `just x402-facilitator`
+   * runs on this machine.
+   */
+  facilitatorUrl: string;
+  /**
+   * The MetalAccountFactory whose clones hold mandates, the trust anchor a
+   * seller and a verifier check a principal's code against. On devnet it is
+   * the first transaction of Anvil dev account #10, which `just deploy` and
+   * the e2e send; that key is public, so a public network deploys
+   * `contracts/script/DeployMetalAccount.s.sol` from a key its operator holds
+   * and records the address here. A network without one takes the address
+   * from the caller. Verifying a payment made under another factory, such as
+   * one from before a network reset, takes that factory from the caller too.
+   */
+  accountFactory?: Address;
+}
+
+/**
+ * The MetalAccountFactory to trust on `network`: `override` when given, else
+ * the network's own. On a network with neither it throws, saying how the
+ * caller passes one (`how`, such as "pass --factory").
+ */
+export function accountFactoryFor(network: MetalNetwork, override: Address | undefined, how: string): Address {
+  if (override !== undefined) return override;
+  if (network.accountFactory !== undefined) return network.accountFactory;
+  throw new Error(`${network.name} names no MetalAccountFactory; ${how}`);
+}
+
+/**
+ * `devnet` is the chain `just devnet` runs on this machine; `testnet` is the
+ * hosted Metal testnet.
+ */
+export const METAL_NETWORKS: Record<MetalNetworkName, MetalNetwork> = {
+  devnet: {
+    name: "devnet",
+    network: "eip155:1337",
+    chainId: 1337,
+    rpc: { url: "http://127.0.0.1:8545" },
+    facilitatorUrl: "http://127.0.0.1:7090/x402/facilitator",
+    // Anvil account #10's first transaction, which `just deploy` and the e2e send.
+    accountFactory: "0xfbfbfDdd6e35dA57b7B0F9a2C10E34Be70B3A4E9",
+  },
+  testnet: {
+    name: "testnet",
+    network: "eip155:63825",
+    chainId: 63825,
+    rpc: { consoleUrl: "https://console-testnet.metalntwx.com" },
+    facilitatorUrl: "https://x402-testnet.metalntwx.com/x402/facilitator",
+    // What `just estate-deploy-account-factory testnet` recorded in
+    // deploy/estate/environments/testnet/account-factory.json for this chain.
+    accountFactory: "0x4D188AC7815a9EAEa219a49D687B71898A487578",
+  },
+};
+
+/** Resolve a name or a CAIP-2 identifier to a Metal network; undefined for any other chain. */
+export function metalNetwork(nameOrNetwork: string): MetalNetwork | undefined {
+  return Object.values(METAL_NETWORKS).find(
+    (n) => n.name === nameOrNetwork || n.network === nameOrNetwork,
+  );
+}
+
+/** A network name or a `MetalNetwork` as a `MetalNetwork`; throws for any other name. */
+export function resolveNetwork(entry: MetalNetworkName | MetalNetwork): MetalNetwork {
+  if (typeof entry !== "string") return entry;
+  const found = metalNetwork(entry);
+  if (!found) throw new Error(`unknown Metal network: ${entry}`);
+  return found;
+}
+
+/**
+ * The JSON-RPC endpoint to reach `network` at: `override` when given, else the
+ * network's default. On a network without a default and no override it throws,
+ * saying how to get an endpoint from the console and, using `how` ("set
+ * METAL_RPC_URL"), how the caller passes it.
+ */
+export function rpcUrlFor(network: MetalNetwork, override: string | undefined, how: string): string {
+  if (override !== undefined) return override;
+  if ("url" in network.rpc) return network.rpc.url;
+  throw new Error(
+    `${network.name} needs an RPC endpoint of your own: sign up at ${network.rpc.consoleUrl}, create an endpoint, then ${how}`,
+  );
+}
+
+/** A dollar token payers authorize ERC-3009 transfers of. */
+export interface DollarToken {
+  address: `0x${string}`;
+  symbol: string;
+  /** MIP20 `name()`: the EIP-712 domain name ERC-3009 signatures use. */
+  name: string;
+  /** MIP20's constant EIP-712 domain version. */
+  version: string;
+  decimals: number;
+}
+
+/** The default gas token and the asset every offer here is priced in. */
+export const USDZ = {
+  address: "0x000000000000000000000000000000000000B5d5",
+  symbol: "*USDZ",
+  name: "USD Zero",
+  version: "1",
+  decimals: 18,
+} as const satisfies DollarToken;
+
+/**
+ * Convert a decimal amount of `token` ("0.01", 2, "$1.50") to base units as
+ * the string x402 requirements carry. Rejects more fractional digits than
+ * the token has; money is never rounded.
+ */
+export function baseUnits(amount: string | number, token: DollarToken): string {
+  const text = String(amount).trim().replace(/^\$/, "");
+  const match = /^(\d+)(?:\.(\d+))?$/.exec(text);
+  if (!match) throw new Error(`not a decimal ${token.symbol} amount: ${String(amount)}`);
+  const whole = match[1] ?? "0";
+  const fraction = match[2] ?? "";
+  if (fraction.length > token.decimals) {
+    throw new Error(`${token.symbol} has ${token.decimals} decimals; ${text} has ${fraction.length}`);
+  }
+  const units = BigInt(whole) * 10n ** BigInt(token.decimals) +
+    BigInt(fraction.padEnd(token.decimals, "0") || "0");
+  return units.toString();
+}
+
+/** `baseUnits` in `*USDZ`. */
+export function usdzBaseUnits(amount: string | number): string {
+  return baseUnits(amount, USDZ);
+}
+
+/** Format base units back to a decimal `*USDZ` string for humans, trailing zeros trimmed. */
+export function formatUsdz(amount: bigint | string): string {
+  const units = BigInt(amount);
+  const scale = 10n ** BigInt(USDZ.decimals);
+  const whole = units / scale;
+  const fraction = (units % scale).toString().padStart(USDZ.decimals, "0").replace(/0+$/, "");
+  return fraction ? `${whole}.${fraction}` : whole.toString();
+}

package/src/node.test.ts

@@ -0,0 +1,24 @@
+import { it, expect } from "vitest";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { openClearingWallet } from "./node.js";
+it("retains one account and its payment state across restart, with exclusive ownership", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "clearing-wallet-"));
+  try {
+    const wallet = await openClearingWallet(directory);
+    const publicKey = wallet.signer.publicKey;
+    await expect(openClearingWallet(directory)).rejects.toThrow(
+      "already in use",
+    );
+    const state = { entries: [], sequence: "0", payments: {} };
+    await wallet.store.save(state);
+    await wallet.close();
+    const reopened = await openClearingWallet(directory);
+    expect(reopened.signer.publicKey).toBe(publicKey);
+    expect(await reopened.store.load()).toEqual(state);
+    await reopened.close();
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});

package/src/node.ts

@@ -0,0 +1,96 @@
+import { DatabaseSync } from "node:sqlite";
+import { mkdir, open, readFile, rename } from "node:fs/promises";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { createClearingSigner } from "./clearing-codec.js";
+import type {
+  ClearingClientState,
+  ClearingClientStore,
+} from "./clearing-client.js";
+import type { Hex } from "viem";
+
+/** A persistent P-256 account and receipt journal for a single server process. */
+export async function openClearingWallet(directory: string) {
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  // SQLite holds an OS lock for the wallet lifetime and releases it on crash.
+  const owner = new DatabaseSync(join(directory, "owner.sqlite"));
+  try {
+    owner.exec(
+      "PRAGMA locking_mode=EXCLUSIVE; BEGIN EXCLUSIVE; CREATE TABLE IF NOT EXISTS owner (id INTEGER)",
+    );
+  } catch (error) {
+    owner.close();
+    throw new Error("clearing wallet is already in use", { cause: error });
+  }
+  try {
+    const keyPath = join(directory, "account.key");
+    let key: Hex;
+    try {
+      key = (await readFile(keyPath, "utf8")).trim() as Hex;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      for (;;) {
+        key = `0x${randomBytes(32).toString("hex")}`;
+        try {
+          createClearingSigner(key);
+          break;
+        } catch {
+          /* Rejection sample the scalar. */
+        }
+      }
+      const file = await open(keyPath, "wx", 0o600);
+      try {
+        await file.writeFile(key);
+        await file.sync();
+      } finally {
+        await file.close();
+      }
+    }
+    const parent = await open(directory, "r");
+    try {
+      await parent.sync();
+    } finally {
+      await parent.close();
+    }
+    const signer = createClearingSigner(key);
+    const statePath = join(directory, "payments.json");
+    const store: ClearingClientStore = {
+      async load() {
+        try {
+          return JSON.parse(
+            await readFile(statePath, "utf8"),
+          ) as ClearingClientState;
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+          throw error;
+        }
+      },
+      async save(state) {
+        const file = await open(statePath + ".next", "w", 0o600);
+        try {
+          await file.writeFile(JSON.stringify(state));
+          await file.sync();
+        } finally {
+          await file.close();
+        }
+        await rename(statePath + ".next", statePath);
+        const parent = await open(directory, "r");
+        try {
+          await parent.sync();
+        } finally {
+          await parent.close();
+        }
+      },
+    };
+    return {
+      signer,
+      store,
+      async close() {
+        owner.close();
+      },
+    };
+  } catch (error) {
+    owner.close();
+    throw error;
+  }
+}