@vurto/sign-tx 0.1.0-stage.1

package/README.md

@@ -0,0 +1,142 @@
+# @vurto/sign-tx
+
+Local browser-signer CLI for the Vurto AnA MCP hard-wallet flow.
+
+Your AI agent never sees your private key. When an MCP tool prepares a transaction (supply, repay, withdraw, borrow, swap, zap, …), it returns the calldata plus a short summary. Pipe that into `sign-tx`, and this CLI spins up a **single-use local page on `127.0.0.1`** that connects to your MetaMask / Rabby / Ledger / Trezor and asks **you** to sign. The transaction hash is printed to stdout so the agent can pick it back up and continue the workflow.
+
+The page works fully offline from Vurto's network — every asset is inlined, the Content-Security-Policy denies all external loads.
+
+## Install
+
+```bash
+npm install -g @vurto/sign-tx
+```
+
+You can also run it ad hoc without installing:
+
+```bash
+npx @vurto/sign-tx --tx '<json>'
+```
+
+## Quick start
+
+```bash
+sign-tx --tx '{
+  "txData": {
+    "to": "0xA238Dd80C259a72e81d7e4664a9801593F98d1c5",
+    "data": "0x617ba037...",
+    "chainId": 8453,
+    "value": "0x0"
+  },
+  "summary": {
+    "action": "supply",
+    "humanDescription": "Supply 100 USDC on Base to Aave V3"
+  },
+  "walletAddress": "0xYourWalletHere",
+  "transactionId": 17
+}'
+```
+
+What happens:
+
+1. `sign-tx` binds an HTTP server on `127.0.0.1` (free port chosen by the OS).
+2. The system browser opens the signer page.
+3. You connect MetaMask / Rabby (the page validates wallet and chain).
+4. You inspect the decoded calldata, gas estimate, and destination contract.
+5. You click **Sign** (or **Reject**).
+6. `sign-tx` prints the result JSON to stdout and exits.
+
+### Result on stdout
+
+```json
+{
+  "txHash": "0xabc...",
+  "from": "0xYour...",
+  "chainId": 8453,
+  "signedAt": "2026-05-27T12:34:56.000Z"
+}
+```
+
+### Exit codes
+
+| Code | Meaning                                    |
+|------|--------------------------------------------|
+| 0    | Transaction signed and broadcast            |
+| 1    | User rejected the request                   |
+| 2    | Timed out waiting for approval              |
+| 3    | Validation error (bad flags or bad JSON)    |
+
+## Flags
+
+| Flag                  | Default | Description |
+|-----------------------|---------|-------------|
+| `--tx <json>`         | —       | Inline JSON payload. Required unless you pipe via stdin. |
+| `--port <n>`          | `0`     | TCP port on `127.0.0.1`. `0` = OS picks a free port. |
+| `--no-open`           | off     | Do not auto-open the browser; just print the URL on stderr. |
+| `--timeout <seconds>` | `180`   | Approval timeout. After this, the CLI exits with code 2. |
+| `--report-to <url>`   | —       | Optional HTTPS endpoint to POST the result to (e.g. an MCP webhook). |
+| `--help`              | —       | Print help. |
+| `--version`           | —       | Print version. |
+
+You can also pipe the JSON instead of using `--tx`:
+
+```bash
+cat tx.json | sign-tx --no-open
+```
+
+## Safety mitigations
+
+- **127.0.0.1 only.** The HTTP server never binds to a public interface.
+- **Single-use session.** A random session token is required for `POST /result`. After a result is delivered, every route returns 410 Gone.
+- **Strict CSP.** `default-src 'none'`; scripts and styles whitelisted by nonce; no external loads possible. No cross-origin frames, no form submissions.
+- **Allow-list of destinations.** Vurto Dual-Aave Adapter, Aave V3 Pool, ParaSwap Augustus V6.2 and TokenTransferProxy across 9 chains. Unknown destinations show a red banner; you can still sign, but only after acknowledging it.
+- **Wallet match.** The connected `eth_accounts[0]` must equal the expected `walletAddress`. Sign is disabled otherwise.
+- **Chain match.** The wallet's current `chainId` must equal the payload's `chainId`. `sign-tx` triggers `wallet_switchEthereumChain` automatically; if you reject the switch, Sign stays disabled.
+- **Unlimited-approval guard.** `approve(spender, MAX_UINT256)` (or any amount > 1B raw units of a known stablecoin) shows a red card with the spender address and forces you to tick "I understand I'm approving an unlimited amount of {TOKEN}" before Sign enables.
+- **Decoded calldata first, raw second.** The page leads with the human-readable summary and decoded named parameters. The raw `to`/`data`/`value` triplet lives behind a collapsible.
+
+## Sigstore verification
+
+Releases are signed with [sigstore/cosign](https://docs.sigstore.dev/). To verify a published tarball:
+
+```bash
+# Download the tarball + bundle from the GitHub release page, then:
+cosign verify-blob \
+  --bundle vurto-sign-tx-0.1.0.tgz.sigstore \
+  --certificate-identity-regexp 'https://github\.com/vurto-cc/vurto-a/\.github/workflows/.*' \
+  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
+  vurto-sign-tx-0.1.0.tgz
+```
+
+A successful verify means the tarball was built by the canonical GitHub Actions workflow in `vurto-cc/vurto-a` — no human can sneak in a malicious build.
+
+## Dev usage from a checkout
+
+If you're hacking on this CLI inside the `vurto-a` repo:
+
+```bash
+cd tools/sign-cli
+npm install
+node bin/sign-tx.js --help
+node --test tests/
+```
+
+A handy smoke test (will time out after 5s with exit code 2):
+
+```bash
+node bin/sign-tx.js --tx '{
+  "txData": {
+    "to": "0xA238Dd80C259a72e81d7e4664a9801593F98d1c5",
+    "data": "0x617ba037000000000000000000000000af88d065e77c8cc2239327c5edb3a432268e58310000000000000000000000000000000000000000000000000000000005f5e1000000000000000000000000001234567890123456789012345678901234567890000000000000000000000000000000000000000000000000000000000000000a",
+    "chainId": 42161,
+    "value": "0x0"
+  },
+  "summary": { "action": "supply", "humanDescription": "Supply 100 USDC on Arbitrum to Aave V3" },
+  "walletAddress": "0x1234567890123456789012345678901234567890",
+  "transactionId": 1
+}' --no-open --timeout 5
+```
+
+## License
+
+MIT.

package/bin/sign-tx.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+
+run(process.argv.slice(2)).then((code) => {
+  process.exit(code);
+}).catch((err) => {
+  process.stderr.write(`sign-tx: fatal: ${err?.stack || err?.message || String(err)}\n`);
+  process.exit(3);
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@vurto/sign-tx",
+  "version": "0.1.0-stage.1",
+  "description": "Vurto AnA local browser-signer CLI: opens a single-use page on 127.0.0.1 that lets you sign a prepared transaction with MetaMask/Rabby and returns the tx hash to stdout.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "sign-tx": "./bin/sign-tx.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test tests/",
+    "check": "node --check bin/sign-tx.js"
+  },
+  "dependencies": {
+    "ethers": "^6.13.0"
+  },
+  "keywords": [
+    "vurto",
+    "aave",
+    "ana",
+    "mcp",
+    "signer",
+    "ethereum",
+    "metamask",
+    "rabby",
+    "hardware-wallet"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vurto-cc/vurto-a.git",
+    "directory": "tools/sign-cli"
+  },
+  "homepage": "https://vurto.cc"
+}

package/src/cli.js

@@ -0,0 +1,238 @@
+import { startSignerServer } from './server.js';
+import { openBrowser } from './openBrowser.js';
+
+const USAGE = `@vurto/sign-tx — sign a prepared transaction in your local browser with MetaMask/Rabby.
+
+USAGE
+  sign-tx --tx '<json>' [options]
+  echo '<json>' | sign-tx [options]
+
+OPTIONS
+  --tx <json>            Inline transaction payload (JSON). If omitted, read from stdin.
+  --port <number>        TCP port to bind on 127.0.0.1 (default: 0 = OS-assigned).
+  --no-open              Do not auto-open the system browser; just print the URL.
+  --timeout <seconds>    Approval timeout in seconds (default: 180).
+  --report-to <url>      Optional HTTPS endpoint that receives a POST with the result.
+  --version              Print version and exit.
+  --help                 Print this help and exit.
+
+EXIT CODES
+  0  transaction signed and broadcast
+  1  user rejected
+  2  timeout
+  3  validation error
+
+EXAMPLES
+  sign-tx --tx "$(cat tx.json)"
+  cat tx.json | sign-tx --no-open --timeout 60
+`;
+
+export function parseArgs(argv) {
+  const out = {
+    tx: null,
+    port: 0,
+    open: true,
+    timeout: 180,
+    reportTo: null,
+    help: false,
+    version: false,
+  };
+  const errors = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case '--help':
+      case '-h':
+        out.help = true;
+        break;
+      case '--version':
+      case '-v':
+        out.version = true;
+        break;
+      case '--no-open':
+        out.open = false;
+        break;
+      case '--tx': {
+        const v = argv[++i];
+        if (v === undefined) { errors.push('--tx requires a JSON string argument'); break; }
+        out.tx = v;
+        break;
+      }
+      case '--port': {
+        const v = argv[++i];
+        const n = Number(v);
+        if (!Number.isInteger(n) || n < 0 || n > 65535) {
+          errors.push(`--port must be an integer 0..65535 (got: ${v})`);
+        } else {
+          out.port = n;
+        }
+        break;
+      }
+      case '--timeout': {
+        const v = argv[++i];
+        const n = Number(v);
+        if (!Number.isFinite(n) || n <= 0 || n > 3600) {
+          errors.push(`--timeout must be a number 1..3600 seconds (got: ${v})`);
+        } else {
+          out.timeout = n;
+        }
+        break;
+      }
+      case '--report-to': {
+        const v = argv[++i];
+        if (v === undefined) { errors.push('--report-to requires a URL argument'); break; }
+        if (!/^https?:\/\//i.test(v)) {
+          errors.push(`--report-to must be an http(s) URL (got: ${v})`);
+        } else {
+          out.reportTo = v;
+        }
+        break;
+      }
+      default:
+        if (a.startsWith('--')) errors.push(`unknown option: ${a}`);
+        else errors.push(`unexpected positional argument: ${a}`);
+    }
+  }
+
+  return { opts: out, errors };
+}
+
+const TX_HASH_RE = /^0x[0-9a-f]{64}$/i;
+const ADDR_RE = /^0x[0-9a-fA-F]{40}$/;
+const HEX_RE = /^0x[0-9a-fA-F]*$/;
+
+export function validatePayload(payload) {
+  const errors = [];
+  if (!payload || typeof payload !== 'object') {
+    return ['payload must be a JSON object'];
+  }
+  const { txData, summary, walletAddress, transactionId } = payload;
+  if (!txData || typeof txData !== 'object') errors.push('payload.txData is required');
+  else {
+    if (!ADDR_RE.test(String(txData.to || ''))) errors.push('payload.txData.to must be a 0x-prefixed 40-hex address');
+    if (typeof txData.data !== 'string' || !HEX_RE.test(txData.data)) errors.push('payload.txData.data must be a hex string');
+    if (!Number.isInteger(txData.chainId) || txData.chainId <= 0) errors.push('payload.txData.chainId must be a positive integer');
+    if (txData.value !== undefined && typeof txData.value !== 'string') errors.push('payload.txData.value must be a hex string when present');
+  }
+  if (!summary || typeof summary !== 'object') errors.push('payload.summary is required');
+  else if (typeof summary.humanDescription !== 'string' || !summary.humanDescription.trim()) {
+    errors.push('payload.summary.humanDescription must be a non-empty string');
+  }
+  if (!ADDR_RE.test(String(walletAddress || ''))) errors.push('payload.walletAddress must be a 0x-prefixed 40-hex address');
+  if (transactionId !== undefined && transactionId !== null && !(typeof transactionId === 'string' || Number.isFinite(transactionId))) {
+    errors.push('payload.transactionId must be a string or number when present');
+  }
+  return errors;
+}
+
+async function readStdin() {
+  if (process.stdin.isTTY) return '';
+  return await new Promise((resolve, reject) => {
+    let buf = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { buf += chunk; });
+    process.stdin.on('end', () => resolve(buf));
+    process.stdin.on('error', reject);
+  });
+}
+
+export async function run(argv, deps = {}) {
+  const stdout = deps.stdout || process.stdout;
+  const stderr = deps.stderr || process.stderr;
+  const startServerFn = deps.startSignerServer || startSignerServer;
+  const openBrowserFn = deps.openBrowser || openBrowser;
+  const readStdinFn = deps.readStdin || readStdin;
+
+  const { opts, errors } = parseArgs(argv);
+  if (errors.length) {
+    for (const e of errors) stderr.write(`sign-tx: ${e}\n`);
+    stderr.write(`\n${USAGE}`);
+    return 3;
+  }
+  if (opts.help) { stdout.write(USAGE); return 0; }
+  if (opts.version) {
+    stdout.write(`@vurto/sign-tx 0.1.0-stage.1\n`);
+    return 0;
+  }
+
+  let txJson = opts.tx;
+  if (!txJson) txJson = (await readStdinFn()).trim();
+  if (!txJson) {
+    stderr.write('sign-tx: missing --tx and no stdin input\n');
+    stderr.write(`\n${USAGE}`);
+    return 3;
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(txJson);
+  } catch (e) {
+    stderr.write(`sign-tx: invalid JSON payload: ${e.message}\n`);
+    return 3;
+  }
+
+  const validation = validatePayload(payload);
+  if (validation.length) {
+    for (const v of validation) stderr.write(`sign-tx: ${v}\n`);
+    return 3;
+  }
+
+  const result = await startServerFn({
+    payload,
+    port: opts.port,
+    timeoutMs: opts.timeout * 1000,
+    onListen: ({ url }) => {
+      stderr.write(`sign-tx: signer ready at ${url}\n`);
+      stderr.write(`sign-tx: waiting up to ${opts.timeout}s for approval...\n`);
+      if (opts.open) {
+        openBrowserFn(url).catch((e) => {
+          stderr.write(`sign-tx: could not auto-open browser (${e.message}); paste the URL manually\n`);
+        });
+      }
+    },
+  });
+
+  if (opts.reportTo && (result.kind === 'signed' || result.kind === 'rejected')) {
+    try {
+      await fetch(opts.reportTo, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          transactionId: payload.transactionId ?? null,
+          result,
+        }),
+      });
+    } catch (e) {
+      stderr.write(`sign-tx: --report-to delivery failed: ${e.message}\n`);
+    }
+  }
+
+  switch (result.kind) {
+    case 'signed': {
+      if (!TX_HASH_RE.test(result.txHash || '')) {
+        stderr.write('sign-tx: signer returned malformed txHash\n');
+        return 3;
+      }
+      stdout.write(JSON.stringify({
+        txHash: result.txHash,
+        from: result.from,
+        chainId: payload.txData.chainId,
+        signedAt: result.signedAt,
+      }) + '\n');
+      return 0;
+    }
+    case 'rejected':
+      stderr.write('sign-tx: user rejected the transaction\n');
+      return 1;
+    case 'timeout':
+      stderr.write('sign-tx: timed out waiting for approval\n');
+      return 2;
+    case 'error':
+      stderr.write(`sign-tx: ${result.message}\n`);
+      return 3;
+    default:
+      stderr.write(`sign-tx: unexpected signer result\n`);
+      return 3;
+  }
+}

