@keeperhub/wallet 0.1.10 → 0.1.12

package/dist/index.d.cts

@@ -1,5 +1,6 @@
+import { H as HmacHeaders, S as SafetyConfig, a as HookDecision, W as WalletConfig } from './payment-signer-CyeRXcX2.cjs';
+export { A as AskTierResponse, B as BalanceSnapshot, C as CheckBalanceOptions, b as ClientOptions, D as DEFAULT_SAFETY_CONFIG, F as FetchInit, K as KeeperHubClient, c as KeeperHubError, M as MppChallenge, P as PayRetryOptions, d as PaymentHint, e as PaymentSigner, f as WalletConfigMissingError, X as X402Challenge, g as checkBalance, h as createPaymentSigner, i as getSafetyConfigPath, l as loadSafetyConfig, p as parseMppChallenge, j as parseX402Challenge, k as paymentSigner, s as selectProtocol, v as validateAndMerge } from './payment-signer-CyeRXcX2.cjs';
 import * as viem from 'viem';
-import { PublicClient } from 'viem';
 export { runCli } from './cli.cjs';
 export { runHookCli } from './hook-entrypoint.cjs';
 export { base } from 'viem/chains';
@@ -9,66 +10,24 @@ type AgentTarget = {
     skillsDir: string;
     settingsFile: string;
     hookSupport: "claude-code" | "notice";
+    /**
+     * Path-segments under $HOME where the agent stores its MCP server registry.
+     * `undefined` for agents without a known MCP config location (cline today
+     * stores per-VS-Code-variant globalStorage state that is too fragile to
+     * auto-detect, so we ship "notice" instead).
+     */
+    mcpConfigRel?: string[];
+    /**
+     * Which MCP config shape to write. `claude-code`, `cursor`, and `windsurf`
+     * all use the standard `{ mcpServers: { name: { command, args, env } } }`
+     * shape. `opencode` uses a divergent `{ mcp: { name: { type:"local",
+     * command:[...], enabled, environment } } }` shape. `notice` agents get
+     * a copy-paste hint instead of an auto-registered entry.
+     */
+    mcpSupport: "claude-code" | "cursor" | "windsurf" | "opencode" | "notice";
 };
 declare function detectAgents(homeOverride?: string): AgentTarget[];
 
