@seedhape/local-wallet 0.2.0

package/src/hosted.ts

@@ -0,0 +1,174 @@
+/**
+ * Talks to the user's Seedhape account. The local wallet holds the key, but
+ * Seedhape holds the rules: every payment is checked and reserved there before
+ * the key signs, and reported back afterwards. If Seedhape can't be reached, no
+ * payment is made (fail closed).
+ */
+
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import type { AddressInfo } from "node:net";
+import keytar from "keytar";
+
+const TOKEN_SERVICE = "seedhape-account-token";
+
+export const seedhapeUrl = () => (process.env.SEEDHAPE_URL ?? "https://www.seedhape.com").replace(/\/$/, "");
+
+export class SeedhapeUnreachableError extends Error {
+  constructor(cause: unknown) {
+    super(`Seedhape could not be reached (${cause instanceof Error ? cause.message : String(cause)}). No payment was made; try again when you're back online.`);
+    this.name = "SeedhapeUnreachableError";
+  }
+}
+
+export class SeedhapeAuthError extends Error {
+  constructor() {
+    super("This local wallet isn't signed in to Seedhape. Run `seedhape login` in a terminal, then try again.");
+    this.name = "SeedhapeAuthError";
+  }
+}
+
+export async function saveToken(token: string, url = seedhapeUrl()): Promise<void> { await keytar.setPassword(TOKEN_SERVICE, url, token); }
+export async function loadToken(url = seedhapeUrl()): Promise<string | null> { return process.env.SEEDHAPE_TOKEN ?? await keytar.getPassword(TOKEN_SERVICE, url); }
+export async function deleteToken(url = seedhapeUrl()): Promise<boolean> { return keytar.deletePassword(TOKEN_SERVICE, url); }
+
+/** POST JSON to the Seedhape API with the stored token. Network failures become SeedhapeUnreachableError. */
+export async function hostedPost<T>(path: string, body: unknown): Promise<{ status: number; body: T }> {
+  const token = await loadToken();
+  if (!token) throw new SeedhapeAuthError();
+  let response: Response;
+  try {
+    response = await fetch(`${seedhapeUrl()}${path}`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(20_000),
+    });
+  } catch (error) {
+    throw new SeedhapeUnreachableError(error);
+  }
+  if (response.status === 401) throw new SeedhapeAuthError();
+  if (response.status >= 500) throw new SeedhapeUnreachableError(`HTTP ${response.status}`);
+  return { status: response.status, body: await response.json() as T };
+}
+
+/** Check that the stored token works, returning the account's spending status. */
+export async function whoAmI(): Promise<{ ok: boolean; detail: string }> {
+  const token = await loadToken();
+  if (!token) return { ok: false, detail: "not signed in" };
+  try {
+    const response = await fetch(`${seedhapeUrl()}/mcp`, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${token}` },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "spending_status", arguments: {} } }),
+      signal: AbortSignal.timeout(20_000),
+    });
+    if (response.status === 401) return { ok: false, detail: "the saved sign-in has expired; run `seedhape login` again" };
+    return { ok: response.ok, detail: response.ok ? "signed in" : `HTTP ${response.status}` };
+  } catch (error) {
+    return { ok: false, detail: new SeedhapeUnreachableError(error).message };
+  }
+}
+
+function openBrowser(url: string) {
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try { spawn(command, args, { stdio: "ignore", detached: true }).unref(); } catch { /* the URL is printed as a fallback */ }
+}
+
+/**
+ * Browser sign-in using Seedhape's OAuth server (the same one Claude and ChatGPT
+ * use for the hosted MCP): dynamic client registration, a loopback redirect,
+ * and PKCE. The token is stored in the OS keychain.
+ */
+export async function loginWithBrowser(log: (line: string) => void): Promise<void> {
+  const base = seedhapeUrl();
+  const verifier = randomBytes(32).toString("base64url");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  const state = randomBytes(16).toString("base64url");
+
+  let resolveCode: (code: string) => void = () => {};
+  let rejectCode: (error: Error) => void = () => {};
+  const codePromise = new Promise<string>((resolve, reject) => { resolveCode = resolve; rejectCode = reject; });
+  const server = createServer((request, response) => {
+    const url = new URL(request.url ?? "/", "http://127.0.0.1");
+    if (url.pathname !== "/callback") { response.writeHead(404).end(); return; }
+    const done = (message: string) => response.writeHead(200, { "content-type": "text/html" }).end(`<!doctype html><meta charset="utf-8"><title>Seedhape</title><body style="font-family:sans-serif;background:#04050a;color:#e9ecf2;display:grid;place-items:center;height:100vh"><p>${message}</p></body>`);
+    if (url.searchParams.get("state") !== state) { done("Sign-in failed: state mismatch. Close this tab and run seedhape login again."); rejectCode(new Error("OAuth state mismatch.")); return; }
+    const code = url.searchParams.get("code");
+    if (!code) { done("Sign-in was cancelled. You can close this tab."); rejectCode(new Error(url.searchParams.get("error") ?? "Sign-in was cancelled.")); return; }
+    done("You're signed in. You can close this tab and return to your agent.");
+    resolveCode(code);
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const redirectUri = `http://127.0.0.1:${(server.address() as AddressInfo).port}/callback`;
+  try {
+    const registration = await fetch(`${base}/oauth/register`, {
+      method: "POST", headers: { "content-type": "application/json" },
+      body: JSON.stringify({ redirect_uris: [redirectUri], client_name: "Seedhape local wallet" }),
+    }).catch((error) => { throw new SeedhapeUnreachableError(error); });
+    const client = await registration.json() as { client_id?: string; error?: string };
+    if (!registration.ok || !client.client_id) throw new Error(client.error ?? "Seedhape did not register this local wallet.");
+
+    const authorize = new URL(`${base}/oauth/authorize`);
+    authorize.search = new URLSearchParams({ response_type: "code", client_id: client.client_id, redirect_uri: redirectUri, code_challenge: challenge, code_challenge_method: "S256", state, scope: "mcp" }).toString();
+    log(`Opening your browser to sign in:\n  ${authorize.toString()}`);
+    openBrowser(authorize.toString());
+
+    const timeout = setTimeout(() => rejectCode(new Error("Sign-in timed out after 5 minutes.")), 5 * 60_000);
+    const code = await codePromise.finally(() => clearTimeout(timeout));
+    const token = await fetch(`${base}/oauth/token`, {
+      method: "POST",
+      body: new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: redirectUri, client_id: client.client_id, code_verifier: verifier }),
+    });
+    const issued = await token.json() as { access_token?: string; error?: string };
+    if (!token.ok || !issued.access_token) throw new Error(issued.error ?? "Seedhape did not issue a token.");
+    await saveToken(issued.access_token, base);
+  } finally {
+    server.close();
+  }
+}
+
+// ── Payment authorization ──────────────────────────────────────────────────
+
+export type HostedRequirement = { scheme: string; network: string; maxAmountRequired: string; payTo: string; asset: string; resource?: string; description?: string; maxTimeoutSeconds?: number };
+export type HostedRefusal = { ok: false; code: string; error: string; hint: string; recovery?: { tool: string }; authorizationId?: string; approvalId?: string; approvalUrl?: string };
+export type HostedAuthorization = { ok: true; authorizationId: string; mandateHash: string; amount: string; payTo: string; network: string; expiresAt: number };
+
+export async function authorizePayment(input: { agentId: string; url: string; requirement: HostedRequirement; purchaseId?: string; confirmUnusual?: boolean; approvalId?: string; method?: "GET" | "POST"; bodySha256?: string }): Promise<HostedAuthorization | HostedRefusal> {
+  const { body } = await hostedPost<HostedAuthorization | HostedRefusal>("/api/local-wallet/authorize", {
+    agent_id: input.agentId, url: input.url, requirement: input.requirement,
+    ...(input.purchaseId ? { purchase_id: input.purchaseId } : {}), ...(input.confirmUnusual ? { confirm_unusual: true } : {}),
+    ...(input.approvalId ? { approval_id: input.approvalId } : {}), ...(input.method ? { method: input.method } : {}), ...(input.bodySha256 ? { body_sha256: input.bodySha256 } : {}),
+  });
+  return body;
+}
+
+export async function settlePayment(input: { authorizationId: string; status: "settled" | "failed"; txHash?: string; error?: string }): Promise<void> {
+  await hostedPost("/api/local-wallet/settle", {
+    authorization_id: input.authorizationId, status: input.status,
+    ...(input.txHash ? { tx_hash: input.txHash } : {}), ...(input.error ? { error: input.error.slice(0, 1000) } : {}),
+  });
+}
+
+/** Call a tool on the hosted Seedhape MCP and return its text result. */
+export async function callHostedTool(name: string, args: Record<string, unknown>): Promise<string> {
+  const token = await loadToken();
+  if (!token) throw new SeedhapeAuthError();
+  let response: Response;
+  try {
+    response = await fetch(`${seedhapeUrl()}/mcp`, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${token}` },
+      body: JSON.stringify({ jsonrpc: "2.0", id: randomBytes(4).readUInt32BE(0), method: "tools/call", params: { name, arguments: args } }),
+      signal: AbortSignal.timeout(30_000),
+    });
+  } catch (error) {
+    throw new SeedhapeUnreachableError(error);
+  }
+  if (response.status === 401) throw new SeedhapeAuthError();
+  const body = await response.json() as { result?: { content?: Array<{ text?: string }> }; error?: { message?: string } };
+  if (body.error) throw new Error(body.error.message ?? `Seedhape tool ${name} failed.`);
+  return body.result?.content?.map((item) => item.text ?? "").join("\n") ?? "";
+}

package/src/identity-backup.ts

@@ -0,0 +1,134 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes, scryptSync } from "node:crypto";
+import { privateKeyToAccount } from "viem/accounts";
+import type { Hex } from "@seedhape/core";
+
+const FORMAT = "seedhape-agent-identity-backup";
+const AAD = Buffer.from(`${FORMAT}:v1`);
+const MAX_BACKUP_BYTES = 10 * 1024 * 1024;
+const FILE_PATH = /^(state\/[a-f0-9]{64}\.state\.json|keys\/[a-f0-9]{64}\.json|metadata\/[a-f0-9]{64}\.(directory|registration)\.json)$/;
+
+export interface LocalIdentityBackupPayload {
+  version: 1;
+  accountId: string;
+  controllerPrivateKey: Hex;
+  keyStoreMasterKey: string;
+  files: Record<string, string>;
+}
+
+interface EncryptedBackup {
+  format: typeof FORMAT;
+  version: 1;
+  kdf: "scrypt-N32768-r8-p1";
+  cipher: "aes-256-gcm";
+  salt: string;
+  iv: string;
+  ciphertext: string;
+  tag: string;
+}
+
+export function encryptIdentityBackup(payload: LocalIdentityBackupPayload, passphrase: string): string {
+  validatePassphrase(passphrase);
+  validatePayload(payload);
+  const salt = randomBytes(16);
+  const iv = randomBytes(12);
+  const key = scryptSync(passphrase, salt, 32, { N: 32_768, r: 8, p: 1, maxmem: 64 * 1024 * 1024 });
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  cipher.setAAD(AAD);
+  const ciphertext = Buffer.concat([cipher.update(JSON.stringify(payload), "utf8"), cipher.final()]);
+  const result: EncryptedBackup = {
+    format: FORMAT,
+    version: 1,
+    kdf: "scrypt-N32768-r8-p1",
+    cipher: "aes-256-gcm",
+    salt: salt.toString("base64url"),
+    iv: iv.toString("base64url"),
+    ciphertext: ciphertext.toString("base64url"),
+    tag: cipher.getAuthTag().toString("base64url"),
+  };
+  const encoded = JSON.stringify(result);
+  if (Buffer.byteLength(encoded) > MAX_BACKUP_BYTES) throw new Error("Identity backup exceeds the 10 MB limit.");
+  return encoded;
+}
+
+export function decryptIdentityBackup(encoded: string, passphrase: string): LocalIdentityBackupPayload {
+  validatePassphrase(passphrase);
+  if (Buffer.byteLength(encoded) > MAX_BACKUP_BYTES) throw new Error("Identity backup exceeds the 10 MB limit.");
+  let backup: EncryptedBackup;
+  try { backup = JSON.parse(encoded) as EncryptedBackup; }
+  catch { throw new Error("Identity backup is not valid JSON."); }
+  if (backup.format !== FORMAT || backup.version !== 1 || backup.kdf !== "scrypt-N32768-r8-p1" || backup.cipher !== "aes-256-gcm") {
+    throw new Error("Unsupported identity backup format.");
+  }
+  const salt = decodeBase64Url(backup.salt, 16, "salt");
+  const iv = decodeBase64Url(backup.iv, 12, "IV");
+  const tag = decodeBase64Url(backup.tag, 16, "authentication tag");
+  const ciphertext = decodeBase64Url(backup.ciphertext, undefined, "ciphertext");
+  const key = scryptSync(passphrase, salt, 32, { N: 32_768, r: 8, p: 1, maxmem: 64 * 1024 * 1024 });
+  try {
+    const decipher = createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAAD(AAD);
+    decipher.setAuthTag(tag);
+    const json = Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+    const payload = JSON.parse(json) as LocalIdentityBackupPayload;
+    validatePayload(payload);
+    return payload;
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("Invalid identity backup")) throw error;
+    throw new Error("Could not decrypt identity backup. Check the passphrase and file integrity.");
+  }
+}
+
+export function validatePayload(payload: LocalIdentityBackupPayload): void {
+  if (!payload || payload.version !== 1 || typeof payload.accountId !== "string" || payload.accountId.length < 1 || payload.accountId.length > 256) {
+    throw new Error("Invalid identity backup: account metadata is missing.");
+  }
+  if (!/^0x[0-9a-fA-F]{64}$/.test(payload.controllerPrivateKey)) throw new Error("Invalid identity backup: controller key is malformed.");
+  if (privateKeyToAccount(payload.controllerPrivateKey).address === "0x0000000000000000000000000000000000000000") throw new Error("Invalid identity backup: controller key is invalid.");
+  const masterKey = decodeBase64Url(payload.keyStoreMasterKey, 32, "key-store key");
+  if (masterKey.length !== 32) throw new Error("Invalid identity backup: key-store key must be 32 bytes.");
+  if (!payload.files || typeof payload.files !== "object" || Array.isArray(payload.files)) throw new Error("Invalid identity backup: file manifest is missing.");
+  const names = Object.keys(payload.files);
+  if (names.length > 256 || names.some((name) => !FILE_PATH.test(name))) throw new Error("Invalid identity backup: file manifest contains an invalid path.");
+  if (names.length < 4) throw new Error("Invalid identity backup: file manifest is incomplete.");
+  let total = 0;
+  for (const [name, contents] of Object.entries(payload.files)) {
+    if (typeof contents !== "string") throw new Error("Invalid identity backup: file contents are malformed.");
+    const bytes = decodeBase64Url(contents, undefined, `file ${name}`);
+    total += bytes.length;
+    if (total > MAX_BACKUP_BYTES) throw new Error("Invalid identity backup: files exceed the size limit.");
+  }
+  const statePaths = names.filter((name) => name.startsWith("state/"));
+  const keyPaths = names.filter((name) => name.startsWith("keys/"));
+  const metadataPaths = names.filter((name) => name.startsWith("metadata/"));
+  if (statePaths.length !== 1 || !keyPaths.length || !metadataPaths.some((path) => path.endsWith(".directory.json")) || !metadataPaths.some((path) => path.endsWith(".registration.json"))) {
+    throw new Error("Invalid identity backup: setup state, signing key, and public metadata are all required.");
+  }
+  try {
+    const stateText = Buffer.from(payload.files[statePaths[0]]!, "base64url").toString("utf8");
+    const state = JSON.parse(stateText) as { controller?: unknown; stage?: unknown; keyStoreRef?: unknown; identityRef?: unknown; keyId?: unknown };
+    const controller = privateKeyToAccount(payload.controllerPrivateKey).address;
+    if (typeof state.controller !== "string" || state.controller.toLowerCase() !== controller.toLowerCase() || state.stage !== "ready" || typeof state.keyStoreRef !== "string" || !/^[a-f0-9]{64}$/.test(state.keyStoreRef) || typeof state.identityRef !== "string" || typeof state.keyId !== "string") {
+      throw new Error();
+    }
+    if (!payload.files[`keys/${state.keyStoreRef}.json`]) throw new Error();
+    const identityHash = createHash("sha256").update(state.identityRef).digest("hex");
+    const directory = JSON.parse(Buffer.from(payload.files[`metadata/${identityHash}.directory.json`] ?? "", "base64url").toString("utf8")) as { identityRef?: string; keyId?: string };
+    const registration = JSON.parse(Buffer.from(payload.files[`metadata/${identityHash}.registration.json`] ?? "", "base64url").toString("utf8")) as { services?: Array<Record<string, unknown>> };
+    if (directory.identityRef !== state.identityRef || directory.keyId !== state.keyId || !registration.services?.some((service) => service.name === "Web Bot Auth" && service.keyId === state.keyId)) throw new Error();
+  } catch {
+    throw new Error("Invalid identity backup: controller does not match the saved setup state.");
+  }
+}
+
+function validatePassphrase(passphrase: string) {
+  if (typeof passphrase !== "string" || passphrase.length < 12 || Buffer.byteLength(passphrase) > 1024) {
+    throw new Error("Backup passphrase must be at least 12 characters and no more than 1 KB.");
+  }
+}
+
+function decodeBase64Url(value: string, expectedLength: number | undefined, label: string): Buffer {
+  if (typeof value !== "string" || !/^[A-Za-z0-9_-]*$/.test(value)) throw new Error(`Invalid identity backup: ${label} encoding is malformed.`);
+  const decoded = Buffer.from(value, "base64url");
+  if (expectedLength !== undefined && decoded.length !== expectedLength) throw new Error(`Invalid identity backup: ${label} must be ${expectedLength} bytes.`);
+  return decoded;
+}