@seedhape/local-wallet 0.2.0

package/src/server.ts

@@ -0,0 +1,187 @@
+/**
+ * Local MCP server for a self-custody agent wallet.
+ *
+ * The key never leaves the OS keychain, and this server is the only thing that
+ * signs with it. It does not keep its own rules: every payment is checked and
+ * reserved by the user's Seedhape account first (pause switch, spending rules,
+ * budget), and the outcome is reported back so it appears in their activity.
+ * If Seedhape can't be reached, nothing is paid.
+ *
+ * Everything else (finding services, budgets, rules, history, funding) lives in
+ * the hosted Seedhape MCP, which the agent should also have connected.
+ */
+
+import { createHash, randomUUID } from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createPublicClient, erc20Abi, http, type Address as ViemAddress } from "viem";
+import { base, baseSepolia } from "viem/chains";
+import { z } from "zod";
+import { PaymentDeclinedError, X402Client, type AssetRef, type Eip712Signer, type OutboundRequestPolicy, type SettlementResponse } from "@seedhape/core";
+import { SeedhapeAuthError, SeedhapeUnreachableError, authorizePayment, seedhapeUrl, settlePayment, whoAmI, type HostedRefusal } from "./hosted.js";
+import type { StoredWebBotAuthKey } from "./keychain.js";
+import { webBotAuthFetch, type RequestSigner } from "./web-bot-auth.js";
+
+export interface LocalWalletDeps {
+  agentId: string;
+  address: `0x${string}` | null;
+  signer: Eip712Signer | null;
+  asset: AssetRef;
+  absoluteMaxPerPayment: bigint;
+  /** Signs every outgoing HTTPS request so merchants can identify this agent (Web Bot Auth). */
+  webBotAuth?: StoredWebBotAuthKey | null;
+  /** On-chain (ERC-8004) identity; preferred over webBotAuth when present. */
+  identity?: { identityRef: string; signatureAgent: string; keyId: string; signRequest: RequestSigner; refreshDirectory(): Promise<void> } | null;
+  /** Tests only: allow a merchant on a private/loopback address. */
+  outboundPolicy?: OutboundRequestPolicy;
+  /** Tests only: replace the network. */
+  fetchImpl?: typeof fetch;
+  /** First-use browser setup; returns credentials to install into this live server. */
+  finishSetup?: () => Promise<Pick<LocalWalletDeps, "address" | "signer" | "webBotAuth" | "identity">>;
+  setupNeeded?: boolean;
+  onSetupError?: (error: unknown) => void;
+}
+
+const text = (value: string) => ({ content: [{ type: "text" as const, text: value }] });
+const usdc = (units: bigint | string, decimals: number) => (Number(units) / 10 ** decimals).toFixed(Math.min(decimals, 6));
+
+function refusalText(refusal: Pick<HostedRefusal, "code" | "error" | "hint" | "recovery" | "approvalId">) {
+  // Waiting for the user: the reason already says how to finish once they approve.
+  if (refusal.approvalId) return `PAYMENT NOT MADE.\n\nReason: ${refusal.error}`;
+  return `PAYMENT NOT MADE.\n\nReason: ${refusal.error}\n\nError code: ${refusal.code}\nNext step: ${refusal.recovery?.tool ? `call ${refusal.recovery.tool} on the hosted Seedhape MCP. ` : ""}${refusal.hint}\n\nDo not repeat this exact call.`;
+}
+
+function failureText(error: unknown) {
+  if (error instanceof SeedhapeAuthError || error instanceof SeedhapeUnreachableError) return `PAYMENT NOT MADE.\n\nReason: ${error.message}`;
+  return `PAYMENT NOT MADE.\n\nReason: ${error instanceof Error ? error.message : String(error)}`;
+}
+
+export function createServer(deps: LocalWalletDeps): McpServer {
+  const server = new McpServer({ name: "seedhape-local-wallet", version: "0.2.0" });
+  const { asset } = deps;
+  let setupInFlight: Promise<void> | undefined;
+
+  const ensureSetup = async () => {
+    if (!deps.setupNeeded || !deps.finishSetup) return false;
+    if (!setupInFlight) {
+      setupInFlight = deps.finishSetup().then((ready) => {
+        Object.assign(deps, ready);
+        deps.setupNeeded = false;
+      }).catch((error) => {
+        deps.onSetupError?.(error);
+      }).finally(() => { setupInFlight = undefined; });
+    }
+    return true;
+  };
+
+  const client = (hooks: Pick<ConstructorParameters<typeof X402Client>[0], "authorise" | "onSettlement">) => new X402Client({
+    ...(deps.signer ? { signer: deps.signer } : {}),
+    allowedNetworks: [asset.network],
+    allowedAssets: [asset.address],
+    absoluteMaxPerPayment: deps.absoluteMaxPerPayment,
+    ...(deps.outboundPolicy ? { outboundPolicy: deps.outboundPolicy } : {}),
+    fetchImpl: webBotAuthFetch(deps.fetchImpl ?? fetch, deps.identity?.signRequest ?? deps.webBotAuth ?? null),
+    ...hooks,
+  });
+
+  server.tool(
+    "wallet_status",
+    "Show this computer's self-custody agent wallet: its agent id, address, USDC balance, and whether it is signed in to Seedhape. Read-only. To add funds or change spending rules, use the hosted Seedhape MCP or the Seedhape website.",
+    {},
+    async () => {
+      if (await ensureSetup()) return text("Finishing setup in your browser. When it’s done, try again.");
+      if (!deps.address) return text(`No local wallet exists for agent '${deps.agentId}'. Run \`seedhape setup\` in a terminal.`);
+      let balance = "unknown";
+      try {
+        const chain = asset.network === "eip155:8453" ? base : baseSepolia;
+        const raw = await createPublicClient({ chain, transport: http(process.env.SEEDHAPE_RPC_URL) }).readContract({ address: asset.address as ViemAddress, abi: erc20Abi, functionName: "balanceOf", args: [deps.address] });
+        balance = `${usdc(raw, asset.decimals)} ${asset.symbol}`;
+      } catch { /* balance stays unknown; the hosted wallet_balance tool can also read it */ }
+      const account = await whoAmI();
+      return text([
+        `Agent wallet: ${deps.agentId}`,
+        `Address: ${deps.address}`,
+        "Payment network: configured",
+        `Balance: ${balance}`,
+        `Seedhape account (${seedhapeUrl()}): ${account.detail}`,
+        `Agent identity: ${deps.identity ? `verified (${deps.identity.identityRef})` : deps.webBotAuth ? "registered signing key" : "not set up; run `seedhape setup`"}`,
+        `Key storage: operating system keychain (never leaves this computer)`,
+      ].join("\n"));
+    },
+  );
+
+  server.tool(
+    "quote",
+    "Get the price of a paid URL without paying: amount, currency, and seller. Always quote first and show the user the price before calling pay.",
+    { url: z.string().url(), method: z.enum(["GET", "POST"]).optional(), body: z.string().optional() },
+    async ({ url, method, body }) => {
+      if (await ensureSetup()) return text("Finishing setup in your browser. When it’s done, try again.");
+      const probe = await client({ authorise: async () => ({ approved: false, reason: "quote only" }) }).probe(url, { method: method ?? "GET", ...(body ? { body, headers: { "content-type": "application/json" } } : {}) });
+      if (!probe.challenge) return text(`${url} does not ask for payment (HTTP ${probe.response.status}).`);
+      const offer = probe.challenge.accepts.find((item) => item.network === asset.network && item.asset.toLowerCase() === asset.address.toLowerCase());
+      if (!offer) return text(`${url} asks for payment in a currency this wallet does not use. Ask the user to choose another wallet or payment option.`);
+      return text(`Price: ${usdc(offer.maxAmountRequired, asset.decimals)} ${asset.symbol}\nSeller: ${offer.payTo}\nResource: ${offer.resource || url}${offer.description ? `\nDescription: ${offer.description}` : ""}`);
+    },
+  );
+
+  server.tool(
+    "pay",
+    "Pay for a URL with this computer's self-custody wallet. Before signing, Seedhape checks the user's pause switch, spending limit, and budget and reserves the amount; if Seedhape refuses or can't be reached, nothing is paid. If the price is above what the user approves automatically, nothing is paid and the response has an approval link: show it to the user, and once they approve call pay again with the same url and the approval_id. On any other refusal the response names the next step; follow it instead of retrying. Set confirm_unusual only when the user explicitly approved a payment Seedhape flagged as unusual in this conversation.",
+    {
+      url: z.string().url(),
+      method: z.enum(["GET", "POST"]).optional(),
+      body: z.string().optional(),
+      confirm_unusual: z.boolean().optional(),
+      purchase_id: z.string().regex(/^[A-Za-z0-9_-]{10,80}$/).optional().describe("Stable id for this purchase so a retry never pays twice."),
+      approval_id: z.string().regex(/^apr_[A-Za-z0-9_-]{10,40}$/).optional().describe("From an earlier response that needed the user's approval. Pass it with the same url once the user has approved."),
+    },
+    async ({ url, method, body, confirm_unusual, purchase_id, approval_id }) => {
+      if (await ensureSetup()) return text("Finishing setup in your browser. When it’s done, try again.");
+      if (!deps.signer || !deps.address) return text(`PAYMENT NOT MADE.\n\nReason: No local wallet exists for agent '${deps.agentId}'. Run \`seedhape setup\` in a terminal.`);
+      const purchaseId = purchase_id ?? `lw_${randomUUID().replace(/-/g, "")}`;
+      // Merchants may look up this agent's key while verifying the request; make sure its directory is fresh.
+      await deps.identity?.refreshDirectory().catch(() => undefined);
+      let authorizationId: string | undefined;
+      let refusal: HostedRefusal | undefined;
+      let settled: { success: boolean; tx?: string } | undefined;
+
+      const x402 = client({
+        // Seedhape decides; this wallet only signs after an approval.
+        authorise: async ({ requirement }) => {
+          const decision = await authorizePayment({ agentId: deps.agentId, url, requirement: { ...requirement, maxAmountRequired: String(requirement.maxAmountRequired) }, purchaseId, method: method ?? "GET", ...(body ? { bodySha256: createHash("sha256").update(body).digest("base64url") } : {}), ...(approval_id ? { approvalId: approval_id } : {}), ...(confirm_unusual ? { confirmUnusual: true } : {}) });
+          if (!decision.ok) { refusal = decision; return { approved: false, reason: decision.error }; }
+          authorizationId = decision.authorizationId;
+          return { approved: true, spendId: decision.authorizationId };
+        },
+        onSettlement: async (_spendId, settlement: SettlementResponse | null, httpStatus: number) => {
+          settled = { success: Boolean(settlement?.success) && httpStatus < 400, ...(settlement?.transaction ? { tx: settlement.transaction } : {}) };
+        },
+      });
+
+      try {
+        const result = await x402.fetch(url, { method: method ?? "GET", ...(body ? { body, headers: { "content-type": "application/json" } } : {}) });
+        if (!result.paid) return text(`No payment was required.\n\n---\n\n${await result.response.text()}`);
+        const outcome = settled ?? { success: result.response.ok };
+        if (authorizationId) await settlePayment({ authorizationId, status: outcome.success ? "settled" : "failed", ...(outcome.tx ? { txHash: outcome.tx } : {}), ...(outcome.success ? {} : { error: `Merchant responded HTTP ${result.response.status}` }) }).catch(() => undefined);
+        const responseBody = await result.response.text();
+        if (!outcome.success) return text(`PAYMENT NOT COMPLETED.\n\nReason: the merchant responded HTTP ${result.response.status}. Your budget reservation was released.\nLedger reference: ${authorizationId}\n\n${responseBody.slice(0, 2000)}`);
+        return text(`Paid ${usdc(result.amount ?? 0n, asset.decimals)} ${asset.symbol}${outcome.tx ? `, tx ${outcome.tx}` : ""}\nLedger reference: ${authorizationId}\n\n---\n\n${responseBody}`);
+      } catch (error) {
+        if (error instanceof SeedhapeAuthError) {
+          deps.setupNeeded = true;
+          if (await ensureSetup()) return text("Finishing setup in your browser. When it’s done, try again.");
+        }
+        if (refusal) return text(refusalText(refusal));
+        if (!authorizationId) return text(failureText(error));
+        // Declined before anything was signed or sent: safe to release the reservation.
+        if (error instanceof PaymentDeclinedError) {
+          await settlePayment({ authorizationId, status: "failed", error: error.message }).catch(() => undefined);
+          return text(failureText(error));
+        }
+        // The payment may have been sent. Leave it pending so it is reconciled, never paid twice.
+        return text(`PAYMENT OUTCOME UNKNOWN.\n\nReason: ${error instanceof Error ? error.message : String(error)}\nLedger reference: ${authorizationId}\n\nThe payment may have gone through. Do not pay again; check spend_history or purchase_receipt on the hosted Seedhape MCP.`);
+      }
+    },
+  );
+
+  return server;
+}

