fix(mcp): bridge follow-ups from #109 review — smoke-script auth, MV3 heartbeat, pending-key collisions

[BitHighlander]

Follow-ups from the review of #109 (merged). All client-side; the tool contract is unchanged.

Fixes

1. Smoke script could never pass (must-fix). scripts/test-mcp-bridge.mjs sent no Authorization header, but the merged vault (#360) runs auth.requireAuth on POST /mcp — every run failed. It now sends Bearer $KEEPKEY_API_KEY, fails fast with guidance when unset, and names the cause on a 401. (Node's fetch sends no Origin/Sec-Fetch-Site, which is what passes the vault's browser-exclusion check.)

2. MV3 heartbeat. Chrome evicts an idle service worker after ~30s, and an idle WebSocket does not prevent that — only WS traffic resets the timer. Without a ping the worker dies on a quiet machine, takes the socket with it, and nothing wakes it back up: an agent polling bex_status would see bridge: "down" indefinitely. A 20s ping keeps us inside the window; the vault ignores frames matching no pending call, so no server-side change.

3. clip() could throw on the success path. It runs on every provider call's result, so a BigInt/circular JSON.stringify failure would have turned a good wallet response into a dApp-visible error. Now returns '[unserializable]'.

4. Approval queue keyed by dApp-supplied id. dApp ids are per-page counters, so two tabs collide on 1: one settle evicted the other tab's entry. Read-only today, but a Phase-2 bex_approve_request(id) would have resolved the wrong origin's prompt — fixed now, before the control tools land on top of it. The queue is keyed by an internal uuid; id is retained for correlating with dApp logs.

5. Agent path init parity. walletRequest re-checks init after ensureStarted() like WALLET_REQUEST does, so a vault-closed agent call gets the actionable "launch the Vault" error.

Verification

make test 111 pass (providerLog 5 → 8: adds same-id two-tab isolation + the unserializable-payload regression). make type-check 15/15, make build green.

Live run against the vault, with a real pairing key — the fixed script doing what it could not do before:

ok: initialize returns keepkey-vault serverInfo
ok: tools/list includes bex_status / bex_accounts / bex_pending_requests / bex_connected_sites / bex_logs
ok: bex_status reports bridge state truthfully
bex_status → { bridge: 'down', connected: false, error: '...is the BEX running with Agent mode enabled?' }
exit=2

Auth, the tool catalog, and bex_status's truthful bridge-down reporting are all confirmed. The last mile still needs a human: flip "Enable Agent mode" in the extension options, reload the extension from this branch's dist/, then re-run for exit 0 — that also exercises the heartbeat and bex_accounts.

KEEPKEY_API_KEY=<pairing key> node scripts/test-mcp-bridge.mjs

Related — a vault-side bug this surfaced

Sending the bearer surfaced a real vault bug: /mcp cannot return its 401 at all. auth.requireAuth (rest-api.ts:1305) throws outside the try at :1420 that maps HttpError → status, and Bun.serve has no top-level error handler, so the throw escapes fetch() and the caller gets a dropped socket instead of a 401.

Independent of this PR (nothing here depends on it), but it's what makes a misconfigured key report 401 rather than an inscrutable fetch failed. Written up for the vault owners in HANDOFF_vault_mcp_401.md on this branch.

🤖 Generated with Claude Code