Merge pull request #529 from szhygulin/feat/460-inv14-durable-binding

feat(security): Invariant #14 — durable-binding source-of-truth verification (#460)

Author: szhygulin

src/modules/btc/multisig.ts

@@ -255,6 +255,15 @@ export interface RegisterBitcoinMultisigWalletResult {
   appVersion: string;
   /** Index of the user's slot in `cosigners` (0-indexed). */
   ourKeyIndex: number;
+  /**
+   * Invariant #14 — one durable-binding entry per cosigner xpub.
+   * The skill renders these in the verification block before the
+   * user confirms the device-side wallet-policy registration; per
+   * Inv #14 the user re-verifies each xpub against its origin
+   * device's backup card (b098 attack class — attacker xpub
+   * embedded as 'co-signer'). Issue #460.
+   */
+  durableBindings: import("../../security/durable-binding.js").DurableBinding[];
 }
 
 export async function registerBitcoinMultisigWallet(
@@ -417,7 +426,14 @@ export async function registerBitcoinMultisigWallet(
     multisigByName.set(args.name, wallet);
     persistMultisig();
 
-    result = { wallet, appVersion: appInfo.version, ourKeyIndex };
+    const { makeDurableBinding } = await import(
+      "../../security/durable-binding.js"
+    );
+    const durableBindings = validatedCosigners.map((c) =>
+      makeDurableBinding("btc-multisig-cosigner-xpub", c.xpub),
+    );
+
+    result = { wallet, appVersion: appInfo.version, ourKeyIndex, durableBindings };
   } finally {
     await transport.close().catch(() => {});
   }

src/modules/compound/actions.ts

@@ -3,6 +3,7 @@ import { cometAbi } from "../../abis/compound-comet.js";
 import { getClient } from "../../data/rpc.js";
 import { buildApprovalTx, chainApproval, resolveApprovalCap } from "../shared/approval.js";
 import { resolveTokenMeta } from "../shared/token-meta.js";
+import { makeDurableBinding } from "../../security/durable-binding.js";
 import type {
   PrepareCompoundSupplyArgs,
   PrepareCompoundWithdrawArgs,
@@ -91,6 +92,7 @@ export async function buildCompoundSupply(p: PrepareCompoundSupplyArgs): Promise
     from: wallet,
     description: `Supply ${p.amount} ${meta.symbol} to Compound V3 ${market} on ${chain}`,
     decoded: { functionName: "supply", args: { asset, amount: p.amount, market } },
+    durableBindings: [makeDurableBinding("compound-comet-address", market)],
   };
   return chainApproval(approval, supplyTx);
 }
@@ -115,6 +117,7 @@ export async function buildCompoundWithdraw(p: PrepareCompoundWithdrawArgs): Pro
     from: wallet,
     description: `Withdraw ${p.amount === "max" ? "all" : p.amount} ${meta.symbol} from Compound V3 ${market} on ${chain}`,
     decoded: { functionName: "withdraw", args: { asset, amount: p.amount, market } },
+    durableBindings: [makeDurableBinding("compound-comet-address", market)],
   };
 }
 
@@ -139,6 +142,7 @@ export async function buildCompoundBorrow(p: PrepareCompoundBorrowArgs): Promise
     from: wallet,
     description: `Borrow ${p.amount} ${meta.symbol} from Compound V3 ${market} on ${chain}`,
     decoded: { functionName: "withdraw(base)", args: { asset: baseToken, amount: p.amount, market } },
+    durableBindings: [makeDurableBinding("compound-comet-address", market)],
   };
 }
 
@@ -182,6 +186,7 @@ export async function buildCompoundRepay(p: PrepareCompoundRepayArgs): Promise<U
     from: wallet,
     description: `Repay ${p.amount === "max" ? "all" : p.amount} ${meta.symbol} on Compound V3 ${market} on ${chain}`,
     decoded: { functionName: "supply(base)", args: { asset: baseToken, amount: p.amount, market } },
