@keeperhub/wallet 0.1.0

package/dist/cli.js

@@ -0,0 +1,616 @@
+// src/cli.ts
+import { Command } from "commander";
+
+// src/balance.ts
+import {
+  createPublicClient,
+  erc20Abi,
+  formatUnits,
+  http
+} from "viem";
+
+// src/chains.ts
+import { defineChain } from "viem";
+import { base } from "viem/chains";
+var tempo = defineChain({
+  id: 4217,
+  name: "Tempo",
+  nativeCurrency: { decimals: 18, name: "Ether", symbol: "ETH" },
+  rpcUrls: {
+    default: {
+      http: [process.env.TEMPO_RPC_URL ?? "https://rpc.tempo.xyz"]
+    }
+  },
+  blockExplorers: {
+    default: { name: "Tempo Explorer", url: "https://explorer.tempo.xyz" }
+  }
+});
+var BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+var TEMPO_USDC_E = "0x20c000000000000000000000b9537d11c60e8b50";
+
+// src/hmac.ts
+import { createHash, createHmac } from "crypto";
+function computeSignature(secret, method, path, subOrgId, body, timestamp) {
+  const bodyDigest = createHash("sha256").update(body).digest("hex");
+  const signingString = `${method}
+${path}
+${subOrgId}
+${bodyDigest}
+${timestamp}`;
+  return createHmac("sha256", secret).update(signingString).digest("hex");
+}
+function buildHmacHeaders(secret, method, path, subOrgId, body) {
+  const timestamp = String(Math.floor(Date.now() / 1e3));
+  const signature = computeSignature(
+    secret,
+    method,
+    path,
+    subOrgId,
+    body,
+    timestamp
+  );
+  return {
+    "X-KH-Sub-Org": subOrgId,
+    "X-KH-Timestamp": timestamp,
+    "X-KH-Signature": signature
+  };
+}
+
+// src/types.ts
+var KeeperHubError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "KeeperHubError";
+    this.code = code;
+  }
+};
+var WalletConfigMissingError = class extends Error {
+  constructor() {
+    super(
+      "Wallet config not found at ~/.keeperhub/wallet.json. Run `npx @keeperhub/wallet add` to provision."
+    );
+    this.name = "WalletConfigMissingError";
+  }
+};
+
+// src/client.ts
+var TRAILING_SLASH = /\/$/;
+function defaultCodeForStatus(status) {
+  if (status === 401) {
+    return "HMAC_INVALID";
+  }
+  if (status === 403) {
+    return "POLICY_BLOCKED";
+  }
+  if (status === 404) {
+    return "NOT_FOUND";
+  }
+  if (status === 502) {
+    return "TURNKEY_UPSTREAM";
+  }
+  return `HTTP_${status}`;
+}
+var KeeperHubClient = class {
+  baseUrl;
+  fetchImpl;
+  wallet;
+  constructor(wallet, opts = {}) {
+    this.wallet = wallet;
+    const envBase = process.env.KEEPERHUB_API_URL;
+    this.baseUrl = (opts.baseUrl ?? envBase ?? "https://app.keeperhub.com").replace(TRAILING_SLASH, "");
+    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+  }
+  /**
+   * HMAC-signed POST/GET to any /api/agentic-wallet/* route except
+   * /provision. Path MUST start with a leading slash. Body is
+   * JSON.stringify'd (or the empty string for GET).
+   *
+   * Error mapping: non-2xx/non-202 surface as `KeeperHubError(code,
+   * message)` where `code` is the server-supplied field or the default
+   * taxonomy (`HMAC_INVALID`, `POLICY_BLOCKED`, `NOT_FOUND`,
+   * `TURNKEY_UPSTREAM`, `HTTP_<status>`). 202 ask-tier surfaces as an
+   * AskTierResponse envelope.
+   */
+  async request(method, path, body) {
+    const bodyStr = body === void 0 ? "" : JSON.stringify(body);
+    const hmacHeaders = buildHmacHeaders(
+      this.wallet.hmacSecret,
+      method,
+      path,
+      this.wallet.subOrgId,
+      bodyStr
+    );
+    const headers = method === "POST" ? { ...hmacHeaders, "content-type": "application/json" } : { ...hmacHeaders };
+    const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      method,
+      headers,
+      body: method === "POST" ? bodyStr : void 0
+    });
+    if (response.status === 202) {
+      const data = await response.json();
+      return { _status: 202, approvalRequestId: data.approvalRequestId };
+    }
+    if (!response.ok) {
+      let code = "UNKNOWN";
+      let message = `HTTP ${response.status}`;
+      try {
+        const data = await response.json();
+        code = data.code ?? defaultCodeForStatus(response.status);
+        message = data.error ?? message;
+      } catch {
+      }
+      throw new KeeperHubError(code, message);
+    }
+    return await response.json();
+  }
+};
+
+// src/balance.ts
+var USDC_DECIMALS = 6;
+async function checkBalance(wallet, opts = {}) {
+  const baseClient = opts.baseClient ?? createPublicClient({
+    chain: base,
+    transport: http()
+  });
+  const tempoClient = opts.tempoClient ?? createPublicClient({
+    chain: tempo,
+    transport: http()
+  });
+  const khClient = opts.khClient ?? new KeeperHubClient(wallet);
+  const [baseRaw, tempoRaw, credit] = await Promise.all([
+    baseClient.readContract({
+      address: BASE_USDC,
+      abi: erc20Abi,
+      functionName: "balanceOf",
+      args: [wallet.walletAddress]
+    }),
+    tempoClient.readContract({
+      address: TEMPO_USDC_E,
+      abi: erc20Abi,
+      functionName: "balanceOf",
+      args: [wallet.walletAddress]
+    }),
+    khClient.request("GET", "/api/agentic-wallet/credit")
+  ]);
+  if ("_status" in credit) {
+    throw new Error("Unexpected 202 response from /api/agentic-wallet/credit");
+  }
+  return {
+    base: {
+      chain: "base",
+      token: "USDC",
+      amount: formatUnits(baseRaw, USDC_DECIMALS),
+      address: wallet.walletAddress
+    },
+    tempo: {
+      chain: "tempo",
+      token: "USDC.e",
+      amount: formatUnits(tempoRaw, USDC_DECIMALS),
+      address: wallet.walletAddress
+    },
+    offChainCredit: {
+      amount: credit.amount,
+      currency: "USD"
+    }
+  };
+}
+
+// src/fund.ts
+var EVM_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+var COINBASE_HOST = "pay.coinbase.com";
+var COINBASE_PATH = "/buy/select-asset";
+function fund(walletAddress) {
+  if (!EVM_ADDRESS_RE.test(walletAddress)) {
+    throw new Error(`Invalid EVM wallet address: ${walletAddress}`);
+  }
+  const params = new URLSearchParams({
+    defaultNetwork: "base",
+    defaultAsset: "USDC",
+    addresses: JSON.stringify({ [walletAddress]: ["base"] }),
+    presetCryptoAmount: "5"
+  });
+  const coinbaseOnrampUrl = `https://${COINBASE_HOST}${COINBASE_PATH}?${params.toString()}`;
+  const disclaimer = "If the Coinbase page does not pre-fill, paste your address manually. For Tempo USDC.e, transfer from an exchange or another wallet to the address above -- Onramp does not support Tempo directly. Coinbase sessionToken URLs are the 2025+ canonical form; legacy query-param URLs may drop prefill on some accounts.";
+  return {
+    coinbaseOnrampUrl,
+    tempoAddress: walletAddress,
+    disclaimer
+  };
+}
+
+// src/skill-install.ts
+import { chmod, copyFile, mkdir, readFile, writeFile } from "fs/promises";
+import { dirname as dirname2, join as join2 } from "path";
+import { fileURLToPath } from "url";
+
+// src/agent-detect.ts
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+var AGENT_SPECS = [
+  {
+    agent: "claude-code",
+    skillsRel: [".claude", "skills"],
+    settingsRel: [".claude", "settings.json"],
+    hookSupport: "claude-code"
+  },
+  {
+    agent: "cursor",
+    skillsRel: [".cursor", "skills"],
+    settingsRel: [".cursor", "settings.json"],
+    hookSupport: "notice"
+  },
+  {
+    agent: "cline",
+    skillsRel: [".cline", "skills"],
+    settingsRel: [".cline", "settings.json"],
+    hookSupport: "notice"
+  },
+  {
+    agent: "windsurf",
+    skillsRel: [".windsurf", "skills"],
+    settingsRel: [".windsurf", "settings.json"],
+    hookSupport: "notice"
+  },
+  {
+    agent: "opencode",
+    skillsRel: [".config", "opencode", "skills"],
+    settingsRel: [".config", "opencode", "settings.json"],
+    hookSupport: "notice"
+  }
+];
+function detectAgents(homeOverride) {
+  const home = homeOverride ?? homedir();
+  const results = [];
+  for (const spec of AGENT_SPECS) {
+    const skillsDir = join(home, ...spec.skillsRel);
+    const settingsFile = join(home, ...spec.settingsRel);
+    if (existsSync(dirname(skillsDir))) {
+      results.push({
+        agent: spec.agent,
+        skillsDir,
+        settingsFile,
+        hookSupport: spec.hookSupport
+      });
+    }
+  }
+  return results;
+}
+
+// src/skill-install.ts
+var HOOK_COMMAND = "keeperhub-wallet-hook";
+var KEEPERHUB_HOOK_MARKER = "keeperhub-wallet-hook";
+function buildKeeperhubEntry() {
+  return {
+    matcher: "*",
+    hooks: [{ type: "command", command: HOOK_COMMAND }]
+  };
+}
+function resolveDefaultSkillSource() {
+  const here = dirname2(fileURLToPath(import.meta.url));
+  return join2(here, "..", "skill", "keeperhub-wallet.skill.md");
+}
+function defaultNotice(msg) {
+  process.stderr.write(`${msg}
+`);
+}
+async function registerClaudeCodeHook(settingsPath) {
+  let raw = null;
+  try {
+    raw = await readFile(settingsPath, "utf-8");
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      throw err;
+    }
+  }
+  let config = {};
+  if (raw !== null) {
+    try {
+      config = JSON.parse(raw);
+    } catch {
+      throw new Error(
+        `settings.json at ${settingsPath} is not valid JSON; aborting hook registration`
+      );
+    }
+  }
+  const hooks = typeof config.hooks === "object" && config.hooks !== null ? config.hooks : {};
+  const existingPreToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
+  const filtered = [];
+  for (const entry of existingPreToolUse) {
+    const serialised = JSON.stringify(entry);
+    if (!serialised.includes(KEEPERHUB_HOOK_MARKER)) {
+      filtered.push(entry);
+    }
+  }
+  filtered.push(buildKeeperhubEntry());
+  hooks.PreToolUse = filtered;
+  config.hooks = hooks;
+  await mkdir(dirname2(settingsPath), { recursive: true, mode: 448 });
+  const payload = `${JSON.stringify(config, null, 2)}
+`;
+  await writeFile(settingsPath, payload, { mode: 384 });
+  await chmod(settingsPath, 384);
+}
+async function writeSkillToAgent(agent, skillSource) {
+  await mkdir(agent.skillsDir, { recursive: true, mode: 493 });
+  const target = join2(agent.skillsDir, "keeperhub-wallet.skill.md");
+  await copyFile(skillSource, target);
+  await chmod(target, 420);
+  return { agent: agent.agent, path: target, status: "written" };
+}
+function buildNoticeMessage(agent) {
+  return `${agent.agent} does not support auto-registered PreToolUse hooks; run \`${HOOK_COMMAND}\` on every tool use via ${agent.agent}'s settings file at ${agent.settingsFile}`;
+}
+async function installSkill(options = {}) {
+  const agents = detectAgents(options.homeOverride);
+  const skillSource = options.skillSourcePath ?? resolveDefaultSkillSource();
+  const onNotice = options.onNotice ?? defaultNotice;
+  const skillWrites = [];
+  const hookRegistrations = [];
+  for (const agent of agents) {
+    const write = await writeSkillToAgent(agent, skillSource);
+    skillWrites.push(write);
+    if (agent.hookSupport === "claude-code") {
+      await registerClaudeCodeHook(agent.settingsFile);
+      hookRegistrations.push({
+        agent: agent.agent,
+        status: "registered"
+      });
+    } else {
+      const message = buildNoticeMessage(agent);
+      hookRegistrations.push({
+        agent: agent.agent,
+        status: "notice",
+        message
+      });
+      onNotice(message);
+    }
+  }
+  return { skillWrites, hookRegistrations };
+}
+
+// src/storage.ts
+import { chmod as chmod2, mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname3, join as join3 } from "path";
+async function readWalletConfig() {
+  const walletPath = join3(homedir2(), ".keeperhub", "wallet.json");
+  let raw;
+  try {
+    raw = await readFile2(walletPath, "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      throw new WalletConfigMissingError();
+    }
+    throw err;
+  }
+  const parsed = JSON.parse(raw);
+  if (!(parsed.subOrgId && parsed.walletAddress && parsed.hmacSecret)) {
+    throw new Error(`Malformed wallet.json at ${walletPath}`);
+  }
+  return parsed;
+}
+async function writeWalletConfig(config) {
+  const walletPath = join3(homedir2(), ".keeperhub", "wallet.json");
+  await mkdir2(dirname3(walletPath), { recursive: true, mode: 448 });
+  await writeFile2(walletPath, JSON.stringify(config, null, 2), { mode: 384 });
+  await chmod2(walletPath, 384);
+}
+function getWalletConfigPath() {
+  return join3(homedir2(), ".keeperhub", "wallet.json");
+}
+
+// src/cli.ts
+var TRAILING_SLASH2 = /\/$/;
+var WALLET_ADDRESS_PATTERN = /^0x[a-fA-F0-9]{40}$/;
+function resolveBaseUrl(override) {
+  const candidate = override ?? process.env.KEEPERHUB_API_URL ?? "https://app.keeperhub.com";
+  return candidate.replace(TRAILING_SLASH2, "");
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function provisionInvalidError(message) {
+  const err = new Error(message);
+  err.code = "PROVISION_RESPONSE_INVALID";
+  return err;
+}
+function validateProvisionResponse(data) {
+  if (typeof data !== "object" || data === null) {
+    throw provisionInvalidError("provision response is not an object");
+  }
+  const { subOrgId, walletAddress, hmacSecret } = data;
+  if (!(isNonEmptyString(subOrgId) && isNonEmptyString(walletAddress) && isNonEmptyString(hmacSecret))) {
+    throw provisionInvalidError(
+      "provision response missing subOrgId, walletAddress, or hmacSecret"
+    );
+  }
+  if (!WALLET_ADDRESS_PATTERN.test(walletAddress)) {
+    throw provisionInvalidError(
+      `provision response walletAddress is not a valid 0x-prefixed 40-hex address: ${walletAddress}`
+    );
+  }
+  return {
+    subOrgId,
+    walletAddress,
+    hmacSecret
+  };
+}
+async function cmdAdd(opts = {}) {
+  const baseUrl = resolveBaseUrl(opts.baseUrl);
+  const response = await fetch(`${baseUrl}/api/agentic-wallet/provision`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: "{}"
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    process.stderr.write(
+      `[keeperhub-wallet] provision failed: HTTP ${response.status}: ${text}
+`
+    );
+    process.exit(1);
+  }
+  const raw = await response.json();
+  const data = validateProvisionResponse(raw);
+  await writeWalletConfig({
+    subOrgId: data.subOrgId,
+    walletAddress: data.walletAddress,
+    hmacSecret: data.hmacSecret
+  });
+  process.stdout.write(`subOrgId: ${data.subOrgId}
+`);
+  process.stdout.write(`walletAddress: ${data.walletAddress}
+`);
+  process.stdout.write(`config written to ${getWalletConfigPath()}
+`);
+}
+async function cmdLink(opts = {}) {
+  const wallet = await readWalletConfig();
+  const baseUrl = resolveBaseUrl(opts.baseUrl);
+  const sessionCookie = process.env.KH_SESSION_COOKIE;
+  if (!sessionCookie) {
+    process.stderr.write(
+      "[keeperhub-wallet] link requires KH_SESSION_COOKIE env var.\nSign in at app.keeperhub.com, copy the session cookie, and re-run with:\n  KH_SESSION_COOKIE='<cookie>' npx @keeperhub/wallet link\n"
+    );
+    process.exit(1);
+  }
+  const body = JSON.stringify({ subOrgId: wallet.subOrgId });
+  const headers = buildHmacHeaders(
+    wallet.hmacSecret,
+    "POST",
+    "/api/agentic-wallet/link",
+    wallet.subOrgId,
+    body
+  );
+  const response = await fetch(`${baseUrl}/api/agentic-wallet/link`, {
+    method: "POST",
+    headers: {
+      ...headers,
+      "content-type": "application/json",
+      cookie: sessionCookie
+    },
+    body
+  });
+  const json = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    process.stderr.write(
+      `[keeperhub-wallet] link failed: ${json.code ?? response.status}: ${json.error ?? ""}
+`
+    );
+    process.exit(1);
+  }
+  if (json.already) {
+    process.stdout.write("already linked\n");
+    return;
+  }
+  process.stdout.write("linked\n");
+}
+async function cmdFund() {
+  const wallet = await readWalletConfig();
+  const out = fund(wallet.walletAddress);
+  process.stdout.write(`${out.coinbaseOnrampUrl}
+`);
+  process.stdout.write(`Tempo address: ${out.tempoAddress}
+`);
+  process.stdout.write(`${out.disclaimer}
+`);
+}
+async function cmdBalance() {
+  const wallet = await readWalletConfig();
+  const snap = await checkBalance(wallet);
+  process.stdout.write(`Base USDC:         ${snap.base.amount}
+`);
+  process.stdout.write(`Tempo USDC.e:      ${snap.tempo.amount}
+`);
+  process.stdout.write(
+    `KeeperHub credit:  ${snap.offChainCredit.amount} ${snap.offChainCredit.currency}
+`
+  );
+}
+async function cmdInfo() {
+  const wallet = await readWalletConfig();
+  process.stdout.write(`subOrgId: ${wallet.subOrgId}
+`);
+  process.stdout.write(`walletAddress: ${wallet.walletAddress}
+`);
+}
+async function runCli(argv = process.argv) {
+  const program = new Command();
+  program.name("keeperhub-wallet").description(
+    "KeeperHub agentic wallet CLI (auto-pay x402 + MPP 402 responses)"
+  ).version("0.1.0");
+  program.command("add").description("Provision a new agentic wallet (no account required)").option("--base-url <url>", "KeeperHub API base URL").action(async (opts) => {
+    await cmdAdd(opts);
+  });
+  program.command("link").description(
+    "Link the current wallet to your KeeperHub account (requires KH_SESSION_COOKIE env)"
+  ).option("--base-url <url>", "KeeperHub API base URL").action(async (opts) => {
+    await cmdLink(opts);
+  });
+  program.command("fund").description(
+    "Print Coinbase Onramp URL (Base USDC) and Tempo deposit address"
+  ).action(async () => {
+    await cmdFund();
+  });
+  program.command("balance").description(
+    "Print unified balance: Base USDC + Tempo USDC.e + off-chain KeeperHub credit"
+  ).action(async () => {
+    await cmdBalance();
+  });
+  program.command("info").description("Print subOrgId and walletAddress from local config").action(async () => {
+    await cmdInfo();
+  });
+  program.command("skill").description(
+    "Install the KeeperHub skill file into detected agent directories"
+  ).addCommand(
+    new Command("install").description(
+      "Write skill file + register PreToolUse hook in all detected agents"
+    ).action(async () => {
+      const result = await installSkill();
+      for (const write of result.skillWrites) {
+        process.stdout.write(
+          `skill: ${write.agent} -> ${write.path} (${write.status})
+`
+        );
+      }
+      for (const reg of result.hookRegistrations) {
+        if (reg.status === "registered") {
+          process.stdout.write(
+            `hook: ${reg.agent} -> PreToolUse registered
+`
+          );
+        } else if (reg.status === "notice") {
+          process.stderr.write(
+            `notice: ${reg.agent} -> ${reg.message ?? ""}
+`
+          );
+        }
+      }
+      if (result.skillWrites.length === 0) {
+        process.stderr.write(
+          "No supported agent skill directories detected under $HOME. Create ~/.claude/, ~/.cursor/, ~/.cline/, ~/.windsurf/, or ~/.config/opencode/ and re-run.\n"
+        );
+      }
+    })
+  );
+  try {
+    await program.parseAsync(argv);
+  } catch (err) {
+    if (err instanceof WalletConfigMissingError) {
+      process.stderr.write(`[keeperhub-wallet] ${err.message}
+`);
+      process.exit(1);
+    }
+    process.stderr.write(
+      `[keeperhub-wallet] ${err.message ?? String(err)}
+`
+    );
+    process.exit(1);
+  }
+}
+export {
+  runCli
+};
+//# sourceMappingURL=cli.js.map