package/src/web-bot-auth.ts

@@ -0,0 +1,94 @@
+/**
+ * Web Bot Auth for a self-custody agent: an Ed25519 key, kept in the OS keychain,
+ * that signs outgoing HTTPS requests so merchants (for example UCP and ACP
+ * checkouts) can tell which agent is calling. Seedhape only ever receives the
+ * public key. Registration, rotation, and revocation go through the hosted
+ * Seedhape MCP, so the user never handles key files, thumbprints, or challenges.
+ */
+
+import { createHash, createPrivateKey, generateKeyPairSync, randomBytes, sign } from "node:crypto";
+import { signWebBotAuth } from "@seedhape/core";
+import type { StoredWebBotAuthKey } from "./keychain.js";
+
+export type CallTool = (name: string, args: Record<string, unknown>) => Promise<string>;
+
+/** RFC 7638 thumbprint; Seedhape requires it as the key id. */
+export function ed25519Thumbprint(jwk: { crv: string; kty: string; x: string }): string {
+  return createHash("sha256").update(JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x })).digest("base64url");
+}
+
+/**
+ * The Signature-Agent URL identifying this agent. It lives under the user's
+ * Seedhape URL with a random suffix, so two agents with the same name never collide.
+ */
+export function defaultSignatureAgent(seedhapeUrl: string, agentId: string): string {
+  return new URL(`/agents/${encodeURIComponent(agentId)}-${randomBytes(4).toString("hex")}`, seedhapeUrl).toString();
+}
+
+export function generateWebBotAuthKey(signatureAgent: string): StoredWebBotAuthKey {
+  const agent = new URL(signatureAgent);
+  if (agent.protocol !== "https:") throw new Error("The Web Bot Auth signature agent must be an HTTPS URL.");
+  const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+  const jwk = publicKey.export({ format: "jwk" }) as { kty: string; crv: string; x: string };
+  const publicJwk = { kty: "OKP" as const, crv: "Ed25519" as const, x: jwk.x };
+  return {
+    privateKeyPem: privateKey.export({ format: "pem", type: "pkcs8" }).toString(),
+    publicJwk,
+    keyId: ed25519Thumbprint(publicJwk),
+    signatureAgent: agent.toString(),
+    createdAt: Math.floor(Date.now() / 1000),
+  };
+}
+
+/** Prove control of the key over Seedhape's one-time challenge. */
+export function signChallenge(key: StoredWebBotAuthKey, challenge: string): string {
+  return sign(null, Buffer.from(challenge), createPrivateKey(key.privateKeyPem)).toString("base64url");
+}
+
+function parse(textResult: string): Record<string, unknown> {
+  try { return JSON.parse(textResult) as Record<string, unknown>; } catch { return { error: textResult }; }
+}
+
+/** Register (or, when `rotate` is set, register as a replacement) this key with the user's Seedhape account. */
+export async function registerWebBotAuthKey(callTool: CallTool, agentId: string, key: StoredWebBotAuthKey, rotate = false): Promise<void> {
+  const challenge = parse(await callTool("web_bot_auth_challenge", { agent_id: agentId, signature_agent: key.signatureAgent, key_id: key.keyId }));
+  if (typeof challenge.challenge !== "string") throw new Error(String(challenge.error ?? (challenge as { message?: string }).message ?? "Seedhape did not return a Web Bot Auth challenge."));
+  const result = parse(await callTool(rotate ? "rotate_web_bot_auth_key" : "register_web_bot_auth_key", {
+    agent_id: agentId, signature_agent: key.signatureAgent, key_id: key.keyId, public_jwk: key.publicJwk,
+    challenge: challenge.challenge, signature: signChallenge(key, challenge.challenge),
+  }));
+  if (result.registered !== true) throw new Error(String(result.error ?? "Seedhape did not register the Web Bot Auth key."));
+}
+
+export async function revokeWebBotAuthKey(callTool: CallTool, key: StoredWebBotAuthKey): Promise<void> {
+  const result = await callTool("revoke_web_bot_auth_key", { signature_agent: key.signatureAgent, key_id: key.keyId });
+  if (!/revoked\.?$/i.test(result.trim()) || /not revoked/i.test(result)) throw new Error(result || "Seedhape did not revoke the key.");
+}
+
+/**
+ * Wrap fetch so every outgoing HTTPS request carries a fresh Web Bot Auth
+ * signature. Each request gets its own nonce: merchants reject a reused one, and
+ * a paid purchase makes two requests (the price probe and the paid retry).
+ * Plain-HTTP URLs are sent unsigned, since the signature covers the HTTPS authority.
+ */
+export type RequestSigner = (url: string) => Promise<Record<string, string | undefined>>;
+
+/** Per-request signer for a keychain Web Bot Auth key. */
+export function keychainSigner(key: StoredWebBotAuthKey): RequestSigner {
+  const privateKey = createPrivateKey(key.privateKeyPem);
+  return async (url) => signWebBotAuth({ url, signatureAgent: key.signatureAgent, keyId: key.keyId, privateKey });
+}
+
+export function webBotAuthFetch(base: typeof fetch, signerOrKey: RequestSigner | StoredWebBotAuthKey | null): typeof fetch {
+  if (!signerOrKey) return base;
+  const signRequest = typeof signerOrKey === "function" ? signerOrKey : keychainSigner(signerOrKey);
+  return (async (input: Parameters<typeof fetch>[0], init?: RequestInit) => {
+    const request = input instanceof Request ? input : null;
+    const url = request ? request.url : input.toString();
+    if (!url.startsWith("https://")) return base(input, init);
+    const signed = await signRequest(url);
+    const headers = new Headers(init?.headers ?? request?.headers);
+    for (const [name, value] of Object.entries(signed)) if (value) headers.set(name, value);
+    return base(input, { ...init, headers });
+  }) as typeof fetch;
+}