+    durableBindings: [makeDurableBinding("compound-comet-address", market)],
   };
   return chainApproval(approval, repayTx);
 }

src/modules/execution/index.ts

@@ -2663,6 +2663,9 @@ export async function prepareRevokeApproval(
   const spenderDisplay = knownLabel ? `${knownLabel} (${spender})` : spender;
   const currentFormatted = formatUnits(currentAllowance, meta.decimals);
 
+  const { makeDurableBinding } = await import(
+    "../../security/durable-binding.js"
+  );
   return enrichTx({
     chain,
     to: token,
@@ -2686,6 +2689,11 @@ export async function prepareRevokeApproval(
         ...(knownLabel ? { spenderLabel: knownLabel } : {}),
       },
     },
+    // Inv #14 (#460) — the spender selected from the user's allowance
+    // set is the durable object the user must re-verify. Complements the
+    // existing set-level enumeration check (Inv #13 / #450 which already
+    // ensures the user picks a row, not the agent).
+    durableBindings: [makeDurableBinding("approval-spender-address", spender)],
   });
 }
 

src/modules/lp/uniswap-v3/actions.ts

@@ -34,6 +34,7 @@ import {
   mintAmountsWithSlippage,
   type PoolState,
 } from "./position-math.js";
+import { makeDurableBinding } from "../../../security/durable-binding.js";
 import type { SupportedChain, UnsignedTx } from "../../../types/index.js";
 
 const SUPPORTED_FEE_TIERS = [100, 500, 3000, 10000] as const;
@@ -487,6 +488,7 @@ export async function buildUniswapIncrease(
         deadline: deadline.toString(),
       },
     },
+    durableBindings: [makeDurableBinding("uniswap-v3-lp-token-id", p.tokenId)],
   };
 
   // 5. Approvals — one per nonzero side; reuse the chain machinery.
@@ -786,6 +788,7 @@ export async function buildUniswapDecrease(
         deadline: deadline.toString(),
       },
     },
+    durableBindings: [makeDurableBinding("uniswap-v3-lp-token-id", p.tokenId)],
   };
 }
 
@@ -859,6 +862,7 @@ export async function buildUniswapCollect(
         amount1Max: "uint128.max",
       },
     },
+    durableBindings: [makeDurableBinding("uniswap-v3-lp-token-id", p.tokenId)],
   };
 }
 
@@ -922,6 +926,7 @@ export async function buildUniswapBurn(
       functionName: "burn",
       args: { tokenId: p.tokenId },
     },
+    durableBindings: [makeDurableBinding("uniswap-v3-lp-token-id", p.tokenId)],
   };
 }
 
@@ -1210,6 +1215,7 @@ export async function buildUniswapRebalance(
         slippageBps: String(slippageBps),
       },
     },
+    durableBindings: [makeDurableBinding("uniswap-v3-lp-token-id", p.tokenId)],
   };
 
   // Approvals — after collect routes the tokens back to the wallet, the

src/modules/morpho/actions.ts

@@ -4,6 +4,7 @@ import { getClient } from "../../data/rpc.js";
 import { CONTRACTS } from "../../config/contracts.js";
 import { buildApprovalTx, chainApproval, resolveApprovalCap } from "../shared/approval.js";
 import { resolveTokenMeta } from "../shared/token-meta.js";
+import { makeDurableBinding } from "../../security/durable-binding.js";
 import type {
   PrepareMorphoSupplyArgs,
   PrepareMorphoWithdrawArgs,
@@ -95,6 +96,7 @@ export async function buildMorphoSupply(p: PrepareMorphoSupplyArgs): Promise<Uns
       functionName: "supply",
       args: { marketId: p.marketId, amount: p.amount, onBehalf: wallet },
     },
+    durableBindings: [makeDurableBinding("morpho-blue-market-id", p.marketId)],
   };
   return chainApproval(approval, supplyTx);
 }
