fix(keepkey): validate Features version fields in initialize() before semver

[BitHighlander]

Summary

KeepKeyHDWallet.initialize() constructs the firmware version string from the protobuf Features response and immediately passes it to semver.gte() to populate the coin-support feature flags:

const fwVersion = `v${out.majorVersion}.${out.minorVersion}.${out.patchVersion}`;
this._supportsOsmosis = semver.gte(fwVersion, "v7.7.0");

If any of majorVersion / minorVersion / patchVersion are undefined (wrong-message-type miscast, decode mismatch, device in an unexpected state, etc.), the code happily produces:

vundefined.undefined.undefined

…and semver.gte() then throws the opaque error:

Invalid Version: vundefined.undefined.undefined

This bubbles up through pairRawDevice() with no actionable diagnostic, which has been observed leaking from the WebUSB pair path in KeepKey Vault on Windows as a silent splash hang on first launch — there's no clue in the engine log that the failure is a malformed Features response.

Fix

Add a guard in initialize() that validates the three version fields are numbers before constructing fwVersion. On failure, throw a clear runtime error that names the missing fields:

KeepKey Initialize returned Features without firmware version (major=undefined, minor=undefined, patch=undefined). Device may be in bootloader mode, mid-update, or returned an unexpected message type.

Consumers (KeepKey Vault engine controller, etc.) can now recognize this failure mode and surface a meaningful UI state instead of crashing or hanging.

Tests

New file packages/hdwallet-keepkey/src/keepkey-initialize.test.ts with 4 tests:

1. Throws clear error when Features has no version fields
2. Throws when only majorVersion is missing
3. Does not throw the validation error when all version fields are present
4. Regression: never produces Invalid Version: vundefined.undefined.undefined

The tests use a hand-rolled mock transport (call, getDeviceID, keyring.addAlias, debugLink) — no USB hardware required.

Verified locally

Step	Result
yarn build (tsc --build)	clean
New tests against unfixed code	3 fail with "Invalid Version: vundefined.undefined.undefined" (exact match for the original bug string)
New tests against fixed code	4/4 pass
Full hdwallet-keepkey suite	13/13 pass (9 baseline + 4 new)
yarn lint:ts (tsc --noEmit)	clean

Scope

Strictly defensive — no behavioral change for any code path where the device returns a properly populated Features. The fix only affects the previously-undiagnosable vundefined.undefined.undefined failure mode.

Test plan

• Unit tests pass (yarn jest --testPathPattern keepkey-initialize)
• Existing tests still pass (yarn jest --testPathPattern hdwallet-keepkey)
• TypeScript typecheck clean (yarn lint:ts)
• Reviewer: skim the new error message wording for consistency with project tone

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hdwallet-sandbox	Ready	Preview, Comment	Apr 8, 2026 10:38pm