@seedhape/local-wallet 0.2.0

package/src/index.ts

@@ -0,0 +1,374 @@
+#!/usr/bin/env node
+/**
+ * Seedhape local wallet (CLI: `seedhape`).
+ *
+ * Keeps an agent's payment key in the operating system keychain and signs
+ * payments on this computer. Spending rules, budget, pause, and history live in
+ * the user's Seedhape account; every payment is checked there first.
+ *
+ *   seedhape setup [--client codex|claude] [--agent <id>]   one-step setup
+ *   seedhape login [--token]                                sign in to Seedhape
+ *   seedhape logout | seedhape whoami
+ *   seedhape wallet:init|wallet:address|wallet:delete <agent-id>
+ *   seedhape webbotauth:init|status|rotate|revoke [--agent <id>]  agent identity key
+ *   seedhape identity:*                                     ERC-8004 identity tools
+ *   seedhape                                                run the local MCP server (stdio)
+ */
+
+import { homedir, hostname } from "node:os";
+import { join, resolve } from "node:path";
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { emitKeypressEvents } from "node:readline";
+import { createServer as createHttpServer } from "node:http";
+import { spawnSync } from "node:child_process";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { LocalSessionKeySigner, USDC, type Hex } from "@seedhape/core";
+import { privateKeyToAccount } from "viem/accounts";
+import { createServer } from "./server.js";
+import { callHostedTool, deleteToken, loadToken, loginWithBrowser, saveToken, seedhapeUrl, whoAmI } from "./hosted.js";
+import { deleteWebBotAuthKey, loadWebBotAuthKey, saveWebBotAuthKey } from "./keychain.js";
+import { loadSeedhapeHostedAgent, setupSeedhapeHostedAgent } from "./agent-identity.js";
+import { defaultSignatureAgent, generateWebBotAuthKey, registerWebBotAuthKey, revokeWebBotAuthKey } from "./web-bot-auth.js";
+import { createLocalWallet, deleteLocalWallet, exportIdentityControllerPrivateKey, identityControllerPrivateKey, importIdentityController, localWalletAddress, localWalletPrivateKey } from "./keychain.js";
+import { createSelfCustodiedBackupPayload, createSelfCustodiedMetadataHandler, loadSelfCustodiedAgent, restoreSelfCustodiedBackupPayload, setupSelfCustodiedAgent } from "./agent-identity.js";
+import { decryptIdentityBackup, encryptIdentityBackup } from "./identity-backup.js";
+
+const AGENT_ID = /^[A-Za-z0-9._-]{1,128}$/;
+const defaultAgentId = () => (hostname().replace(/[^A-Za-z0-9._-]/g, "-").slice(0, 60) || "local") + "-agent";
+const flag = (args: string[], name: string) => { const index = args.indexOf(name); return index >= 0 ? args[index + 1] : undefined; };
+const say = (line: string) => console.error(line);
+
+function promptSecret(label: string): Promise<string> {
+  const input = process.stdin;
+  if (!input.isTTY || typeof input.setRawMode !== "function") throw new Error("Identity backup/restore requires an interactive terminal so the passphrase is not echoed.");
+  return new Promise((resolvePrompt, rejectPrompt) => {
+    emitKeypressEvents(input);
+    input.setRawMode(true);
+    input.resume();
+    let value = "";
+    process.stderr.write(`${label} (hidden): `);
+    const cleanup = () => {
+      input.off("keypress", onKeypress);
+      input.setRawMode(false);
+      process.stderr.write("\n");
+    };
+    const onKeypress = (character: string, key: { name?: string; ctrl?: boolean; meta?: boolean }) => {
+      if (key.ctrl && key.name === "c") {
+        cleanup();
+        rejectPrompt(new Error("Cancelled."));
+      } else if (key.name === "return" || key.name === "enter") {
+        cleanup();
+        resolvePrompt(value);
+      } else if (key.name === "backspace") {
+        if (value.length) {
+          value = value.slice(0, -1);
+          process.stderr.write("\b \b");
+        }
+      } else if (character && !key.ctrl && !key.meta && character >= " ") {
+        value += character;
+        process.stderr.write("*");
+      }
+    };
+    input.on("keypress", onKeypress);
+  });
+}
+
+
+async function login(args: string[]) {
+  if (args.includes("--token")) {
+    const token = (await promptSecret(`Paste a connection token from ${seedhapeUrl()}/connect-mcp`)).trim();
+    if (!token) throw new Error("No token entered.");
+    await saveToken(token);
+  } else {
+    await loginWithBrowser(say);
+  }
+  const account = await whoAmI();
+  if (!account.ok) throw new Error(`The saved sign-in did not work: ${account.detail}`);
+  say(`✓ Signed in to ${seedhapeUrl()}. Token saved in your keychain.`);
+}
+
+/** Create (or reuse) the keychain wallet and register its public address with the user's Seedhape account. */
+async function registerWallet(agentId: string, chain: string) {
+  const address = await createLocalWallet(agentId);
+  const key = await localWalletPrivateKey(agentId);
+  if (!key) throw new Error("The wallet could not be read back from the keychain.");
+  const existing = await callHostedTool("external_agent_wallet_status", {});
+  if (existing.toLowerCase().includes(address.toLowerCase())) return { address, alreadyRegistered: true };
+  const challenge = JSON.parse(await callHostedTool("external_agent_wallet_challenge", { agent_id: agentId, address, chain })) as { message?: string; error?: string };
+  if (!challenge.message) throw new Error(challenge.error ?? "Seedhape did not return a registration challenge.");
+  const signature = await privateKeyToAccount(key).signMessage({ message: challenge.message });
+  const registered = JSON.parse(await callHostedTool("register_external_agent_wallet", { agent_id: agentId, address, chain, message: challenge.message, signature })) as { registered?: boolean; error?: string };
+  if (!registered.registered) throw new Error(registered.error ?? "Seedhape did not register the wallet.");
+  return { address, alreadyRegistered: false };
+}
+
+/** Add both the hosted Seedhape MCP and this local wallet to Codex or Claude Code. */
+function addToClient(client: "codex" | "claude", agentId: string, network: string) {
+  const mcpUrl = `${seedhapeUrl()}/mcp`;
+  const env = [`SEEDHAPE_LOCAL_AGENT=${agentId}`, `SEEDHAPE_NETWORK=${network}`, `SEEDHAPE_URL=${seedhapeUrl()}`];
+  const commands: string[][] = client === "codex"
+    ? [["codex", "mcp", "add", "Seedhape", "--url", mcpUrl], ["codex", "mcp", "add", "seedhape-wallet", ...env.flatMap((value) => ["--env", value]), "--", "npx", "-y", "@seedhape/local-wallet"]]
+    : [["claude", "mcp", "add", "--transport", "http", "seedhape", mcpUrl], ["claude", "mcp", "add", "seedhape-wallet", ...env.flatMap((value) => ["-e", value]), "--", "npx", "-y", "@seedhape/local-wallet"]];
+  for (const command of commands) {
+    const run = spawnSync(command[0], command.slice(1), { stdio: "inherit" });
+    if (run.error || run.status !== 0) say(`     Could not run it automatically. Run this yourself:\n       ${command.join(" ")}`);
+  }
+}
+
+/** Create and register this agent's Web Bot Auth key, reusing an existing one. */
+async function initWebBotAuth(agentId: string, signatureAgent?: string) {
+  const existing = await loadWebBotAuthKey(agentId);
+  if (existing && (!signatureAgent || new URL(signatureAgent).toString() === existing.signatureAgent)) {
+    // Re-registering a key this account already owns is a no-op on the server.
+    await registerWebBotAuthKey(callHostedTool, agentId, existing);
+    return { key: existing, created: false };
+  }
+  const key = generateWebBotAuthKey(signatureAgent ?? defaultSignatureAgent(seedhapeUrl(), agentId));
+  await registerWebBotAuthKey(callHostedTool, agentId, key);
+  await saveWebBotAuthKey(agentId, key);
+  return { key, created: true };
+}
+
+/** Replace the key: register the new one, switch to it, then revoke the old one. */
+async function rotateWebBotAuth(agentId: string) {
+  const old = await loadWebBotAuthKey(agentId);
+  if (!old) throw new Error(`No Web Bot Auth key exists for ${agentId}. Run \`seedhape webbotauth:init\` first.`);
+  const next = generateWebBotAuthKey(old.signatureAgent);
+  await registerWebBotAuthKey(callHostedTool, agentId, next, true);
+  await saveWebBotAuthKey(agentId, next);
+  await revokeWebBotAuthKey(callHostedTool, old);
+  return next;
+}
+
+async function setup(args: string[]) {
+  const agentId = flag(args, "--agent") ?? defaultAgentId();
+  if (!AGENT_ID.test(agentId)) throw new Error("Agent ids may use letters, digits, '.', '_' and '-'.");
+  const network = process.env.SEEDHAPE_NETWORK ?? "base";
+  const asset = USDC[network];
+  if (!asset) throw new Error(`Unsupported network "${network}". Use one of: ${Object.keys(USDC).join(", ")}`);
+  say("1/4  Signing in to Seedhape…");
+  if ((await whoAmI()).ok) say("     Already signed in.");
+  else await login([]);
+  say(`2/4  Creating the wallet "${agentId}" in your keychain and registering its address…`);
+  const wallet = await registerWallet(agentId, asset.network);
+  say(`     ${wallet.alreadyRegistered ? "Already registered" : "Registered"}: ${wallet.address} (the private key stays on this computer)`);
+  say("3/4  Creating this agent's identity so merchants can tell it's you…");
+  const dataDir = process.env.SEEDHAPE_DATA_DIR ?? join(homedir(), ".seedhape");
+  try {
+    // Preferred: an on-chain ERC-8004 identity that any merchant can verify. Seedhape hosts its metadata and covers gas.
+    const agent = await setupSeedhapeHostedAgent(dataDir, { name: agentId, description: "A self-custody Seedhape agent. Its keys stay on the owner's computer." }, say);
+    say(`     On-chain identity ready: ${agent.identityRef}`);
+  } catch (error) {
+    say(`     On-chain identity not available (${error instanceof Error ? error.message : String(error)}).`);
+    try {
+      // Fallback: a Web Bot Auth key registered with Seedhape; works with Seedhape-hosted merchants.
+      const identity = await initWebBotAuth(agentId, flag(args, "--signature-agent"));
+      say(`     Using a Seedhape-registered key instead (${identity.created ? "created" : "already set up"}). Run setup again later to get the on-chain identity.`);
+    } catch (fallbackError) {
+      // Payments don't depend on it, so setup carries on; the user can retry later.
+      say(`     Skipped: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}\n     Payments still work. Run setup again to retry.`);
+    }
+  }
+  const client = flag(args, "--client");
+  if (client === "codex" || client === "claude") {
+    say(`4/4  Adding Seedhape to ${client === "codex" ? "Codex" : "Claude Code"}…`);
+    addToClient(client, agentId, network);
+  } else {
+    say("4/4  Skipped adding to an agent client (use --client codex or --client claude).");
+  }
+  say(`\nNext:\n  • Set its spending limit: ${seedhapeUrl()}/limits/advanced?wallet=${encodeURIComponent(agentId)}\n  • Send USDC on ${network} to ${wallet.address}\n  • Then ask your agent to buy something.`);
+}
+
+async function finishFirstUseSetup(agentId: string, network: string, dataDir: string, log: (line: string) => void) {
+  const account = await whoAmI();
+  if (!account.ok) {
+    log("Opening your browser to connect your Seedhape account…");
+    await loginWithBrowser(log);
+    const signedIn = await whoAmI();
+    if (!signedIn.ok) throw new Error(`Sign-in did not finish: ${signedIn.detail}`);
+  }
+
+  log("Creating your local wallet and connecting it to Seedhape…");
+  const wallet = await registerWallet(agentId, network);
+
+  let identity = await loadSeedhapeHostedAgent(dataDir, (error) => log(`Identity refresh: ${error instanceof Error ? error.message : String(error)}`)).catch(() => undefined);
+  let webBotAuth = await loadWebBotAuthKey(agentId).catch(() => null);
+  if (!identity && !webBotAuth) {
+    log("Setting up your agent identity…");
+    try {
+      const ready = await setupSeedhapeHostedAgent(dataDir, { name: agentId, description: "A self-custody Seedhape agent. Its keys stay on this computer." }, log);
+      identity = await loadSeedhapeHostedAgent(dataDir, (error) => log(`Identity refresh: ${error instanceof Error ? error.message : String(error)}`));
+      if (!identity) log(`Identity saved (${ready.identityRef}); it will be available after restarting the wallet.`);
+    } catch (error) {
+      log(`On-chain identity is unavailable (${error instanceof Error ? error.message : String(error)}). Setting up a simpler identity instead…`);
+      try { webBotAuth = (await initWebBotAuth(agentId)).key; }
+      catch (fallbackError) { log(`Identity setup skipped: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}. Payments can still work.`); }
+    }
+  }
+  const key = await localWalletPrivateKey(agentId) as Hex | null;
+  if (!key) throw new Error("The local wallet could not be loaded from this computer's keychain.");
+  return { address: privateKeyToAccount(key).address, signer: new LocalSessionKeySigner(key), identity: identity ?? null, webBotAuth: webBotAuth ?? null };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const [command, commandAgent, commandOption] = args;
+  const dataDir = process.env.SEEDHAPE_DATA_DIR ?? join(homedir(), ".seedhape");
+  if (command === "login") return login(args.slice(1));
+  if (command === "logout") { say((await deleteToken()) ? "Signed out." : "Not signed in."); return; }
+  if (command === "whoami") { const account = await whoAmI(); say(`${seedhapeUrl()}: ${account.detail}`); return; }
+  if (command === "setup") return setup(args.slice(1));
+  if (command?.startsWith("webbotauth:")) {
+    const agentId = flag(args, "--agent") ?? process.env.SEEDHAPE_LOCAL_AGENT ?? defaultAgentId();
+    if (command === "webbotauth:init") { const { key, created } = await initWebBotAuth(agentId, flag(args, "--signature-agent")); say(`${created ? "Created and registered" : "Already set up"}: ${key.signatureAgent} (key ${key.keyId})`); return; }
+    if (command === "webbotauth:rotate") { const key = await rotateWebBotAuth(agentId); say(`Rotated. New key ${key.keyId}; the old key is revoked.`); return; }
+    if (command === "webbotauth:revoke") {
+      const key = await loadWebBotAuthKey(agentId);
+      if (!key) { say("No Web Bot Auth key to revoke."); return; }
+      await revokeWebBotAuthKey(callHostedTool, key);
+      await deleteWebBotAuthKey(agentId);
+      say("Revoked and removed from your keychain.");
+      return;
+    }
+    if (command === "webbotauth:status") { const key = await loadWebBotAuthKey(agentId); say(key ? `Signing as ${key.signatureAgent}\nKey id: ${key.keyId}\nCreated: ${new Date(key.createdAt * 1000).toISOString()}` : "Not set up. Run `seedhape webbotauth:init`."); return; }
+    throw new Error(`Unknown command "${command}". Use webbotauth:init, webbotauth:status, webbotauth:rotate, or webbotauth:revoke.`);
+  }
+  if (command === "identity:setup") {
+    const agent = await setupSelfCustodiedAgent(dataDir);
+    console.log(`Self-custodied ERC-8004 identity ready: ${agent.identityRef}`);
+    console.log(`Controller: ${agent.controller}`);
+    console.log(`Web Bot Auth directory: ${agent.directoryUri}`);
+    console.log(`Network: ${agent.chainId === 8453 ? "Base" : "Base Sepolia"}`);
+    console.log("Create a complete encrypted backup with `seedhape identity:backup <file>` and keep its passphrase separate.");
+    return;
+  }
+  if (command === "identity:controller-import") {
+    const privateKey = await promptSecret("Existing ERC-8004 controller private key (0x-prefixed)");
+    const address = await importIdentityController(process.env.SEEDHAPE_AGENT_IDENTITY_CONTROLLER_ID ?? "local-primary", privateKey as Hex);
+    console.log(`Imported controller ${address} into the local OS keychain.`);
+    console.log("Next run `seedhape identity:import <identity-reference>` to verify ownership and finish local setup.");
+    return;
+  }
+  if (command === "identity:import") {
+    if (!commandAgent || commandOption !== "--replace-registration") throw new Error("Import replaces the existing onchain metadata URI. Save the existing metadata, then run: seedhape identity:import eip155:<8453|84532>:<registry-address>:<agent-id> --replace-registration");
+    const controller = await identityControllerPrivateKey(process.env.SEEDHAPE_AGENT_IDENTITY_CONTROLLER_ID ?? "local-primary");
+    if (!controller) throw new Error("Import the current ERC-8004 controller first with `seedhape identity:controller-import`.");
+    const agent = await setupSelfCustodiedAgent(dataDir, commandAgent, true);
+    console.log(`Existing self-custodied ERC-8004 identity ready: ${agent.identityRef}`);
+    console.log(`Controller: ${agent.controller}`);
+    console.log(`Web Bot Auth directory: ${agent.directoryUri}`);
+    console.log(`Network: ${agent.chainId === 8453 ? "Base" : "Base Sepolia"}`);
+    return;
+  }
+  if (command === "identity:export") {
+    if (commandAgent !== "--confirm") throw new Error("This prints your identity controller private key. Re-run as `seedhape identity:export --confirm` only in a trusted local terminal.");
+    const key = await exportIdentityControllerPrivateKey(process.env.SEEDHAPE_AGENT_IDENTITY_CONTROLLER_ID ?? "local-primary");
+    if (!key) throw new Error("No local identity controller exists. Run `seedhape identity:setup` first.");
+    console.error("WARNING: anyone with this key controls the onchain agent identity. Store the next line offline; never paste it into chat or commit it.");
+    console.log(key);
+    return;
+  }
+  if (command === "identity:backup") {
+    if (!commandAgent) throw new Error("Usage: seedhape identity:backup <encrypted-backup-file>");
+    const first = await promptSecret("Choose a backup passphrase (12+ characters)");
+    const second = await promptSecret("Repeat backup passphrase");
+    if (first !== second) throw new Error("Passphrases do not match.");
+    const payload = await createSelfCustodiedBackupPayload(dataDir);
+    const encrypted = encryptIdentityBackup(payload, first);
+    const destination = resolve(commandAgent);
+    await writeFile(destination, `${encrypted}\n`, { flag: "wx", mode: 0o600 });
+    console.log(`Encrypted identity backup created at ${destination}. Keep the passphrase separate from the file.`);
+    return;
+  }
+  if (command === "identity:restore") {
+    if (!commandAgent) throw new Error("Usage: seedhape identity:restore <encrypted-backup-file>");
+    const source = resolve(commandAgent);
+    const info = await stat(source);
+    if (!info.isFile() || info.size > 10 * 1024 * 1024) throw new Error("Identity backup must be a regular file no larger than 10 MB.");
+    const passphrase = await promptSecret("Backup passphrase");
+    const payload = decryptIdentityBackup(await readFile(source, "utf8"), passphrase);
+    const restored = await restoreSelfCustodiedBackupPayload(dataDir, payload);
+    console.log(`Restored identity ${restored.identityRef} controlled by ${restored.controller}.`);
+    console.log(`Identity keychain slot: ${payload.accountId}. Restore with this SEEDHAPE_AGENT_IDENTITY_CONTROLLER_ID value or leave it unset.`);
+    console.log("Verify SEEDHAPE_AGENT_TRUST_* and SEEDHAPE_AGENT_METADATA_ORIGIN match this identity before starting the MCP server.");
+    return;
+  }
+  if (command === "identity:metadata-server") {
+    const origin = process.env.SEEDHAPE_AGENT_METADATA_ORIGIN;
+    if (!origin) throw new Error("Set SEEDHAPE_AGENT_METADATA_ORIGIN to the public HTTPS origin routed to this metadata server.");
+    const publicOrigin = new URL(origin);
+    if (publicOrigin.protocol !== "https:" || publicOrigin.pathname !== "/" || publicOrigin.search || publicOrigin.hash) throw new Error("SEEDHAPE_AGENT_METADATA_ORIGIN must be an HTTPS origin without a path.");
+    const handler = await createSelfCustodiedMetadataHandler(dataDir);
+    const host = process.env.SEEDHAPE_AGENT_METADATA_BIND ?? "127.0.0.1";
+    const port = Number(process.env.SEEDHAPE_AGENT_METADATA_PORT ?? "8787");
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error("SEEDHAPE_AGENT_METADATA_PORT must be a valid TCP port.");
+    const server = createHttpServer(async (incoming, outgoing) => {
+      try {
+        const url = new URL(incoming.url ?? "/", origin);
+        if (url.origin !== publicOrigin.origin) {
+          outgoing.statusCode = 400;
+          outgoing.end("Invalid metadata origin.");
+          return;
+        }
+        const response = await handler(new Request(url, { method: incoming.method ?? "GET" }));
+        outgoing.statusCode = response.status;
+        response.headers.forEach((value, name) => outgoing.setHeader(name, value));
+        outgoing.end(incoming.method === "HEAD" ? undefined : Buffer.from(await response.arrayBuffer()));
+      } catch (error) {
+        outgoing.statusCode = 500;
+        outgoing.end(error instanceof Error ? error.message : "Metadata request failed.");
+      }
+    });
+    server.listen(port, host, () => console.error(`Self-custodied agent metadata handler listening on ${host}:${port}; proxy ${origin}/.well-known/seedhape-agents/* here.`));
+    return;
+  }
+  if (command === "wallet:init") {
+    if (!commandAgent) throw new Error("Usage: seedhape wallet:init <agent-id>");
+    console.log(await createLocalWallet(commandAgent));
+    return;
+  }
+  if (command === "wallet:address") {
+    if (!commandAgent) throw new Error("Usage: seedhape wallet:address <agent-id>");
+    const address = await localWalletAddress(commandAgent);
+    if (!address) throw new Error(`No local wallet exists for ${commandAgent}.`);
+    console.log(address);
+    return;
+  }
+  if (command === "wallet:delete") {
+    if (!commandAgent) throw new Error("Usage: seedhape wallet:delete <agent-id>");
+    console.log((await deleteLocalWallet(commandAgent)) ? "Deleted." : "No wallet found.");
+    return;
+  }
+  if (command && command !== "serve") throw new Error(`Unknown command "${command}". Run \`seedhape setup\` to get started.`);
+
+  // Default: run the local MCP server over stdio for Codex, Claude Code, or another MCP client.
+  const network = process.env.SEEDHAPE_NETWORK ?? "base";
+  const asset = USDC[network];
+  if (!asset) throw new Error(`Unsupported network "${network}". Use one of: ${Object.keys(USDC).join(", ")}`);
+  const agentId = process.env.SEEDHAPE_LOCAL_AGENT ?? process.env.SEEDHAPE_LOCAL_KEYTAR_AGENT ?? defaultAgentId();
+  const key = await localWalletPrivateKey(agentId) as Hex | null;
+  const hasSavedAccount = Boolean(await loadToken());
+  const identity = await loadSeedhapeHostedAgent(process.env.SEEDHAPE_DATA_DIR ?? join(homedir(), ".seedhape"), (error) => say(`seedhape: could not refresh the agent's key directory: ${error instanceof Error ? error.message : String(error)}`)).catch((error) => { say(`seedhape: on-chain identity unavailable (${error instanceof Error ? error.message : String(error)}); continuing without it.`); return undefined; });
+  const webBotAuth = await loadWebBotAuthKey(agentId).catch(() => null);
+  const server = createServer({
+    agentId,
+    address: key ? privateKeyToAccount(key).address : null,
+    signer: key ? new LocalSessionKeySigner(key) : null,
+    webBotAuth,
+    identity: identity ?? null,
+    asset,
+    absoluteMaxPerPayment: BigInt(process.env.SEEDHAPE_ABSOLUTE_MAX ?? "1000000"),
+    setupNeeded: !hasSavedAccount || !key || (!identity && !webBotAuth),
+    finishSetup: () => finishFirstUseSetup(agentId, asset.network, dataDir, say),
+    onSetupError: (error) => say(`seedhape: browser setup did not finish (${error instanceof Error ? error.message : String(error)}). Try any wallet tool again to retry.`),
+  });
+  await server.connect(new StdioServerTransport());
+  const shutdown = () => process.exit(0);
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
+main().catch((error) => {
+  console.error(`seedhape: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+});

package/src/keychain.ts

@@ -0,0 +1,114 @@
+import keytar from "keytar";
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+import type { Address, Hex } from "@seedhape/core";
+
+const SERVICE = "seedhape-agent-wallet";
+const IDENTITY_SERVICE = "seedhape-agent-identity-controller";
+const IDENTITY_KEYSTORE_SERVICE = "seedhape-agent-identity-keystore";
+
+export async function createLocalWallet(agentId: string): Promise<Address> {
+  const existing = await keytar.getPassword(SERVICE, agentId);
+  if (existing) return privateKeyToAccount(existing as Hex).address;
+  const privateKey = generatePrivateKey();
+  await keytar.setPassword(SERVICE, agentId, privateKey);
+  return privateKeyToAccount(privateKey).address;
+}
+
+export async function localWalletAddress(agentId: string): Promise<Address | null> {
+  const privateKey = await keytar.getPassword(SERVICE, agentId);
+  return privateKey ? privateKeyToAccount(privateKey as Hex).address : null;
+}
+
+export async function localWalletPrivateKey(agentId: string): Promise<Hex | null> {
+  const privateKey = await keytar.getPassword(SERVICE, agentId);
+  return privateKey as Hex | null;
+}
+
+export async function deleteLocalWallet(agentId: string): Promise<boolean> {
+  return keytar.deletePassword(SERVICE, agentId);
+}
+
+/** Identity controller is stored under a separate OS-keychain service from payment wallets. */
+export async function createOrGetIdentityController(agentId: string): Promise<Hex> {
+  const existing = await keytar.getPassword(IDENTITY_SERVICE, agentId);
+  if (existing) return existing as Hex;
+  const privateKey = generatePrivateKey();
+  await keytar.setPassword(IDENTITY_SERVICE, agentId, privateKey);
+  const persisted = await keytar.getPassword(IDENTITY_SERVICE, agentId);
+  if (!persisted) throw new Error("Could not persist identity controller in the operating system keychain.");
+  return persisted as Hex;
+}
+
+/** Import a controller only into an empty slot, or accept the same key idempotently. */
+export async function importIdentityController(agentId: string, privateKey: Hex): Promise<Address> {
+  const importedAddress = privateKeyToAccount(privateKey).address;
+  const existing = await keytar.getPassword(IDENTITY_SERVICE, agentId);
+  if (existing && privateKeyToAccount(existing as Hex).address.toLowerCase() !== importedAddress.toLowerCase()) {
+    throw new Error("A different identity controller is already stored in this OS keychain slot. Set SEEDHAPE_AGENT_IDENTITY_CONTROLLER_ID to a fresh slot.");
+  }
+  if (!existing) await keytar.setPassword(IDENTITY_SERVICE, agentId, privateKey);
+  return importedAddress;
+}
+
+export async function identityControllerPrivateKey(agentId: string): Promise<Hex | null> {
+  return await keytar.getPassword(IDENTITY_SERVICE, agentId) as Hex | null;
+}
+
+/** Explicit recovery export; callers must only invoke this in a trusted local terminal. */
+export async function exportIdentityControllerPrivateKey(agentId: string): Promise<Hex | null> {
+  return identityControllerPrivateKey(agentId);
+}
+
+export async function createOrGetIdentityKeyStoreMasterKey(agentId: string): Promise<Buffer> {
+  const existing = await keytar.getPassword(IDENTITY_KEYSTORE_SERVICE, agentId);
+  if (existing) return Buffer.from(existing, "base64url");
+  const masterKey = Buffer.from(generatePrivateKey().slice(2), "hex");
+  await keytar.setPassword(IDENTITY_KEYSTORE_SERVICE, agentId, masterKey.toString("base64url"));
+  const persisted = await keytar.getPassword(IDENTITY_KEYSTORE_SERVICE, agentId);
+  if (!persisted) throw new Error("Could not persist the identity key-store key in the operating system keychain.");
+  return Buffer.from(persisted, "base64url");
+}
+
+export async function identityKeyStoreMasterKey(agentId: string): Promise<Buffer | null> {
+  const existing = await keytar.getPassword(IDENTITY_KEYSTORE_SERVICE, agentId);
+  return existing ? Buffer.from(existing, "base64url") : null;
+}
+
+export async function restoreIdentityCredentials(agentId: string, controllerKey: Hex, masterKey: Buffer): Promise<void> {
+  if (masterKey.length !== 32) throw new Error("Identity backup key-store key must be 32 bytes.");
+  const controller = privateKeyToAccount(controllerKey).address;
+  const currentController = await keytar.getPassword(IDENTITY_SERVICE, agentId);
+  const currentMaster = await keytar.getPassword(IDENTITY_KEYSTORE_SERVICE, agentId);
+  if (currentController && privateKeyToAccount(currentController as Hex).address.toLowerCase() !== controller.toLowerCase()) {
+    throw new Error("A different identity controller is already stored under this OS keychain account. Use a fresh SEEDHAPE_AGENT_IDENTITY_CONTROLLER_ID or back up the existing identity first.");
+  }
+  if (currentMaster && !Buffer.from(currentMaster, "base64url").equals(masterKey)) {
+    throw new Error("A different identity key-store key is already stored under this OS keychain account. Use a fresh SEEDHAPE_AGENT_IDENTITY_CONTROLLER_ID or back up the existing identity first.");
+  }
+  if (!currentController) await keytar.setPassword(IDENTITY_SERVICE, agentId, controllerKey);
+  if (!currentMaster) await keytar.setPassword(IDENTITY_KEYSTORE_SERVICE, agentId, masterKey.toString("base64url"));
+}
+
+// ── Web Bot Auth (Ed25519 key that proves which agent is calling) ──────────
+const WEB_BOT_AUTH_SERVICE = "seedhape-web-bot-auth";
+
+export type StoredWebBotAuthKey = {
+  privateKeyPem: string;
+  publicJwk: { kty: "OKP"; crv: "Ed25519"; x: string };
+  keyId: string;
+  signatureAgent: string;
+  createdAt: number;
+};
+
+export async function saveWebBotAuthKey(agentId: string, key: StoredWebBotAuthKey): Promise<void> {
+  await keytar.setPassword(WEB_BOT_AUTH_SERVICE, agentId, JSON.stringify(key));
+}
+
+export async function loadWebBotAuthKey(agentId: string): Promise<StoredWebBotAuthKey | null> {
+  const raw = await keytar.getPassword(WEB_BOT_AUTH_SERVICE, agentId);
+  return raw ? JSON.parse(raw) as StoredWebBotAuthKey : null;
+}
+
+export async function deleteWebBotAuthKey(agentId: string): Promise<boolean> {
+  return keytar.deletePassword(WEB_BOT_AUTH_SERVICE, agentId);
+}

package/src/seedhape-identity.ts

@@ -0,0 +1,113 @@
+/**
+ * On-chain (ERC-8004) identity for a self-custody agent, with Seedhape doing the
+ * hosting so the user configures nothing:
+ *
+ *   • Seedhape tells the wallet which Base registry / AgentTrust contract to use.
+ *   • Seedhape can top up the identity controller's gas once per account.
+ *   • Seedhape serves the agent's public registration and key directory.
+ *
+ * Every key stays on this machine. Merchants reject key-directory signatures
+ * older than 5 minutes, so while the wallet runs it re-signs the directory and
+ * uploads just the signature every few minutes.
+ */
+
+import type { PrivateKeyAccount } from "viem/accounts";
+import { FileAgentMetadataPublisher, type AgentMetadataPublisher, type AgentOperationalKeyStore, type AgentTrustConfig } from "@seedhape/core";
+import { SeedhapeAuthError, SeedhapeUnreachableError, loadToken, seedhapeUrl } from "./hosted.js";
+
+export type IdentityConfig =
+  | { enabled: false }
+  | { enabled: true; network: "base" | "base-sepolia"; chainId: 8453 | 84532; identityRegistry: `0x${string}`; trustContract: `0x${string}`; rpcUrl: string; signatureAgent: string; minimumControllerBalanceWei: string; gasSponsored: boolean };
+
+/** Directory signatures last just under the 5-minute maximum and are refreshed well before expiry. */
+export const DIRECTORY_LIFETIME_SECONDS = 290;
+export const DIRECTORY_REFRESH_MS = 240_000;
+
+async function call<T>(method: "GET" | "POST" | "PUT", path: string, body?: unknown): Promise<T> {
+  const token = await loadToken();
+  if (!token) throw new SeedhapeAuthError();
+  let response: Response;
+  try {
+    response = await fetch(`${seedhapeUrl()}${path}`, {
+      method,
+      headers: { authorization: `Bearer ${token}`, ...(body ? { "content-type": "application/json" } : {}) },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+      signal: AbortSignal.timeout(60_000),
+    });
+  } catch (error) {
+    throw new SeedhapeUnreachableError(error);
+  }
+  if (response.status === 401) throw new SeedhapeAuthError();
+  const parsed = await response.json().catch(() => ({})) as T & { error?: string };
+  if (!response.ok) throw new Error(parsed.error ?? `Seedhape returned HTTP ${response.status}.`);
+  return parsed;
+}
+
+export const fetchIdentityConfig = () => call<IdentityConfig>("GET", "/api/local-wallet/identity");
+
+export function trustConfigFrom(config: Extract<IdentityConfig, { enabled: true }>): AgentTrustConfig {
+  return { network: config.network, chainId: config.chainId, identityRegistry: config.identityRegistry, contractAddress: config.trustContract, rpcUrl: config.rpcUrl };
+}
+
+export const requestGasSponsorship = (controller: string) =>
+  call<{ outcome: "funded" } | { outcome: "pending"; transactionHash: string } | { outcome: "manual"; reason: string }>("POST", "/api/local-wallet/identity/sponsor", { controller });
+
+/** Must match the hosted ownershipMessage() exactly. */
+export const ownershipMessage = (identityRef: string, keyId: string) => `Seedhape self-custody agent metadata\nidentity=${identityRef}\nkey=${keyId}`;
+
+export type PublishedDirectory = { identityRef: string; keyId: string; keyStoreRef: string; publicJwk: Record<string, unknown>; directoryUri: string };
+
+/** Sign the key directory locally and upload only the signature (plus public key) to Seedhape. */
+export async function uploadDirectory(keyStore: AgentOperationalKeyStore, directory: PublishedDirectory, owner?: PrivateKeyAccount): Promise<void> {
+  const signer = await keyStore.getSigner(directory.keyStoreRef);
+  const signed = await signer.signDirectory({ url: directory.directoryUri, keyId: directory.keyId, expiresInSeconds: DIRECTORY_LIFETIME_SECONDS });
+  await call("PUT", "/api/local-wallet/identity/directory", {
+    identityRef: directory.identityRef, keyId: directory.keyId, publicJwk: directory.publicJwk,
+    signature: signed.Signature, signatureInput: signed["Signature-Input"],
+    ...(owner ? { ownerSignature: await owner.signMessage({ message: ownershipMessage(directory.identityRef, directory.keyId) }) } : {}),
+  });
+}
+
+/**
+ * Metadata publisher used by setupAgent: keeps the local files (so identity
+ * backups keep working) and publishes the same metadata through Seedhape.
+ */
+export class SeedhapeMetadataPublisher implements AgentMetadataPublisher {
+  private readonly files: FileAgentMetadataPublisher;
+  private refresher: ReturnType<typeof setInterval> | undefined;
+
+  constructor(metadataDirectory: string, private readonly signatureAgent: string, private readonly keyStore: AgentOperationalKeyStore, private readonly owner: PrivateKeyAccount) {
+    this.files = new FileAgentMetadataPublisher(metadataDirectory, signatureAgent);
+  }
+
+  async publishWebBotAuthDirectory(input: { instanceId: string; identityRef: string; keyId: string; keyStoreRef: string; publicJwk: Record<string, unknown> }) {
+    const published = await this.files.publishWebBotAuthDirectory(input);
+    const directory = { ...input, directoryUri: published.directoryUri };
+    await uploadDirectory(this.keyStore, directory, this.owner);
+    // Setup keeps going (on-chain transactions, then a live check of the directory), so keep the signature fresh meanwhile.
+    this.stop();
+    this.refresher = setInterval(() => { void uploadDirectory(this.keyStore, directory).catch(() => undefined); }, DIRECTORY_REFRESH_MS);
+    this.refresher.unref?.();
+    return published;
+  }
+
+  async publishRegistration(input: { identityRef: string; registration: Record<string, unknown> }): Promise<string> {
+    const uri = await this.files.publishRegistration(input);
+    await call("PUT", "/api/local-wallet/identity/registration", input);
+    return uri;
+  }
+
+  stop() { if (this.refresher) clearInterval(this.refresher); this.refresher = undefined; }
+}
+
+/** Keep a ready agent's directory fresh while the local wallet runs. Returns a function that refreshes immediately. */
+export function startDirectoryRefresher(keyStore: AgentOperationalKeyStore, directory: PublishedDirectory, onError: (error: unknown) => void = () => {}) {
+  let last = 0;
+  const refresh = async (force = false) => {
+    if (!force && Date.now() - last < 60_000) return;
+    try { await uploadDirectory(keyStore, directory); last = Date.now(); } catch (error) { onError(error); }
+  };
+  const timer = setInterval(() => { void refresh(true); }, DIRECTORY_REFRESH_MS);
+  timer.unref?.();
+  return { refresh, stop: () => clearInterval(timer) };
+}