feat (wallet): web app handoff for signing (#96)

Author: zerts

CONTEXT.md

@@ -0,0 +1,55 @@
+# Zerion CLI
+
+Command-line interface for AI agents to analyze wallets and trade on-chain. Builds transactions locally and (today) signs them with a local keystore. An in-progress experiment moves **transaction signing** out of the CLI and into the Zerion web app.
+
+## Language
+
+**Transaction signing**:
+The act of turning a fully-formed unsigned transaction into a signed, broadcast, confirmed on-chain transaction. Covers `send`, `swap`, `bridge`, `consolidate`.
+_Avoid_: "signing" unqualified — the CLI also does **message signing**, which is out of scope for the web-app handoff.
+
+**Message signing**:
+Off-chain signing: EIP-191 / EIP-712 (`wallet sign-message`, `wallet sign-typed-data`) on EVM, and raw ed25519 message signing (`wallet sign-message --chain solana`) on Solana. Local by default; routes to the **web-app handoff** via the message link contract when the wallet is read-only or `--review` is passed. EVM hands off an EIP-191/EIP-712 request; Solana hands off a raw-bytes request (`kind: "solanaMessage"`). EIP-712 typed data stays EVM-only (Solana has no typed-data equivalent).
+
+**Web-app handoff**:
+The flow where, instead of signing locally, the CLI builds a fully-formed signing request (a transaction bundle or an EIP-191/EIP-712 message), encodes it into a web-app link, opens the browser, and waits for a localhost callback with the result.
+
+**Signing route**:
+The per-request decision between **local signing** and the **web-app handoff**. Production model: local signing is the default; the handoff fires when a trigger hits (read-only wallet, USD value above the wallet's threshold, or an explicit force flag). One routing function shared by `send`/`swap`/`bridge` (`decideSigningRoute`); a value-less sibling for messages (`decideMessageSigningRoute` — read-only and `--review` triggers only, since review thresholds are USD amounts and messages have no sell-side value).
+
+**Read-only wallet**:
+A first-class saved wallet ("my wallet") that has **no secret material** — just a name + address in a dedicated registry (not the OWS keystore, not the watchlist). Created with `zerion wallet add <address|ens|solana-pubkey> --name <name>` (EVM 0x, ENS resolved once at add time, or base58 Solana pubkey). The stored address's ecosystem fixes which chains it can sign for — an EVM read-only wallet refuses `--chain solana` and vice versa. Appears in `wallet list`; read commands work normally; **transaction signing and message signing always route to the web-app handoff**; key-requiring commands (export-key, backup) error clearly.
+_Distinct from_: **watch entry** — a watchlist address used only for tracking/lookups, never a wallet.
+
+**Review threshold**:
+A per-wallet USD amount; any transaction whose value exceeds it routes to the **web-app handoff** instead of auto-signing. Set with `zerion wallet set-review-threshold <wallet> <usd|off>`; stored as a `reviewThresholds` map in `~/.zerion/config.json` (same pattern as `walletOrigins`). Unset/`off` = always auto-sign.
+Valuation: **sell-side value, per bundle** — send = amount × token price; swap/bridge = the quote's sell-side USD; an approve inherits its bundle's value; gas never counts. Prices come from `market_data.price` via `getFungible`. **No price ⇒ fail closed** (route to review with a stderr note).
+
+**Link contract**:
+The URL shapes the web app owns. Transactions: `https://<host>/cli/transaction?address=<signer>#tx=<base64url(deflateRaw(JSON.stringify(payload)))>`; each `transactions[]` entry carries either `{ evm: TransactionEVM, label? }` (EVM) or `{ solana: { raw: <base64 unsigned tx> }, label? }` (Solana). Messages: `https://<host>/cli/message?address=<signer>#msg=<same codec>`, whose payload carries exactly one **message request** — `{ kind: "personal", raw: <0x-hex bytes>, display?: <utf8 text>, chainId }` for EIP-191, `{ kind: "typedData", typedData: {domain,types,primaryType,message}, chainId }` for EIP-712, or `{ kind: "solanaMessage", raw: <0x-hex bytes>, display? }` for Solana (raw ed25519, no chainId). The `address` query param is a 0x address for EVM and a base58 pubkey for Solana. The CLI is the producer of these links; the web app is the consumer.
+
+**Callback**:
+A fire-and-forget `POST http://127.0.0.1:<port>/` the web app sends back with signing progress/result (`signed` / `completed` / `rejected` / `failed`; the message handoff has no `signed` progress event, and its `completed` carries `signature` instead of `hashes`).
+Production hardening (decided 2026-07-03): the payload carries a **one-time nonce** the web app must echo in every callback POST — events without it are ignored; and on `completed` the CLI **verifies each reported hash on-chain** before reporting success (trust-but-verify).
+
+## Relationships
+
+- A **web-app handoff** replaces **transaction signing**'s local sign+broadcast+wait step; the CLI still builds the fully-formed transaction bundle.
+- A **link contract** carries 1–N transactions (all same chain) or exactly one message request, plus an optional **callback** port.
+- **Message signing** uses the same handoff machinery (shared callback listener, one-time token, browser open) via the `/cli/message` link; its trust-but-verify step validates the returned **signature** against the signer address instead of checking hashes on-chain — viem `verifyMessage`/`verifyTypedData` (EOA + ERC-1271) for EVM, ed25519 verify for Solana.
+- The handoff's **callback path is ecosystem-agnostic**: on-chain hash checks and signature verification are supplied by the caller as an injected `client` (viem for EVM; a Solana adapter from `chain/solana-handoff.js` — `solanaReceiptAdapter` maps a returned signature to success/reverted via `getSignatureStatuses`, `solanaMessageVerifier` checks the ed25519 signature). `handoff.js` itself imports no chain SDK.
+
+## Notes
+
+- The **link contract**'s EVM transaction is the Zerion API's hex-string `TransactionEVM` shape (not viem's BigInt shape). The CLI fills `nonce` + `gas` but leaves `maxFee`/`maxPriorityFee`/`gasPrice` **null** — the connected wallet in the web app estimates fees at sign time.
+- The signer named in the link is the CLI's own resolved wallet address; the human connects a wallet controlling that address in the browser.
+- **Callback port** is ephemeral (`listen(0)`), read back, and baked into `payload.port` before the browser opens. Server binds `127.0.0.1` only, no auth token (localhost dev experiment). Terminal events `completed`/`rejected`/`failed` resolve & exit (0 / non-zero); `signed` is stderr progress. Default wait timeout 5 min (`--timeout`).
+- **Browser open** is best-effort per-platform `child_process` (no new dep); the URL is always printed to stderr so headless/agent environments can open it manually.
+- **Web-app base URL**: `ZERION_WEB_APP_BASE` env → config `webAppBase` → default `https://app.zerion.io`; path `/cli/transaction` is constant.
+- On the handoff path the CLI **does not** require the agent token / passphrase (no keystore unlock), but **still** runs `enforceExecutablePolicies` as a pre-filter.
+- **Production gating** (decided 2026-07-03): all pre-sign checks — balance gates (native + ERC-20), `quote.blocking`, `enforceExecutablePolicies` — run on **both** signing routes before a link is formed or a tx is signed. Only `requireAgentToken` is local-route-only.
+- **Policy-script path check escape hatch**: `ZERION_UNSAFE_POLICY_PATHS=1` (env var only, never persisted) skips the `POLICIES_DIR` containment check in `enforceExecutablePolicies`, printing a loud stderr warning on every run where it's active. Debug-only.
+- The experiment's **hard-replace** at the sign call sites (local code commented with `RESTORE:` markers) is temporary; production restores local signing behind the **signing route** decision.
+- **Bypass paths refuse**: commands that cannot hand off (`consolidate`) exit with a clear error when the wallet is read-only or the value exceeds its **review threshold** — the guardrail never downgrades to a warning. (Solana `swap`/`bridge`/`send` and message signing now hand off — see below.)
+- **Message signing via web app** (WLT-1687, implemented 2026-07-08): `sign-message`/`sign-typed-data` route through `decideMessageSigningRoute` — read-only wallet or `--review` hands off via the `/cli/message` link, everything else signs locally. On the handoff path no agent token is required; the returned signature is verified against the signer address when a verifier is available (fails on definite mismatch, warns-and-accepts when verification can't run). `export-key`/`backup` on a **read-only wallet** still error clearly (no key material).
+- **Solana handoff** (implemented 2026-07-08): `swap`/`bridge`/`send` on Solana and `sign-message --chain solana` now hand off to the web app on the same triggers as EVM (read-only wallet, `--review`, value over threshold). Transactions carry the API's unsigned base64 tx (`transaction_swap.solana.raw`) or, for native `send`, a locally-built unsigned transfer (`buildUnsignedSolanaTransfer`, balance-gated); the connected Solana wallet signs + broadcasts and returns the signature as a `hashes` entry, verified via `getSignatureStatuses`. Solana messages sign the raw bytes with ed25519, verified by pubkey. **Read-only Solana wallets** are now first-class (base58 address). EIP-712 typed data and `consolidate` remain EVM-only.

cli/commands/trading/bridge.js

@@ -1,6 +1,9 @@
-import { getSwapOffers, pickOffer, isQuoteExecutable, executeSwap } from "../../utils/trading/swap.js";
+import { getSwapOffers, pickOffer, isQuoteExecutable, executeSwap, executeViaWebApp } from "../../utils/trading/swap.js";
 import { requireAgentToken, parseTimeout, parseSlippage, handleTradingError } from "../../utils/trading/guards.js";
 import { resolveWallet, resolveDestination } from "../../utils/wallet/resolve.js";
+import { reportHandoff } from "../../utils/web-app/handoff.js";
+import { decideSigningRoute } from "../../utils/trading/signing-route.js";
+import { bundleSellUsd } from "../../utils/trading/valuation.js";
 import { print, printError } from "../../utils/common/output.js";
 import { formatBridgeOffers } from "../../utils/common/format.js";
 import { validateTradingChainAsync } from "../../utils/common/validate.js";
@@ -195,6 +198,7 @@ export default async function bridge(args, flags) {
   }
 
   try {
+    // Balance precondition gate — runs regardless of signing route.
     if (quote.preconditions.enough_balance === false) {
       printError("insufficient_funds", `Insufficient ${quote.from.symbol} balance`, {
         suggestion: `Fund your wallet: zerion wallet fund --wallet ${walletName}`,
@@ -220,18 +224,26 @@ export default async function bridge(args, flags) {
       },
     };
 
-    const passphrase = await requireAgentToken("for trading", walletName);
     const timeout = parseTimeout(flags.timeout);
-    const result = await executeSwap(quote, walletName, passphrase, { timeout });
 
+    // Sell-side USD value drives routing (bridge = inputAmount × price(from)).
+    const usdValue = await bundleSellUsd({ fungibleId: quote.from.fungibleId, amount });
+    const { route, reason } = decideSigningRoute({ walletName, force: flags.review, usdValue });
+    process.stderr.write(`Signing route: ${route} — ${reason}.\n`);
+
+    if (route === "web-app") {
+      const result = await executeViaWebApp(quote, { address, timeout, isBridge: true });
+      reportHandoff(quoteSummary, result);
+      return;
+    }
+
+    // Local route — unlock the keystore, sign/broadcast, poll bridge delivery.
+    const passphrase = await requireAgentToken("for trading", walletName);
+    const result = await executeSwap(quote, walletName, passphrase, { timeout });
     print({
       ...quoteSummary,
-      tx: {
-        hash: result.hash,
-        status: result.status,
-        blockNumber: result.blockNumber,
-        gasUsed: result.gasUsed,
-      },
+      signedVia: "local",
+      tx: { hash: result.hash, status: result.status, blockNumber: result.blockNumber, gasUsed: result.gasUsed },
       bridgeDelivery: result.bridgeDelivery,
       executed: true,
     });

cli/commands/trading/send.js

@@ -4,14 +4,17 @@ import { requireAgentToken, parseTimeout, handleTradingError, enforceExecutableP
 import * as api from "../../utils/api/client.js";
 import { getPublicClient, broadcastAndWait, signAndSerialize } from "../../utils/trading/transaction.js";
 import { resolveWallet } from "../../utils/wallet/resolve.js";
+import { toTransactionEVM, toSolanaTransaction, signViaWebApp, reportHandoff } from "../../utils/web-app/handoff.js";
+import { decideSigningRoute } from "../../utils/trading/signing-route.js";
+import { bundleSellUsd } from "../../utils/trading/valuation.js";
 import { print, printError } from "../../utils/common/output.js";
 import { getConfigValue } from "../../utils/config.js";
-import { getEvmAddress } from "../../utils/wallet/keystore.js";
 import { NATIVE_ASSET_ADDRESS } from "../../utils/common/constants.js";
 import { formatSwapQuote } from "../../utils/common/format.js";
 import { validateTradingChainAsync } from "../../utils/common/validate.js";
 import { isSolana } from "../../utils/chain/registry.js";
 import { sendSolanaNative } from "../../utils/chain/solana-send.js";
+import { buildUnsignedSolanaTransfer, solanaReceiptAdapter } from "../../utils/chain/solana-handoff.js";
 
 const ERC20_TRANSFER_ABI = parseAbi([
   "function transfer(address to, uint256 amount) returns (bool)",
@@ -114,18 +117,18 @@ export default async function send(args, flags) {
       },
     };
 
-    // Agent token required — no interactive passphrase for trading
-    const passphrase = await requireAgentToken("for trading", walletName);
-
     const client = await getPublicClient(chain);
-    const walletAddress = getEvmAddress(walletName);
+    // resolveWallet already returned the wallet's EVM address; use it directly
+    // so read-only wallets (no keystore entry) resolve too.
+    const walletAddress = address;
 
     const [nonce, feeData] = await Promise.all([
       client.getTransactionCount({ address: walletAddress, blockTag: "pending" }),
       client.estimateFeesPerGas(),
     ]);
 
-    // Balance check: prevent broadcasting doomed transactions (include gas cost for native)
+    // Native balance gate — must cover amount + estimated gas. Runs regardless
+    // of signing route (defense in depth ahead of the human review).
     const balance = await client.getBalance({ address: walletAddress });
     const estimatedGasCost = 21000n * (feeData.maxFeePerGas || 0n);
     if (isNative && balance < amountParsed + estimatedGasCost) {
@@ -139,6 +142,8 @@ export default async function send(args, flags) {
     const baseTx = {
       type: "eip1559",
       chainId: client.chain.id,
+      // Fees are set for the local sign path; toTransactionEVM drops them for
+      // the web-app handoff (the connected wallet re-estimates at sign time).
       maxFeePerGas: feeData.maxFeePerGas,
       maxPriorityFeePerGas: feeData.maxPriorityFeePerGas,
       nonce,
@@ -158,7 +163,7 @@ export default async function send(args, flags) {
         process.exit(1);
       }
 
-      // ERC-20 balance check before broadcast
+      // ERC-20 balance gate.
       try {
         const tokenBalance = await client.readContract({
           address: tokenAddress,
@@ -187,19 +192,37 @@ export default async function send(args, flags) {
       tx = { ...baseTx, to: tokenAddress, value: 0n, data, gas };
     }
 
-    await enforceExecutablePolicies({ to: tx.to, value: tx.value, data: tx.data });
-    const signedTxHex = await signAndSerialize(tx, chain, walletName, passphrase);
+    // Policy pre-filter — runs on BOTH signing routes, before a link is formed
+    // or a tx is signed.
+    await enforceExecutablePolicies({ to: tx.to, value: tx.value, data: tx.data, chain });
+
     const timeout = parseTimeout(flags.timeout);
-    const result = await broadcastAndWait(client, signedTxHex, { timeout });
 
+    // Sell-side USD value drives the routing decision (send = amount × price).
+    const usdValue = await bundleSellUsd({ fungibleId: resolved.fungibleId, amount });
+    const { route, reason } = decideSigningRoute({ walletName, force: flags.review, usdValue });
+    process.stderr.write(`Signing route: ${route} — ${reason}.\n`);
+
+    if (route === "web-app") {
+      const evm = toTransactionEVM(tx, { chainIdNum: client.chain.id, from: walletAddress });
+      const result = await signViaWebApp({
+        address: walletAddress,
+        transactions: [{ evm, label: `Send ${amount} ${resolved.symbol}` }],
+        timeout,
+        client,
+      });
+      reportHandoff(summary, result);
+      return;
+    }
+
+    // Local route — unlock the keystore, sign, broadcast, wait for receipt.
+    const passphrase = await requireAgentToken("for trading", walletName);
+    const signedTxHex = await signAndSerialize(tx, chain, walletName, passphrase);
+    const result = await broadcastAndWait(client, signedTxHex, { timeout });
     print({
       ...summary,
-      tx: {
-        hash: result.hash,
-        status: result.status,
-        blockNumber: result.blockNumber,
-        gasUsed: result.gasUsed,
-      },
+      signedVia: "local",
+      tx: { hash: result.hash, status: result.status, blockNumber: result.blockNumber, gasUsed: result.gasUsed },
       executed: true,
     }, formatSwapQuote);
   } catch (err) {
@@ -227,7 +250,48 @@ async function sendOnSolana({ token, amount, to, flags }) {
     process.exit(1);
   }
 
+  const summary = {
+    send: {
+      token: "SOL",
+      amount,
+      from: address,
+      to,
+      chain: "solana",
+      type: "native",
+    },
+  };
+
   try {
+    const timeout = parseTimeout(flags.timeout);
+
+    // Sell-side USD value drives routing (send = amount × price(SOL)). Resolve
+    // SOL's fungible id best-effort; if it's unavailable the router fail-closes
+    // to review when a threshold is set.
+    let fungibleId = null;
+    try {
+      fungibleId = (await resolveToken("SOL", "solana")).fungibleId;
+    } catch {
+      // no id → usdValue null → router fail-closes under a threshold
+    }
+    const usdValue = await bundleSellUsd({ fungibleId, amount });
+    const { route, reason } = decideSigningRoute({ walletName, force: flags.review, usdValue });
+    process.stderr.write(`Signing route: ${route} — ${reason}.\n`);
+
+    if (route === "web-app") {
+      // Build the unsigned transfer (balance-gated) and hand it to the web app;
+      // the connected Solana wallet signs and broadcasts.
+      const { raw } = await buildUnsignedSolanaTransfer({ from: address, to, amountSol: amount });
+      const result = await signViaWebApp({
+        address,
+        transactions: [{ solana: toSolanaTransaction(raw), label: `Send ${amount} SOL` }],
+        timeout,
+        client: solanaReceiptAdapter(),
+      });
+      reportHandoff(summary, result);
+      return;
+    }
+
+    // Local route — unlock the keystore, sign, broadcast, confirm.
     const passphrase = await requireAgentToken("for trading", walletName);
     const result = await sendSolanaNative({
       from: address,
@@ -238,14 +302,8 @@ async function sendOnSolana({ token, amount, to, flags }) {
     });
 
     print({
-      send: {
-        token: "SOL",
-        amount,
-        from: address,
-        to,
-        chain: "solana",
-        type: "native",
-      },
+      ...summary,
+      signedVia: "local",
       tx: {
         hash: result.hash,
         status: result.status,