@keeperhub/wallet 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,328 @@
+import * as viem from 'viem';
+import { PublicClient } from 'viem';
+export { runCli } from './cli.js';
+export { runHookCli } from './hook-entrypoint.js';
+export { base } from 'viem/chains';
+
+type AgentTarget = {
+    agent: "claude-code" | "cursor" | "cline" | "windsurf" | "opencode";
+    skillsDir: string;
+    settingsFile: string;
+    hookSupport: "claude-code" | "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);
+}
+declare class WalletConfigMissingError extends Error {
+    constructor();
+}
+
+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 BalanceSnapshot = {
+    base: {
+        chain: "base";
+        token: "USDC";
+        amount: string;
+        address: `0x${string}`;
+    };
+    tempo: {
+        chain: "tempo";
+        token: "USDC.e";
+        amount: string;
+        address: `0x${string}`;
+    };
+    offChainCredit: {
+        amount: string;
+        currency: "USD";
+    };
+};
+type CheckBalanceOptions = {
+    /** Injectable viem client for Base (tests mock readContract). */
+    baseClient?: PublicClient;
+    /** Injectable viem client for Tempo (tests mock readContract). */
+    tempoClient?: PublicClient;
+    /** Injectable KeeperHubClient (tests inject a mocked fetch). */
+    khClient?: KeeperHubClient;
+};
+/**
+ * Read the wallet's balance across Base + Tempo + off-chain KeeperHub credit
+ * in parallel. All three 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: {
+            readonly name: "Tempo Explorer";
+            readonly url: "https://explorer.tempo.xyz";
+        };
+    };
+    blockTime?: number | undefined | undefined;
+    contracts?: {
+        [x: string]: viem.ChainContract | {
+            [sourceId: number]: viem.ChainContract | undefined;
+        } | undefined;
+        ensRegistry?: viem.ChainContract | undefined;
+        ensUniversalResolver?: viem.ChainContract | undefined;
+        multicall3?: viem.ChainContract | undefined;
+        erc6492Verifier?: viem.ChainContract | undefined;
+    } | undefined;
+    ensTlds?: readonly string[] | undefined;
+    id: 4217;
+    name: "Tempo";
+    nativeCurrency: {
+        readonly decimals: 18;
+        readonly name: "Ether";
+        readonly symbol: "ETH";
+    };
+    experimental_preconfirmationTime?: number | undefined | undefined;
+    rpcUrls: {
+        readonly default: {
+            readonly http: readonly [string];
+        };
+    };
+    sourceId?: number | undefined | undefined;
+    testnet?: boolean | undefined | undefined;
+    custom?: Record<string, unknown> | undefined;
+    extendSchema?: Record<string, unknown> | undefined;
+    fees?: viem.ChainFees<undefined> | undefined;
+    formatters?: undefined;
+    prepareTransactionRequest?: ((args: viem.PrepareTransactionRequestParameters, options: {
+        phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+    }) => Promise<viem.PrepareTransactionRequestParameters>) | [fn: ((args: viem.PrepareTransactionRequestParameters, options: {
+        phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+    }) => Promise<viem.PrepareTransactionRequestParameters>) | undefined, options: {
+        runAt: readonly ("beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters")[];
+    }] | undefined;
+    serializers?: viem.ChainSerializers<undefined, viem.TransactionSerializable> | undefined;
+    verifyHash?: ((client: viem.Client, parameters: viem.VerifyHashActionParameters) => Promise<viem.VerifyHashActionReturnType>) | undefined;
+};
+/** Circle-issued USDC on Base mainnet. */
+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 FundInstructions = {
+    /** Coinbase Onramp deeplink (legacy query-param form). */
+    coinbaseOnrampUrl: string;
+    /** Tempo deposit address — same as the input wallet (EVM address shared). */
+    tempoAddress: `0x${string}`;
+    /** Plain-ASCII guidance string; no emojis (CLAUDE.md rule). */
+    disclaimer: string;
+};
+/**
+ * Build Coinbase Onramp URL + Tempo deposit address for the given wallet.
+ *
+ * No HTTP calls are performed. The caller is expected to either print the
+ * resulting URL (CLI) or render it in a chat bubble (skill). The returned
+ * `disclaimer` explains the Onramp deprecation + the Tempo external-transfer
+ * fallback in plain ASCII so terminal clients with ASCII-only fonts render
+ * identically to emoji-capable clients.
+ *
+ * @throws if `walletAddress` does not match /^0x[0-9a-fA-F]{40}$/.
+ */
+declare function fund(walletAddress: string): FundInstructions;
+
+/**
+ * Mirror of lib/agentic-wallet/hmac.ts::computeSignature.
+ * Format (byte-for-byte identical to server):
+ *   `${method}\n${path}\n${subOrgId}\n${sha256_hex(body)}\n${timestamp}`
+ * Post-HI-05: subOrgId is a signed field.
+ *
+ * @security Do NOT log the secret or the returned signature. Any stdout
+ *   emitter (the global console object or util.inspect) added to this
+ *   file is a T-34-08 violation (grep-enforced).
+ */
+declare function computeSignature(secret: string, method: string, path: string, subOrgId: string, body: string, timestamp: string): string;
+/**
+ * Build the three X-KH-* headers that authenticate every request to
+ * /api/agentic-wallet/* (except /provision, which uses the session cookie).
+ *
+ * Timestamp is unix seconds (Math.floor(Date.now() / 1000)); the server
+ * enforces a symmetric 300-second replay window.
+ */
+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;
+    /** Injected for tests */
+    walletLoader?: () => Promise<WalletConfig>;
+    /** Injected for tests */
+    configLoader?: () => Promise<SafetyConfig>;
+    /** Injected for tests */
+    clientFactory?: (w: WalletConfig) => KeeperHubClient;
+    /**
+     * Called when the ask tier opens an approval URL. Default: write to stderr
+     * (stdout is reserved for the Claude Code hook JSON output).
+     */
+    onAskOpen?: (url: string) => void;
+    /** Polling config for the ask tier */
+    poll?: {
+        intervalMs: number;
+        maxAttempts: number;
+    };
+};
+/**
+ * Factory returning the PreToolUse hook function. The hook enforces the three
+ * client-side safety tiers (auto / ask / block) sourced EXCLUSIVELY from
+ * ~/.keeperhub/safety.json -- never from the tool payload (GUARD-05).
+ */
+declare function createPreToolUseHook(options?: CreateHookOptions): Promise<(input: unknown) => Promise<HookDecision>>;
+
+type MppChallenge = {
+    serialized: string;
+};
+declare function parseMppChallenge(response: Response): MppChallenge | 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;
+    };
+};
+type PaymentSigner = {
+    pay: (response: Response) => Promise<Response>;
+};
+declare function createPaymentSigner(opts?: PaySignerOptions): PaymentSigner;
+declare const paymentSigner: PaymentSigner;
+
+type InstallResult = {
+    skillWrites: Array<{
+        agent: string;
+        path: string;
+        status: "written" | "skipped";
+    }>;
+    hookRegistrations: Array<{
+        agent: string;
+        status: "registered" | "notice" | "skipped";
+        message?: string;
+    }>;
+};
+type InstallOptions = {
+    homeOverride?: string;
+    skillSourcePath?: string;
+    onNotice?: (msg: string) => void;
+};
+declare function registerClaudeCodeHook(settingsPath: string): Promise<void>;
+declare function installSkill(options?: InstallOptions): Promise<InstallResult>;
+
+declare function readWalletConfig(): Promise<WalletConfig>;
+declare function writeWalletConfig(config: WalletConfig): Promise<void>;
+declare function getWalletConfigPath(): string;
+
+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>;
+
+export { type AgentTarget, type AskTierResponse, BASE_USDC, type BalanceSnapshot, type CheckBalanceOptions, type ClientOptions, type CreateHookOptions, DEFAULT_SAFETY_CONFIG, type FundInstructions, type HmacHeaders, type HookDecision, type InstallOptions, type InstallResult, KeeperHubClient, KeeperHubError, type MppChallenge, type PaymentSigner, 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, tempo, validateAndMerge, writeWalletConfig };