@hpp-io/x402-mcp-bridge 0.0.1 → 0.0.3

package/dist/index.js

@@ -10,10 +10,13 @@ import { loadConfig } from "./config.js";
 import { setLogLevel, log } from "./log.js";
 import { RawEoaSigner } from "./signers/raw-eoa.js";
 import { AutoTopup } from "./autoTopup.js";
+import { DirectBalance } from "./funds/direct-balance.js";
 import { connectUpstream } from "./client.js";
 import { startBridgeServer } from "./server.js";
+import { DiscoveryClient } from "./discovery.js";
+import { isKeychainURI, resolveKeychain } from "./keychain.js";
 const PKG_NAME = "@hpp-io/x402-mcp-bridge";
-const PKG_VERSION = "0.0.1"; // mirrors package.json — bump together
+const PKG_VERSION = "0.0.3"; // mirrors package.json — bump together
 export async function runBridge(env = process.env) {
     const cfg = loadConfig(env);
     setLogLevel(cfg.LOG_LEVEL);
@@ -21,39 +24,82 @@ export async function runBridge(env = process.env) {
         name: PKG_NAME,
         version: PKG_VERSION,
         chain: cfg.HPP_NETWORK,
+        walletMode: cfg.walletMode,
         safe: cfg.SAFE_ADDRESS,
         resourceServer: cfg.RESOURCE_SERVER_URL,
     });