@@ -129,6 +131,7 @@ export async function buildMorphoWithdraw(p: PrepareMorphoWithdrawArgs): Promise
       functionName: "withdraw",
       args: { marketId: p.marketId, amount: p.amount, receiver: wallet },
     },
+    durableBindings: [makeDurableBinding("morpho-blue-market-id", p.marketId)],
   };
 }
 
@@ -154,6 +157,7 @@ export async function buildMorphoBorrow(p: PrepareMorphoBorrowArgs): Promise<Uns
       functionName: "borrow",
       args: { marketId: p.marketId, amount: p.amount, receiver: wallet },
     },
+    durableBindings: [makeDurableBinding("morpho-blue-market-id", p.marketId)],
   };
 }
 
@@ -252,6 +256,7 @@ export async function buildMorphoRepay(p: PrepareMorphoRepayArgs): Promise<Unsig
       functionName: "repay",
       args: { marketId: p.marketId, amount: displayAmount, onBehalf: wallet },
     },
+    durableBindings: [makeDurableBinding("morpho-blue-market-id", p.marketId)],
   };
   return chainApproval(approval, repayTx);
 }
@@ -296,6 +301,7 @@ export async function buildMorphoSupplyCollateral(
       functionName: "supplyCollateral",
       args: { marketId: p.marketId, amount: p.amount, onBehalf: wallet },
     },
+    durableBindings: [makeDurableBinding("morpho-blue-market-id", p.marketId)],
   };
   return chainApproval(approval, tx);
 }
@@ -329,5 +335,6 @@ export async function buildMorphoWithdrawCollateral(
       functionName: "withdrawCollateral",
       args: { marketId: p.marketId, amount: p.amount, receiver: wallet },
     },
+    durableBindings: [makeDurableBinding("morpho-blue-market-id", p.marketId)],
   };
 }

src/modules/solana/actions.ts

@@ -182,6 +182,15 @@ export interface PreparedSolanaTx {
   estimatedFeeLamports?: number;
   /** Surfaced on native_send / spl_send / nonce_close so the summary can show "Nonce: <addr>". */
   nonceAccount?: string;
+  /**
+   * Invariant #14 — durable-binding source-of-truth verification
+   * (issue #460). Populated by builders for ops that bind funds to a
+   * durable on-chain object selected from a multi-candidate set
+   * (validator vote pubkey, MarginFi bank). Absent for ops where the
+   * recipient/destination IS the durable identifier and Inv #1 already
+   * covers it.
+   */
+  durableBindings?: import("../../security/durable-binding.js").DurableBinding[];
 }
 
 /**

src/modules/solana/marginfi.ts

@@ -814,6 +814,12 @@ export interface PreparedMarginfiTx {
    * the real cost to the user BEFORE they blind-sign (issue #103).
    */
   rentLamports?: number;
+  /**
+   * Invariant #14 — bank pubkey on supply/withdraw/borrow/repay; absent
+   * on `marginfi_init` (no candidate-set selection — only one MarginfiAccount
+   * PDA per (wallet, group)). Issue #460.
+   */
+  durableBindings?: import("../../security/durable-binding.js").DurableBinding[];
 }
 
 export interface MarginfiInitParams {
@@ -1266,6 +1272,9 @@ async function wrapWithNonce(
   };
 
   const { handle } = issueSolanaDraftHandle(draft);
+  const { makeDurableBinding } = await import(
+    "../../security/durable-binding.js"
+  );
   return {
     handle,
     action: actionAction,
@@ -1275,6 +1284,9 @@ async function wrapWithNonce(
     decoded: draft.meta.decoded,
     nonceAccount: nonceAccountStr,
     marginfiAccount: marginfiAccountStr,
+    durableBindings: [
+      makeDurableBinding("marginfi-bank-pubkey", ctx.bank.address.toBase58()),
+    ],
   };
 }
 

src/modules/solana/native-stake.ts

@@ -102,6 +102,8 @@ export interface PreparedNativeStakeTx {
   rentLamports?: number;
   /** Stake account address — surfaced on delegate so the user can refer to it later. */
   stakeAccount?: string;
+  /** Invariant #14 — vote pubkey on delegate; absent on deactivate/withdraw (no candidate-set selection). Issue #460. */
+  durableBindings?: import("../../security/durable-binding.js").DurableBinding[];
 }
 
 const LAMPORTS_PER_SOL = 1_000_000_000;
@@ -265,6 +267,9 @@ export async function buildNativeStakeDelegate(
   });
 
   const { handle } = issueSolanaDraftHandle(draft);
