@metalntwx/metal-pay 0.2.0 → 0.3.1

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,177 @@
+import { createServer } from "node:http";
+import { inspect } from "node:util";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createPublicClient, erc20Abi, http, type HttpTransport } from "viem";
+import { METAL_NETWORKS, rpcTransport, 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`),
+    );
+  });
+});
+
+const PASSWORD_ECHO = "ops:s3cr3t-pass";
+const PASSWORD = "s3cr3t-pass";
+
+describe("rpcTransport", () => {
+  /** An endpoint that fails each request over HTTP, never answers it, or answers it with a JSON-RPC error. */
+  const node = createServer((req, res) => {
+    let body = "";
+    req.on("data", (c) => (body += c));
+    req.on("end", () => {
+      const { id } = JSON.parse(body);
+      if (req.url?.startsWith("/http-error/")) return res.writeHead(502).end("bad gateway");
+      if (req.url?.startsWith("/hang/")) return;
+      res.setHeader("content-type", "application/json");
+      // An endpoint whose error names a different path on its own host than the one requested,
+      // as an Express-style 404 or a proxy's own error page can.
+      // A server error that echoes the request path alone, or a header that names it, or the credentials it was given.
+      if (req.url?.startsWith("/echoes-path-only/"))
+        return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32000, message: `Cannot POST ${req.url}` } }));
+      if (req.url?.startsWith("/echoes-header/")) return res.writeHead(502, { "content-type": "text/plain", location: req.url, "x-upstream": req.url }).end("bad gateway");
+      // A provider that names the key alone, a percent-encoded path as it decodes it, or the password alone.
+      if (req.url?.startsWith("/echoes-segment/"))
+        return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32000, message: `Unauthorized: invalid project id ${req.url.split("?")[0]!.slice("/echoes-segment/".length)}` } }));
+      if (req.url?.startsWith("/echoes-query/"))
+        return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32000, message: `Unauthorized: invalid api key ${new URL(req.url, "http://x").searchParams.get("key")}` } }));
+      if (req.url?.startsWith("/echoes-decoded/"))
+        return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32000, message: `Unauthorized: ${decodeURIComponent(req.url.slice("/echoes-decoded/".length))}` } }));
+      if (req.url?.startsWith("/echoes-password/"))
+        return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32000, message: `bad password ${PASSWORD}` } }));
+      if (req.url?.startsWith("/echoes-in-data/"))
+        return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32000, message: "upstream failed", data: { reason: `Cannot POST ${req.url}`, trace: [`at ${req.url}`] } } }));
+      if (req.url?.startsWith("/echoes-userinfo/"))
+        return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32000, message: `bad credentials ${PASSWORD_ECHO}` } }));
+      if (req.url?.startsWith("/echoes-another-path/"))
+        return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32000, message: `Cannot POST ${origin}/leaked-key-in-another-path/${req.url.slice("/echoes-another-path/".length)}` } }));
+      res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32000, message: "header not found" } }));
+    });
+  });
+  let origin: string;
+  beforeAll(async () => {
+    origin = await new Promise<string>((resolve) =>
+      node.listen(0, "127.0.0.1", () => resolve(`http://127.0.0.1:${(node.address() as { port: number }).port}`)),
+    );
+  });
+  afterAll(() => new Promise<void>((resolve) => node.close(() => resolve()) && node.closeAllConnections()));
+  const CREDENTIAL = "k3y-0f-the-endpoint";
+  /** The error, its causes and their fields, as a log prints them. */
+  const printed = (error: unknown) => inspect(error, { depth: Infinity });
+  const failures = (url: string, transport = rpcTransport) => {
+    const client = createPublicClient({ transport: transport(url) });
+    return Promise.all([
+      client.getChainId().catch((e: unknown) => e),
+      client.readContract({ address: `0x${"33".repeat(20)}`, abi: erc20Abi, functionName: "totalSupply" }).catch((e: unknown) => e),
+    ]);
+  };
+
+  it("throws viem's errors without the RPC URL, in them or their causes", async () => {
+    const urls = [`${origin}/http-error/${CREDENTIAL}`, `${origin}/rpc-error/${CREDENTIAL}`, `${origin}/q?key=${CREDENTIAL}`, `http://127.0.0.1:1/${CREDENTIAL}`];
+    for (const url of urls) {
+      for (const error of await failures(url)) {
+        expect(error).toBeInstanceOf(Error);
+        expect(printed(error)).toContain("[RPC URL hidden]");
+        expect(printed(error)).not.toContain(CREDENTIAL);
+        expect(printed(error)).not.toMatch(/https?:\/\/127\.0\.0\.1/);
+      }
+    }
+  });
+
+  it("names an RPC endpoint that gives no answer, or a server error, as unreachable, and one that answers with an RPC error as answering", async () => {
+    // A short timeout and no retries, so a request that hangs fails at once.
+    const quick = (url: string) => ((options) => rpcTransport(url)({ ...options, timeout: 300, retryCount: 0 })) as HttpTransport;
+    for (const url of [`${origin}/hang/${CREDENTIAL}`, `${origin}/http-error/${CREDENTIAL}`, `http://127.0.0.1:1/${CREDENTIAL}`]) {
+      for (const error of await failures(url, quick)) {
+        expect(String(error)).toMatch(/^\w+: the RPC endpoint could not be reached: /);
+        expect(printed(error)).not.toContain(CREDENTIAL);
+      }
+    }
+    for (const error of await failures(`${origin}/rpc-error/${CREDENTIAL}`, quick)) expect(String(error)).not.toMatch(/could not be reached/);
+  });
+
+  it("is the check that fails: viem's own transport prints the URL", async () => {
+    for (const error of await failures(`${origin}/http-error/${CREDENTIAL}`, (url) => http(url))) expect(printed(error)).toContain(CREDENTIAL);
+  });
+
+  /** Every string an error carries, in its fields, its causes and its headers, as a log or a catch block could read them. */
+  const strings = (value: unknown, seen = new Set<unknown>()): string[] => {
+    if (typeof value === "string") return [value];
+    if (value === null || typeof value !== "object" || seen.has(value)) return [];
+    seen.add(value);
+    if (value instanceof Headers) return [...value].flat();
+    const fields = Object.getOwnPropertyNames(value).map((key) => (value as Record<string, unknown>)[key]);
+    return fields.flatMap((field) => strings(field, seen));
+  };
+
+  it("hides the path and query of the RPC URL where the endpoint echoes them without the host", async () => {
+    for (const url of [`${origin}/echoes-path-only/${CREDENTIAL}`, `${origin}/echoes-path-only/v1?key=${CREDENTIAL}`]) {
+      for (const error of await failures(url)) {
+        expect(error).toBeInstanceOf(Error);
+        expect(strings(error).join("\n")).not.toContain(CREDENTIAL);
+      }
+    }
+  });
+
+  it("hides the RPC URL where the endpoint names it in a response header", async () => {
+    for (const error of await failures(`${origin}/echoes-header/${CREDENTIAL}`)) {
+      expect(error).toBeInstanceOf(Error);
+      expect(strings(error).join("\n")).not.toContain(CREDENTIAL);
+    }
+  });
+
+  it("hides the RPC URL wherever the endpoint puts it in its error, nested objects and lists included", async () => {
+    for (const error of await failures(`${origin}/echoes-in-data/${CREDENTIAL}`)) {
+      expect(error).toBeInstanceOf(Error);
+      expect(strings(error).join("\n")).not.toContain(CREDENTIAL);
+    }
+  });
+
+  it("hides a key the endpoint echoes alone: a path segment, a query value, or a percent-encoded segment as it decodes it", async () => {
+    for (const url of [
+      `${origin}/echoes-segment/${CREDENTIAL}`,
+      `${origin}/echoes-segment/v1/${CREDENTIAL}/rpc?x=1`,
+      `${origin}/echoes-query/v1?key=${CREDENTIAL}`,
+      `${origin}/echoes-decoded/${encodeURIComponent("key with space and more")}`,
+    ]) {
+      for (const error of await failures(url)) {
+        expect(error).toBeInstanceOf(Error);
+        const text = strings(error).join("\n");
+        expect(text).not.toContain(CREDENTIAL);
+        expect(text).not.toContain("key with space and more");
+      }
+    }
+  });
+
+  it("hides a password the endpoint echoes alone", async () => {
+    const [user] = PASSWORD_ECHO.split(":");
+    for (const error of await failures(`http://${user}:${PASSWORD}@${origin.slice("http://".length)}/echoes-password/x`)) {
+      expect(error).toBeInstanceOf(Error);
+      expect(strings(error).join("\n")).not.toContain(PASSWORD);
+    }
+  });
+
+  it("hides the user and password of the RPC URL where the endpoint echoes them", async () => {
+    const [user, password] = PASSWORD_ECHO.split(":");
+    for (const error of await failures(`http://${user}:${password}@${origin.slice("http://".length)}/echoes-userinfo/x`)) {
+      expect(error).toBeInstanceOf(Error);
+      expect(strings(error).join("\n")).not.toContain(PASSWORD_ECHO);
+      expect(strings(error).join("\n")).not.toContain(password);
+    }
+  });
+
+  it("hides a same-host URL that differs from rpcUrl, which only the same-host check catches", async () => {
+    for (const error of await failures(`${origin}/echoes-another-path/${CREDENTIAL}`)) {
+      expect(printed(error)).toContain("[RPC URL hidden]");
+      expect(printed(error)).not.toContain(CREDENTIAL);
+      expect(printed(error)).not.toMatch(/https?:\/\/127\.0\.0\.1/);
+    }
+  });
+});

