@keeperhub/wallet 0.1.11 → 0.1.13

package/dist/payment-signer-CyeRXcX2.d.ts

@@ -0,0 +1,236 @@
+import { PublicClient } from 'viem';
+
+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>;
+
+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>;
+}
+
+/**
+ * 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 MppChallenge = {
+    serialized: 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>;
+};
+/**
+ * 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;
+
+export { type AskTierResponse as A, type BalanceSnapshot as B, type CheckBalanceOptions as C, DEFAULT_SAFETY_CONFIG as D, type FetchInit as F, type HmacHeaders as H, KeeperHubClient as K, type MppChallenge as M, type PayRetryOptions as P, type SafetyConfig as S, type WalletConfig as W, type X402Challenge as X, type HookDecision as a, type ClientOptions as b, KeeperHubError as c, type PaymentHint as d, type PaymentSigner as e, WalletConfigMissingError as f, checkBalance as g, createPaymentSigner as h, getSafetyConfigPath as i, parseX402Challenge as j, paymentSigner as k, loadSafetyConfig as l, parseMppChallenge as p, selectProtocol as s, validateAndMerge as v };

package/package.json

@@ -1,56 +1,59 @@
 {
-  "name": "@keeperhub/wallet",
-  "version": "0.1.11",
-  "description": "KeeperHub agentic wallet: auto-pay x402 and MPP 402 responses with a server-side Turnkey proxy.",
-  "license": "Apache-2.0",
-  "type": "module",
-  "engines": {
-    "node": ">=20"
-  },
-  "bin": {
-    "keeperhub-wallet": "./bin/keeperhub-wallet.js",
-    "keeperhub-wallet-hook": "./bin/keeperhub-wallet-hook.js"
-  },
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    }
-  },
-  "files": [
-    "dist",
-    "bin",
-    "skill",
-    "README.md",
-    "LICENSE"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/KeeperHub/agentic-wallet.git"
-  },
-  "homepage": "https://docs.keeperhub.com/ai-tools/agentic-wallet",
-  "bugs": {
-    "url": "https://github.com/KeeperHub/agentic-wallet/issues"
-  },
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "type-check": "tsc --noEmit"
-  },
-  "dependencies": {
-    "viem": "2.48.1",
-    "commander": "14.0.3"
-  },
-  "devDependencies": {
-    "tsup": "8.5.1",
-    "typescript": "5.9.2",
-    "@types/node": "24.1.0",
-    "vitest": "4.1.2",
-    "msw": "2.13.4"
-  }
+	"name": "@keeperhub/wallet",
+	"version": "0.1.13",
+	"description": "KeeperHub agentic wallet: auto-pay x402 and MPP 402 responses with a server-side Turnkey proxy.",
+	"license": "Apache-2.0",
+	"type": "module",
+	"engines": {
+		"node": ">=20"
+	},
+	"bin": {
+		"keeperhub-wallet": "./bin/keeperhub-wallet.js",
+		"keeperhub-wallet-hook": "./bin/keeperhub-wallet-hook.js",
+		"keeperhub-wallet-mcp": "./bin/keeperhub-wallet-mcp.js"
+	},
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"files": [
+		"dist",
+		"bin",
+		"skill",
+		"README.md",
+		"LICENSE"
+	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/KeeperHub/agentic-wallet.git"
+	},
+	"homepage": "https://docs.keeperhub.com/ai-tools/agentic-wallet",
+	"bugs": {
+		"url": "https://github.com/KeeperHub/agentic-wallet/issues"
+	},
+	"scripts": {
+		"build": "tsup",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"type-check": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "1.29.0",
+		"commander": "14.0.3",
+		"viem": "2.48.1",
+		"zod": "4.4.2"
+	},
+	"devDependencies": {
+		"@types/node": "24.1.0",
+		"msw": "2.13.4",
+		"tsup": "8.5.1",
+		"typescript": "5.9.2",
+		"vitest": "4.1.2"
+	}
 }

package/skill/keeperhub-wallet.skill.md

@@ -17,7 +17,14 @@ description: |
   binds payment to the workflow slug server-side and supports per-call
   safety thresholds in ~/.keeperhub/safety.json.
 
-  Install with `npx @keeperhub/wallet skill install`.
+  WHEN A KEEPERHUB-WALLET MCP SERVER IS LOADED, PREFER THE MCP TOOLS over
+  shelling out: `mcp__keeperhub-wallet__call_workflow` for paid invocation
+  by slug, `mcp__keeperhub-wallet__balance` and
+  `mcp__keeperhub-wallet__info` for status checks. The first tool call
+  auto-provisions a wallet if `~/.keeperhub/wallet.json` is missing — no
+  manual `add` ceremony required.
+
+  Install with `npx -p @keeperhub/wallet keeperhub-wallet skill install`.
 license: Apache-2.0
 ---
 
@@ -30,7 +37,7 @@ Enables automatic payment of HTTP 402 responses (x402 on Base USDC + MPP on Temp
 **Recommended — one command, fully wired up:**
 
 ```
-npx @keeperhub/wallet skill install
+npx -p @keeperhub/wallet keeperhub-wallet skill install
 ```
 
 This writes the skill file into every detected agent directory under `$HOME` (Claude Code, Cursor, Cline, Windsurf, OpenCode) **and** registers the `keeperhub-wallet-hook` PreToolUse safety hook in `~/.claude/settings.json`. Re-running is safe — the installer is idempotent and preserves any foreign keys already in `settings.json`.
@@ -44,7 +51,7 @@ npx skills add keeperhub/agentic-wallet-skills
 This installs the skill file via the vercel-labs/skills convention but **does not register the PreToolUse safety hook**. Without the hook, signing operations are not gated by your auto/ask/block thresholds. After running `skills add` you MUST also run:
 
 ```
-npx @keeperhub/wallet skill install
+npx -p @keeperhub/wallet keeperhub-wallet skill install
 ```
 
 to activate the safety hook. The combination is safe — `skill install` is idempotent and will not duplicate the skill file written by `skills add`.
@@ -52,17 +59,17 @@ to activate the safety hook. The combination is safe — `skill install` is idem
 After install, provision a wallet with:
 
 ```
-npx @keeperhub/wallet add
+npx -p @keeperhub/wallet keeperhub-wallet add
 ```
 
 ## Commands
 
 Direct npm package invocation:
 
-- `npx @keeperhub/wallet add` — provision a new agentic wallet (no KeeperHub account required).
-- `npx @keeperhub/wallet info` — print `subOrgId` and `walletAddress` for the current wallet.
-- `npx @keeperhub/wallet fund` — print a Coinbase Onramp URL (Base USDC) and a Tempo deposit address.
-- `npx @keeperhub/wallet balance` — print on-chain balance across Base USDC and Tempo USDC.e.
+- `npx -p @keeperhub/wallet keeperhub-wallet add` — provision a new agentic wallet (no KeeperHub account required).
+- `npx -p @keeperhub/wallet keeperhub-wallet info` — print `subOrgId` and `walletAddress` for the current wallet.
+- `npx -p @keeperhub/wallet keeperhub-wallet fund` — print a Coinbase Onramp URL (Base USDC) and a Tempo deposit address.
+- `npx -p @keeperhub/wallet keeperhub-wallet balance` — print on-chain balance across Base USDC and Tempo USDC.e.
 
 Equivalent Go CLI wrappers (thin pass-through; delegate to the npm package):
 
@@ -78,7 +85,7 @@ Three-tier PreToolUse hook enforced on every signing call:
 - **ask** — amount above `auto_approve_max_usd` and at or below `block_threshold_usd` returns `{decision: "ask"}` so Claude Code surfaces an inline prompt in the agent chat.
 - **block** — amount above `block_threshold_usd`, or a contract not in `allowlisted_contracts`, is denied without calling `/sign`.
 
-Thresholds live in `~/.keeperhub/safety.json` (chmod 0o644). The `npx @keeperhub/wallet skill install` path registers the `keeperhub-wallet-hook` PreToolUse entry in `~/.claude/settings.json` automatically. For agents without auto-registration support (Cursor, Cline, Windsurf, OpenCode), the installer prints a copy-paste notice with the hook invocation.
+Thresholds live in `~/.keeperhub/safety.json` (chmod 0o644). The `npx -p @keeperhub/wallet keeperhub-wallet skill install` path registers the `keeperhub-wallet-hook` PreToolUse entry in `~/.claude/settings.json` automatically. For agents without auto-registration support (Cursor, Cline, Windsurf, OpenCode), the installer prints a copy-paste notice with the hook invocation.
 
 The hook reads only the payment-challenge fields `amount`, `unit`, and the asset contract address from the tool payload. Forged fields like `trust-level hint`, `is-safe boolean`, or `admin-override bit` are ignored by design (GUARD-05).