+  const { makeDurableBinding } = await import(
+    "../../security/durable-binding.js"
+  );
   return {
     handle,
     action: "native_stake_delegate",
@@ -275,6 +280,9 @@ export async function buildNativeStakeDelegate(
     nonceAccount: ctx.noncePubkey.toBase58(),
     rentLamports,
     stakeAccount: stakePubkey.toBase58(),
+    durableBindings: [
+      makeDurableBinding("solana-validator-vote-pubkey", validatorPk.toBase58()),
+    ],
   };
 }
 

src/modules/tron/actions.ts

@@ -729,6 +729,9 @@ export async function buildTronVote(args: BuildTronVoteArgs): Promise<UnsignedTr
   });
   await assertBandwidthSufficient(args.from, res.raw_data_hex, apiKey);
 
+  const { makeDurableBinding } = await import(
+    "../../security/durable-binding.js"
+  );
   const tx: UnsignedTronTx = {
     chain: "tron",
     action: "vote",
@@ -745,6 +748,13 @@ export async function buildTronVote(args: BuildTronVoteArgs): Promise<UnsignedTr
         allocation: JSON.stringify(args.votes),
       },
     },
+    // Inv #14 — one binding per Super Representative the user is voting
+    // for. Empty `args.votes` (clear-all-votes) intentionally surfaces
+    // an empty array rather than absent so the skill can distinguish
+    // "clear" from "tool didn't emit bindings".
+    durableBindings: args.votes.map((v) =>
+      makeDurableBinding("tron-super-representative-address", v.address),
+    ),
   };
   return issueTronHandle(tx);
 }

src/security/durable-binding.ts