package/src/contractAllowList.js

@@ -0,0 +1,94 @@
+const CHAINS = Object.freeze({
+  1:        { name: 'Ethereum',    explorer: 'https://etherscan.io',          symbol: 'ETH' },
+  10:       { name: 'Optimism',    explorer: 'https://optimistic.etherscan.io', symbol: 'ETH' },
+  56:       { name: 'BNB Chain',   explorer: 'https://bscscan.com',           symbol: 'BNB' },
+  100:      { name: 'Gnosis',      explorer: 'https://gnosisscan.io',         symbol: 'xDAI' },
+  137:      { name: 'Polygon',     explorer: 'https://polygonscan.com',       symbol: 'POL' },
+  146:      { name: 'Sonic',       explorer: 'https://sonicscan.org',         symbol: 'S' },
+  8453:     { name: 'Base',        explorer: 'https://basescan.org',          symbol: 'ETH' },
+  42161:    { name: 'Arbitrum',    explorer: 'https://arbiscan.io',           symbol: 'ETH' },
+  43114:    { name: 'Avalanche',   explorer: 'https://snowtrace.io',          symbol: 'AVAX' },
+});
+
+const AAVE_V3_POOL = {
+  1:     '0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2',
+  10:    '0x794a61358D6845594F94dc1DB02A252b5b4814aD',
+  56:    '0x6807dc923806fE8Fd134338EABCA509979a7e0cB',
+  100:   '0xb50201558B00496A145fE76f7424749556E326D8',
+  137:   '0x794a61358D6845594F94dc1DB02A252b5b4814aD',
+  146:   '0x5362dBb1e601abF3a4c14c22ffEdA64042E5eAA3',
+  8453:  '0xA238Dd80C259a72e81d7e4664a9801593F98d1c5',
+  42161: '0x794a61358D6845594F94dc1DB02A252b5b4814aD',
+  43114: '0x794a61358D6845594F94dc1DB02A252b5b4814aD',
+};
+
+const VURTO_DUAL_AAVE_ADAPTER = {
+  1:     '0x7014309A43860dcEDdC0Ae2cDbDCE16F724e10Da',
+  56:    '0x7014309A43860dcEDdC0Ae2cDbDCE16F724e10Da',
+  100:   '0x7014309A43860dcEDdC0Ae2cDbDCE16F724e10Da',
+  137:   '0x9cCc0B9e7F36c0ae5b95f6d9C522c74f789A0035',
+  8453:  '0x009D3f5c5cee523D9005125E2e0EE51878eff21F',
+  42161: '0x9397a49Ee8b4E7B71d38f920fb9F1c8E1b1F4d11',
+};
+
+const PARASWAP_AUGUSTUS_V6_2 = {
+  1:     '0x6A000F20005980200259B80c5102003040001068',
+  10:    '0x6A000F20005980200259B80c5102003040001068',
+  56:    '0x6A000F20005980200259B80c5102003040001068',
+  137:   '0x6A000F20005980200259B80c5102003040001068',
+  8453:  '0x6A000F20005980200259B80c5102003040001068',
+  42161: '0x6A000F20005980200259B80c5102003040001068',
+  43114: '0x6A000F20005980200259B80c5102003040001068',
+};
+
+const PARASWAP_TOKEN_TRANSFER_PROXY = {
+  1:     '0x6A0009d27Ee0d1A6c8aabb27DDE7e83C5d7C20fF',
+  10:    '0x6A0009d27Ee0d1A6c8aabb27DDE7e83C5d7C20fF',
+  56:    '0x6A0009d27Ee0d1A6c8aabb27DDE7e83C5d7C20fF',
+  137:   '0x6A0009d27Ee0d1A6c8aabb27DDE7e83C5d7C20fF',
+  8453:  '0x6A0009d27Ee0d1A6c8aabb27DDE7e83C5d7C20fF',
+  42161: '0x6A0009d27Ee0d1A6c8aabb27DDE7e83C5d7C20fF',
+  43114: '0x6A0009d27Ee0d1A6c8aabb27DDE7e83C5d7C20fF',
+};
+
+function lower(addr) {
+  return String(addr || '').toLowerCase();
+}
+
+function buildAllowMap() {
+  const out = new Map();
+  const add = (chainId, addr, name, category) => {
+    if (!addr) return;
+    const key = `${chainId}:${lower(addr)}`;
+    out.set(key, { chainId, address: addr, name, category });
+  };
+  for (const [chainId, addr] of Object.entries(AAVE_V3_POOL)) add(Number(chainId), addr, `Aave V3 Pool (${CHAINS[chainId]?.name || `chain ${chainId}`})`, 'aave-pool');
+  for (const [chainId, addr] of Object.entries(VURTO_DUAL_AAVE_ADAPTER)) add(Number(chainId), addr, `Vurto Dual-Aave Adapter (${CHAINS[chainId]?.name || `chain ${chainId}`})`, 'vurto-adapter');
+  for (const [chainId, addr] of Object.entries(PARASWAP_AUGUSTUS_V6_2)) add(Number(chainId), addr, `ParaSwap Augustus V6.2 (${CHAINS[chainId]?.name || `chain ${chainId}`})`, 'paraswap-router');
+  for (const [chainId, addr] of Object.entries(PARASWAP_TOKEN_TRANSFER_PROXY)) add(Number(chainId), addr, `ParaSwap TokenTransferProxy (${CHAINS[chainId]?.name || `chain ${chainId}`})`, 'paraswap-proxy');
+  return out;
+}
+
+const ALLOW_MAP = buildAllowMap();
+
+export function lookupContract(chainId, address) {
+  if (!Number.isInteger(Number(chainId)) || typeof address !== 'string') return null;
+  return ALLOW_MAP.get(`${Number(chainId)}:${lower(address)}`) || null;
+}
+
+export function getChainInfo(chainId) {
+  return CHAINS[Number(chainId)] || null;
+}
+
+export function isErc20Selector(data) {
+  if (typeof data !== 'string' || data.length < 10) return null;
+  const sel = data.slice(0, 10).toLowerCase();
+  if (sel === '0x095ea7b3') return 'approve';
+  if (sel === '0xa9059cbb') return 'transfer';
+  if (sel === '0x23b872dd') return 'transferFrom';
+  return null;
+}
+
+export function snapshotAllowList() {
+  return Array.from(ALLOW_MAP.values());
+}