-type WalletConfig = {
-    /** Turnkey sub-org ID returned by POST /api/agentic-wallet/provision */
-    subOrgId: string;
-    /** EVM-shared wallet address (same for Base chainId 8453 and Tempo chainId 4217) */
-    walletAddress: `0x${string}`;
-    /** 64-char lowercase hex HMAC secret, minted server-side at provision; never logged */
-    hmacSecret: string;
-};
-type HmacHeaders = {
-    "X-KH-Sub-Org": string;
-    "X-KH-Timestamp": string;
-    "X-KH-Signature": string;
-};
-type HookDecision = {
-    decision: "allow" | "deny" | "ask";
-    reason?: string;
-};
-declare class KeeperHubError extends Error {
-    readonly code: string;
-    constructor(code: string, message: string);
-}
-/** Protocol preference for a single pay() or fetch() call. "auto" preserves
- *  the x402-first default when both challenges are offered. */
-type PaymentHint = "x402" | "mpp" | "auto";
-declare class WalletConfigMissingError extends Error {
-    constructor();
-}
-
-type BalanceSnapshot = {
-    base: {
-        chain: "base";
-        token: "USDC";
-        amount: string;
-        address: `0x${string}`;
-    };
-    tempo: {
-        chain: "tempo";
-        token: "USDC.e";
-        amount: string;
-        address: `0x${string}`;
-    };
-};
-type CheckBalanceOptions = {
-    /** Injectable viem client for Base (tests mock readContract). */
-    baseClient?: PublicClient;
-    /** Injectable viem client for Tempo (tests mock readContract). */
-    tempoClient?: PublicClient;
-};
-/**
- * Read the wallet's on-chain balance across Base + Tempo in parallel. Both
- * legs must resolve; any single failure rejects the Promise.
- *
- * Amounts are formatted as decimal strings (6-decimal USDC precision) so the
- * caller can render them without BigInt math.
- */
-declare function checkBalance(wallet: WalletConfig, opts?: CheckBalanceOptions): Promise<BalanceSnapshot>;
-
 declare const tempo: {
     blockExplorers: {
         readonly default: {
@@ -121,49 +80,6 @@ declare const BASE_USDC: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
 /** Bridged USDC (USDC.e) on Tempo mainnet. NOT the same contract as BASE_USDC. */
 declare const TEMPO_USDC_E: "0x20c000000000000000000000b9537d11c60e8b50";
 
-type ClientOptions = {
-    /** Defaults to process.env.KEEPERHUB_API_URL ?? "https://app.keeperhub.com" */
-    baseUrl?: string;
-    /** Injected for tests; defaults to global fetch */
-    fetch?: typeof fetch;
-};
-/**
- * 202 ask-tier envelope returned by /sign and /approval-request when the
- * risk classifier routes a request to the ask queue. Callers poll
- * `/api/agentic-wallet/approval-request/:id` until status !== "pending".
- */
-type AskTierResponse = {
-    _status: 202;
-    approvalRequestId: string;
-};
-/**
- * HMAC-signed HTTP client for the KeeperHub agentic-wallet API surface.
- * Every request to /api/agentic-wallet/* (except /provision, which uses
- * the session cookie) flows through this class.
- *
- * @security No logging of headers, body, or response bodies. Any stdout
- *   emitter (the global console object or util.inspect) added to this
- *   file is a T-34-08 violation (grep-enforced in CI).
- */
-declare class KeeperHubClient {
-    private readonly baseUrl;
-    private readonly fetchImpl;
-    private readonly wallet;
-    constructor(wallet: WalletConfig, opts?: ClientOptions);
-    /**
-     * 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.
-     */
-    request<T>(method: "GET" | "POST", path: string, body?: unknown): Promise<T | AskTierResponse>;
-}
-
 type FundInstructions = {
     /** Coinbase Onramp deeplink (legacy query-param form). */
     coinbaseOnrampUrl: string;
@@ -205,28 +121,6 @@ declare function computeSignature(secret: string, method: string, path: string,
  */
 declare function buildHmacHeaders(secret: string, method: string, path: string, subOrgId: string, body: string): HmacHeaders;
 
-/**
- * User-owned safety config at ~/.keeperhub/safety.json. File mode 0o644 so the
- * user can freely edit thresholds and the allowlist; server-side Turnkey policy
- * remains the authoritative hard cap (GUARD-06).
- */
-type SafetyConfig = {
-    auto_approve_max_usd: number;
-    ask_threshold_usd: number;
-    block_threshold_usd: number;
-    allowlisted_contracts: string[];
-};
-/**
- * Defaults per 34-CONTEXT lines 61-68. Thresholds bracket the Turnkey policy
- * hard cap (100 USDC). Allowlisted contracts mirror the server Turnkey policy
- * allowlist (lib/agentic-wallet/policy.ts FACILITATOR_ALLOWLIST) -- lowercased
- * for case-insensitive match against tool_input.to / paymentChallenge.payTo.
- */
-declare const DEFAULT_SAFETY_CONFIG: SafetyConfig;
-declare function loadSafetyConfig(): Promise<SafetyConfig>;
-declare function validateAndMerge(partial: Partial<SafetyConfig>): SafetyConfig;
-declare function getSafetyConfigPath(): string;
-
 type CreateHookOptions = {
     /** Match against tool_name. Default: /keeperhub|wallet|sign/i */
     toolNameMatcher?: (name: string) => boolean;
@@ -257,126 +151,31 @@ type CreateHookOptions = {
  */
 declare function createPreToolUseHook(options?: CreateHookOptions): Promise<(input: unknown) => Promise<HookDecision>>;
 
-type MppChallenge = {
-    serialized: string;
+type McpCommand = {
+    command: string;
+    args: string[];
+    /** Optional environment overrides. Currently unused but reserved for future flags. */
+    env?: Record<string, string>;
 };
-declare function parseMppChallenge(response: Response): MppChallenge | null;
-
-type X402Challenge = {
-    x402Version: 2;
-    accepts: Array<{
-        scheme: "exact";
-        network: string;
-        asset: string;
-        amount: string;
-        payTo: string;
-        maxTimeoutSeconds: number;
-        extra: Record<string, unknown>;
-    }>;
-    resource: {
-        url: string;
-        description: string;
-        mimeType: string;
-    };
-};
-declare function parseX402Challenge(response: Response): Promise<X402Challenge | null>;
-
-type PaySignerOptions = {
-    /** Override wallet loader (primarily for tests). */
-    walletLoader?: () => Promise<WalletConfig>;
-    /** Override KeeperHubClient factory (tests inject a mocked fetch). */
-    clientFactory?: (wallet: WalletConfig) => KeeperHubClient;
-    /** Replayed fetch (tests intercept the retry). */
-    fetchImpl?: typeof fetch;
-    /** Approval polling override: interval + max attempts. */
-    approval?: {
-        intervalMs: number;
-        maxAttempts: number;
-    };
-};
-/**
- * Retry options threaded through `pay()` and `fetch()` into the post-sign
- * retry. Lets callers forward the original request body and headers so the
- * paid workflow receives the same payload on the retry as on the 402 attempt
- * -- otherwise a workflow whose input schema requires a body (e.g.
- * `{address}` on `/api/mcp/workflows/<slug>/call`) rejects the retry with
- * 400 "Invalid JSON body".
- */
-type PayRetryOptions = {
-    /**
-     * Body to re-send on the retry. Must be a type that can be sent twice --
-     * string, ArrayBuffer, Uint8Array, FormData, URLSearchParams, or Blob.
-     * ReadableStream bodies are NOT supported because the first fetch() already
-     * consumed the stream; pass a string/Buffer instead.
-     */
-    body?: RequestInit["body"];
-    /**
-     * Additional request headers to merge onto the retry (e.g. Content-Type).
-     * The payment auth header (PAYMENT-SIGNATURE or Authorization) is set by
-     * the signer and overrides any same-named header in this map.
-     */
-    headers?: RequestInit["headers"];
-    /** HTTP method for the retry. Defaults to "POST". */
-    method?: string;
-    /**
-     * Per-call protocol preference. "x402" forces Base USDC; "mpp" forces Tempo
-     * USDC.e; "auto" (default, also the behaviour when omitted) uses x402 when
-     * offered, MPP otherwise. Throws KeeperHubError("X402_NOT_OFFERED") or
-     * KeeperHubError("MPP_NOT_OFFERED") when the requested protocol is absent
-     * from the challenge (KEEP-361).
-     */
-    paymentHint?: PaymentHint;
-};
-/** RequestInit extended with paymentHint for per-call protocol selection. */
-type FetchInit = RequestInit & {
-    paymentHint?: PaymentHint;
-};
-type PaymentSigner = {
-    /**
-     * Pays a 402 response and returns the post-payment retry Response.
-     * Non-402 responses are returned unchanged.
-     *
-     * Pass `options.body` (and usually `options.headers`) if the paid
-     * workflow's input schema requires a body -- `pay()` does not have access
-     * to the original request otherwise.
-     *
-     * For most agent code, prefer `signer.fetch(url, init)` which threads the
-     * body/headers automatically.
-     */
-    pay: (response: Response, options?: PayRetryOptions) => Promise<Response>;
-    /**
-     * `fetch(url, init)` wrapper: does the initial fetch, and on 402 calls
-     * `pay()` with `init.body` + `init.headers` so the retry carries the
-     * original payload. Returns whatever the retry (or first response, if not
-     * 402) returns. No-op for non-402 responses.
-     *
-     * Pass `init.paymentHint` to force a specific payment protocol for this
-     * call. Omitting it is equivalent to `paymentHint: "auto"` (x402-first).
-     */
-    fetch: (input: string | URL, init?: FetchInit) => Promise<Response>;
+type RegisterMcpServerOptions = {
+    /** Override $HOME (tests). */
+    homeOverride?: string;
+    /** Override the launch command (tests, monorepo setups). */
+    command?: McpCommand;
 };
-/**
- * Pure function that decides which payment protocol to use given challenge
- * availability and caller's hint. Exported for unit testing.
- *
- * Returns "x402" or "mpp" to direct the caller to the appropriate path,
- * or null when hint is "auto" and no challenge is present (pay() then
- * returns the original 402 response unchanged). Throws KeeperHubError with
- * a specific code when the requested protocol is unavailable (KEEP-361).
- */
-declare function selectProtocol(x402: X402Challenge | null, mpp: MppChallenge | null, hint: PaymentHint | undefined): "x402" | "mpp" | null;
-declare function createPaymentSigner(opts?: PaySignerOptions): PaymentSigner;
-declare const paymentSigner: PaymentSigner;
 
 /**
  * Pick the hook command to write into settings.json.
  *
- * Returns the bare bin name if it resolves on PATH (global install or a
- * dev-time `npm link`), otherwise a version-pinned `npx` invocation that
- * pulls the installer's own version of `@keeperhub/wallet` on demand.
- * Override-able via the env var `KEEPERHUB_WALLET_HOOK_COMMAND` for
- * test fixtures and unusual deployments (env input is trusted — it is
- * written verbatim into settings.json and executed by the user's shell).
+ * Returns the bare bin name if it resolves to a STABLE install on PATH
+ * (global install, brew, distro pkg, dev-time `npm link`), otherwise a
+ * version-pinned `npx` invocation that pulls the installer's own version
+ * of `@keeperhub/wallet` on demand. Implementation lives in
+ * runtime-detect.ts so the hook + MCP installers share a single decision.
+ *
+ * Override-able via the env var `KEEPERHUB_WALLET_HOOK_COMMAND` for test
+ * fixtures and unusual deployments (env input is trusted — it is written
+ * verbatim into settings.json and executed by the user's shell).
  */
 declare function resolveHookCommand(): string;
 type InstallResult = {
@@ -387,7 +186,13 @@ type InstallResult = {
     }>;
     hookRegistrations: Array<{
         agent: string;
-        status: "registered" | "notice" | "skipped";
+        status: "registered" | "notice" | "skipped" | "failed";
+        message?: string;
+    }>;
+    mcpRegistrations: Array<{
+        agent: string;
+        status: "registered" | "notice" | "skipped" | "failed";
+        path?: string;
         message?: string;
     }>;
 };
@@ -401,6 +206,12 @@ type InstallOptions = {
      * Override for tests, monorepo setups, or unusual deployments.
      */
     hookCommand?: string;
+    /**
+     * MCP command + args to register with each detected agent. Defaults to
+     * {@link resolveMcpCommand}. Tests pass an explicit value to pin
+     * assertions regardless of host PATH.
+     */
+    mcpCommand?: RegisterMcpServerOptions["command"];
 };
 type RegisterClaudeCodeHookOptions = {
     /**
@@ -411,10 +222,38 @@ type RegisterClaudeCodeHookOptions = {
     hookCommand?: string;
 };
 declare function registerClaudeCodeHook(settingsPath: string, options?: RegisterClaudeCodeHookOptions): Promise<void>;
+/**
+ * Install the keeperhub-wallet skill plus the PreToolUse safety hook plus
+ * the keeperhub-wallet MCP server into every detected agent.
+ *
+ * Per-agent flow:
+ *  1. Copy `keeperhub-wallet.skill.md` into the agent's `skills/` dir.
+ *  2. If the agent supports PreToolUse hooks (claude-code), register the
+ *     safety hook in `settings.json`. Otherwise print a stderr notice.
+ *  3. If the agent supports MCP server registration (claude-code, cursor,
+ *     windsurf, opencode), register the keeperhub-wallet MCP server in the
+ *     agent's MCP config file (claude.json / mcp.json / opencode.json).
+ *     Otherwise print a stderr notice.
+ *
+ * MCP idempotency is automatic: each agent's MCP config keys servers by name,
+ * so a re-run overwrites the existing `keeperhub-wallet` entry rather than
+ * appending a duplicate. All other keys are byte-preserved.
+ */
 declare function installSkill(options?: InstallOptions): Promise<InstallResult>;
 
 declare function readWalletConfig(): Promise<WalletConfig>;
+/**
+ * Atomic write: serialise to a sibling tmp file, fsync via the close, then
+ * rename(2) into place. Concurrent provisioning races (two MCP sessions
+ * spawning at once on a fresh install) collapse to last-rename-wins on the
+ * final path rather than torn-write-wins. Combined with the in-process
+ * promise cache in mcp-server.ts:ensureWallet this gates duplicate-mint
+ * within a single process AND keeps disk consistent across multiple.
+ *
+ * The tmp filename includes 16 bytes of randomness so two writers don't
+ * stomp each other's tmp files mid-write either.
+ */
 declare function writeWalletConfig(config: WalletConfig): Promise<void>;
 declare function getWalletConfigPath(): string;
 
-export { type AgentTarget, type AskTierResponse, BASE_USDC, type BalanceSnapshot, type CheckBalanceOptions, type ClientOptions, type CreateHookOptions, DEFAULT_SAFETY_CONFIG, type FetchInit, type FundInstructions, type HmacHeaders, type HookDecision, type InstallOptions, type InstallResult, KeeperHubClient, KeeperHubError, type MppChallenge, type PayRetryOptions, type PaymentHint, type PaymentSigner, type RegisterClaudeCodeHookOptions, type SafetyConfig, TEMPO_USDC_E, type WalletConfig, WalletConfigMissingError, type X402Challenge, buildHmacHeaders, checkBalance, computeSignature, createPaymentSigner, createPreToolUseHook, detectAgents, fund, getSafetyConfigPath, getWalletConfigPath, installSkill, loadSafetyConfig, parseMppChallenge, parseX402Challenge, paymentSigner, readWalletConfig, registerClaudeCodeHook, resolveHookCommand, selectProtocol, tempo, validateAndMerge, writeWalletConfig };
+export { type AgentTarget, BASE_USDC, type CreateHookOptions, type FundInstructions, HmacHeaders, HookDecision, type InstallOptions, type InstallResult, type RegisterClaudeCodeHookOptions, SafetyConfig, TEMPO_USDC_E, WalletConfig, buildHmacHeaders, computeSignature, createPreToolUseHook, detectAgents, fund, getWalletConfigPath, installSkill, readWalletConfig, registerClaudeCodeHook, resolveHookCommand, tempo, writeWalletConfig };