package/test/identity-backup.test.mjs

@@ -0,0 +1,90 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createHash, randomBytes } from "node:crypto";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+import { FileAgentOperationalKeyStore } from "@seedhape/core";
+import { restoreSelfCustodiedBackupPayload } from "../dist/agent-identity.js";
+import { decryptIdentityBackup, encryptIdentityBackup } from "../dist/identity-backup.js";
+
+function fixture() {
+  const controllerPrivateKey = generatePrivateKey();
+  const controller = privateKeyToAccount(controllerPrivateKey).address;
+  const identityRef = "eip155:84532:0x1111111111111111111111111111111111111111/7";
+  const identityHash = createHash("sha256").update(identityRef).digest("hex");
+  const keyStoreRef = "a".repeat(64);
+  const stateFile = `${createHash("sha256").update("local-primary").digest("hex")}.state.json`;
+  const encode = (value) => Buffer.from(typeof value === "string" ? value : JSON.stringify(value)).toString("base64url");
+  return {
+    version: 1,
+    accountId: "local-primary",
+    controllerPrivateKey,
+    keyStoreMasterKey: Buffer.alloc(32, 2).toString("base64url"),
+    files: {
+      [`state/${stateFile}`]: encode({ stage: "ready", controller, identityRef, keyStoreRef, keyId: "ed25519-test" }),
+      [`keys/${keyStoreRef}.json`]: encode("encrypted key fixture"),
+      [`metadata/${identityHash}.directory.json`]: encode({ identityRef, keyId: "ed25519-test" }),
+      [`metadata/${identityHash}.registration.json`]: encode({ services: [{ name: "Web Bot Auth", keyId: "ed25519-test" }] }),
+    },
+  };
+}
+
+test("encrypts and round-trips all identity backup contents only with the passphrase", () => {
+  const payload = fixture();
+  const encoded = encryptIdentityBackup(payload, "correct horse battery staple");
+  assert.notEqual(encoded.includes(payload.controllerPrivateKey), true);
+  assert.deepEqual(decryptIdentityBackup(encoded, "correct horse battery staple"), payload);
+  assert.throws(() => decryptIdentityBackup(encoded, "incorrect passphrase"), /Could not decrypt identity backup/);
+});
+
+test("restores a full local identity tree atomically without overwriting an existing one", async () => {
+  const temporary = await mkdtemp(join(tmpdir(), "seedhape-identity-backup-test-"));
+  try {
+    const source = join(temporary, "source");
+    const destination = join(temporary, "restored");
+    const controllerPrivateKey = generatePrivateKey();
+    const controller = privateKeyToAccount(controllerPrivateKey).address;
+    const masterKey = randomBytes(32);
+    const keyStore = new FileAgentOperationalKeyStore(join(source, "keys"), masterKey);
+    const key = await keyStore.createOrGetEd25519("local-primary");
+    const identityRef = "eip155:84532:0x1111111111111111111111111111111111111111/9";
+    const identityHash = createHash("sha256").update(identityRef).digest("hex");
+    const stateHash = createHash("sha256").update("local-primary").digest("hex");
+    const state = { stage: "ready", controller, identityRef, keyStoreRef: key.keyRef, keyId: key.keyId };
+    const metadataDirectory = { identityRef, keyId: key.keyId, keyStoreRef: key.keyRef, publicJwk: key.publicJwk };
+    const registration = { services: [{ name: "Web Bot Auth", keyId: key.keyId }] };
+    const files = {
+      [`state/${stateHash}.state.json`]: Buffer.from(JSON.stringify(state)).toString("base64url"),
+      [`keys/${key.keyRef}.json`]: (await readFile(join(source, "keys", `${key.keyRef}.json`))).toString("base64url"),
+      [`metadata/${identityHash}.directory.json`]: Buffer.from(JSON.stringify(metadataDirectory)).toString("base64url"),
+      [`metadata/${identityHash}.registration.json`]: Buffer.from(JSON.stringify(registration)).toString("base64url"),
+    };
+    const payload = { version: 1, accountId: "local-primary", controllerPrivateKey, keyStoreMasterKey: masterKey.toString("base64url"), files };
+    const restored = await restoreSelfCustodiedBackupPayload(destination, payload, async () => undefined);
+    assert.deepEqual(restored, { controller, identityRef });
+    const restoredFiles = new FileAgentOperationalKeyStore(join(destination, "agent-identity", "keys"), masterKey);
+    const signer = await restoredFiles.getSigner(key.keyRef);
+    assert.equal(typeof signer.signRequest, "function");
+    await assert.rejects(() => restoreSelfCustodiedBackupPayload(destination, payload, async () => undefined), /already exists/);
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+  }
+});
+
+test("authenticates the encrypted bundle and rejects modified ciphertext", () => {
+  const encoded = encryptIdentityBackup(fixture(), "a sufficiently long backup phrase");
+  const parsed = JSON.parse(encoded);
+  parsed.ciphertext = `${parsed.ciphertext.slice(0, -1)}${parsed.ciphertext.endsWith("A") ? "B" : "A"}`;
+  assert.throws(() => decryptIdentityBackup(JSON.stringify(parsed), "a sufficiently long backup phrase"), /Could not decrypt identity backup/);
+});
+
+test("rejects unsafe backup paths and incomplete identity backups", () => {
+  const payload = fixture();
+  payload.files["../outside"] = Buffer.from("no").toString("base64url");
+  assert.throws(() => encryptIdentityBackup(payload, "a sufficiently long backup phrase"), /invalid path/);
+  const incomplete = fixture();
+  delete incomplete.files[Object.keys(incomplete.files).find((path) => path.endsWith(".directory.json"))];
+  assert.throws(() => encryptIdentityBackup(incomplete, "a sufficiently long backup phrase"), /incomplete|all required/);
+});

