@hpp-io/x402-mcp-bridge 0.0.1

package/LICENSE

@@ -0,0 +1,19 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   See https://www.apache.org/licenses/LICENSE-2.0 for the full text.
+
+   Copyright 2026 HPP / Noosphere contributors.

package/README.md

@@ -0,0 +1,129 @@
+# @hpp-io/x402-mcp-bridge
+
+> stdio MCP bridge that lets Claude Desktop / OpenClaw / other MCP hosts make
+> autonomous **HPP USDC.e** payments via x402 — funds stay in a Safe, the
+> bridge auto-tops up a delegate EOA within an on-chain spend cap
+> (AllowanceModule).
+
+## What it is
+
+The MCP host (Claude Desktop, OpenClaw, Cursor, …) doesn't know how to sign
+EIP-3009 payments. This bridge runs as a stdio subprocess that the host
+spawns, exposes itself as an MCP server to the host, and internally:
+
+1. Connects upstream to a remote x402 MCP server (SSE / StreamableHTTP).
+2. Forwards `listTools` / `callTool` between host and remote.
+3. When the remote returns 402, the bridge:
+   - Tops up the delegate EOA from the user's Safe via
+     `AllowanceModule.executeAllowanceTransfer` (chain-enforced daily cap).
+   - Signs EIP-3009 `transferWithAuthorization` with the delegate key.
+   - Retries the call.
+
+The host sees a normal MCP server and never deals with payment.
+
+## Install / use
+
+```jsonc
+// claude_desktop_config.json
+{
+  "mcpServers": {
+    "hpp-x402": {
+      "command": "npx",
+      "args": ["-y", "@hpp-io/x402-mcp-bridge"],
+      "env": {
+        "DELEGATE_PRIVATE_KEY": "0x...",
+        "SAFE_ADDRESS": "0x...",
+        "ALLOWANCE_MODULE_ADDRESS": "0x...",
+        "USDCE_ADDRESS": "0x...",
+        "RESOURCE_SERVER_URL": "https://your-x402-server/mcp/sse",
+        "HPP_RPC_URL": "https://sepolia.hpp.io",
+        "HPP_NETWORK": "eip155:181228"
+      }
+    }
+  }
+}
+```
+
+Same config block works for OpenClaw and any other MCP host that supports
+stdio MCP servers. See [`examples/`](./examples/) for ready-to-merge JSON
+snippets and a [local development guide](./examples/local-dev.md) for using
+the bridge before it's published to npm.
+
+## Pre-flight (one-time, on-chain)
+
+Before the bridge can do anything, you need a Safe with USDC.e and an
+AllowanceModule entry that authorises a delegate EOA to pull from it:
+
+1. Deploy / use an existing Safe at [`safe.hpp.io`](https://safe.hpp.io).
+2. Send USDC.e to the Safe.
+3. Enable the AllowanceModule on the Safe (one Safe transaction).
+4. `addDelegate(<delegate EOA>)` and
+   `setAllowance(<delegate>, USDC.e, <daily cap>, 1440 minutes, 0)` —
+   one Safe transaction each (or batched via Safe's MultiSend).
+5. Send a small amount of native ETH to the delegate EOA (it pays gas
+   for `executeAllowanceTransfer`).
+
+Verified end-to-end on HPP Sepolia 2026-05-06 — the chain enforces the
+daily cap, and `deleteAllowance` instantly blocks future top-ups.
+
+## Architecture
+
+See [DESIGN.md in the parent task](../noosphere-evm/.claude/tasks/x402-mcp-wallet/design/DESIGN.md).
+
+In short:
+
+```
+host (Claude Desktop)
+   │ stdio (MCP)
+   ▼
+[ this bridge ]
+   ─ Signer (delegate EOA)
+   ─ AutoTopup (Safe + AllowanceModule)
+   ─ remote MCP client (@x402/mcp wrapped)
+   │
+   │ SSE / StreamableHTTP (MCP + x402)
+   ▼
+remote x402 MCP server
+```
+
+## Releasing to npm
+
+Two paths, both via the GitHub Actions [Publish workflow](.github/workflows/publish.yml):
+
+```
+# (1) Recommended: tag-driven release
+git checkout main && git pull
+npm version patch          # or minor / major
+git push --follow-tags     # → workflow runs, publishes to npm
+
+# (2) Ad-hoc: workflow_dispatch from GitHub UI
+#     Actions tab → "Publish to npm" → Run workflow
+#     Optional `dry_run` toggle for verification
+```
+
+Required secret on the GitHub repo: `NPM_TOKEN` (npmjs.com → Profile →
+Access Tokens → Generate "Automation" token scoped to `@hpp-io`).
+
+The `prepublishOnly` script in package.json runs `typecheck && build`
+locally too, so manual `npm publish` from a developer's machine still
+guards against shipping broken builds.
+
+## Status
+
+**v0.0.1 — PoC.** Working end-to-end against HPP Sepolia (smoke proves
+both the "delegate has balance" and "delegate empty → autoTopup → pay"
+paths). Not yet published to npm; install via local path or git clone.
+
+Roadmap:
+
+- v0.1: package on npm, full README with screenshots, OS keychain wrapper
+  for `DELEGATE_PRIVATE_KEY` (`keychain://hpp-x402-delegate`).
+- v0.2: additional `Signer` implementations (HPP self-hosted server-wallet
+  API, ERC-4337 session keys).
+- v0.3: structured guardrail layer (allowlist of `RESOURCE_SERVER_URL`,
+  per-call max payment cap) — mirrors Coinbase AgentKit's
+  `X402ActionProvider`.
+
+## License
+
+Apache-2.0

package/bin/hpp-x402-safe-revoke.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import("../dist/cli/revoke.js").catch((err) => {
+  process.stderr.write(`hpp-x402-safe-revoke fatal: ${err?.message ?? err}\n`);
+  process.exit(1);
+});

package/bin/hpp-x402-safe-setup.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import("../dist/cli/setup.js").catch((err) => {
+  process.stderr.write(`hpp-x402-safe-setup fatal: ${err?.message ?? err}\n`);
+  process.exit(1);
+});

package/bin/x402-mcp-bridge.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Entry shim for `npx @hpp-io/x402-mcp-bridge` and Claude Desktop's
+ * "command": "npx" launch path. Imports the compiled ESM build.
+ */
+import("../dist/index.js").then((m) => {
+  return m.runBridge();
+}).catch((err) => {
+  process.stderr.write(`x402-mcp-bridge fatal: ${err?.message ?? err}\n`);
+  process.exit(1);
+});

package/dist/autoTopup.d.ts

@@ -0,0 +1,50 @@
+/**
+ * AutoTopup — pulls USDC.e from the user's Safe to the delegate EOA via
+ * AllowanceModule.executeAllowanceTransfer.
+ *
+ * Triggered lazily before each x402 payment when the delegate's balance
+ * is insufficient. The chain enforces the daily cap; if a topup would
+ * exceed the allowance the call reverts with
+ *
+ *   "newSpent > allowance.spent && newSpent <= allowance.amount"
+ *
+ * which the bridge maps to a clear "spend cap exceeded" error for the
+ * MCP host (and therefore the LLM and the user).
+ *
+ * Implementation note: Verified end-to-end on HPP Sepolia 2026-05-06,
+ * see ../noosphere-evm/.claude/tasks/x402-mcp-wallet/design/DEPLOYMENTS.md
+ */
+import { type Address, type Hex } from "viem";
+import type { Signer } from "./signer.js";
+export interface AutoTopupOptions {
+    /** PoC-only: explicit pull amount (atomic). If unset, a dynamic value
+     *  based on `requiredAtomic` × headroom is used. */
+    fixedAmountAtomic?: bigint;
+    /** Headroom multiplier for dynamic topup. Default 10. */
+    headroomX?: bigint;
+}
+export declare class AutoTopup {
+    private readonly signer;
+    private readonly safe;
+    private readonly allowanceModule;
+    private readonly token;
+    private readonly chainId;
+    private readonly rpcUrl;
+    private readonly opts;
+    private readonly publicClient;
+    private readonly walletClient;
+    constructor(signer: Signer, safe: Address, allowanceModule: Address, token: Address, chainId: number, rpcUrl: string, opts?: AutoTopupOptions);
+    /**
+     * Ensure the delegate holds at least `requiredAtomic` of `token`.
+     * No-op when balance already sufficient. Returns the topup tx hash
+     * (or null if no topup was needed).
+     */
+    ensure(requiredAtomic: bigint): Promise<Hex | null>;
+    /** Read delegate's current ERC-20 balance. */
+    private balanceOfDelegate;
+    /** allowance.amount - allowance.spent (after on-chain auto-reset, which
+     *  AllowanceModule applies inside getTokenAllowance). */
+    private remainingAllowance;
+    /** Sign + send AllowanceModule.executeAllowanceTransfer. */
+    private execute;
+}

package/dist/autoTopup.js

@@ -0,0 +1,193 @@
+/**
+ * AutoTopup — pulls USDC.e from the user's Safe to the delegate EOA via
+ * AllowanceModule.executeAllowanceTransfer.
+ *
+ * Triggered lazily before each x402 payment when the delegate's balance
+ * is insufficient. The chain enforces the daily cap; if a topup would
+ * exceed the allowance the call reverts with
+ *
+ *   "newSpent > allowance.spent && newSpent <= allowance.amount"
+ *
+ * which the bridge maps to a clear "spend cap exceeded" error for the
+ * MCP host (and therefore the LLM and the user).
+ *
+ * Implementation note: Verified end-to-end on HPP Sepolia 2026-05-06,
+ * see ../noosphere-evm/.claude/tasks/x402-mcp-wallet/design/DEPLOYMENTS.md
+ */
+import { createPublicClient, createWalletClient, http, defineChain, } from "viem";
+import { RawEoaSigner } from "./signers/raw-eoa.js";
+const ERC20_BALANCE_ABI = [
+    {
+        type: "function",
+        name: "balanceOf",
+        inputs: [{ name: "account", type: "address" }],
+        outputs: [{ name: "", type: "uint256" }],
+        stateMutability: "view",
+    },
+];
+const ALLOWANCE_ABI = [
+    {
+        type: "function",
+        name: "getTokenAllowance",
+        inputs: [
+            { name: "safe", type: "address" },
+            { name: "delegate", type: "address" },
+            { name: "token", type: "address" },
+        ],
+        outputs: [{ name: "", type: "uint256[5]" }],
+        stateMutability: "view",
+    },
+    {
+        type: "function",
+        name: "executeAllowanceTransfer",
+        inputs: [
+            { name: "safe", type: "address" },
+            { name: "token", type: "address" },
+            { name: "to", type: "address" },
+            { name: "amount", type: "uint96" },
+            { name: "paymentToken", type: "address" },
+            { name: "payment", type: "uint96" },
+            { name: "delegate", type: "address" },
+            { name: "signature", type: "bytes" },
+        ],
+        outputs: [],
+        stateMutability: "nonpayable",
+    },
+];
+export class AutoTopup {
+    signer;
+    safe;
+    allowanceModule;
+    token;
+    chainId;
+    rpcUrl;
+    opts;
+    publicClient;
+    walletClient;
+    constructor(signer, safe, allowanceModule, token, chainId, rpcUrl, opts = {}) {
+        this.signer = signer;
+        this.safe = safe;
+        this.allowanceModule = allowanceModule;
+        this.token = token;
+        this.chainId = chainId;
+        this.rpcUrl = rpcUrl;
+        this.opts = opts;
+        if (!(signer instanceof RawEoaSigner)) {
+            // The contract calls below require a viem-account-shaped signer.
+            // The Signer interface itself doesn't yet expose `sendTransaction`,
+            // so the autoTopup path currently requires RawEoaSigner. When new
+            // signer kinds land we'll widen this through a `tx.send` helper.
+            throw new Error("AutoTopup currently requires RawEoaSigner; other signer types pending");
+        }
+        const chain = defineChain({
+            id: chainId,
+            name: `chain-${chainId}`,
+            nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+            rpcUrls: { default: { http: [rpcUrl] } },
+        });
+        this.publicClient = createPublicClient({ chain, transport: http(rpcUrl) });
+        this.walletClient = createWalletClient({
+            chain,
+            transport: http(rpcUrl),
+            account: signer.viemAccount,
+        });
+    }
+    /**
+     * Ensure the delegate holds at least `requiredAtomic` of `token`.
+     * No-op when balance already sufficient. Returns the topup tx hash
+     * (or null if no topup was needed).
+     */
+    async ensure(requiredAtomic) {
+        const balance = await this.balanceOfDelegate();
+        if (balance >= requiredAtomic)
+            return null;
+        const need = requiredAtomic - balance;
+        const headroom = this.opts.headroomX ?? 10n;
+        const wanted = this.opts.fixedAmountAtomic ?? need * headroom > 0n
+            ? this.opts.fixedAmountAtomic ?? need * headroom
+            : need;
+        // Cap at remaining allowance to avoid the (otherwise inevitable) revert.
+        const remaining = await this.remainingAllowance();
+        const amount = wanted > remaining ? remaining : wanted;
+        if (amount < need) {
+            throw new Error(`spend cap exceeded — required ${requiredAtomic} but only ${balance + remaining} available before allowance reset`);
+        }
+        return this.execute(amount);
+    }
+    /** Read delegate's current ERC-20 balance. */
+    async balanceOfDelegate() {
+        return (await this.publicClient.readContract({
+            address: this.token,
+            abi: ERC20_BALANCE_ABI,
+            functionName: "balanceOf",
+            args: [this.signer.address],
+        }));
+    }
+    /** allowance.amount - allowance.spent (after on-chain auto-reset, which
+     *  AllowanceModule applies inside getTokenAllowance). */
+    async remainingAllowance() {
+        const a = (await this.publicClient.readContract({
+            address: this.allowanceModule,
+            abi: ALLOWANCE_ABI,
+            functionName: "getTokenAllowance",
+            args: [this.safe, this.signer.address, this.token],
+        }));
+        if (a[0] === 0n)
+            return 0n;
+        return a[1] >= a[0] ? 0n : a[0] - a[1];
+    }
+    /** Sign + send AllowanceModule.executeAllowanceTransfer. */
+    async execute(amountAtomic) {
+        const a = (await this.publicClient.readContract({
+            address: this.allowanceModule,
+            abi: ALLOWANCE_ABI,
+            functionName: "getTokenAllowance",
+            args: [this.safe, this.signer.address, this.token],
+        }));
+        const nonce = Number(a[4]);
+        const signature = await this.signer.signTypedData({
+            domain: { chainId: this.chainId, verifyingContract: this.allowanceModule },
+            types: {
+                AllowanceTransfer: [
+                    { name: "safe", type: "address" },
+                    { name: "token", type: "address" },
+                    { name: "to", type: "address" },
+                    { name: "amount", type: "uint96" },
+                    { name: "paymentToken", type: "address" },
+                    { name: "payment", type: "uint96" },
+                    { name: "nonce", type: "uint16" },
+                ],
+            },
+            primaryType: "AllowanceTransfer",
+            message: {
+                safe: this.safe,
+                token: this.token,
+                to: this.signer.address,
+                amount: amountAtomic,
+                paymentToken: "0x0000000000000000000000000000000000000000",
+                payment: 0n,
+                nonce,
+            },
+        });
+        const txHash = await this.walletClient.writeContract({
+            address: this.allowanceModule,
+            abi: ALLOWANCE_ABI,
+            functionName: "executeAllowanceTransfer",
+            args: [
+                this.safe,
+                this.token,
+                this.signer.address,
+                amountAtomic,
+                "0x0000000000000000000000000000000000000000",
+                0n,
+                this.signer.address,
+                signature,
+            ],
+            chain: null,
+            account: this.signer.viemAccount,
+        });
+        await this.publicClient.waitForTransactionReceipt({ hash: txHash });
+        return txHash;
+    }
+}
+//# sourceMappingURL=autoTopup.js.map

package/dist/autoTopup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoTopup.js","sourceRoot":"","sources":["../src/autoTopup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,IAAI,EACJ,WAAW,GAKZ,MAAM,MAAM,CAAC;AAGd,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,MAAM,iBAAiB,GAAG;IACxB;QACE,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,WAAW;QACjB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC9C,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACxC,eAAe,EAAE,MAAM;KACxB;CACO,CAAC;AAEX,MAAM,aAAa,GAAG;IACpB;QACE,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,mBAAmB;QACzB,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE;YACjC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;YACrC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE;SACnC;QACD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;QAC3C,eAAe,EAAE,MAAM;KACxB;IACD;QACE,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,0BAA0B;QAChC,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE;YACjC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE;YAClC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE;YAC/B,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE;YAClC,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,EAAE;YACzC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE;YACnC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;YACrC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE;SACrC;QACD,OAAO,EAAE,EAAE;QACX,eAAe,EAAE,YAAY;KAC9B;CACO,CAAC;AAUX,MAAM,OAAO,SAAS;IAKD;IACA;IACA;IACA;IACA;IACA;IACA;IAVF,YAAY,CAAe;IAC3B,YAAY,CAAe;IAE5C,YACmB,MAAc,EACd,IAAa,EACb,eAAwB,EACxB,KAAc,EACd,OAAe,EACf,MAAc,EACd,OAAyB,EAAE;QAN3B,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAS;QACb,oBAAe,GAAf,eAAe,CAAS;QACxB,UAAK,GAAL,KAAK,CAAS;QACd,YAAO,GAAP,OAAO,CAAQ;QACf,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAuB;QAE5C,IAAI,CAAC,CAAC,MAAM,YAAY,YAAY,CAAC,EAAE,CAAC;YACtC,iEAAiE;YACjE,oEAAoE;YACpE,kEAAkE;YAClE,iEAAiE;YACjE,MAAM,IAAI,KAAK,CACb,uEAAuE,CACxE,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,GAAG,WAAW,CAAC;YACxB,EAAE,EAAE,OAAO;YACX,IAAI,EAAE,SAAS,OAAO,EAAE;YACxB,cAAc,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE;YAC9D,OAAO,EAAE,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE;SACzC,CAAC,CAAC;QACH,IAAI,CAAC,YAAY,GAAG,kBAAkB,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC3E,IAAI,CAAC,YAAY,GAAG,kBAAkB,CAAC;YACrC,KAAK;YACL,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC;YACvB,OAAO,EAAE,MAAM,CAAC,WAAW;SAC5B,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,MAAM,CAAC,cAAsB;QACjC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC/C,IAAI,OAAO,IAAI,cAAc;YAAE,OAAO,IAAI,CAAC;QAE3C,MAAM,IAAI,GAAG,cAAc,GAAG,OAAO,CAAC;QACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,GAAG,CAAC;QAC5C,MAAM,MAAM,GACV,IAAI,CAAC,IAAI,CAAC,iBAAiB,IAAI,IAAI,GAAG,QAAQ,GAAG,EAAE;YACjD,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,IAAI,IAAI,GAAG,QAAQ;YAChD,CAAC,CAAC,IAAI,CAAC;QAEX,yEAAyE;QACzE,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAClD,MAAM,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;QACvD,IAAI,MAAM,GAAG,IAAI,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CACb,iCAAiC,cAAc,aAC7C,OAAO,GAAG,SACZ,mCAAmC,CACpC,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAED,8CAA8C;IACtC,KAAK,CAAC,iBAAiB;QAC7B,OAAO,CAAC,MAAM,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC;YAC3C,OAAO,EAAE,IAAI,CAAC,KAAK;YACnB,GAAG,EAAE,iBAAiB;YACtB,YAAY,EAAE,WAAW;YACzB,IAAI,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;SAC5B,CAAC,CAAW,CAAC;IAChB,CAAC;IAED;6DACyD;IACjD,KAAK,CAAC,kBAAkB;QAC9B,MAAM,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC;YAC9C,OAAO,EAAE,IAAI,CAAC,eAAe;YAC7B,GAAG,EAAE,aAAa;YAClB,YAAY,EAAE,mBAAmB;YACjC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC;SACnD,CAAC,CAAsD,CAAC;QACzD,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE;YAAE,OAAO,EAAE,CAAC;QAC3B,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC;IAED,4DAA4D;IACpD,KAAK,CAAC,OAAO,CAAC,YAAoB;QACxC,MAAM,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC;YAC9C,OAAO,EAAE,IAAI,CAAC,eAAe;YAC7B,GAAG,EAAE,aAAa;YAClB,YAAY,EAAE,mBAAmB;YACjC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC;SACnD,CAAC,CAAsD,CAAC;QACzD,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAE3B,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC;YAChD,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,iBAAiB,EAAE,IAAI,CAAC,eAAe,EAAE;YAC1E,KAAK,EAAE;gBACL,iBAAiB,EAAE;oBACjB,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE;oBACjC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE;oBAClC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE;oBAC/B,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE;oBAClC,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,EAAE;oBACzC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACnC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE;iBAClC;aACF;YACD,WAAW,EAAE,mBAAmB;YAChC,OAAO,EAAE;gBACP,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;gBACvB,MAAM,EAAE,YAAY;gBACpB,YAAY,EAAE,4CAA4C;gBAC1D,OAAO,EAAE,EAAE;gBACX,KAAK;aACN;SACF,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,aAAa,CAAC;YACnD,OAAO,EAAE,IAAI,CAAC,eAAe;YAC7B,GAAG,EAAE,aAAa;YAClB,YAAY,EAAE,0BAA0B;YACxC,IAAI,EAAE;gBACJ,IAAI,CAAC,IAAI;gBACT,IAAI,CAAC,KAAK;gBACV,IAAI,CAAC,MAAM,CAAC,OAAO;gBACnB,YAAY;gBACZ,4CAA4C;gBAC5C,EAAE;gBACF,IAAI,CAAC,MAAM,CAAC,OAAO;gBACnB,SAAS;aACV;YACD,KAAK,EAAE,IAAI;YACX,OAAO,EAAG,IAAI,CAAC,MAAuB,CAAC,WAAW;SACnD,CAAC,CAAC;QACH,MAAM,IAAI,CAAC,YAAY,CAAC,yBAAyB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QACpE,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}

package/dist/cli/install-claude.d.ts

@@ -0,0 +1,25 @@
+export declare function configPath(): string;
+export interface InstallEnv {
+    DELEGATE_PRIVATE_KEY: string;
+    SAFE_ADDRESS: string;
+    ALLOWANCE_MODULE_ADDRESS: string;
+    USDCE_ADDRESS: string;
+    RESOURCE_SERVER_URL: string;
+    HPP_RPC_URL: string;
+    HPP_NETWORK: string;
+    LOG_LEVEL?: string;
+}
+export interface InstallResult {
+    configPath: string;
+    backupPath: string | null;
+    changed: boolean;
+    preservedEntries: string[];
+}
+/**
+ * Merge an `hpp-x402` server entry into the host config and write it.
+ * `command`/`args` default to launching the published bridge via npx.
+ */
+export declare function installClaudeDesktop(env: InstallEnv, opts?: {
+    force?: boolean;
+    bridgeAbsPath?: string;
+}): InstallResult;

package/dist/cli/install-claude.js

@@ -0,0 +1,82 @@
+/**
+ * Merge an `hpp-x402` MCP server entry into the user's
+ * claude_desktop_config.json. Importable function (used by setup CLI
+ * with --install-claude) and a standalone bin entry.
+ *
+ * Preserves all other mcpServers entries; backs up the original.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { homedir, platform } from "node:os";
+const ENTRY_NAME = "hpp-x402";
+export function configPath() {
+    const p = platform();
+    if (p === "darwin") {
+        return resolve(homedir(), "Library/Application Support/Claude/claude_desktop_config.json");
+    }
+    if (p === "win32") {
+        return resolve(process.env.APPDATA ?? "", "Claude/claude_desktop_config.json");
+    }
+    return resolve(homedir(), ".config/Claude/claude_desktop_config.json");
+}
+/**
+ * Merge an `hpp-x402` server entry into the host config and write it.
+ * `command`/`args` default to launching the published bridge via npx.
+ */
+export function installClaudeDesktop(env, opts = {}) {
+    const path = configPath();
+    let existing = {};
+    if (existsSync(path)) {
+        existing = JSON.parse(readFileSync(path, "utf8"));
+    }
+    else {
+        mkdirSync(dirname(path), { recursive: true });
+    }
+    const command = opts.bridgeAbsPath ? "node" : "npx";
+    const args = opts.bridgeAbsPath
+        ? [opts.bridgeAbsPath]
+        : ["-y", "@hpp-io/x402-mcp-bridge"];
+    const entry = {
+        command,
+        args,
+        env: {
+            DELEGATE_PRIVATE_KEY: env.DELEGATE_PRIVATE_KEY,
+            SAFE_ADDRESS: env.SAFE_ADDRESS,
+            ALLOWANCE_MODULE_ADDRESS: env.ALLOWANCE_MODULE_ADDRESS,
+            USDCE_ADDRESS: env.USDCE_ADDRESS,
+            RESOURCE_SERVER_URL: env.RESOURCE_SERVER_URL,
+            HPP_RPC_URL: env.HPP_RPC_URL,
+            HPP_NETWORK: env.HPP_NETWORK,
+            LOG_LEVEL: env.LOG_LEVEL ?? "info",
+        },
+    };
+    const mcpServers = (existing.mcpServers ??= {});
+    const prior = mcpServers[ENTRY_NAME];
+    if (prior && JSON.stringify(prior) === JSON.stringify(entry)) {
+        return {
+            configPath: path,
+            backupPath: null,
+            changed: false,
+            preservedEntries: Object.keys(mcpServers).filter((k) => k !== ENTRY_NAME),
+        };
+    }
+    if (prior && !opts.force) {
+        throw new Error(`existing hpp-x402 entry differs; pass force:true (or --force in CLI) to overwrite`);
+    }
+    mcpServers[ENTRY_NAME] = entry;
+    const merged = { ...existing, mcpServers };
+    let backupPath = null;
+    if (existsSync(path)) {
+        const ts = new Date().toISOString().replace(/[:.]/g, "-");
+        backupPath = path + "." + ts + ".bak";
+        copyFileSync(path, backupPath);
+    }
+    writeFileSync(path, JSON.stringify(merged, null, 2) + "\n", "utf8");
+    return {
+        configPath: path,
+        backupPath,
+        changed: true,
+        preservedEntries: Object.keys(mcpServers).filter((k) => k !== ENTRY_NAME),
+    };
+}
+//# sourceMappingURL=install-claude.js.map

package/dist/cli/install-claude.js.map

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

package/dist/cli/revoke.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/revoke.js

@@ -0,0 +1,123 @@
+import { buildClients, execSafeTx, encodeDeleteAllowance, } from "./safe.js";
+const DEFAULTS = {
+    "eip155:181228": {
+        rpc: "https://sepolia.hpp.io",
+        usdc: "0x401eCb1D350407f13ba348573E5630B83638E30D",
+        module: "0x3CcE72483929e0517Dafc8fD192547B3B65f9b07",
+        chainId: 181228,
+    },
+};
+function parseArgs(argv) {
+    const out = {};
+    for (let i = 2; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith("--"))
+            continue;
+        const k = a.slice(2);
+        const next = argv[i + 1];
+        if (!next || next.startsWith("--")) {
+            out[k] = true;
+        }
+        else {
+            out[k] = next;
+            i++;
+        }
+    }
+    return out;
+}
+function requireStr(a, k) {
+    const v = a[k];
+    if (typeof v !== "string" || v.length === 0) {
+        console.error(`missing --${k}`);
+        process.exit(1);
+    }
+    return v;
+}
+const ERC20_ABI = [
+    {
+        type: "function",
+        name: "balanceOf",
+        inputs: [{ name: "account", type: "address" }],
+        outputs: [{ name: "", type: "uint256" }],
+        stateMutability: "view",
+    },
+    {
+        type: "function",
+        name: "transfer",
+        inputs: [
+            { name: "to", type: "address" },
+            { name: "amount", type: "uint256" },
+        ],
+        outputs: [{ name: "", type: "bool" }],
+        stateMutability: "nonpayable",
+    },
+];
+async function main() {
+    const args = parseArgs(process.argv);
+    const network = args.network || "eip155:181228";
+    const def = DEFAULTS[network];
+    if (!def) {
+        console.error(`unsupported network: ${network}`);
+        process.exit(1);
+    }
+    const ownerPk = requireStr(args, "owner-pk");
+    const safe = requireStr(args, "safe");
+    const delegate = requireStr(args, "delegate");
+    const rpc = args.rpc || def.rpc;
+    const usdc = (args.usdc || def.usdc);
+    const module = (args.module || def.module);
+    const drain = args.drain === true;
+    const delegatePk = args["delegate-pk"];
+    if (drain && !delegatePk) {
+        console.error("--drain requires --delegate-pk to sign the transfer back");
+        process.exit(1);
+    }
+    const cfg = { rpcUrl: rpc, chainId: def.chainId };
+    console.log(`hpp-x402-safe-revoke`);
+    console.log(`  Safe         : ${safe}`);
+    console.log(`  Delegate     : ${delegate}`);
+    console.log(`  Mode         : ${drain ? "deleteAllowance + drain" : "deleteAllowance only"}`);
+    console.log("");
+    // ---- 1) deleteAllowance (Safe Tx, owner signs) ---------------------
+    console.log("[1/2] AllowanceModule.deleteAllowance…");
+    const deleteTx = await execSafeTx(cfg, ownerPk, safe, module, encodeDeleteAllowance(delegate, usdc));
+    console.log(`      ✓ deleted (Safe tx ${deleteTx})`);
+    // ---- 2) (optional) drain delegate's remaining USDC.e ---------------
+    if (drain) {
+        console.log("[2/2] Draining delegate's USDC.e back to Safe…");
+        const { publicClient, walletClient } = buildClients(cfg, delegatePk);
+        const balance = (await publicClient.readContract({
+            address: usdc,
+            abi: ERC20_ABI,
+            functionName: "balanceOf",
+            args: [delegate],
+        }));
+        if (balance === 0n) {
+            console.log("      ✓ delegate already empty — nothing to drain");
+        }
+        else {
+            const tx = await walletClient.writeContract({
+                address: usdc,
+                abi: ERC20_ABI,
+                functionName: "transfer",
+                args: [safe, balance],
+            });
+            await publicClient.waitForTransactionReceipt({ hash: tx });
+            console.log(`      ✓ drained ${Number(balance) / 1e6} USDC.e (tx ${tx})`);
+        }
+    }
+    else {
+        console.log("[2/2] Skipped drain (no --drain flag).");
+    }
+    console.log("\n🎉 revocation complete.");
+    console.log("\nThe delegate can no longer pull from the Safe via AllowanceModule.");
+    if (!drain) {
+        console.log("⚠ delegate may still hold leftover USDC.e it pulled earlier.");
+        console.log("  Run again with --drain --delegate-pk 0x... to recover that balance.");
+    }
+}
+main().catch((err) => {
+    console.error("\nERROR:", err?.message ?? err);
+    process.exit(1);
+});
+//# sourceMappingURL=revoke.js.map