-    // ---- Signer (PoC: raw EOA from env) ---------------------------------
-    const signer = new RawEoaSigner(cfg.DELEGATE_PRIVATE_KEY);
-    log.info("signer.loaded", { address: signer.address });
-    // ---- AutoTopup --------------------------------------------------------
-    const autoTopup = new AutoTopup(signer, cfg.SAFE_ADDRESS, cfg.ALLOWANCE_MODULE_ADDRESS, cfg.USDCE_ADDRESS, cfg.chainId, cfg.HPP_RPC_URL, {
-        headroomX: BigInt(cfg.TOPUP_HEADROOM_X),
-        fixedAmountAtomic: cfg.TOPUP_AMOUNT_ATOMIC
-            ? BigInt(cfg.TOPUP_AMOUNT_ATOMIC)
-            : undefined,
-    });
-    // ---- Upstream MCP client (with x402 payment wrapper) ----------------
-    const upstream = await connectUpstream({
-        url: cfg.RESOURCE_SERVER_URL,
-        network: cfg.HPP_NETWORK,
-        signer,
-        autoTopup,
-        bridgeName: PKG_NAME,
-        bridgeVersion: PKG_VERSION,
+    // ---- Signer (raw key from env or OS keychain) -----------------------
+    const delegateKey = isKeychainURI(cfg.DELEGATE_PRIVATE_KEY)
+        ? resolveKeychain(cfg.DELEGATE_PRIVATE_KEY)
+        : cfg.DELEGATE_PRIVATE_KEY;
+    const signer = new RawEoaSigner(delegateKey);
+    log.info("signer.loaded", {
+        address: signer.address,
+        source: isKeychainURI(cfg.DELEGATE_PRIVATE_KEY) ? "keychain" : "env",
     });
+    // ---- Funds (wallet mode) --------------------------------------------
+    // Safe mode: autoTopup pulls USDC.e from the Safe within the on-chain daily
+    // cap when the delegate is short. Light mode: the delegate holds USDC.e
+    // directly; DirectBalance only checks the balance and surfaces a funding
+    // instruction when short (no Safe, no on-chain topup, no native gas).
+    const funds = cfg.walletMode === "safe"
+        ? new AutoTopup(signer, cfg.SAFE_ADDRESS, cfg.ALLOWANCE_MODULE_ADDRESS, cfg.USDCE_ADDRESS, cfg.chainId, cfg.HPP_RPC_URL, {
+            headroomX: BigInt(cfg.TOPUP_HEADROOM_X),
+            fixedAmountAtomic: cfg.TOPUP_AMOUNT_ATOMIC
+                ? BigInt(cfg.TOPUP_AMOUNT_ATOMIC)
+                : undefined,
+        })
+        : new DirectBalance(signer.address, cfg.USDCE_ADDRESS, cfg.chainId, cfg.HPP_RPC_URL);
+    // ---- Upstream MCP client (optional) ---------------------------------
+    // When RESOURCE_SERVER_URL is unset, run in local-tools-only mode (credit
+    // top-up / A2A) and skip the upstream connection.
+    let upstream;
+    if (cfg.RESOURCE_SERVER_URL) {
+        upstream = await connectUpstream({
+            url: cfg.RESOURCE_SERVER_URL,
+            network: cfg.HPP_NETWORK,
+            rpcUrl: cfg.HPP_RPC_URL,
+            signer,
+            funds,
+            bridgeName: PKG_NAME,
+            bridgeVersion: PKG_VERSION,
+        });
+    }
+    else {
+        log.info("upstream.skipped", {
+            reason: "RESOURCE_SERVER_URL unset — local tools only (x402_http_call, pay_a2a_agent)",
+        });
+    }
     // ---- stdio MCP server (host-facing) ---------------------------------
+    // HPP_X402_A2A_RPC_TIMEOUT_MS — per-request timeout for pay_a2a_agent's
+    // A2A JSON-RPC calls. Falls back to the in-module default when unset or
+    // not a positive integer.
+    const a2aRpcTimeoutRaw = process.env.HPP_X402_A2A_RPC_TIMEOUT_MS;
+    const a2aRpcTimeoutParsed = a2aRpcTimeoutRaw ? Number(a2aRpcTimeoutRaw) : NaN;
+    const a2aRpcTimeoutMs = Number.isFinite(a2aRpcTimeoutParsed) && a2aRpcTimeoutParsed > 0
+        ? a2aRpcTimeoutParsed
+        : undefined;
+    // Curated service discovery — register hpp_discover / hpp_call when enabled.
+    const discovery = cfg.discoveryEnabled
+        ? new DiscoveryClient(cfg.discoveryUrl)
+        : undefined;
+    if (discovery)
+        log.info("discovery.enabled", { url: cfg.discoveryUrl });
     await startBridgeServer({
         upstream,
         name: PKG_NAME,
         version: PKG_VERSION,
+        signer,
+        network: cfg.HPP_NETWORK,
+        funds,
+        discovery,
+        a2aRpcTimeoutMs,
     });
     // Graceful shutdown: when the host closes our stdin (or Claude Desktop
     // restarts), node exits. Belt-and-suspenders: handle signals too.
     const shutdown = async (sig) => {
         log.info("bridge.shutdown", { signal: sig });
-        await upstream.close();
+        await upstream?.close();
         process.exit(0);
     };
     process.on("SIGINT", () => void shutdown("SIGINT"));

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,UAAU,EAAe,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAIhD,MAAM,QAAQ,GAAG,yBAAyB,CAAC;AAC3C,MAAM,WAAW,GAAG,OAAO,CAAC,CAAC,uCAAuC;AAEpE,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAAyB,OAAO,CAAC,GAAG;IAClE,MAAM,GAAG,GAAW,UAAU,CAAC,GAAG,CAAC,CAAC;IACpC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAC3B,GAAG,CAAC,IAAI,CAAC,cAAc,EAAE;QACvB,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,WAAW;QACpB,KAAK,EAAE,GAAG,CAAC,WAAW;QACtB,IAAI,EAAE,GAAG,CAAC,YAAY;QACtB,cAAc,EAAE,GAAG,CAAC,mBAAmB;KACxC,CAAC,CAAC;IAEH,wEAAwE;IACxE,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,GAAG,CAAC,oBAAqC,CAAC,CAAC;IAC3E,GAAG,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IAEvD,0EAA0E;IAC1E,MAAM,SAAS,GAAG,IAAI,SAAS,CAC7B,MAAM,EACN,GAAG,CAAC,YAA6B,EACjC,GAAG,CAAC,wBAAyC,EAC7C,GAAG,CAAC,aAA8B,EAClC,GAAG,CAAC,OAAO,EACX,GAAG,CAAC,WAAW,EACf;QACE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC;QACvC,iBAAiB,EAAE,GAAG,CAAC,mBAAmB;YACxC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC;YACjC,CAAC,CAAC,SAAS;KACd,CACF,CAAC;IAEF,wEAAwE;IACxE,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC;QACrC,GAAG,EAAE,GAAG,CAAC,mBAAmB;QAC5B,OAAO,EAAE,GAAG,CAAC,WAAsB;QACnC,MAAM;QACN,SAAS;QACT,UAAU,EAAE,QAAQ;QACpB,aAAa,EAAE,WAAW;KAC3B,CAAC,CAAC;IAEH,wEAAwE;IACxE,MAAM,iBAAiB,CAAC;QACtB,QAAQ;QACR,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,WAAW;KACrB,CAAC,CAAC;IAEH,uEAAuE;IACvE,kEAAkE;IAClE,MAAM,QAAQ,GAAG,KAAK,EAAE,GAAW,EAAE,EAAE;QACrC,GAAG,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QAC7C,MAAM,QAAQ,CAAC,KAAK,EAAE,CAAC;QACvB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IACpD,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,4DAA4D;AAC5D,yEAAyE;AACzE,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,UAAU,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACpD,SAAS,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACxB,GAAG,CAAC,KAAK,CAAC,cAAc,EAAE,EAAE,GAAG,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QAC3D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,UAAU,EAAe,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE1D,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAI/D,MAAM,QAAQ,GAAG,yBAAyB,CAAC;AAC3C,MAAM,WAAW,GAAG,OAAO,CAAC,CAAC,uCAAuC;AAEpE,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAAyB,OAAO,CAAC,GAAG;IAClE,MAAM,GAAG,GAAW,UAAU,CAAC,GAAG,CAAC,CAAC;IACpC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAC3B,GAAG,CAAC,IAAI,CAAC,cAAc,EAAE;QACvB,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,WAAW;QACpB,KAAK,EAAE,GAAG,CAAC,WAAW;QACtB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,IAAI,EAAE,GAAG,CAAC,YAAY;QACtB,cAAc,EAAE,GAAG,CAAC,mBAAmB;KACxC,CAAC,CAAC;IAEH,wEAAwE;IACxE,MAAM,WAAW,GAAG,aAAa,CAAC,GAAG,CAAC,oBAAoB,CAAC;QACzD,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,oBAAoB,CAAC;QAC3C,CAAC,CAAE,GAAG,CAAC,oBAAsC,CAAC;IAChD,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,WAAW,CAAC,CAAC;IAC7C,GAAG,CAAC,IAAI,CAAC,eAAe,EAAE;QACxB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK;KACrE,CAAC,CAAC;IAEH,wEAAwE;IACxE,4EAA4E;IAC5E,wEAAwE;IACxE,yEAAyE;IACzE,sEAAsE;IACtE,MAAM,KAAK,GACT,GAAG,CAAC,UAAU,KAAK,MAAM;QACvB,CAAC,CAAC,IAAI,SAAS,CACX,MAAM,EACN,GAAG,CAAC,YAA6B,EACjC,GAAG,CAAC,wBAAyC,EAC7C,GAAG,CAAC,aAA8B,EAClC,GAAG,CAAC,OAAO,EACX,GAAG,CAAC,WAAW,EACf;YACE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC;YACvC,iBAAiB,EAAE,GAAG,CAAC,mBAAmB;gBACxC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC;gBACjC,CAAC,CAAC,SAAS;SACd,CACF;QACH,CAAC,CAAC,IAAI,aAAa,CACf,MAAM,CAAC,OAAO,EACd,GAAG,CAAC,aAA8B,EAClC,GAAG,CAAC,OAAO,EACX,GAAG,CAAC,WAAW,CAChB,CAAC;IAER,wEAAwE;IACxE,0EAA0E;IAC1E,kDAAkD;IAClD,IAAI,QAAiE,CAAC;IACtE,IAAI,GAAG,CAAC,mBAAmB,EAAE,CAAC;QAC5B,QAAQ,GAAG,MAAM,eAAe,CAAC;YAC/B,GAAG,EAAE,GAAG,CAAC,mBAAmB;YAC5B,OAAO,EAAE,GAAG,CAAC,WAAsB;YACnC,MAAM,EAAE,GAAG,CAAC,WAAW;YACvB,MAAM;YACN,KAAK;YACL,UAAU,EAAE,QAAQ;YACpB,aAAa,EAAE,WAAW;SAC3B,CAAC,CAAC;IACL,CAAC;SAAM,CAAC;QACN,GAAG,CAAC,IAAI,CAAC,kBAAkB,EAAE;YAC3B,MAAM,EAAE,8EAA8E;SACvF,CAAC,CAAC;IACL,CAAC;IAED,wEAAwE;IACxE,wEAAwE;IACxE,wEAAwE;IACxE,0BAA0B;IAC1B,MAAM,gBAAgB,GAAG,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC;IACjE,MAAM,mBAAmB,GAAG,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAC9E,MAAM,eAAe,GACnB,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAC,IAAI,mBAAmB,GAAG,CAAC;QAC7D,CAAC,CAAC,mBAAmB;QACrB,CAAC,CAAC,SAAS,CAAC;IAEhB,6EAA6E;IAC7E,MAAM,SAAS,GAAG,GAAG,CAAC,gBAAgB;QACpC,CAAC,CAAC,IAAI,eAAe,CAAC,GAAG,CAAC,YAAY,CAAC;QACvC,CAAC,CAAC,SAAS,CAAC;IACd,IAAI,SAAS;QAAE,GAAG,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC;IAExE,MAAM,iBAAiB,CAAC;QACtB,QAAQ;QACR,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,WAAW;QACpB,MAAM;QACN,OAAO,EAAE,GAAG,CAAC,WAAsB;QACnC,KAAK;QACL,SAAS;QACT,eAAe;KAChB,CAAC,CAAC;IAEH,uEAAuE;IACvE,kEAAkE;IAClE,MAAM,QAAQ,GAAG,KAAK,EAAE,GAAW,EAAE,EAAE;QACrC,GAAG,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QAC7C,MAAM,QAAQ,EAAE,KAAK,EAAE,CAAC;QACxB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IACpD,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,4DAA4D;AAC5D,yEAAyE;AACzE,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,UAAU,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACpD,SAAS,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACxB,GAAG,CAAC,KAAK,CAAC,cAAc,EAAE,EAAE,GAAG,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QAC3D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/keychain.d.ts

@@ -0,0 +1,23 @@
+export type KeychainURI = `keychain://${string}`;
+export declare function isKeychainURI(value: string): value is KeychainURI;
+export declare function isHexKey(value: string): value is `0x${string}`;
+/**
+ * Parse a `keychain://hpp-x402/<account>` URI into its account name.
+ * Throws on a malformed URI so the bridge fails loudly at startup
+ * instead of silently looking up the wrong slot.
+ */
+export declare function parseKeychainURI(uri: string): {
+    service: string;
+    account: string;
+};
+export declare function buildKeychainURI(account: string): KeychainURI;
+/**
+ * Resolve a keychain URI to the stored hex private key. Throws if the
+ * keychain entry is missing or holds a value that doesn't look like a
+ * key (catches "I stored garbage in this slot" mistakes early).
+ */
+export declare function resolveKeychain(uri: string): `0x${string}`;
+export declare function setKeychain(account: string, hexKey: `0x${string}`): void;
+export declare function deleteKeychain(account: string): boolean;
+export declare function getKeychainURIPattern(): string;
+export declare const KEYCHAIN_SERVICE = "hpp-x402";

package/dist/keychain.js

@@ -0,0 +1,111 @@
+/**
+ * OS keychain wrapper around @napi-rs/keyring.
+ *
+ * Lets users store the delegate private key in macOS Keychain / Windows
+ * Credential Vault / Linux libsecret instead of a plaintext .env. The
+ * bridge accepts `DELEGATE_PRIVATE_KEY` as either:
+ *
+ *   - `0x[64 hex]`                       — raw key (dev / quickstart)
+ *   - `keychain://hpp-x402/<account>`    — opaque URI; resolved at startup
+ *
+ * The service component of the URI is fixed to `hpp-x402` for now; the
+ * account is user-chosen (e.g. `delegate-default`, `delegate-mainnet`).
+ * Keeping the service constant means a single namespace appears in the
+ * OS Keychain UI, and the CLI commands stay short.
+ *
+ * Security notes:
+ *   - The plaintext key still exists in process memory after `getPassword`.
+ *     Defense-in-depth means rotating the delegate quickly is cheap (it
+ *     only holds today's allowance, not the Safe balance).
+ *   - We never log the resolved key. Errors surface only the URI.
+ */
+import { Entry } from "@napi-rs/keyring";
+const KEYCHAIN_PREFIX = "keychain://";
+const SERVICE = "hpp-x402";
+const HEX_KEY_RE = /^0x[0-9a-fA-F]{64}$/;
+const ACCOUNT_RE = /^[a-zA-Z0-9._-]+$/;
+export function isKeychainURI(value) {
+    return value.startsWith(KEYCHAIN_PREFIX);
+}
+export function isHexKey(value) {
+    return HEX_KEY_RE.test(value);
+}
+/**
+ * Parse a `keychain://hpp-x402/<account>` URI into its account name.
+ * Throws on a malformed URI so the bridge fails loudly at startup
+ * instead of silently looking up the wrong slot.
+ */
+export function parseKeychainURI(uri) {
+    if (!isKeychainURI(uri)) {
+        throw new Error(`not a keychain URI: ${uri}`);
+    }
+    const rest = uri.slice(KEYCHAIN_PREFIX.length);
+    const slash = rest.indexOf("/");
+    if (slash === -1) {
+        throw new Error(`keychain URI missing account: ${uri} (expected keychain://${SERVICE}/<account>)`);
+    }
+    const service = rest.slice(0, slash);
+    const account = rest.slice(slash + 1);
+    if (service !== SERVICE) {
+        throw new Error(`keychain URI service must be "${SERVICE}", got "${service}"`);
+    }
+    if (!ACCOUNT_RE.test(account)) {
+        throw new Error(`keychain URI account "${account}" must match ${ACCOUNT_RE} (no spaces, slashes, etc.)`);
+    }
+    return { service, account };
+}
+export function buildKeychainURI(account) {
+    if (!ACCOUNT_RE.test(account)) {
+        throw new Error(`invalid account name "${account}" — must match ${ACCOUNT_RE}`);
+    }
+    return `keychain://${SERVICE}/${account}`;
+}
+/**
+ * Resolve a keychain URI to the stored hex private key. Throws if the
+ * keychain entry is missing or holds a value that doesn't look like a
+ * key (catches "I stored garbage in this slot" mistakes early).
+ */
+export function resolveKeychain(uri) {
+    const { service, account } = parseKeychainURI(uri);
+    const entry = new Entry(service, account);
+    let secret;
+    try {
+        secret = entry.getPassword();
+    }
+    catch (err) {
+        throw new Error(`keychain read failed for ${uri}: ${err.message}\n` +
+            `Set it first with: hpp-x402-keychain set ${account}`);
+    }
+    if (!secret) {
+        throw new Error(`keychain entry not found: ${uri}\n` +
+            `Set it first with: hpp-x402-keychain set ${account}`);
+    }
+    if (!isHexKey(secret)) {
+        throw new Error(`keychain entry ${uri} does not contain a 0x + 64-hex private key`);
+    }
+    return secret;
+}
+export function setKeychain(account, hexKey) {
+    if (!isHexKey(hexKey)) {
+        throw new Error("expected 0x + 64 hex chars");
+    }
+    if (!ACCOUNT_RE.test(account)) {
+        throw new Error(`invalid account name "${account}"`);
+    }
+    const entry = new Entry(SERVICE, account);
+    entry.setPassword(hexKey);
+}
+export function deleteKeychain(account) {
+    const entry = new Entry(SERVICE, account);
+    try {
+        return entry.deletePassword();
+    }
+    catch {
+        return false;
+    }
+}
+export function getKeychainURIPattern() {
+    return `keychain://${SERVICE}/<account>`;
+}
+export const KEYCHAIN_SERVICE = SERVICE;
+//# sourceMappingURL=keychain.js.map

package/dist/keychain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keychain.js","sourceRoot":"","sources":["../src/keychain.ts"],"names":[],"mappings":"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"}

package/dist/policy.d.ts

@@ -0,0 +1,73 @@
+export interface HostLimits {
+    /** Reject non-https targets. Defaults true. */
+    requireHttps?: boolean;
+    /** Max atomic units per single call. */
+    maxPerCallAtomic?: string;
+    /** Max atomic units per host per UTC day. (Ledger = follow-up; parsed now.) */
+    maxPerDayAtomic?: string;
+    /**
+     * H2 idempotency: min interval (ms) between *paid* calls to this host.
+     * A paid call within the window returns the previous result instead of
+     * paying again — blunts agent-retry / heartbeat double-fire. 0/undefined
+     * disables. GET/unpaid (non-402) calls are never throttled.
+     */
+    cooldownMs?: number;
+}
+export interface HostPolicy {
+    /** header name -> value-source string */
+    headers?: Record<string, string>;
+    limits?: HostLimits;
+}
+export interface PolicyDefaults {
+    /** Allow calling hosts with no explicit entry. Defaults false (deny). */
+    allowUnlisted?: boolean;
+    limits?: HostLimits;
+}
+export type PolicyFile = {
+    _defaults?: PolicyDefaults;
+} & {
+    [host: string]: HostPolicy | PolicyDefaults | undefined;
+};
+/** Load the policy file. Missing file = empty policy (deny-by-default). */
+export declare function loadPolicy(): PolicyFile;
+/** Absolute path of the active policy file (for tooling/diagnostics). */
+export declare function policyFilePath(): string;
+/** Write the policy file (used by the `hpp-x402-policy` CLI). 0600. */
+export declare function savePolicy(policy: PolicyFile): void;
+/** Resolve a value-source string to its secret/value. Throws if unresolved. */
+export declare function resolveSource(src: string): string;
+/**
+ * Resolve the auth headers to inject for `host`. Throws (no silent
+ * unauthenticated send) if a configured source can't be resolved.
+ */
+export declare function resolveCredentials(policy: PolicyFile, host: string): Record<string, string>;
+export interface AccessDecision {
+    ok: boolean;
+    error?: string;
+    /** Effective limits (defaults merged with host) — used for amount checks. */
+    limits: HostLimits;
+}
+/** ③ pre-flight: host allowlist (deny-by-default) + https. */
+export declare function checkAccess(policy: PolicyFile, url: string): AccessDecision;
+/** ③ per-call amount cap. Returns a deny reason or null. */
+export declare function checkAmount(limits: HostLimits, amountAtomic: bigint): string | null;
+/**
+ * Cooldown gate for a paid call to `host`. If a paid call happened within
+ * `cooldownMs`, returns the previous result text so the caller can return it
+ * verbatim instead of paying again. `now` is injectable for tests.
+ */
+export declare function checkCooldown(host: string, cooldownMs: number | undefined, now?: number): {
+    throttled: boolean;
+    cachedResult?: string;
+    remainingMs?: number;
+};
+/**
+ * Best-effort per-host advisory lock around the paid ceremony. Returns a
+ * release fn, or null when another in-flight payment to this host holds it
+ * (caller must NOT pay — closes the cooldown's check-then-act race for
+ * concurrent calls). Stale locks (crashed process, older than LOCK_TTL_MS)
+ * are reclaimed.
+ */
+export declare function acquireHostLock(host: string): (() => void) | null;
+/** Record a successful paid call to `host` (for the cooldown gate). */
+export declare function recordPaid(host: string, resultText: string, now?: number): void;

package/dist/policy.js

@@ -0,0 +1,249 @@
+/**
+ * Host policy — generic credential injection + spend guardrails for the
+ * HTTP x402 tool (`x402_http_call`).
+ *
+ * The proxy tool is generic (`{url, method, body}`); each x402 service has
+ * its own auth header and spend limits. We keep that service-specific part
+ * as *data* (this policy file), not code, so adding a service is one entry
+ * and no service name is ever hardcoded.
+ *
+ * File: `$HPP_X402_CRED_FILE` or `${HPP_X402_HOME|~/.hpp-x402}/policy.json`.
+ * Shape (host-keyed):
+ *
+ *   {
+ *     "_defaults": { "allowUnlisted": false,
+ *                    "limits": { "requireHttps": true, "maxPerCallAtomic": "1000000" } },
+ *     "hub-stage.hpp.io": {
+ *       "headers": { "X-Api-Key": "file:~/.hpphub/config.json#api_key" },
+ *       "limits":  { "requireHttps": true, "maxPerCallAtomic": "5000000" }
+ *     }
+ *   }
+ *
+ * Security: secrets are referenced by *value-source* (file:/env:/keychain://),
+ * resolved locally at call time, never passed through tool args (LLM-visible)
+ * and never logged.
+ */
+import { Entry } from "@napi-rs/keyring";
+import { readFileSync, writeFileSync, mkdirSync, openSync, closeSync, unlinkSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve as pathResolve, dirname } from "node:path";
+function expandHome(p) {
+    if (!p.startsWith("~"))
+        return p;
+    return pathResolve(homedir(), p.slice(1).replace(/^[/\\]+/, ""));
+}
+function policyPath() {
+    if (process.env.HPP_X402_CRED_FILE)
+        return expandHome(process.env.HPP_X402_CRED_FILE);
+    const home = process.env.HPP_X402_HOME ?? pathResolve(homedir(), ".hpp-x402");
+    return pathResolve(home, "policy.json");
+}
+/** Load the policy file. Missing file = empty policy (deny-by-default). */
+export function loadPolicy() {
+    const path = policyPath();
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return {};
+        throw new Error(`x402 policy file unreadable (${path}): ${err.message}`);
+    }
+}
+function getHostPolicy(policy, host) {
+    if (host === "_defaults")
+        return undefined;
+    return policy[host]; // exact match only — no wildcard (C1)
+}
+/** Absolute path of the active policy file (for tooling/diagnostics). */
+export function policyFilePath() {
+    return policyPath();
+}
+/** Write the policy file (used by the `hpp-x402-policy` CLI). 0600. */
+export function savePolicy(policy) {
+    const path = policyPath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(policy, null, 2) + "\n", { mode: 0o600 });
+}
+/** Resolve a value-source string to its secret/value. Throws if unresolved. */
+export function resolveSource(src) {
+    if (src.startsWith("literal:"))
+        return src.slice("literal:".length);
+    if (src.startsWith("env:")) {
+        const v = process.env[src.slice("env:".length)];
+        if (!v)
+            throw new Error(`env var not set`);
+        return v;
+    }
+    if (src.startsWith("keychain://")) {
+        const rest = src.slice("keychain://".length);
+        const slash = rest.indexOf("/");
+        if (slash === -1)
+            throw new Error(`malformed keychain source (need keychain://svc/acct)`);
+        const secret = new Entry(rest.slice(0, slash), rest.slice(slash + 1)).getPassword();
+        if (!secret)
+            throw new Error(`keychain entry not found`);
+        return secret;
+    }
+    if (src.startsWith("file:")) {
+        const body = src.slice("file:".length);
+        const hash = body.indexOf("#");
+        if (hash === -1)
+            throw new Error(`file source needs #<field> (e.g. file:~/x.json#api_key)`);
+        const json = JSON.parse(readFileSync(expandHome(body.slice(0, hash)), "utf8"));
+        let v = json;
+        for (const k of body.slice(hash + 1).split(".")) {
+            if (v == null || typeof v !== "object") {
+                v = undefined;
+                break;
+            }
+            v = v[k];
+        }
+        if (typeof v !== "string" || v === "")
+            throw new Error(`file source field empty/not-a-string`);
+        return v;
+    }
+    throw new Error(`unknown value-source scheme`);
+}
+/** Mask a source for error text (literal: hides its value; others are safe). */
+function maskSource(src) {
+    return src.startsWith("literal:") ? "literal:***" : src;
+}
+/**
+ * Resolve the auth headers to inject for `host`. Throws (no silent
+ * unauthenticated send) if a configured source can't be resolved.
+ */
+export function resolveCredentials(policy, host) {
+    const hp = getHostPolicy(policy, host);
+    const out = {};
+    if (!hp?.headers)
+        return out;
+    for (const [name, source] of Object.entries(hp.headers)) {
+        try {
+            out[name] = resolveSource(source);
+        }
+        catch (err) {
+            throw new Error(`credential for ${host} header "${name}" unresolved (${maskSource(source)}): ${err.message}`);
+        }
+    }
+    return out;
+}
+/** ③ pre-flight: host allowlist (deny-by-default) + https. */
+export function checkAccess(policy, url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return { ok: false, error: `invalid url`, limits: {} };
+    }
+    const host = u.host.toLowerCase();
+    const hp = getHostPolicy(policy, host);
+    const limits = { ...(policy._defaults?.limits ?? {}), ...(hp?.limits ?? {}) };
+    if (!hp && policy._defaults?.allowUnlisted !== true) {
+        return { ok: false, error: `host not allowlisted: ${host}`, limits };
+    }
+    const requireHttps = limits.requireHttps ?? true;
+    if (requireHttps && u.protocol !== "https:") {
+        return { ok: false, error: `https required for ${host}`, limits };
+    }
+    return { ok: true, limits };
+}
+/** ③ per-call amount cap. Returns a deny reason or null. */
+export function checkAmount(limits, amountAtomic) {
+    if (limits.maxPerCallAtomic != null) {
+        const cap = BigInt(limits.maxPerCallAtomic);
+        if (amountAtomic > cap) {
+            return `amount ${amountAtomic} exceeds per-call cap ${cap}`;
+        }
+    }
+    // maxPerDayAtomic: enforced once the daily ledger lands (follow-up).
+    return null;
+}
+function spendStatePath() {
+    const home = process.env.HPP_X402_HOME ?? pathResolve(homedir(), ".hpp-x402");
+    return pathResolve(home, "topup-state.json");
+}
+function loadSpendState() {
+    try {
+        return JSON.parse(readFileSync(spendStatePath(), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Cooldown gate for a paid call to `host`. If a paid call happened within
+ * `cooldownMs`, returns the previous result text so the caller can return it
+ * verbatim instead of paying again. `now` is injectable for tests.
+ */
+export function checkCooldown(host, cooldownMs, now = Date.now()) {
+    if (!cooldownMs || cooldownMs <= 0)
+        return { throttled: false };
+    const entry = loadSpendState()[host];
+    if (!entry)
+        return { throttled: false };
+    const elapsed = now - entry.lastPaidAt;
+    if (elapsed < cooldownMs) {
+        return { throttled: true, cachedResult: entry.lastResult, remainingMs: cooldownMs - elapsed };
+    }
+    return { throttled: false };
+}
+const LOCK_TTL_MS = 120_000;
+function lockPath(host) {
+    const home = process.env.HPP_X402_HOME ?? pathResolve(homedir(), ".hpp-x402");
+    return pathResolve(home, "locks", `${host.replace(/[^a-zA-Z0-9._-]/g, "_")}.lock`);
+}
+/**
+ * Best-effort per-host advisory lock around the paid ceremony. Returns a
+ * release fn, or null when another in-flight payment to this host holds it
+ * (caller must NOT pay — closes the cooldown's check-then-act race for
+ * concurrent calls). Stale locks (crashed process, older than LOCK_TTL_MS)
+ * are reclaimed.
+ */
+export function acquireHostLock(host) {
+    const p = lockPath(host);
+    try {
+        mkdirSync(dirname(p), { recursive: true });
+    }
+    catch {
+        /* noop */
+    }
+    try {
+        if (Date.now() - statSync(p).mtimeMs > LOCK_TTL_MS)
+            unlinkSync(p);
+    }
+    catch {
+        /* no existing lock */
+    }
+    let fd;
+    try {
+        fd = openSync(p, "wx"); // O_CREAT|O_EXCL|O_WRONLY — fails if it exists
+    }
+    catch {
+        return null; // held by another in-flight payment
+    }
+    closeSync(fd);
+    return () => {
+        try {
+            unlinkSync(p);
+        }
+        catch {
+            /* noop */
+        }
+    };
+}
+/** Record a successful paid call to `host` (for the cooldown gate). */
+export function recordPaid(host, resultText, now = Date.now()) {
+    try {
+        const state = loadSpendState();
+        state[host] = { lastPaidAt: now, lastResult: resultText };
+        const home = process.env.HPP_X402_HOME ?? pathResolve(homedir(), ".hpp-x402");
+        mkdirSync(home, { recursive: true });
+        writeFileSync(spendStatePath(), JSON.stringify(state, null, 2), { mode: 0o600 });
+    }
+    catch {
+        // best-effort — cooldown is a safety net, never block a paid call on it
+    }
+}
+//# sourceMappingURL=policy.js.map

package/dist/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -1,7 +1,24 @@
 import type { UpstreamClient } from "./client.js";
+import type { DiscoveryClient } from "./discovery.js";
+import type { RawEoaSigner } from "./signers/raw-eoa.js";
+import type { Funds } from "./funds.js";
+import type { Network } from "@x402/core/types";
 export interface BridgeServerOptions {
-    upstream: UpstreamClient;
+    /** Upstream resource server. Undefined = local-tools-only mode. */
+    upstream?: UpstreamClient;
     name: string;
     version: string;
+    /** Delegate signer + network — used by the local `pay_a2a_agent` tool. */
+    signer: RawEoaSigner;
+    network: Network;
+    funds?: Funds;
+    /** Curated-discovery client. Present = register hpp_discover / hpp_call. */
+    discovery?: DiscoveryClient;
+    /**
+     * Per-request timeout for the A2A JSON-RPC calls in `pay_a2a_agent`.
+     * Surfaced via env `HPP_X402_A2A_RPC_TIMEOUT_MS` (set at CLI entry);
+     * defaults to {@link DEFAULT_A2A_RPC_TIMEOUT_MS} (60s) when omitted.
+     */
+    a2aRpcTimeoutMs?: number;
 }
 export declare function startBridgeServer(opts: BridgeServerOptions): Promise<void>;