package/src/networks.ts

@@ -0,0 +1,242 @@
+import type { Network } from "@x402/core/types";
+import { HttpRequestError, TimeoutError, http, type Address, type HttpTransport } 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: "0xcEc6e13AC50078AE3f1e163d5fbd257DAcED8023",
+  },
+};
+
+/** 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}`,
+  );
+}
+
+/** What an RPC URL reads as in an error. */
+const HIDDEN_RPC_URL = "[RPC URL hidden]";
+
+/**
+ * viem's `http` transport to `rpcUrl`, whose errors do not carry the URL: it
+ * can hold the endpoint's credential, so each error it throws, and each of
+ * that error's causes, names it as `[RPC URL hidden]`. An endpoint that
+ * gives no answer, or a server error, is named as one that could not be
+ * reached.
+ */
+export function rpcTransport(rpcUrl: string): HttpTransport {
+  const transport = http(rpcUrl);
+  const parsed = URL.canParse(rpcUrl) ? new URL(rpcUrl) : undefined;
+  const host = parsed?.host;
+  // What an endpoint can echo of the URL without its host: the path and
+  // query, which can hold a key, and the user and password.
+  const decoded = (text: string) => {
+    try {
+      return decodeURIComponent(text);
+    } catch {
+      return text;
+    }
+  };
+  const path = parsed ? parsed.pathname + parsed.search : "";
+  const secrets = [rpcUrl];
+  if (path.length > 1) secrets.push(path);
+  // A key is often echoed alone: each path segment and query value long enough to be one.
+  if (parsed) {
+    const parts = [...decoded(parsed.pathname).split("/"), ...[...parsed.searchParams.values()]];
+    for (const part of parts) if (part.length >= 8) secrets.push(part);
+  }
+  if (parsed?.username || parsed?.password) {
+    const [user, password] = [decoded(parsed.username), decoded(parsed.password)];
+    secrets.push(`${user}:${password}`);
+    if (password.length >= 4) secrets.push(password);
+  }
+  // viem prints the URL as given, or without its user and password.
+  const hide = (text: string) =>
+    secrets
+      .reduce((hidden, secret) => hidden.replaceAll(secret, HIDDEN_RPC_URL), text)
+      .replace(/https?:\/\/[^\s"'<>]+/g, (url) => (URL.canParse(url) && new URL(url).host === host ? HIDDEN_RPC_URL : url));
+  // Every string the error holds, in its fields, its causes, its arrays and
+  // its response headers, as viem or the endpoint put it there: the fields
+  // that name the URL are not a list to keep.
+  const scrub = (value: unknown, seen: Set<unknown>) => {
+    if (value === null || typeof value !== "object" || seen.has(value)) return;
+    seen.add(value);
+    for (const key of Object.getOwnPropertyNames(value)) {
+      const fields = value as Record<string, unknown>;
+      let field: unknown;
+      try {
+        field = fields[key];
+      } catch {
+        continue;
+      }
+      let hidden: unknown = field;
+      if (typeof field === "string") hidden = hide(field);
+      else if (field instanceof Headers) {
+        const entries = [...field].map(([name, text]) => [name, hide(text)] as [string, string]);
+        if (entries.some(([name, text]) => field.get(name) !== text)) hidden = new Headers(entries);
+      } else scrub(field, seen);
+      if (hidden !== field)
+        try {
+          fields[key] = hidden;
+        } catch {
+          // A property that cannot be written holds what it held.
+        }
+    }
+  };
+  return ((options) => {
+    const made = transport(options);
+    return {
+      ...made,
+      request: (async (args, requestOptions) => {
+        try {
+          return await made.request(args, requestOptions);
+        } catch (error) {
+          if (error instanceof TimeoutError || (error instanceof HttpRequestError && (error.status === undefined || error.status >= 500))) {
+            error.shortMessage = `the RPC endpoint could not be reached: ${error.shortMessage}`;
+            error.message = `the RPC endpoint could not be reached: ${error.message}`;
+          }
+          scrub(error, new Set());
+          throw error;
+        }
+      }) as typeof made.request,
+    };
+  }) as HttpTransport;
+}
+
+/** 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 magnitude = units < 0n ? -units : units;
+  const scale = 10n ** BigInt(USDZ.decimals);
+  const whole = magnitude / scale;
+  const fraction = (magnitude % scale).toString().padStart(USDZ.decimals, "0").replace(/0+$/, "");
+  return `${units < 0n ? "-" : ""}${fraction ? `${whole}.${fraction}` : whole}`;
+}

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 });
+  }
+});