fix(keepkey-webusb): correct stalled-read recovery + time-bound USB transfers

[BitHighlander]

Summary

Two robustness fixes to the KeepKey WebUSB transports, surfaced by a Windows USB audit of keepkey-vault (companion PR #227). These address the "device froze / had to restart the app" class of Windows reports (distinct from the "device not detected" symptom, which is fixed app-side in the vault).

Commit 1 — clearHalt on the correct endpoint when a read stalls (both transports)

readChunk() reads the IN endpoint (transferIn), but on a "stall" status it called clearHalt("out", …) — the wrong endpoint and direction. On WinUSB a halted IN pipe is only resumed by resetting that same pipe, so the IN pipe stayed halted and every subsequent read re-stalled until a physical replug. It also fell through and returned the stalled transfer's empty/short buffer, which the framing parser then rejected as "message not valid".

Fix: clearHalt("in", …) on the pipe that actually stalled, and throw a retryable "bad read" instead of returning a non-packet. Applied to both hdwallet-keepkey-nodewebusb (Node/libusb) and hdwallet-keepkey-webusb (browser).

Commit 2 — time-bound USB transfers (hdwallet-keepkey-nodewebusb)

transferIn/transferOut were submitted with no timeout (libusb defaults to infinite). A device that stops responding — mid-reboot, suspended by Windows USB selective-suspend, or unplugged mid-write — left the promise pending forever, holding the claimed interface and producing a false ConflictingApp (LIBUSB code 19) on the next pair.

Fix: wrap each transfer in a timeout —

• writes: DEFAULT_TIMEOUT (5 s) — a write never legitimately blocks;
• reads: LONG_TIMEOUT (5 min) — a read may legitimately wait on a device button press (PIN, passphrase, tx/seed confirmation), so it must not be cut short.

On timeout we throw; the caller's existing disconnect path closes the device, which aborts the orphaned native transfer and releases the interface.

Scope / notes

• Read ceiling is LONG_TIMEOUT (5 min) because the transport can't see the per-call timeout — msgTimeout in hdwallet-keepkey is set but never plumbed down to readChunk. A follow-up could thread the call timeout through readChunk/writeChunk for tighter bounds on normal (non-button) operations. The current bound is strictly better than infinite and safe for all button flows.
• FIX-3 (timeouts) is applied to the Node transport (the one the desktop vault uses, where the Windows hangs were reported); the browser webusb transport gets the clearHalt fix only. The same timeout pattern could be mirrored there.
• Not built locally (no deps installed in the worktree), but the timeout helper mirrors the existing withTimeout pattern used in keepkey-vault, and core.DEFAULT_TIMEOUT/core.LONG_TIMEOUT are already used by hdwallet-keepkey/src/transport.ts.

Testing requested before merge

Exercise on real hardware on Windows: PIN entry, passphrase, a tx signing left to sit >60 s, and seed verification — confirm none time out — plus an unplug-mid-operation to confirm clean recovery (no false "device in use" on reconnect).

After merge, bump the modules/hdwallet submodule pointer in keepkey-vault.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hdwallet-sandbox	Ready	Preview, Comment	Jun 7, 2026 8:45pm

[BitHighlander]

Superseded by the focused, lower-risk split: #45 contains just the clearHalt IN/OUT correctness fix. The transfer-timeout half of this PR is deferred (it touches the shared transport more invasively and needs its own cross-platform validation); it can come back as a separate PR if/when Windows USB diagnostics confirm a real wedged-transfer problem. Closing to keep the correctness fix clean and independently reviewable.