Merge pull request #66 from szhygulin/release/0.5.2

release/0.5.2

Author: szhygulin

README.md

@@ -36,13 +36,15 @@ This is an **agent-driven portfolio management** tool, not a wallet replacement.
 
 ## Security model
 
+**VaultPilot assumes the AI agent can be compromised, the MCP server can be compromised, and your host computer can be compromised. Only your Ledger device is trusted.** Every transaction is cryptographically bound across every layer so that tampering anywhere — a swapped recipient, a rewritten swap route, a smuggled approval — produces a visible mismatch on the device screen, giving you the chance to reject before anything is signed.
+
 Private keys never leave the Ledger device. Every state-changing transaction is prepared read-only by the server, previewed in human-readable form, and approved on the device's own screen — the only display in the pipeline that isn't filtered through the agent.
 
 ```
 user-intent ──► agent ──► MCP server ──► WalletConnect / USB-HID ──► Ledger Live / host ──► Ledger device
 ```
 
-VaultPilot layers defenses so most single-layer compromises are caught by at least one cross-check, and the cases that aren't are called out honestly. The layers include a server-side prepare↔send fingerprint, an independent 4byte.directory selector cross-check, an agent-side ABI decode and pair-consistency pre-sign hash recomputation that auto-run at `preview_send` and are reported in a `CHECKS PERFORMED` block (with a swiss-knife decoder URL as a suggested fallback when the agent's ABI decode is low-confidence), a Ledger blind-sign hash the user matches on-device, a verbatim `PREPARE RECEIPT` of the args the agent actually passed, a `previewToken` + `userDecision` gate against accidental preview-step collapse, and — for skeptical users on high-value flows — a `get_verification_artifact` that routes bytes to a second, independent LLM for cross-verification.
+VaultPilot layers defenses so most single-layer compromises are caught by at least one cross-check, and the cases that aren't are called out honestly. The layers include a server-side prepare↔send fingerprint, an independent 4byte.directory selector cross-check, an agent-side ABI decode and pair-consistency pre-sign hash recomputation that auto-run at `preview_send` and are reported in a `CHECKS PERFORMED` block (with a swiss-knife decoder URL as a suggested fallback when the agent's ABI decode is low-confidence), an on-device final check — in blind-sign mode the user matches a Ledger-displayed hash against the one the server returned; in clear-sign mode (Aave, Lido, 1inch, LiFi, approve plugins) the user checks decoded fields (function name, amount, recipient, spender) against the compact summary shown in chat — a verbatim `PREPARE RECEIPT` of the args the agent actually passed, a `previewToken` + `userDecision` gate against accidental preview-step collapse, a WalletConnect session-topic cross-check (the agent surfaces the last 8 chars of the WC session `topic` and asks the user to confirm a matching session exists in Ledger Live → Settings → Connected Apps, catching peer impersonation any self-reported name/URL can't), and — for skeptical users on high-value flows — a `get_verification_artifact` that routes bytes to a second, independent LLM for cross-verification.
 
 **See [SECURITY.md](./SECURITY.md)** for the full defenses table, threat → catches-it mapping, honest limits, the `payloadFingerprint` verification recipe, and the second-agent verification flow.
 
@@ -88,7 +90,7 @@ Meta:
 
 Execution (Ledger-signed):
 
-- `pair_ledger_live` (WalletConnect, EVM), `pair_ledger_tron` (USB HID, TRON), `get_ledger_status` — session management and account discovery; `get_ledger_status` returns per-chain EVM exposure (`accountDetails[]` with `address`, `chainIds`, `chains`) so duplicate-looking addresses across chains are disambiguated, and a `tron: [{ address, path, appVersion, accountIndex }, …]` array (one entry per paired TRON account) when `pair_ledger_tron` has been called. Pass `accountIndex: 1` (2, 3, …) to pair additional TRON accounts.
+- `pair_ledger_live` (WalletConnect, EVM), `pair_ledger_tron` (USB HID, TRON), `get_ledger_status` — session management and account discovery; `get_ledger_status` returns per-chain EVM exposure (`accountDetails[]` with `address`, `chainIds`, `chains`) so duplicate-looking addresses across chains are disambiguated, the WalletConnect session `topic` (the agent is instructed to surface its last 8 chars and ask the user to verify a matching session in Ledger Live → Settings → Connected Apps before the first `send_transaction` — any WC peer can self-report "Ledger Wallet" / `wc.apps.ledger.com`, but the session topic is unique per pairing), and a `tron: [{ address, path, appVersion, accountIndex }, …]` array (one entry per paired TRON account) when `pair_ledger_tron` has been called. Pass `accountIndex: 1` (2, 3, …) to pair additional TRON accounts.
 - `prepare_aave_supply` / `_withdraw` / `_borrow` / `_repay`
 - `prepare_compound_supply` / `_withdraw` / `_borrow` / `_repay`
 - `prepare_morpho_supply` / `_withdraw` / `_borrow` / `_repay` / `_supply_collateral` / `_withdraw_collateral`

SECURITY.md

@@ -8,6 +8,22 @@ agent prepare transactions against your Ledger device.
 For the product overview, install instructions, and tool reference, see the
 main [README](./README.md).
 
+## Why trust VaultPilot?
+
+VaultPilot assumes the AI agent can be compromised, the MCP server can be
+compromised, and your host computer can be compromised. Only your Ledger
+hardware is trusted. Every transaction is cryptographically bound across
+every layer so that tampering at any point — a swapped recipient, a
+rewritten swap route, a smuggled approval — produces a visible mismatch
+on your Ledger screen, giving you the chance to reject before anything
+is signed.
+
+In practice: the agent relays a hash it computed locally, the MCP relays
+the bytes it intends to broadcast, and the Ledger re-derives its own hash
+from the bytes it actually receives. You compare the two on the device's
+own screen — the one display in the pipeline that no software on the host
+can forge. No layer in between can fake a match it doesn't have.
+
 ## Trust boundaries
 
 The signing pipeline crosses several independent trust boundaries, each of

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "vaultpilot-mcp",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "mcpName": "io.github.szhygulin/vaultpilot-mcp",
   "description": "MCP server for AI agents (Claude Code, Claude Desktop, Cursor) to manage a self-custodial crypto portfolio through a Ledger hardware wallet. Reads on-chain wallet balances, ENS, token prices, and DeFi positions across Ethereum/Arbitrum/Polygon/Base (Aave V3, Compound V3, Morpho Blue, Uniswap V3 LP, Lido stETH, EigenLayer), surfaces liquidation/health-factor alerts and protocol risk scores, then prepares unsigned EVM transactions (supply, borrow, repay, withdraw, stake, unstake, native/ERC-20 send, and LiFi-routed swaps and cross-chain bridges) that the user signs on their Ledger device via WalletConnect — private keys never leave the hardware wallet.",
   "type": "module",

package.json

@@ -3,7 +3,7 @@
   "name": "io.github.szhygulin/vaultpilot-mcp",
   "title": "VaultPilot MCP",
   "description": "Self-custodial crypto portfolio: read EVM DeFi, sign on Ledger via WalletConnect.",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "websiteUrl": "https://github.com/szhygulin/vaultpilot-mcp",
   "repository": {
     "url": "https://github.com/szhygulin/vaultpilot-mcp",
@@ -14,7 +14,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "vaultpilot-mcp",
-      "version": "0.5.1",
+      "version": "0.5.2",
       "transport": { "type": "stdio" },
       "environmentVariables": [
         {

server.json

@@ -381,9 +381,13 @@ async function sendTronTransaction(args: SendTransactionArgs): Promise<{
     const rehash = tronPayloadFingerprint(tx.rawDataHex);
     if (rehash !== tx.verification.payloadHash) {
       throw new Error(
-        `TRON payload hash mismatch at send time. Previewed ${tx.verification.payloadHash}, ` +
+        `SECURITY: TRON payload hash mismatch at send time. Previewed ${tx.verification.payloadHash}, ` +
           `about to sign ${rehash}. The rawDataHex changed between preview and send — refusing ` +
-          `to forward to the Ledger.`,
+          `to forward to the Ledger. Do NOT retry this handle. Re-prepare the transaction from ` +
+          `scratch (call the prepare_* tool again) and compare the new preview carefully — a ` +
+          `drift here means the bytes mutated inside the MCP process between the moment the user ` +
+          `reviewed them and the moment they would have been signed, which is not a normal ` +
+          `operating condition and may indicate a compromised intermediary.`,
       );
     }
   }
@@ -522,9 +526,13 @@ async function runEvmPreSignGuards(tx: UnsignedTx): Promise<void> {
     });
     if (rehash !== tx.verification.payloadHash) {
       throw new Error(
-        `Payload hash mismatch at preview/send time. Previewed ${tx.verification.payloadHash}, ` +
-          `about to sign ${rehash}. The transaction bytes changed between prepare and preview — ` +
-          `refusing to proceed.`,
+        `SECURITY: payload hash mismatch at preview/send time. Previewed ${tx.verification.payloadHash}, ` +
+          `about to sign ${rehash}. The transaction bytes (chain/to/value/data) changed between ` +
+          `prepare and preview — refusing to proceed. Do NOT retry this handle. Re-prepare the ` +
+          `transaction from scratch and compare the new preview against user intent carefully: ` +
+          `this drift means the bytes mutated inside the MCP process after the user reviewed ` +
+          `them, which is not a normal operating condition and may indicate a compromised ` +
+          `intermediary swapping bytes at send time.`,
       );
     }
   }
@@ -719,11 +727,14 @@ export async function sendTransaction(args: SendTransactionArgs): Promise<{
   }
   if (args.previewToken !== stashed.previewToken) {
     throw new Error(
-      "`previewToken` does not match the current pin on this handle. This usually means " +
-        "preview_send was re-called with `refresh: true` after you captured the token — the " +
-        "new pin has a new token (and a new preSignHash the user must re-match on-device). " +
-        "Call preview_send again, surface the fresh hash + EXTRA CHECKS menu to the user, and " +
-        "retry with the new token.",
+      "SECURITY: `previewToken` does not match the current pin on this handle. The benign " +
+        "explanation is that preview_send was re-called with `refresh: true` after the token " +
+        "was captured — in that case, the new pin has a new token AND a new preSignHash the " +
+        "user MUST re-match on-device. Do NOT retry with the old token: call preview_send " +
+        "again, surface the fresh CHECKS PERFORMED block and the new blind-sign hash to the " +
+        "user, and pass the new token. If the user did not ask for a refresh and the hash on " +
+        "their Ledger screen no longer matches the one they were shown, reject on-device — a " +
+        "token drift without a user-initiated refresh is not expected.",
     );
   }
   const tx = consumeHandle(args.handle);

src/modules/execution/index.ts

@@ -238,9 +238,14 @@ export async function signTronTxOnLedger(
       const { address } = await app.getAddress(path, false);
       if (address !== req.expectedFrom) {
         throw new Error(
-          `Ledger device address (${address}) does not match the prepared tx's \`from\` ` +
-            `(${req.expectedFrom}). Either connect the Ledger that holds keys for \`from\`, ` +
-            `or re-prepare the tx for the Ledger-derived address (\`pair_ledger_tron\`).`
+          `SECURITY: Ledger device address (${address}) does not match the prepared tx's \`from\` ` +
+            `(${req.expectedFrom}). Do NOT retry until you know which of these two is the cause: ` +
+            `(1) the wrong Ledger is connected, or (2) the \`from\` field in the prepared tx was ` +
+            `tampered with between prepare and send. Check the device — if the address it derives ` +
+            `on-screen is the one you expected (${address}), the tx's \`from\` was altered: abort, ` +
+            `re-prepare from scratch, and compare the new preview's \`from\` against user intent. ` +
+            `If the address on-screen is not your expected account, connect the correct Ledger or ` +
+            `re-prepare the tx for the Ledger-derived address via \`pair_ledger_tron\`.`
         );
       }
       const signature = await app.signTransaction(
@@ -251,7 +256,13 @@ export async function signTronTxOnLedger(
       // Ledger returns the signature as a hex string (65 bytes: r || s || v).
       if (!/^[0-9a-fA-F]{130}$/.test(signature)) {
         throw new Error(
-          `Ledger returned an unexpected signature shape (length ${signature.length}). Expected 130 hex chars.`
+          `SECURITY: Ledger returned an unexpected signature shape (length ${signature.length}, ` +
+            `expected 130 hex chars = 65 bytes r‖s‖v). Do NOT retry or broadcast this signature. ` +
+            `A well-formed Ledger TRON signature is always 130 hex chars; anything else means the ` +
+            `signature did not come from a healthy device exchange. Disconnect and reconnect the ` +
+            `Ledger, reopen the TRON app, and re-prepare the transaction from scratch. If the ` +
+            `error repeats on a clean reconnect, treat the host's USB/HID path as potentially ` +
+            `compromised and stop using it for signing until investigated.`
         );
       }
       return { signature, signerAddress: address };