Integrate Secure Hardware Wallet Support for Bitcoin Management

[jamespepper81]

Summary
Add support for secure hardware wallets (e.g., Ledger, Trezor, Coldcard, KeepKey) so that users can manage Bitcoin keys and sign transactions using a local hardware device rather than relying on software-only key storage.

Why this matters

• Hardware wallets provide significant security improvements by keeping private keys isolated from host systems.
• Supporting hardware wallets will increase trust and adoption among security-conscious users and organizations.
• Enables advanced workflows such as PSBT signing, descriptor-based wallets, and multisig with external signers.

Goals

• Detect and communicate with major hardware wallet vendors (Ledger, Trezor, Coldcard, KeepKey).
• Allow creating and importing descriptor-based accounts using hardware signers.
• Build a signing flow that supports PSBTs and offline signing (export/import) where direct USB is not possible.
• Provide a secure UI for device selection, fingerprinting, and signing with clear user prompts.
• Document supported devices, connection requirements (WebHID/WebUSB/HID), and UX limitations.

Non-goals

• Implementing support for every vendor immediately — start with Ledger and Trezor, add others iteratively.
• Replacing existing key management paradigms; hardware wallets are an additional option.

Acceptance Criteria

• The app can list available connected hardware wallets (at least Ledger + Trezor).
• The app can create a wallet/account tied to a hardware device (descriptor or xpub-derived flow).
• The app can prepare a PSBT and send it to the hardware device for signing (direct USB or via file for Coldcard).
• The app verifies device fingerprints (xpub/device attestation where available) and displays them to users.
• The UI clearly indicates when private keys remain on the hardware device and are not exportable.
• Automated and manual tests exist for the signing flow (including PSBT round-trip).
• Documentation and user guide added (how to connect, limitations, recommended firmware versions).
• Security review completed for the hardware interaction surface.

Implementation plan / suggested tasks

1. Research & prototype
   • Evaluate libraries: HWI (python), ledgerjs, trezor-connect, webhid/webusb integrations.
   • Pick an initial integration approach (e.g., ledgerjs + trezor-connect WebUSB/WebHID paths).
2. Device detection & connection
   • Implement device detection module with capability matrix (vendor, model, connection type).
   • UI component: device chooser with vendor icons and last-used preference.
3. Account creation & xpub handling
   • Support descriptor creation from device-derived xpubs.
   • Persist descriptors and device metadata (fingerprint, derivation path) in wallet metadata.
4. PSBT signing flow
   • Generate PSBTs from prepared transactions.
   • Send PSBT to device for signing; handle asynchronous responses and errors.
   • Support offline signing via export/import PSBT (file or QR).
5. UX & security messaging
   • Add clear messaging that keys never leave the hardware device.
   • Show device fingerprint / xpub fingerprint for verification.
   • Provide guidance for troubleshooting (permissions, firmware).
6. Testing & CI
   • Automated tests that mock device responses.
   • Manual test checklist for human QA across devices.
7. Docs & release notes
   • Add a user-facing docs page with device compatibility, connection steps, and known issues.

Security considerations

• Do not persist private keys or sensitive device secrets in application storage.
• Validate device attestation data where available (e.g., Ledger/Trezor attestation APIs).
• Harden the PSBT passing mechanism against tampering: display exact transaction details on device and in-app before signing.
• Minimize privileged browser APIs and request only necessary permissions (WebHID/WebUSB).
• Consider privacy leakage: connecting devices may create fingerprinting signals — document and minimize.

UX considerations

• Clear modal flow for connection, signing, and error recovery.
• Timeouts and retry logic for flaky USB connections.
• Option to “remember this device for this wallet” (store only non-secret metadata).
• Fallback path: PSBT file export/import or QR for fully air-gapped signing (Coldcard-style).

Testing strategy

• Unit tests for device-selection logic and PSBT assembly.
• Integration tests using emulators or test frameworks (e.g., trezor emulator, simulated ledger).
• Manual tests on physical devices across OS (Windows/macOS/Linux) and browsers that support required APIs.
• Security/pen-test focused test cases for replay, tampering, and UI spoofing.

Dependencies & references

• ledgerjs: https://github.com/LedgerHQ/ledgerjs
• trezor-connect: https://github.com/trezor/connect
• HWI (for reference / CLI usage): https://github.com/bitcoin-core/HWI
• PSBT spec: BIP-174
• Descriptor wallets: BIP-32 / BIP-44 descriptors

Suggested labels

• enhancement
• security
• feature/hardware-wallet
• high priority (optional)

Suggested estimate

• M (4–8 sprints depending on number of devices and QA)