package/test/identity-fork.test.mjs

@@ -0,0 +1,128 @@
+// Opt-in end-to-end test of the self-custody on-chain identity against a local
+// fork of Base mainnet (the deployed ERC-8004 registry and AgentTrust contract).
+// Run with: SEEDHAPE_FORK_TEST=1 node --test test/identity-fork.test.mjs
+// Needs `anvil` (Foundry) on PATH and network access to https://mainnet.base.org.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { createHash, createPublicKey } from "node:crypto";
+import { createServer } from "node:http";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createPublicClient, http, parseAbi, verifyMessage } from "viem";
+import { base } from "viem/chains";
+import keytar from "keytar";
+import { parseAgentIdentityRef, resolveAgentWebBotAuthKey, verifyWebBotAuth, verifyWebBotAuthDirectory } from "@seedhape/core";
+
+const REGISTRY = "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432";
+const TRUST = "0xa885daddd9cd398e39b0d34c941faf87761788e0";
+const ORIGIN = "https://seedhape.test";
+const enabled = process.env.SEEDHAPE_FORK_TEST === "1";
+
+async function startAnvil(port) {
+  const anvil = spawn("anvil", ["--fork-url", process.env.SEEDHAPE_FORK_RPC ?? "https://mainnet.base.org", "--port", String(port), "--silent"], { stdio: "ignore" });
+  const rpcUrl = `http://127.0.0.1:${port}`;
+  for (let attempt = 0; attempt < 60; attempt++) {
+    try {
+      const response = await fetch(rpcUrl, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_chainId", params: [] }) });
+      if (response.ok) return { anvil, rpcUrl };
+    } catch { /* not up yet */ }
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+  anvil.kill();
+  throw new Error("anvil did not start");
+}
+
+const rpc = (rpcUrl, method, params) => fetch(rpcUrl, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }) }).then((response) => response.json());
+
+/** A fake Seedhape applying the same rules as the hosted /api/local-wallet/identity/* endpoints. */
+async function fakeSeedhape(rpcUrl) {
+  const rows = new Map(); // metadata id -> { keyId, publicJwk, signature, signatureInput, expires, registration }
+  const calls = [];
+  const client = createPublicClient({ chain: base, transport: http(rpcUrl) });
+  const idFor = (ref) => createHash("sha256").update(ref).digest("hex");
+  const server = createServer(async (request, response) => {
+    let raw = ""; for await (const chunk of request) raw += chunk;
+    const body = raw ? JSON.parse(raw) : {};
+    const send = (status, value) => response.writeHead(status, { "content-type": "application/json" }).end(JSON.stringify(value));
+    calls.push(`${request.method} ${request.url}`);
+    if (request.headers.authorization !== "Bearer fork-token") return send(401, {});
+    if (request.url === "/api/local-wallet/identity") return send(200, { enabled: true, network: "base", chainId: 8453, identityRegistry: REGISTRY, trustContract: TRUST, rpcUrl, signatureAgent: ORIGIN, minimumControllerBalanceWei: "2000000000000000", gasSponsored: true });
+    if (request.url === "/api/local-wallet/identity/sponsor") {
+      await rpc(rpcUrl, "anvil_setBalance", [body.controller, "0x2386F26FC10000"]); // 0.01 ETH, standing in for the sponsor's top-up
+      return send(200, { outcome: "funded" });
+    }
+    if (request.url === "/api/local-wallet/identity/directory") {
+      const directoryUrl = `${ORIGIN}/.well-known/seedhape-agents/${idFor(body.identityRef)}/jwks.json`;
+      if (!verifyWebBotAuthDirectory({ url: directoryUrl, headers: { Signature: body.signature, "Signature-Input": body.signatureInput }, publicKey: body.publicJwk, expectedKeyId: body.keyId })) return send(409, { error: "bad directory signature" });
+      const existing = rows.get(idFor(body.identityRef));
+      if (!existing || existing.keyId !== body.keyId) {
+        const { agentId } = parseAgentIdentityRef(body.identityRef);
+        const owner = await client.readContract({ address: REGISTRY, abi: parseAbi(["function ownerOf(uint256) view returns (address)"]), functionName: "ownerOf", args: [agentId] });
+        const message = `Seedhape self-custody agent metadata\nidentity=${body.identityRef}\nkey=${body.keyId}`;
+        if (!body.ownerSignature || !(await verifyMessage({ address: owner, message, signature: body.ownerSignature }))) return send(409, { error: "owner signature invalid" });
+      }
+      rows.set(idFor(body.identityRef), { ...existing, keyId: body.keyId, publicJwk: body.publicJwk, signature: body.signature, signatureInput: body.signatureInput });
+      return send(200, { signatureAgent: ORIGIN, directoryUri: directoryUrl });
+    }
+    if (request.url === "/api/local-wallet/identity/registration") {
+      const row = rows.get(idFor(body.identityRef));
+      if (!row) return send(409, { error: "directory first" });
+      row.registration = body.registration;
+      return send(200, { registrationUri: `${ORIGIN}/.well-known/seedhape-agents/${idFor(body.identityRef)}/registration.json` });
+    }
+    send(404, {});
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  // What merchants fetch over HTTPS from Seedhape's public origin.
+  const publicFetch = async (input) => {
+    const url = new URL(String(input));
+    const match = /^\/\.well-known\/seedhape-agents\/([0-9a-f]{64})\/(jwks|registration)\.json$/.exec(url.pathname);
+    const row = match && rows.get(match[1]);
+    if (!row) return new Response("not found", { status: 404 });
+    if (match[2] === "registration") return new Response(JSON.stringify(row.registration), { headers: { "content-type": "application/json" } });
+    return new Response(JSON.stringify({ keys: [{ ...row.publicJwk, kid: row.keyId, use: "sig", alg: "EdDSA" }] }), { headers: { "content-type": "application/jwk-set+json", Signature: row.signature, "Signature-Input": row.signatureInput } });
+  };
+  return { server, url: `http://127.0.0.1:${server.address().port}`, publicFetch, calls, rows };
+}
+
+test("setup creates an on-chain identity that merchants can verify, with nothing for the user to configure", { skip: !enabled && "set SEEDHAPE_FORK_TEST=1 (needs anvil + network)", timeout: 600_000 }, async () => {
+  const { anvil, rpcUrl } = await startAnvil(8599);
+  const dataDir = await mkdtemp(join(tmpdir(), "seedhape-fork-"));
+  const accountId = `fork-test-${process.pid}`;
+  process.env.SEEDHAPE_AGENT_IDENTITY_CONTROLLER_ID = accountId;
+  process.env.SEEDHAPE_TOKEN = "fork-token";
+  delete process.env.SEEDHAPE_AGENT_METADATA_ORIGIN;
+  const seedhape = await fakeSeedhape(rpcUrl);
+  process.env.SEEDHAPE_URL = seedhape.url;
+  try {
+    const { setupSeedhapeHostedAgent, loadSeedhapeHostedAgent } = await import("../dist/agent-identity.js");
+    const agent = await setupSeedhapeHostedAgent(dataDir, { name: "fork-agent", description: "Fork test agent" }, () => {}, { fetchImpl: seedhape.publicFetch });
+    assert.equal(agent.stage, "ready");
+    assert.match(agent.identityRef, new RegExp(`^eip155:8453:${REGISTRY}:\\d+$`, "i"));
+    assert.ok(seedhape.calls.includes("POST /api/local-wallet/identity/sponsor"), "gas was sponsored");
+
+    // A merchant resolves the key from the chain + Seedhape-hosted metadata, exactly as Seedhape's verifier does.
+    const trust = { network: "base", chainId: 8453, identityRegistry: REGISTRY, contractAddress: TRUST, rpcUrl };
+    const resolved = await resolveAgentWebBotAuthKey({ config: trust, identityRef: agent.identityRef, signatureAgent: ORIGIN, keyId: agent.webBotAuth.keyId, fetchImpl: seedhape.publicFetch });
+    assert.equal(resolved.keyId, agent.webBotAuth.keyId);
+
+    // The running wallet signs requests with Agent-Identity and keeps the directory fresh.
+    const loaded = await loadSeedhapeHostedAgent(dataDir);
+    try {
+      const headers = await loaded.signRequest("https://merchant.example/signal");
+      assert.equal(headers["Agent-Identity"], agent.identityRef);
+      await verifyWebBotAuth({ url: "https://merchant.example/signal", headers, publicKey: createPublicKey({ key: resolved.publicJwk, format: "jwk" }), expectedKeyId: resolved.keyId });
+    } finally { loaded.stop(); }
+
+    // Running setup again is idempotent: same identity, no new registration.
+    const again = await setupSeedhapeHostedAgent(dataDir, { name: "fork-agent", description: "Fork test agent" }, () => {}, { fetchImpl: seedhape.publicFetch });
+    assert.equal(again.identityRef, agent.identityRef);
+  } finally {
+    seedhape.server.close();
+    anvil.kill();
+    await rm(dataDir, { recursive: true, force: true });
+    for (const service of ["seedhape-agent-identity-controller", "seedhape-agent-identity-keystore"]) await keytar.deletePassword(service, accountId).catch(() => undefined);
+  }
+});

package/test/pay-flow.test.mjs

@@ -0,0 +1,139 @@
+// End-to-end check of the local wallet's pay flow against a fake merchant and a
+// fake Seedhape account: the wallet must ask Seedhape before signing, send
+// nothing when refused or offline, and report the outcome afterwards.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createServer as createHttp } from "node:http";
+import { generatePrivateKey } from "viem/accounts";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { LocalSessionKeySigner, USDC } from "@seedhape/core";
+
+const asset = USDC["base-sepolia"];
+const payTo = "0x1111111111111111111111111111111111111111";
+
+function listen(handler) {
+  return new Promise((resolve) => {
+    const server = createHttp(handler);
+    server.listen(0, "127.0.0.1", () => resolve({ server, url: `http://127.0.0.1:${server.address().port}` }));
+  });
+}
+
+async function readJson(request) {
+  let raw = "";
+  for await (const chunk of request) raw += chunk;
+  return raw ? JSON.parse(raw) : null;
+}
+
+/** Fake Seedhape: records calls; `decision` controls authorize's answer. */
+async function fakeSeedhape(decision) {
+  const calls = { authorize: [], settle: [] };
+  const { server, url } = await listen(async (request, response) => {
+    const body = await readJson(request);
+    if (request.headers.authorization !== "Bearer test-token") { response.writeHead(401).end("{}"); return; }
+    if (request.url === "/api/local-wallet/authorize") {
+      calls.authorize.push(body);
+      const answer = decision === "approve"
+        ? { ok: true, authorizationId: "auth-1", mandateHash: "0xabc", amount: body.requirement.maxAmountRequired, payTo: body.requirement.payTo, network: body.requirement.network, expiresAt: 0 }
+        : { ok: false, code: "SPENDING_PAUSED", error: "Spending is paused for this account.", hint: "The user has paused all agent spending.", recovery: { tool: "pause_spending" } };
+      response.writeHead(answer.ok ? 200 : 409, { "content-type": "application/json" }).end(JSON.stringify(answer));
+      return;
+    }
+    if (request.url === "/api/local-wallet/settle") {
+      calls.settle.push(body);
+      response.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ ok: true, status: body.status }));
+      return;
+    }
+    response.writeHead(404).end("{}");
+  });
+  return { server, url, calls };
+}
+
+/** Fake merchant: 402 until a payment header arrives; `settles` controls whether payment succeeds. */
+async function fakeMerchant(settles = true) {
+  const seen = { paidRequests: 0 };
+  const { server, url } = await listen((request, response) => {
+    const payment = request.headers["x-payment"] ?? request.headers["payment-signature"];
+    const challenge = { x402Version: 1, accepts: [{ scheme: "exact", network: "base-sepolia", maxAmountRequired: "10000", resource: `${url}/signal`, description: "Market signal", payTo, asset: asset.address, maxTimeoutSeconds: 60, extra: { name: "USDC", version: "2" } }] };
+    if (!payment) { response.writeHead(402, { "content-type": "application/json" }).end(JSON.stringify(challenge)); return; }
+    seen.paidRequests += 1;
+    if (!settles) { response.writeHead(402, { "content-type": "application/json" }).end(JSON.stringify({ ...challenge, error: "insufficient_funds" })); return; }
+    const settlement = Buffer.from(JSON.stringify({ success: true, transaction: `0x${"ab".repeat(32)}`, network: "base-sepolia" })).toString("base64");
+    response.writeHead(200, { "content-type": "text/plain", "x-payment-response": settlement }).end("signal: bullish");
+  });
+  return { server, url, seen };
+}
+
+async function connectWallet() {
+  process.env.SEEDHAPE_TOKEN = "test-token";
+  const { createServer } = await import("../dist/server.js");
+  const key = generatePrivateKey();
+  const signer = new LocalSessionKeySigner(key);
+  const server = createServer({ agentId: "laptop", address: signer.address, signer, asset, absoluteMaxPerPayment: 1_000_000n, outboundPolicy: { allowPrivateNetworks: true } });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  await server.connect(serverTransport);
+  const client = new Client({ name: "test", version: "1" });
+  await client.connect(clientTransport);
+  const pay = async (url) => (await client.callTool({ name: "pay", arguments: { url } })).content[0].text;
+  return { client, pay };
+}
+
+test("an approved payment is authorized first, paid, then reported as settled", async () => {
+  const seedhape = await fakeSeedhape("approve");
+  const merchant = await fakeMerchant(true);
+  process.env.SEEDHAPE_URL = seedhape.url;
+  const { client, pay } = await connectWallet();
+  try {
+    const result = await pay(`${merchant.url}/signal`);
+    assert.match(result, /^Paid 0\.010000 USDC/);
+    assert.match(result, /signal: bullish/);
+    assert.equal(seedhape.calls.authorize.length, 1);
+    assert.equal(seedhape.calls.authorize[0].agent_id, "laptop");
+    assert.equal(seedhape.calls.authorize[0].requirement.maxAmountRequired, "10000");
+    assert.equal(merchant.seen.paidRequests, 1);
+    assert.deepEqual(seedhape.calls.settle.map((call) => call.status), ["settled"]);
+    assert.equal(seedhape.calls.settle[0].authorization_id, "auth-1");
+  } finally { await client.close(); seedhape.server.close(); merchant.server.close(); }
+});
+
+test("a refused payment never reaches the merchant and explains the next step", async () => {
+  const seedhape = await fakeSeedhape("refuse");
+  const merchant = await fakeMerchant(true);
+  process.env.SEEDHAPE_URL = seedhape.url;
+  const { client, pay } = await connectWallet();
+  try {
+    const result = await pay(`${merchant.url}/signal`);
+    assert.match(result, /^PAYMENT NOT MADE\./);
+    assert.match(result, /Spending is paused/);
+    assert.match(result, /Next step: call pause_spending/);
+    assert.equal(merchant.seen.paidRequests, 0, "no signed payment may be sent");
+    assert.equal(seedhape.calls.settle.length, 0);
+  } finally { await client.close(); seedhape.server.close(); merchant.server.close(); }
+});
+
+test("when Seedhape is unreachable, nothing is paid", async () => {
+  const merchant = await fakeMerchant(true);
+  const closed = await listen(() => {});
+  const deadUrl = closed.url;
+  await new Promise((resolve) => closed.server.close(resolve));
+  process.env.SEEDHAPE_URL = deadUrl;
+  const { client, pay } = await connectWallet();
+  try {
+    const result = await pay(`${merchant.url}/signal`);
+    assert.match(result, /^PAYMENT NOT MADE\./);
+    assert.match(result, /could not be reached/);
+    assert.equal(merchant.seen.paidRequests, 0);
+  } finally { await client.close(); merchant.server.close(); }
+});
+
+test("a payment the merchant rejects is reported as failed so the budget is released", async () => {
+  const seedhape = await fakeSeedhape("approve");
+  const merchant = await fakeMerchant(false);
+  process.env.SEEDHAPE_URL = seedhape.url;
+  const { client, pay } = await connectWallet();
+  try {
+    const result = await pay(`${merchant.url}/signal`);
+    assert.match(result, /PAYMENT NOT COMPLETED/);
+    assert.deepEqual(seedhape.calls.settle.map((call) => call.status), ["failed"]);
+  } finally { await client.close(); seedhape.server.close(); merchant.server.close(); }
+});