@@ -0,0 +1,96 @@
+/**
+ * Invariant #14 — durable-binding source-of-truth verification (issue
+ * #460). For any op that binds funds to a durable on-chain object
+ * selected from a multi-candidate set (validator pubkey, TRON Super
+ * Representative, Compound Comet, Morpho marketId, MarginFi bank, LP
+ * tokenId, BTC multisig xpub, allowance spender), the agent MUST
+ * source the candidate from an authority outside the MCP, surface it
+ * verbatim with provenance, and byte-equality-check the prepared
+ * bytes before signing.
+ *
+ * The MCP-side contribution to that defense: every prepare_* tool in
+ * an Inv #14 op class emits a structured `durableBindings: DurableBinding[]`
+ * field on its response. The skill consumes it as the assertion target —
+ * unambiguous, no parsing of the human-readable `decoded.args` text.
+ *
+ * Tools intentionally NOT covered:
+ *   - Plain native-coin sends — recipient is the durable object, but
+ *     it's already covered by Invariant #1 (recipient cross-check).
+ *   - Token sends — same; the recipient + the token contract are
+ *     covered by Inv #1 + Inv #11 today.
+ *   - Read-only tools — no bytes prepared, no Inv #14 surface.
+ */
+
+/**
+ * Closed enum of the durable-object kinds Invariant #14 covers. Add a
+ * new kind here only after wiring the corresponding prepare_* tool to
+ * emit it; the skill's match logic is keyed on these strings.
+ */
+export type DurableBindingKind =
+  | "solana-validator-vote-pubkey"
+  | "tron-super-representative-address"
+  | "compound-comet-address"
+  | "morpho-blue-market-id"
+  | "marginfi-bank-pubkey"
+  | "uniswap-v3-lp-token-id"
+  | "btc-multisig-cosigner-xpub"
+  | "approval-spender-address";
+
+export interface DurableBinding {
+  /** Stable kind discriminator the skill matches against. */
+  kind: DurableBindingKind;
+  /**
+   * Full identifier verbatim, no truncation. Format depends on the
+   * kind: base58 for Solana / TRON pubkeys, 0x-prefixed checksum hex
+   * for EVM addresses, decimal string for tokenIds, raw xpub string
+   * for BTC multisig cosigners, lowercase hex for Morpho marketIds.
+   */
+  identifier: string;
+  /**
+   * Free-form text suggesting where the user should re-verify
+   * externally. Per Inv #14, the user MUST source the candidate from
+   * an authority outside the MCP's enumeration; this hint nudges them
+   * at the right URL / app. Phrased as a recommendation, not a hard
+   * statement of trust — the agent renders it verbatim in the
+   * verification block.
+   */
+  provenanceHint: string;
+}
+
+/**
+ * Canonical provenance hints per kind. Centralized so every prepare
+ * tool emitting a given kind sends the user to the same external
+ * authority — surface drift between tools would erode the user's
+ * mental model of "for this kind, I look here".
+ */
+const PROVENANCE_HINTS: Record<DurableBindingKind, string> = {
+  "solana-validator-vote-pubkey":
+    "Re-verify on stakewiz.com or validators.app — confirm commission, delinquent flag, and that the vote pubkey matches the validator the user actually intends to delegate to.",
+  "tron-super-representative-address":
+    "Re-verify on tronscan.org/#/sr — confirm SR identity, ranking, and that the base58 address is the validator the user means (brand-name spoof / base58 confusable swap is the b044 attack class).",
+  "compound-comet-address":
+    "Re-verify on v3.compound.finance/markets — confirm the Comet address matches the (chain, base-asset) the user actually intends to interact with (wrong-Comet routing on the wrong asset is the b053 attack class).",
+  "morpho-blue-market-id":
+    "Re-verify on app.morpho.org/market/{id} — confirm collateral / loan-token / oracle / IRM / LLTV match the market the user means (b055 attack class: permissionless-market injection with adversarial parameters).",
+  "marginfi-bank-pubkey":
+    "Re-verify on app.marginfi.com — confirm bank is operational (not paused / killed-by-bankruptcy), oracle setup is healthy, and the asset matches the user's intent (b059 attack class: lookalike-bank injection).",
+  "uniswap-v3-lp-token-id":
+    "Re-verify on app.uniswap.org/positions/v3/<chain>/<tokenId> — confirm the position owner is your wallet, not an attacker-injected LP NFT enumerated into your portfolio (b063 attack class).",
+  "btc-multisig-cosigner-xpub":
+    "Re-verify each cosigner xpub against the origin device's backup card / set-up record — never trust an xpub passed to this tool through a third-party communication channel (b098 attack class: attacker xpub embedded as 'co-signer').",
+  "approval-spender-address":
+    "Re-verify on etherscan.io/address/<spender> — confirm the spender contract identity matches the protocol the user intends to grant allowance to (a086 / b118 attack class: reverse-revoke distraction).",
+};
+
+/**
+ * Build a `DurableBinding` with the canonical provenance hint for the
+ * given kind. Prepare tools call this rather than constructing the
+ * object literal so all kind ↔ hint pairings live in one place.
+ */
+export function makeDurableBinding(
+  kind: DurableBindingKind,
+  identifier: string,
+): DurableBinding {
+  const provenanceHint = PROVENANCE_HINTS[kind];
+  return { kind, identifier, provenanceHint };
+}