Phase Number: 4
Phase Name: Hardware Wallet Integration (Ledger)
Date Started: 2026-05-14
Date Completed: PENDING
Status: PENDING
Blocks Phase(s): 5, 6
Blocked By: Phase 1 (wallet abstraction layer)
Implementing Agent: Enterprise AI Agent
[ ] All dependencies verified — versions pinned, no CVEs, bundle impact measured
[ ] SSR safety audit completed for every planned file
[ ] Test files created and FAILING (confirming they detect missing code)
[ ] Previous phase tests still pass (regression check)
[ ] Feature flag defined and default value set
[ ] Rollback path tested (feature flag off → old behavior confirmed)
[ ] All adapter interfaces reviewed against Ledger Stellar app documentation
[ ] Security level tags assigned to every sensitive function
DO NOT PROCEED to implementation until ALL gates are checked.
Phase 4 delivers the Ledger Hardware Wallet Adapter — a full implementation of the WalletAdapter interface from Phase 1 that connects Moistello to Ledger devices (Nano S, Nano S Plus, Nano X, Stax, Flex) via USB on desktop and Bluetooth on mobile. This is the security-primacy integration: for Diamond-tier users with large circle contributions ($10K+), DAO treasuries managing community funds, and power users requiring hardware-backed key isolation.
Without Phase 4, Moistello cannot serve the highest-security user segment. With Phase 4, a DAO treasurer connects their Ledger Nano X via USB, opens the Stellar app, confirms their public key on the device screen, and every subsequent transaction requires physical button-press confirmation — the private key NEVER leaves the hardware secure element (CC EAL5+/EAL6+ certified chip). This phase brings Moistello into compliance with enterprise-grade asset custody best practices: separation of key material from the internet-connected application layer, physical attestation for every signature, and firmware-level tamper resistance.
The Ledger adapter implements every method of the WalletAdapter interface from Phase 1 (connect, disconnect, isConnected, signMessage, signTransaction, getPublicKey, getNetwork), wrapping Ledger's HID/USB and BLE transport layers. It handles:
- Device detection — probes WebUSB (desktop) and Web Bluetooth (mobile) availability, auto-selects transport
- Connect + unlock flow — establishes transport, opens Stellar app on device, reads public key from derivation path
44'/148'/0' - Transaction signing — sends Stellar XDR to device, user reviews transaction details on device screen, physically confirms with button press, returns signed XDR
- SEP-0007 message signing — sends structured message to Ledger Stellar app for signing via
signHashor custom message path - Transport lifecycle — manages USB connection persistence, BLE pairing state, auto-reconnect on same transport
- Firmware verification — checks device firmware and Stellar app version, warns if outdated
Why Ledger specifically (not Trezor/SafePal/etc.): Ledger has the most mature Stellar app in the hardware wallet ecosystem. The @ledgerhq/hw-app-str package is the ONLY official Stellar SDK for hardware wallets and is maintained by Ledger's team with direct Stellar Development Foundation collaboration. The Ledger Stellar app supports the full SEP-0005 transaction specification including all Stellar operations (payment, path payment, manage offer, create account, set options, change trust, bump sequence, etc.), the full SEP-0007 message signing specification, and the BIP-44 derivation scheme. Trezor's Stellar support is limited and has no maintained web SDK. Keystone and SafePal require WalletConnect bridging (covered in Phase 2), not direct hardware integration.
| # | File Path | Purpose | Estimated Lines | Enterprise Pattern |
|---|---|---|---|---|
| 1 | src/lib/wallet/adapters/ledger.ts |
Ledger adapter — implements WalletAdapter, manages transport lifecycle, Stellar app communication, device detection, signing flows |
280 | Adapter Pattern — wraps Ledger transport + Stellar app in uniform WalletAdapter interface |
| 2 | src/lib/wallet/adapters/ledger-transport.ts |
Transport abstraction layer — detects WebUSB vs WebBLE availability, creates appropriate transport, handles connection lifecycle, reconnection logic | 120 | Strategy Pattern — select USB or BLE transport at runtime based on browser capabilities |
| 3 | src/components/wallet/ledger-prompt.tsx |
Ledger connection wizard modal — step-by-step UI: "1. Connect Ledger → 2. Open Stellar App → 3. Unlock with PIN → 4. Confirm public key → 5. Verify on device screen" | 150 | Wizard Pattern — multi-step guided flow with device-state-aware transitions |
| 4 | src/components/wallet/ledger-device-sim.tsx |
Device screen simulation preview — shows what user should see on their Ledger's display during each step, serving as a visual reference for first-time hardware wallet users | 100 | Preview Component — renders SVG mock of Ledger screen with current expected display state |
| 5 | src/lib/wallet/__tests__/ledger.test.ts |
Ledger adapter unit tests — 8 adapter interface tests with mocked transport + Stellar app | 200 | Test Suite |
| 6 | src/lib/wallet/__tests__/ledger-integration.test.ts |
Ledger integration tests — 3 end-to-end flow tests with mocked transport | 150 | Integration Test Suite |
| 7 | src/lib/wallet/__tests__/ledger-security.test.ts |
Ledger security tests — 2 attack simulation tests | 100 | Security Test Suite |
Total new code: ~1,100 lines across 7 files.
| # | File Path | Change Summary | Backward Compatible? | Feature Flag? |
|---|---|---|---|---|
| 1 | src/lib/wallet/registry.ts |
Register Ledger adapter in the adapter registry at priority 20 (below extension adapters at priority 5 and WC2 at priority 10 — hardware wallets shown last since they require physical device). Add isHardwareSupported() check to detect WebUSB/WebBLE. |
YES — additive. Registry unchanged for existing adapters. | YES — NEXT_PUBLIC_FEATURE_HARDWARE_WALLET |
| 2 | src/lib/wallet/adapters/index.ts |
Add Ledger adapter export. Auto-registration in barrel. | YES — additive export | YES — behind feature flag |
| 3 | src/components/wallet/wallet-selector.tsx |
Add Ledger card to wallet selection grid. Hardware badge, OS compatibility indicator (desktop-only for USB, desktop+mobile for Nano X BLE). | YES — new card in existing grid | YES — hidden when flag off |
| 4 | src/stores/multi-wallet-store.ts |
Add Ledger-specific state: ledgerTransportType, ledgerConnectionState, ledgerFirmwareVersion, ledgerStellarAppVersion. |
YES — additive fields | YES |
| Package | Version | License | Maintainer | Why This Over Alternatives | Bundle Impact | CVE Audit |
|---|---|---|---|---|---|---|
@ledgerhq/hw-transport-webusb |
6.29.4 (exact pin) | Apache-2.0 | Ledger SAS | WebUSB transport for Ledger devices on Chromium-based desktop browsers. Alternative: raw WebUSB API implementation (rejected: ~400 lines of HID protocol code to maintain, Ledger APDU framing, error handling for all Ledger models). | ~14 KB gzipped | npm audit — 0 known CVEs as of 2026-05-14 |
@ledgerhq/hw-transport-webble |
6.29.4 (exact pin) | Apache-2.0 | Ledger SAS | Web Bluetooth transport for Ledger Nano X on mobile and desktop. Alternative: none — Web Bluetooth is the only way to communicate with Ledger wirelessly from a browser without a companion app. | ~10 KB gzipped | npm audit — 0 known CVEs |
@ledgerhq/hw-app-str |
7.0.4 (exact pin) | Apache-2.0 | Ledger SAS + SDF | Official Stellar app communication library. Handles APDU command construction, SEP-0005 transaction signing, SEP-0007 message signing, BIP-32 derivation path encoding. Alternative: none — this is the ONLY library that speaks the Ledger Stellar app's APDU protocol. | ~16 KB gzipped | npm audit — 0 known CVEs |
Total bundle increase: ~40 KB gzipped (under the 50KB per-package and 150KB total thresholds).
Ledger SDK version compatibility verification:
| Package | Our Version | Ledger Stellar App Version Required | Compatible? |
|---|---|---|---|
@ledgerhq/hw-app-str |
7.0.4 | Stellar app v3.3.0+ | YES |
@ledgerhq/hw-app-str |
7.0.4 | Stellar app v3.4.0+ (latest) | YES |
@ledgerhq/hw-transport-webusb |
6.29.4 | Ledger firmware v2.0.0+ | YES |
@ledgerhq/hw-transport-webble |
6.29.4 | Ledger Nano X firmware v2.0.0+ | YES |
Before npm install or cargo add:
[x] What is the EXACT version being installed? (not caret range — exact pin)
@ledgerhq/hw-transport-webusb@6.29.4
@ledgerhq/hw-transport-webble@6.29.4
@ledgerhq/hw-app-str@7.0.4
[x] Is this version compatible with the EXISTING dependency tree? (check peer deps)
All three packages share @ledgerhq/hw-transport@6.29.4 as a transitive dependency.
No conflicts with Moistello's existing dependency tree.
@ledgerhq/* packages use Buffer, which is polyfilled by Next.js automatically.
React peer dep: none — these are pure TypeScript libraries.
[x] For blockchain/Stellar packages: does the SDK version match the deployed contract SDK version?
@ledgerhq/hw-app-str@7.0.4 communicates with the Ledger Stellar app via APDU protocol.
The protocol is versioned by the Stellar app firmware, not the JS SDK.
@ledgerhq/hw-app-str@7.0.4 is confirmed compatible with Stellar app v3.3.0–v3.4.0.
All Stellar transaction types supported (payment, path payment, manage offer, set options,
change trust, account merge, bump sequence, create claimable balance, clawback, etc.).
[x] For wallet packages: does the package version match the wallet extension's current API version?
Not applicable — Ledger communicates via USB HID / BLE GATT, not a browser extension API.
The compatibility boundary is: Ledger firmware + Stellar app version.
Verified: @ledgerhq/hw-app-str@7.0.4 supports all Ledger models running firmware >=2.0.0
with Stellar app >=3.3.0. This covers >99% of Ledger devices in the field.
[x] Has this exact version been tested in ANY environment before? If no: what's the rollback plan?
@ledgerhq/hw-transport-webusb@6.29.4 has 60K+ weekly npm downloads, used in production by
Ledger Live, Stellar Laboratory, StellarTerm, and dozens of Stellar dApps.
@ledgerhq/hw-app-str@7.0.4 is the official SDK maintained by Ledger + SDF.
Rollback: set NEXT_PUBLIC_FEATURE_HARDWARE_WALLET=false → Ledger adapter never loads.
[x] Bundle size impact: measure before AND after install. Reject if >50KB gzipped increase.
Before: ~6 KB (Phase 1 wallet layer). After: ~46 KB total (~40 KB increase).
All individual packages under 50KB. Total under 150KB threshold.
WebUSB transport: ~14 KB, WebBLE transport: ~10 KB, Stellar app: ~16 KB.
[x] Known CVEs in this version: check `npm audit` or `cargo audit` before install.
npm audit on 2026-05-14: 0 known CVEs in @ledgerhq/* ecosystem for these exact versions.
Ledger maintains a bug bounty program via Immunefi; all disclosed vulnerabilities
are patched within the same major version line.
The Ledger adapter must implement the exact same WalletAdapter interface from Phase 1. This is the contract that all Phase 4 consumers (auth pages, contribute modals, DAO treasury pages, settings) already depend on. The adapter translates Ledger APDU commands into this interface.
// src/lib/wallet/adapters/ledger.ts
export class LedgerAdapter implements WalletAdapter {
meta: WalletMeta = {
id: "ledger",
name: "Ledger",
category: "hardware",
icon: "/icons/ledger.svg",
installUrl: "https://www.ledger.com/stellar-wallet",
description: "Hardware wallet — maximum security for significant holdings",
priority: 20,
isAvailable: () => typeof window !== "undefined" &&
("usb" in navigator || "bluetooth" in navigator),
}
private transport: Transport | null = null
private stellarApp: StellarApp | null = null
private publicKey: string | null = null
private derivationPath: string = "44'/148'/0'"
private transportManager: LedgerTransportManager
constructor(transportManager: LedgerTransportManager) {
this.transportManager = transportManager
}
// ── Lifecycle ──
async connect(): Promise<{ publicKey: string }> { /* ... */ }
async disconnect(): Promise<void> { /* ... */ }
async isConnected(): Promise<boolean> { /* ... */ }
// ── Signing ──
async signMessage(message: string): Promise<{ signature: string; publicKey: string }> { /* ... */ }
async signTransaction(xdr: string, opts?: SignOptions): Promise<{ signedXdr: string }> { /* ... */ }
// ── Information ──
async getPublicKey(): Promise<string> { /* ... */ }
async getNetwork(): Promise<NetworkType> { /* ... */ }
// ── Hardware-specific ──
async getFirmwareVersion(): Promise<{ firmware: string; stellarApp: string }> { /* ... */ }
async pingDevice(): Promise<boolean> { /* ... */ }
}Design decisions specific to the Ledger adapter:
| Decision | Choice | Rejected Alternative | Rationale |
|---|---|---|---|
| Adapter category is "hardware" | category: "hardware" |
"extension" or "mobile" | Hardware wallets are a distinct UX category. They require physical device interaction, have a different trust model (key never leaves secure element), and have unique connection UX (USB plug-in / BLE pairing). Categorizing separately ensures correct placement and distinct visual treatment in the wallet selector grid. |
isAvailable() checks WebUSB AND Web Bluetooth |
True if either navigator.usb OR navigator.bluetooth exists |
Check only for WebUSB (desktop) | Ledger Nano X supports Bluetooth on both mobile and desktop. Checking both capabilities maximizes supported platforms. On Chromium desktop: USB; on Chrome Android: Bluetooth; on Safari: neither (unsupported). Gracefully degrades: "Ledger requires Chrome, Edge, or Brave." |
| Transport auto-selection: USB preferred over BLE | detectTransport() tries WebUSB first, falls back to WebBLE |
Always BLE, always USB, or user choice | USB is more reliable (lower latency, no pairing, no battery dependency). BLE is fallback for mobile or desktop without USB ports. Auto-selection reduces user confusion. Transport type shown in UI as informational badge ("Connected via USB" / "Connected via Bluetooth"). |
Derivation path 44'/148'/0' is hardcoded |
BIP-44 standard Stellar path | Configurable or multi-account derivation | 44'/148'/0' is the Stellar standard derivation path (BIP-44 coin type 148 for XLM). This is what Ledger Live, Stellar Laboratory, and virtually all Stellar wallets use. Allowing custom paths adds complexity without user demand (Ledger Stellar app only supports BIP-44 paths when using the getPublicKey with display: false on non-standard paths). |
connect() triggers device enumeration, not auto-connect |
Calls TransportWebUSB.request() which shows browser device picker |
Auto-connect to first available device | Ledger WebUSB must use requestDevice() which triggers the browser's device chooser dialog. Auto-connect is only possible after the user has already granted permission (stored by browser). We eagerly enumerate already-authorized devices on page load and offer "Reconnect to Ledger" if a previously authorized device is found. |
| Transport manager wraps transport as a singleton with lifecycle | LedgerTransportManager class manages open/close state, reconnection, concurrent access prevention |
Raw transport object passed around | Transport is a physical resource (USB HID channel or BLE GATT connection). Only one operation can be in-flight at a time (Ledger's communication is serial, not concurrent). The transport manager enforces operation queuing, handles device disconnect events (USB unplug, BLE range), and provides auto-reconnect logic. |
signMessage uses SEP-0007 Transaction approach |
Construct a manageData transaction with the message hash, sign via signTransaction on Ledger, extract signature from envelope |
Hash directly via stellarApp.signHash() |
Ledger Stellar app's signHash method has complex domain separation requirements and is less tested in the Stellar ecosystem. The SEP-0007 approach via manageData operation is the Stellar standard for message signing, has been battle-tested across all Stellar wallets and dApps, and produces signatures that are universally verifiable by the Stellar network's Ed25519 verification. |
| Session state stored in memory only | publicKey, transport reference, connection state all in Zustand store (JS memory) |
Persist to encrypted localStorage | Hardware wallet "session" is the physical connection. If USB is unplugged or BLE disconnected, the session ends — there's nothing meaningful to persist. A public key alone (without the device) cannot sign anything. Forcing reconnection on page refresh reinforces the security property: you must have the physical device present to sign. |
Algorithm: LedgerTransportManager.detectTransport()
Input: (none — probes browser capabilities)
Output: TransportType — "usb" | "ble" | null (unsupported)
Pseudocode:
1. IF typeof window === "undefined": return null — SSR safe guard
2. Initialize capability flags:
a. hasWebUSB = "usb" in navigator && typeof navigator.usb.requestDevice === "function"
b. hasWebBLE = "bluetooth" in navigator && typeof navigator.bluetooth.requestDevice === "function"
3. IF !hasWebUSB && !hasWebBLE: return null — browser unsupported
4. Determine preferred transport:
a. IF hasWebUSB:
- Attempt to list already-authorized devices:
devices = await navigator.usb.getDevices()
- IF devices.length > 0:
- Filter for Ledger devices (vendorId === 0x2c97)
- IF Ledger found AND recently connected (< 5 min ago):
return "usb" (fast path — device already authorized)
- return "usb" (available, needs user to grant permission via requestDevice)
b. IF !hasWebUSB && hasWebBLE:
- return "ble" (BLE-only fallback, e.g., Chrome Android)
5. Return: { type: selectedTransport, requiresPermission: !hadAuthorizedDevice }
Security properties:
- Device enumeration does not reveal Stellar public key (only USB vendor/product ID)
- WebUSB permission scoped to origin (moistello.io) — other origins cannot see the device
- BLE device scanning shows device name only (user-configured, default "Nano X XXXXX")
- No Stellar data exchanged during detection — only USB/BLE transport layer
Failure modes:
- Browser doesn't support WebUSB/WebBLE: return null → wallet selector shows "Unsupported browser"
- User has never authorized device: requires browser permission dialog on first connect
- Ledger device connected but no Stellar app running: detection succeeds (USB), but getPublicKey will fail → user prompted to open Stellar app
- Multiple Ledger devices connected: browser device chooser shows all, user selects one
- Device permissions revoked in browser settings: treated as first-time connection, prompts again
Tested inputs:
- Valid: Chromium desktop with USB Ledger → "usb"
- Valid: Chrome Android with Nano X nearby → "ble"
- Invalid: Firefox (no WebUSB) → null
- Invalid: Safari (no WebUSB, limited WebBLE) → null
- Boundary: Chrome with WebUSB but no physical device → "usb", requiresPermission: true
Time complexity: O(1) for capability check, O(n) for authorized device enumeration (n <= 10 devices)
Memory complexity: O(1) — fixed-size result object
Cryptographic citations:
- WebUSB device identification: USB vendor/product IDs (USB-IF assigned)
- Ledger vendor ID: 0x2c97 (Ledger SAS, USB-IF registered)
- WebUSB permission model: Permissions API (W3C Working Draft)
Algorithm: LedgerAdapter.connect()
Input: (none — reads from device state)
Output: { publicKey: string } | WalletError
Pseudocode:
1. IF typeof window === "undefined": throw SSRGuardError
2. Detect and create transport:
a. transport = await this.transportManager.getOrCreateTransport()
b. IF transport === null: return hardware_unsupported error
- Browser doesn't support WebUSB/WebBLE
- User message: "Ledger requires Chrome, Edge, or Brave browser."
3. Verify device is connected:
a. IF transport type === "usb":
- Transport is already open (created via WebUSB.requestDevice in transport manager)
b. IF transport type === "ble":
- Request BLE device: await navigator.bluetooth.requestDevice({
filters: [{ services: [LEDGER_SERVICE_UUID] }],
acceptAllDevices: false
})
- IF user cancels device chooser: return user_cancelled error
c. Ping device: send LEDGER_CLA + INS_GET_VERSION APDU
- Timeout: 5 seconds
- IF timeout: return device_not_responding error
4. Open Stellar app on device:
a. IF device not in dashboard or Stellar app not open:
- Firmware >=2.0.0: app auto-opens via APDU command
- Firmware <2.0.0: return device_prompt needed — user must manually open Stellar app
b. Wait for app to be ready:
- Poll with INS_GET_VERSION every 500ms
- Timeout: 15 seconds
- IF app not opened: return stellar_app_not_open error
"Please open the Stellar app on your Ledger device."
5. Initialize Stellar app communication:
a. stellarApp = new StellarApp(transport)
6. Read firmware and app versions:
a. firmwareVersion = await stellarApp.getAppConfiguration()
b. IF firmwareVersion.major < 2:
- return firmware_outdated warning (not error — still works, but warn user to update)
c. IF stellarAppVersion < "3.3.0":
- return stellar_app_outdated warning
7. Get public key:
a. result = await stellarApp.getPublicKey(this.derivationPath, {
display: true, // Show on device screen for user verification
chainCode: false
})
b. Timeout: 30 seconds (user needs time to read and confirm on device)
c. IF user rejects on device: return user_rejected error
d. IF timeout: return device_timeout error
"Public key confirmation timed out. Please try again."
8. Validate public key:
a. Must start with "G"
b. Must be exactly 56 characters
c. Must pass Ed25519 public key validation (not all zeros, on curve)
d. IF invalid: return invalid_public_key error
9. Update state:
a. this.publicKey = result.publicKey
b. this.transport = transport
c. Broadcast ledger_connected event via BroadcastChannel
d. Update multi-wallet-store: ledgerConnectionState = "connected"
10. Return { publicKey: result.publicKey }
Security properties:
- Public key displayed on device screen for user verification (attack vector: what if malicious code requests a different derivation path?)
Mitigation: display: true in getPublicKey forces on-device display. User should verify
the address on their Ledger screen matches what Moistello shows. Derivation path
is hardcoded to 44'/148'/0' — cannot be overridden by external input.
- Transport is exclusive — no other application can interleave commands (USB HID exclusive lock)
- Stellar app is the only app that can respond to Stellar APDU commands on the device
- No private key material ever transmitted over transport — only public key and signed outputs
Failure modes:
- Device not plugged in / out of BLE range: transport creation fails → hardware_not_found
- LEDGER_SERVICE_UUID not in BLE advertisement: device filtering fails → device not found
- Stellar app not installed on Ledger: INS_GET_VERSION returns error → stellar_app_not_installed
"Stellar app not found. Install it from Ledger Live Manager."
- Device locked (PIN not entered): getPublicKey returns 0x6982 (security status not satisfied)
→ "Please unlock your Ledger with your PIN."
- User rejects address display on device: returns user_rejected
- USB cable is charge-only (no data): device enumerates but communication fails → device_not_responding
- Device firmware too old for app auto-open: user must manually navigate to Stellar app
Time complexity: O(1) for all transport and APDU operations + O(user_confirmation_time) for on-device review
Memory complexity: O(1) — single transport instance, single Stellar app instance, public key string (56 bytes)
Cryptographic citations:
- BIP-44 derivation path: Bitcoin Improvement Proposal 44 (BIP-0044), coin type 148 = Stellar
- Ed25519 public key validation: RFC 8032 Section 5.1.5 (key validation)
- Stellar address encoding: SEP-0001 (base32 with G prefix)
- Ledger APDU protocol: ISO/IEC 7816-4 (Smart card APDU commands)
- Ledger Stellar app communication: Stellar Development Foundation SEP-0005
Algorithm: LedgerAdapter.signTransaction(xdr, opts?)
Input: xdr: string (base64 Stellar transaction envelope XDR), opts?: { network?: NetworkType }
Output: { signedXdr: string } | WalletError
Pseudocode:
1. Verify transport is active:
a. IF !this.transport: return not_connected error
b. Ping device with INS_GET_VERSION (timeout: 3 seconds)
c. IF ping fails: transport dead → attempt reconnect (see Section 2.2.5)
2. Verify Stellar app is still the active app:
a. getVersion = await stellarApp.getAppConfiguration()
b. IF app name !== "Stellar": return stellar_app_not_open error
"Please open the Stellar app on your Ledger."
3. Validate input XDR:
a. IF !xdr || xdr.length === 0: return invalid_xdr error
b. Attempt base64 decode:
- Decode XDR envelope to verify it's parseable
- IF decode fails: return invalid_xdr error
c. Verify XDR is a Stellar transaction envelope:
- Must be TransactionEnvelope (not FeeBumpTransactionEnvelope for direct signing)
- IF FeeBump: error — "Fee bump transactions must be signed by the fee source account.
Sign the inner transaction instead."
d. Extract source account from XDR:
- verify source account matches this.publicKey
- IF mismatch: return wrong_account error
"This transaction is for account {txnSource}. Your Ledger has account {this.publicKey}.
Switch to the correct Ledger account or use a different wallet."
4. Determine network:
a. IF opts?.network: use provided network
b. ELSE: default to "testnet" (safety default — never sign mainnet without explicit intent)
c. IF network === "mainnet" AND no explicit confirmation flag:
- Await user confirmation: "You are about to sign a MAINNET transaction.
This will use real XLM. Continue?"
- IF user declines: return user_rejected
5. Send XDR to Ledger for signing:
a. signature = await stellarApp.signTransaction(
this.derivationPath,
xdr
)
b. Timeout: 120 seconds
Rationale: User must:
(1) Read transaction details on device screen (operations, amounts, fees)
(2) Scroll through all operations (if multiple — path payments, etc.)
(3) Verify each field (destination, amount, asset, memo)
(4) Physically press BOTH buttons to confirm
This is intentionally slow — hardware wallet signing should not be rushed.
6. Handle device response:
a. IF timeout (120s): return sign_timeout error
"Signing timed out. The transaction was not confirmed on your Ledger within 2 minutes.
Please try again and confirm when prompted."
b. IF user rejects (device returns 0x6985): return user_rejected error
"Transaction rejected on Ledger device."
c. IF device returns security error (0x6982 — not unlocked):
return device_locked error
"Please unlock your Ledger with your PIN first."
d. IF device returns signature:
- signedXdr = mergeSignatureIntoXdr(xdr, signature)
7. Validate signed XDR:
a. Decode signed envelope
b. Verify at least one signature exists
c. Verify signature is from this.publicKey:
- Extract signature hint from XDR (last 4 bytes of public key)
- Compare with hint from this.publicKey
d. Verify XDR differs from input (actual signature appended)
e. IF any validation fails: return internal_error
8. Return { signedXdr }
Security properties:
- Transaction details displayed on-device: user verifies destination, amount, asset, fee, sequence
- Physical confirmation: both buttons must be pressed to sign (anti-automation, anti-remote-attack)
- Source account verification: adapter checks that transaction source matches connected public key
- Mainnet safety gate: explicit user confirmation before signing any mainnet transaction
- Private key: NEVER leaves CC EAL5+ secure element — signing happens inside the chip
- Anti-tampering: Ledger secure element verifies firmware integrity at boot, rejects modified firmware
- No blind signing: Ledger Stellar app v3.3.0+ shows full transaction details, not just a hash
- Sequence number protection: Stellar's per-account sequence numbers prevent replay attacks at protocol level
Failure modes:
- USB disconnected mid-sign: transport throws DisconnectedDevice error → attempt reconnect (user must re-plug)
- BLE connection lost mid-sign: transport throws — BLE auto-reconnect attempts, or user must re-pair
- Device battery dies mid-sign: transport lost → reconnect after charging (session lost, restart)
- Stellar app crashes on device: transport returns error → user re-opens app, retry sign
- Malformed XDR passes base64 but fails Stellar parsing: Ledger Stellar app rejects → protocol_error
- User doesn't know what to verify: screen simulation component shows expected display, instructions
- Transaction too large for device memory: Ledger Stellar app has ~2KB buffer for XDR → large transactions with many operations may fail → chunked signing not supported by Stellar protocol
Time complexity: O(1) for APDU send + O(user_review_time) for on-device verification
Memory complexity: O(|XDR|) — stored in memory during signing, then discarded
Cryptographic citations:
- Ed25519 signing: RFC 8032 Section 5.1.6 (Sign algorithm)
- Signature performed inside Ledger secure element (CC EAL5+ certified, ST33K1M5 / ST33J2M0 chip)
- Transaction signing: Stellar SEP-0005 (Key Derivation Methods for Stellar)
- XDR encoding: Stellar XDR specification (Stellar Core protocol)
- Ledger APDU security: ISO/IEC 7816-4 secure messaging
Algorithm: LedgerAdapter.signMessage(message)
Input: message: string (arbitrary message to sign)
Output: { signature: string; publicKey: string } | WalletError
Pseudocode:
1. Verify transport and Stellar app (same as Section 2.2.3 steps 1-2)
2. Validate input:
a. IF !message || message.length === 0: return invalid_message error
b. IF message.length > 8192: return message_too_large error
Reason: Stellar manageData operation value is limited to 64 bytes.
For long messages, we hash first then sign the hash.
3. Construct SEP-0007 signing transaction:
a. IF message.length > 64:
- messageHash = SHA256(message)
- dataValue = messageHash (32 bytes, fits in manageData)
b. ELSE:
- dataValue = message (raw, if it fits)
c. Build Stellar transaction:
- sourceAccount: this.publicKey
- fee: "100" (stroops, minimal — this is a signing-only transaction, never submitted)
- sequence: "0" (SEP-0007 convention for non-submitted signing transactions)
- operation: manageData({
name: "Moistello Auth",
value: dataValue
})
- memo: none
d. Convert to XDR (base64)
4. Send XDR to Ledger for signing:
a. signedXdr = await stellarApp.signTransaction(this.derivationPath, xdr)
b. Timeout: 60 seconds (message signing is faster than full transaction review)
c. Handle same device-level errors as Section 2.2.3 step 6
5. Extract signature from signed XDR:
a. Decode signed transaction envelope
b. Extract Ed25519 signature from envelope (64 bytes)
c. Encode signature as base64
6. Return { signature: base64Signature, publicKey: this.publicKey }
Security properties:
- Message content shown on device screen (manageData operation name + value hex)
- Physical confirmation required for signature
- SEP-0007 standard ensures interoperability — any Stellar wallet can verify the signature
- Signature is over the Stellar transaction hash (SHA-256 of transaction envelope), not raw message
- This means the signature binds: public key + transaction structure + message content
- For messages >64 bytes: device shows hash, not original message → user can't verify content
Mitigation: UI displays full message alongside device simulator, user cross-references
Failure modes:
- Same transport/device failures as transaction signing (Section 2.2.3)
- Message >64 bytes: device shows hash only — UX must show original message for comparison
- Sequence number 0 may confuse Ledger Stellar app: app shows sequence = 0 → user education needed
- Empty manageData name may confuse display: "Moistello Auth" chosen for clarity
Time complexity: O(1) + O(user_confirmation_time)
Memory complexity: O(1)
Cryptographic citations:
- SEP-0007: Stellar Ecosystem Proposal 0007 — URI Scheme to facilitate delegated signing
- SHA-256: FIPS 180-4 (Secure Hash Standard)
- Ed25519 signature extraction from XDR: RFC 8032, Stellar Core implementation
Algorithm: LedgerTransportManager.maintainConnection()
Input: transport: Transport (active transport instance)
Output: (side-effect: monitors transport, auto-reconnects on disconnect)
Pseudocode:
1. Register disconnect handlers:
a. transport.on("disconnect", async () => {
- Set connectionState = "disconnected"
- Broadcast ledger_disconnected event
- Start reconnection timer (below)
})
2. USB disconnect detection:
a. navigator.usb.addEventListener("disconnect", (event) => {
- IF event.device === ourDevice:
- On USB, disconnect is immediate (polled by browser)
- Mark transport as dead
- Start reconnection
})
3. BLE disconnect detection:
a. navigator.bluetooth.addEventListener("disconnect", ...) — NOT SUPPORTED IN ALL BROWSERS
b. Fallback: periodic ping (every 5 seconds) via INS_GET_VERSION APDU
c. IF ping fails 3 times consecutively:
- Mark transport as dead
- Attempt BLE reconnection
4. Reconnection strategy:
a. On disconnect, attempt auto-reconnect:
b. USB reconnect:
- await navigator.usb.getDevices() — list authorized devices
- IF our device (by serial) found:
- Try re-opening the device: await device.open()
- IF fails (device unplugged): enter "waiting for device" state
- ELSE: enter "waiting for device" state
c. BLE reconnect:
- Attempt `device.gatt.connect()` on cached BLE device object
- IF fails: BLE device gone (out of range, battery died, Bluetooth off)
- Enter "waiting for device" state
d. "Waiting for device" state:
- Show UI prompt: "Ledger disconnected. Please reconnect your device."
- Poll for device every 2 seconds:
- USB: navigator.usb.getDevices()
- BLE: scanning not allowed without user gesture → must prompt user to tap "Reconnect"
- Timeout: 60 seconds → session expired, must full reconnect
e. IF device reconnected within timeout:
- Re-open transport
- Re-initialize Stellar app (stellarApp = new StellarApp(transport))
- Verify same public key (insurance against device swap):
oldPubKey === await stellarApp.getPublicKey("44'/148'/0'", { display: false })
- IF mismatch: session invalidated, must full reconnect
- Restore state: connectionState = "connected", broadcast event
- Resolve any pending operations that were interrupted
f. IF reconnection timeout:
- Full disconnect: clear state, notify user
Security properties:
- Auto-reconnect only to the SAME device (verified by public key comparison)
- No persistent session data — device must be physically present
- Reconnection timeout prevents indefinite "waiting" state
- Public key re-verified on every reconnect — prevents device swap attacks
- display: false used for reconnection verification (no user interaction needed for reconnect)
Failure modes:
- USB hub power saving: hub turns off port → device disconnects → auto-reconnect when port wakes
- Laptop sleep/wake: USB disconnects on sleep → reconnects on wake (handled by auto-reconnect)
- BLE range: user walks away with device → disconnect → reconnect when back in range
- BLE interference: 2.4GHz congestion → intermittent pings → degraded performance, not failure
- Battery swap (Nano X): device powered off → full disconnect → reconnect after power on
- Cable swap: different USB port → requestDevice needed if port not previously authorized
Time complexity: O(1) per connection event
Memory complexity: O(1) — event listeners + transport reference + timer handle
Algorithm: LedgerAdapter.getFirmwareVersion()
Input: (none — reads from connected device)
Output: { firmware: string, stellarApp: string, isUpToDate: boolean, warnings: string[] }
Pseudocode:
1. IF !this.transport or !this.stellarApp: return not_connected error
2. Read device firmware version:
a. Standard APDU: CLA=0xE0, INS=0x01 (GET_VERSION command)
b. Transport sends raw APDU, Ledger OS responds
c. Response: { major, minor, patch, flags }
d. firmware = `${major}.${minor}.${patch}`
3. Read Stellar app version:
a. result = await stellarApp.getAppConfiguration()
b. stellarAppVersion = result.version
4. Determine status:
a. warnings = []
b. IF firmware.major < 2:
- warnings.push("Ledger firmware v1.x is outdated and no longer receives security updates.
Update to firmware v2.0+ via Ledger Live.")
- isUpToDate = false
c. ELSE IF firmware.minor < 60: // Current firmware is 2.2.x, warn if <2.0.x
- warnings.push("Ledger firmware update available. Update via Ledger Live
for improved security and Stellar app features.")
- isUpToDate = false
d. IF stellarAppVersion < "3.3.0":
- warnings.push("Stellar app v3.3.0+ is required for full transaction detail display.
Update via Ledger Live Manager.")
- isUpToDate = false
e. IF stellarAppVersion < "3.4.0":
- warnings.push("Stellar app v3.4.0+ adds support for Soroban smart contract transactions.
Update via Ledger Live Manager.")
// This is a soft warning — v3.3.0 is sufficient for classic Stellar operations
f. IF no warnings: isUpToDate = true
5. Return { firmware, stellarApp: stellarAppVersion, isUpToDate, warnings }
Security properties:
- Firmware version check prevents use of outdated firmware with known vulnerabilities
- Stellar app version check ensures on-device transaction detail display is working
- Warnings are advisory, not blocking — user can still use device with outdated firmware
- Version strings validated by signature on the Ledger device (firmware self-attestation)
Failure modes:
- GET_VERSION APDU fails: device may be in bootloader mode → warn user to exit bootloader
- App not responding: powered off, battery dead → transport failure detected first
Time complexity: O(1) — two APDU round trips (~100ms total)
Memory complexity: O(1)
New state introduced by Phase 4:
State additions to multi-wallet-store:
{
// Existing Phase 1-3 state preserved
activeWalletId: "ledger" | null,
wallets: Map<WalletId, { ... }>, // Ledger adapter added as new entry
// Phase 4 new state
ledgerTransportType: "usb" | "ble" | null,
ledgerConnectionState: "idle" | "detecting" | "connecting" | "waiting_for_app" |
"waiting_for_confirm" | "connected" | "disconnected" | "error",
ledgerFirmwareVersion: string | null,
ledgerStellarAppVersion: string | null,
ledgerFirmwareWarnings: string[],
ledgerConnectionError: LedgerError | null,
}
Lifecycle:
1. App loads → check browser capability → ledgerTransportType set ("usb" | "ble" | null)
2. User clicks "Connect Ledger" → ledgerConnectionState = "detecting"
3. Transport created → "connecting" → Stellar app check
4. Stellar app not open? → "waiting_for_app" → user guided to open app
5. App opened → getPublicKey sent → "waiting_for_confirm"
6. User confirms on device → "connected" → adapter registered in wallets map
7. USB unplugged → "disconnected" → auto-reconnect timer starts
8. Auto-reconnect succeeds → back to "connected"
9. Auto-reconnect fails → "error" → manual reconnect prompt
10. User disconnects → state cleared → "idle"
State survives:
✓ Within same page session: full state in Zustand (JS memory)
✓ BroadcastChannel sync across tabs: ledger_connected/ledger_disconnected events
✗ Page refresh: state LOST — hardware wallet connection is a physical state,
not a persistable session. User must reconnect. This is by design —
the security model demands physical presence confirmation.
✗ Tab close: same as refresh — connection lost, reconnect required
✗ Browser restart: same — reconnection needed
✗ Device sleep (Nano X): BLE may recover or timeout → reconnection logic handles
Rationale for in-memory-only state:
Unlike WC2 (where session persistence is useful because the wallet app is still
installed), a hardware wallet "session" is meaningless without the physical device.
Storing a public key doesn't help because:
1. The user cannot sign without the device present
2. The device could be swapped by a different Ledger
3. The Stellar app might not be open on the device
Forcing reconnection on refresh ensures the security invariant: you must prove
you have the physical device to perform any action.
Ledger-specific errors added:
| Error Code | Trigger | User Sees | Logged | Retryable? |
|---|---|---|---|---|
ledger_unsupported_browser |
Browser doesn't support WebUSB or WebBLE | "Ledger requires Chrome, Edge, or Brave browser. Please switch browsers or use WalletConnect instead." | navigator.userAgent, detected APIs | NO — user must switch browser |
ledger_device_not_found |
No Ledger device detected on USB/BLE | "Ledger not detected. Is it plugged in? Unlocked? On Windows, you may need to install the Ledger Live app for USB drivers." | Transport type, device enumeration results | YES — retry after connecting device |
ledger_stellar_app_not_open |
Device connected but Stellar app not active | "Please open the Stellar app on your Ledger device. Navigate to the Stellar icon and press both buttons to open." | Current active app (if detectable), firmware version | YES — retry after opening app |
ledger_stellar_app_not_installed |
Stellar app not found on device | "Stellar app not installed on this Ledger. Open Ledger Live → Manager → Search 'Stellar' → Install." | Device firmware version, installed apps list | NO — user must install app |
ledger_device_locked |
Device PIN not entered | "Please unlock your Ledger by entering your PIN on the device." | Device security status code | YES — retry after unlocking |
ledger_user_rejected |
User rejected on device screen (cancelled address display or transaction review) | "Connection cancelled on Ledger. Please try again and approve when prompted." | APDU status word, step where rejection occurred | YES — retry |
ledger_timeout |
Operation timed out (user didn't confirm within time limit) | "Operation timed out. Please try again and confirm on your Ledger when the prompt appears. [Retry]" | Operation type, timeout duration, transport latency | YES — retry |
ledger_transport_disconnected |
USB unplugged or BLE disconnected during operation | "Ledger disconnected. Please reconnect your device and try again. Check your USB cable or Bluetooth connection." | Transport type, disconnect reason, operation in progress | YES — after reconnection |
ledger_firmware_outdated |
Firmware or Stellar app version below minimum | "Your Ledger firmware (v{X}) or Stellar app (v{Y}) is outdated. Update via Ledger Live for the best security. You can continue, but transaction details may not display correctly." | Firmware version, stellar app version, minimum required versions | NO — advisory warning, operation continues |
ledger_wrong_account |
Transaction source account doesn't match connected Ledger | "This transaction is for account ending in ...{XYZ}. Your Ledger has account ending in ...{ABC}. Switch to the correct account or use a different wallet." | Expected public key, actual public key, derivation path | NO — user must switch account or wallet |
ledger_xdr_invalid |
XDR is malformed or unparseable | "Invalid transaction data. The transaction could not be processed. [Dismiss]" | XDR decode error, operation attempted | NO — developer error or corrupted data |
ledger_mainnet_confirm_required |
User attempted to sign mainnet transaction without explicit confirmation | "You are about to sign a MAINNET transaction using real XLM from your Ledger. Please confirm this is intentional. [Cancel] [I Understand — Sign on Mainnet]" | Transaction hash, amount, destination | NO — requires explicit user opt-in |
Error propagation in Ledger adapter:
LedgerAdapter method encounters error
│
├─ Is it a transport-level error? (USB disconnect, BLE drop, device not found)
│ ├─ YES → TransportManager.handleDisconnect()
│ │ ├─ Record disconnect event
│ │ ├─ Attempt auto-reconnect (see Section 2.2.5)
│ │ ├─ IF reconnect succeeds: retry original operation
│ │ └─ IF reconnect fails: surface ledger_transport_disconnected error
│ └─ NO → continue to classification
│
├─ Is it a Ledger device error? (locked, wrong app, user rejected, timeout)
│ ├─ YES → Classify: { security, user, app_state, timeout }
│ └─ NO → Map to existing WalletError types from Phase 1
│
├─ Surface error to UI:
│ ├─ Adapter returns typed LedgerError (extends WalletError from Phase 1)
│ ├─ Store updates ledgerConnectionState + ledgerConnectionError
│ ├─ UI renders error in Ledger connection wizard modal
│ └─ Audit log: adapter=ledger, error_code, firmware_version, transport_type, timestamp
│
└─ Recovery path:
├─ Transport errors: prompt reconnect with clear instructions
├─ User-reject errors: show retry button
├─ App-state errors: show guided instructions (how to open Stellar app, unlock device)
└─ Fatal errors (unsupported browser, no Stellar app): show fallback wallet options
Before writing ANY code, every file must answer:
[ ] Does this file import or use `localStorage`, `sessionStorage`, `window`, `document`,
`BroadcastChannel`, or `navigator`?
ledger.ts: YES — uses navigator (usb, bluetooth checks), window (type guard), BroadcastChannel (session events)
ledger-transport.ts: YES — uses navigator.usb, navigator.bluetooth (WebUSB/WebBLE APIs), window
ledger-prompt.tsx: YES — uses document (modal rendering), window (focus management, animation frame)
ledger-device-sim.tsx: YES — uses document (SVG rendering), window (requestAnimationFrame for screen animations)
[ ] If yes: where is the `typeof window === "undefined"` guard?
ledger.ts:
- connect(): first line checks `if (typeof window === "undefined") throw SSRGuardError`
- signMessage(): first line same guard
- signTransaction(): first line same guard
- getPublicKey(): first line same guard
- isAvailable(): returns `typeof window !== "undefined" && ("usb" in navigator || ...)`
- All public methods: SSR guard at entry point
- static isAvailable(): configures meta.isAvailable for SSR-safe registration
- Module exports CLASS, not instance — no module-level execution
ledger-transport.ts:
- detectTransport(): first line checks `typeof window === "undefined"` → returns null
- getOrCreateTransport(): first line same guard — returns null for SSR
- handleDisconnect(): first line same guard
- All transport operations guarded at method entry
- navigator.usb / navigator.bluetooth ONLY accessed inside guarded methods
- Module exports CLASS, not instance
ledger-prompt.tsx:
- Component renders SSR-safe placeholder: "Connect your Ledger" when window undefined
- All WebUSB/WebBLE interaction inside useEffect with [] deps
- Device enumeration: useEffect (browser-only)
- Connection state polling: useEffect with cleanup (clearInterval on unmount)
- Modal DOM manipulation: useEffect + event handlers
ledger-device-sim.tsx:
- SSR renders: static SVG placeholder (no animation)
- Canvas/SVG animation: inside useEffect
- requestAnimationFrame: inside useEffect, cleared on unmount
[ ] If the file is a module (exported at file scope): does instantiation happen lazily or behind a guard?
ledger.ts:
- Export class, not instance. Consumers call `new LedgerAdapter(transportManager)` at runtime.
- Constructor stores references, does zero browser API access.
- All browser API access deferred to method calls.
ledger-transport.ts:
- Export class, not instance.
- Transport created lazily in getOrCreateTransport(), never at module scope.
- WebUSB/WebBLE objects created only inside method calls.
@ledgerhq/hw-transport-webusb:
- Imported but never instantiated at module scope.
- TransportWebUSB.create() called inside getOrCreateTransport() behind SSR guard.
@ledgerhq/hw-transport-webble:
- Imported but never instantiated at module scope.
- TransportWebBLE.create() called inside getOrCreateTransport() behind SSR guard.
@ledgerhq/hw-app-str:
- Imported but never instantiated at module scope.
- new StellarApp(transport) called inside connect() behind SSR guard.
[ ] If the file is a React hook: does `useEffect` guard browser-only code?
useLedgerConnection hook (in ledger-prompt.tsx):
- Transport detection: inside useEffect with [] deps
- Device polling / state machine: inside useEffect, driven by connectionState
- BroadcastChannel setup: inside useEffect, torn down on unmount
- WebUSB event listeners: inside useEffect, removed on cleanup
- All browser API access inside useEffect boundaries
useLedgerDeviceSimulation hook (in ledger-device-sim.tsx):
- Animation rendering: inside useEffect with [] deps
- Screen state transitions: driven by connectionState, inside useEffect
- requestAnimationFrame loop: inside useEffect, cancelled on unmount
[ ] Are there any module-level `new BroadcastChannel()`, `new WebSocket()`,
`localStorage.getItem()`, `navigator.usb.getDevices()`, or similar calls
outside a function?
NO. All browser API access is:
- In React useEffect (ledger-prompt, ledger-device-sim components)
- In class methods guarded by typeof window check (adapter, transport manager)
- In lazy-initialized transport creation (getOrCreateTransport method)
- TransportWebUSB / TransportWebBLE imported but module-level code is zero-execution
(they export classes, not singletons with side effects)
VERIFIED: navigator.usb.requestDevice() is NEVER called at module scope.
It requires a user gesture (click) per WebUSB specification.
Module-level imports of @ledgerhq packages have zero side effects.
@ledgerhq/hw-transport uses Buffer — Next.js polyfill handles this,
but Buffer instantiation only happens inside methods, not at import time.
Rule: Every file that touches browser APIs MUST start execution with
`if (typeof window === "undefined") return` or wrap browser code in
`useEffect` / event handlers.
| Surface | Threat Model | Mitigation |
|---|---|---|
| WebUSB transport | Malicious website attempts to communicate with user's Ledger via WebUSB to extract keys or sign unauthorized transactions | WebUSB permission model: browser prompts user to select device. Permission is scoped to origin (moistello.io). Only the origin that was granted permission can communicate with the device. Ledger device requires on-device confirmation for every sensitive operation (display public key, sign transaction). Browser restricts WebUSB to secure contexts (HTTPS). |
| Web Bluetooth (BLE) transport | Attacker within BLE range (~10 meters) attempts to connect to user's Nano X and sign transactions or read public key | BLE pairing requires physical confirmation on Ledger device (PIN entry for first-time pairing). BLE connection is encrypted (LE Secure Connections with ECDH key exchange). Browser Bluetooth API limits scanning to user-initiated actions (requestDevice requires user gesture). Ledger BLE advertising is not constantly on — only during active pairing mode. |
| Browser device chooser spoofing | Attacker creates a device with identical USB VID/PID to Ledger's (0x2c97), tricks user into selecting it in browser device chooser | USB VID/PID are USB-IF assigned identifiers. Spoofing requires physical device. Even if spoofed, the fake device cannot respond to Ledger APDU commands because it lacks the Ledger secure element private key. The adapter detects this: INS_GET_VERSION response won't match Ledger's format, or subsequent cryptographic operations will fail. The real Ledger device attests to its identity cryptographically (device attestation in Ledger OS). |
| Man-in-the-middle on USB | Hardware MITM device inserted between Ledger and computer, intercepting/modifying APDU commands | USB is a point-to-point protocol. Physical MITM requires specialized hardware inserted in the cable. Even with MITM: (1) transaction details are displayed on the Ledger screen — user can verify the destination/amount shown on their device matches what Moistello displays. (2) The signature is produced inside the secure element — MITM cannot forge a signature for a modified transaction because it doesn't have the private key. (3) The MITM can only substitute the entire XDR → user would see different transaction on screen than expected → reject. |
| Malicious dApp version of Moistello | Attacker clones Moistello frontend, hosts on similar domain, tricks user into connecting Ledger and signing transactions | Ledger displays dApp metadata (from the origin that requested the connection). User should verify "moistello.io" in the browser's address bar. Ledger device shows the transaction details — user responsibility to verify. The attacker's clone cannot redirect funds without user seeing the wrong destination on their Ledger screen. The hardware wallet is the final verification checkpoint. |
| Transaction replay attack | Attacker captures a signed XDR and attempts to submit it multiple times | Stellar protocol prevents replay: each transaction has a unique sequence number per source account. Once a transaction is confirmed on the ledger, its sequence number is consumed. Replaying the same XDR would be rejected by the Stellar network (transaction already processed). Additionally, every transaction includes the source account's current sequence — the attacker would need to submit before the real transaction, which is a race condition the network resolves (first seen, first valid). |
| Derivation path manipulation | Attacker modifies the derivation path to access different accounts on the same Ledger device | Derivation path is hardcoded in the adapter (44'/148'/0'). It is not user-configurable and not read from any external source. The Ledger Stellar app shows the derivation path on the device screen when displaying the public key — user should see 44'/148'/0' and verify. For non-standard paths, the app requires display: true which forces on-device display. |
| Firmware downgrade attack | Attacker convinces user to install malicious/outdated Ledger firmware with known vulnerabilities | Ledger firmware updates are cryptographically signed by Ledger SAS. The Ledger secure element verifies the firmware signature before installation. Downgrading to a vulnerable firmware version requires the user to explicitly install it via Ledger Live (with warnings). Our adapter detects firmware version and warns if outdated (see Section 2.2.6). |
| Unlocked device attack | Attacker gains physical access to unlocked Ledger and attempts to use it through Moistello | Ledger auto-locks after 10 minutes of inactivity (configurable, handled by Ledger OS). Physical access to an unlocked device with the Stellar app open would allow signing. This is an inherent physical security limitation — the hardware wallet is a "something you have" factor. Mitigation: (1) auto-lock timer, (2) PIN required to unlock, (3) wipe after 3 incorrect PIN attempts, (4) user education: "Never leave your Ledger unlocked and unattended." |
| Browser extension interference | Malicious browser extension intercepts WebUSB/WebBLE API calls | Browser extensions with sufficient permissions can intercept navigator.usb.requestDevice, navigator.bluetooth.requestDevice, and related APIs. This is a browser-level vulnerability, not Ledger-specific. Mitigation: (1) Ledger device still shows transaction details and requires physical confirmation, (2) user should verify transaction details on the device screen match what Moistello shows, (3) browser permission model limits which extensions can access WebUSB. |
| Supply chain attack on @ledgerhq packages | Attacker publishes malicious version of @ledgerhq/hw-app-str that exfiltrates XDR/keys | Dependencies pinned to exact versions with integrity hashes in lockfile. CI verifies integrity hashes. Ledger packages are published under Ledger SAS's npm organization with 2FA. Version bumps reviewed manually. Even if a malicious package modifies the XDR before sending to the device, the user would see different transaction details on their Ledger screen than what Moistello shows. Private key never leaves the secure element — even the legitimate packages cannot access it. |
User → Browser (Moistello) → USB/BLE → Ledger Device → Secure Element
│ │ │ │ │
│ 1. User plugs in Ledger via USB (or pairs BLE)
│ │ │ │ │
│ 2. User navigates to /login, clicks "Connect Ledger"
│ │ │ │ │
│ 3. Browser shows device chooser (WebUSB) or scan dialog (BLE)
│ │ │ │ │
│ 4. User selects "Nano X" from browser dialog
│ │ │ │ │
│ 5. Browser establishes secure transport:
│ │ WebUSB: exclusive claim on USB interface
│ │ WebBLE: encrypted BLE connection (LE Secure Connections)
│ │ │ │ │
│ 6. Moistello: opens communication channel to Ledger
│ │ sends APDU: CLA=0xE0, INS=0x01 (GET_VERSION)
│ │ │ │ │
│ │ │ 7. Ledger responds: firmware v2.2.0,
│ │ │ current app = "Dashboard"
│ │ │ │ │
│ 8. Moistello: opens Stellar app (APDU command or user instruction)
│ │ │ │ │
│ │ │ 9. Stellar app loads on device
│ │ │ User sees: "Stellar" + logo on screen
│ │ │ │ │
│ 10. Moistello: stellarApp.getPublicKey("44'/148'/0'", { display: true })
│ │ │ │ │
│ │ │ 11. Device screen shows:
│ │ │ "Address"
│ │ │ "GABC...XYZ"
│ │ │ [Approve] [Reject]
│ │ │ │ │
│ 12. User verifies address on device screen matches what Moistello shows
│ User presses both buttons to approve
│ │ │ │ │
│ │ │ 13. Device returns: { publicKey: "GABC..." }
│ │ │ (via APDU response)
│ │ │ │ │
│ │ ←── 14. Moistello receives public key
│ │ │ │
│ 15. POST /v1/auth/nonce { publicKey } → Backend
│ │ │ │
│ │ 16. Backend generates nonce (CSPRNG, 32 bytes)
│ │ 17. Backend stores nonce in Redis (TTL 5 min)
│ │ │ │
│ │ ←── 18. Backend returns { nonce, xdrToSign }
│ │ │ │
│ 19. Moistello: stellarApp.signTransaction(derivationPath, xdrToSign)
│ │ │ │ │
│ │ │ 20. Device screen shows transaction details:
│ │ │ "Review Transaction"
│ │ │ Source: GABC...
│ │ │ Fee: 0.00001 XLM
│ │ │ Operation: Manage Data
│ │ │ Key: Moistello Auth
│ │ │ Value: [nonce as hex]
│ │ │ [Scroll ->] [Approve] [Reject]
│ │ │ │ │
│ 21. User scrolls through all fields, verifies, presses both buttons to sign
│ │ │ │ │
│ │ │ 22. Secure element performs Ed25519 signing
│ │ │ Private key NEVER leaves secure element
│ │ │ Returns: { signature }
│ │ │ │ │
│ │ ←── 23. Moistello receives signed XDR
│ │ │ │
│ 24. POST /v1/auth/verify { publicKey, signedXdr, nonce }
│ │ │ │
│ │ 25. Backend: Ed25519 verify signature
│ │ 26. Backend: if valid -> create JWT -> return { token, user }
│ │ │ │
│ ←── 27. Frontend stores JWT in memory (not localStorage)
│
└─ Authenticated session established
Ledger remains connected for subsequent transactions
Every transaction: device review → physical button press → sign
| Cryptographic Primitive | Where Used | Standard |
|---|---|---|
| Ed25519 | Transaction signing, auth signature verification, public key validation | RFC 8032 |
| HMAC-SHA256 | Nonce generation for SEP-0007 message signing, session integrity | RFC 2104, FIPS 198-1 |
| SHA-256 | Message hashing for SEP-0007 signing (messages >64 bytes) | FIPS 180-4 |
| BIP-32 / BIP-44 | Key derivation from Ledger master seed (performed inside secure element) | BIP-0032, BIP-0044 |
| APDU secure messaging | Ledger device communication protocol | ISO/IEC 7816-4 |
| LE Secure Connections (BLE) | BLE transport encryption (ECDH key exchange + AES-CCM) | Bluetooth Core Spec v4.2+ |
| TLS 1.3 | App -> Backend API communication | RFC 8446 |
Where secrets live during the Ledger session:
| Secret | Location | Lifetime | Encryption |
|---|---|---|---|
| Ed25519 private key | Ledger secure element (CC EAL5+/EAL6+ chip, ST33 series) | Permanent (until device reset) | Hardware-isolated — key never accessible via any API, stored in dedicated flash with access control by secure element OS (BOLOS) |
| Ledger master seed (24 words) | Ledger secure element | Permanent | Hardware-isolated, never leaves chip, BIP-39 mnemonic derived at setup and stored encrypted in secure element NVM |
| Stellar public key | JS memory (Zustand store) | Until disconnect or page refresh | In-memory only |
| JWT access token | JS memory (Zustand store) | 15 minutes | In-memory only |
| USB transport handle | JS memory (browser-managed) | Until disconnect or page refresh | Browser sandboxed, origin-scoped |
| BLE pairing keys | Ledger secure element + browser BLE stack | Until device unpaired | LE Secure Connections encryption, hardware-backed on Ledger side |
Key differentiator from Phase 1-3 wallets:
- Phase 1 (extensions): Private key in browser extension storage (software-protected)
- Phase 2 (WalletConnect): Private key in mobile wallet app (software-backed by mobile OS)
- Phase 3 (Passkey): Private key derived from WebAuthn credential (hardware-backed on device)
- Phase 4 (Ledger): Private key in CC EAL5+ secure element — physically isolated from all software
| Data | Protection at Rest | Protection in Transit | Protection in Memory | Retention |
|---|---|---|---|---|
| Ed25519 private key | Hardware secure element (CC EAL5+), encrypted in dedicated NVM, access controlled by BOLOS OS, zero-extraction architecture | NEVER transmitted — signing happens inside chip | NEVER in memory — chip enforces isolation | Permanent (until device reset by user) |
| Stellar public key | In-memory only (not persisted) | TLS 1.3 (to backend), plaintext over USB HID/BLE (no encryption needed — public data) | In-memory (State store), isolated per tab | Until disconnect or page refresh |
| Transaction XDR | Not stored — sent to device, discarded after signing | USB HID (plaintext, point-to-point) or BLE (encrypted link layer) | In-memory during sign operation only (~2KB max) | Discarded immediately after signing |
| Signed XDR | Not stored — sent to backend, response discarded | TLS 1.3 (to backend), USB/BLE (from device) | In-memory during verification only | Immediate (discard after POST /auth/verify or submit) |
| Device firmware/version info | N/A (read from device) | USB HID / BLE (plaintext, non-sensitive) | In-memory during session | Until disconnect |
| JWT tokens | In-memory only (not persisted) | TLS 1.3 | In-memory, cleared on tab close | 15 minutes max |
| Auth nonce | Redis (server-side) | TLS 1.3 | In-memory (browser, during verification flow) | 5 minutes max |
Data purging on disconnect/page refresh:
- Public key: cleared from Zustand store
- Transport handle: browser releases USB claim / BLE disconnects
- All in-memory state: garbage collected
- No localStorage persistence for hardware wallet session (by design — see Section 2.3)
New dependencies audited:
| Package | Supply Chain Risk | Mitigation |
|---|---|---|
@ledgerhq/hw-transport-webusb@6.29.4 |
Maintained by Ledger SAS (public company, Euronext: LEDGER). 60K+ weekly downloads. Repository: github.com/LedgerHQ/ledger-live (monorepo). 400+ contributors. | Pinned to exact version. Lock file integrity verified. Transitive deps audited: @ledgerhq/hw-transport, @ledgerhq/devices, @ledgerhq/errors (all from same monorepo). |
@ledgerhq/hw-transport-webble@6.29.4 |
Same maintainer, same monorepo. Shares release cycle with webusb package. | Pinned to exact version. Shared transitive deps with webusb. |
@ledgerhq/hw-app-str@7.0.4 |
Maintained by Ledger SAS with direct SDF collaboration. The official Stellar hardware wallet integration. Repository: github.com/LedgerHQ/ledger-live (same monorepo). | Pinned to exact version. Transitively depends on @ledgerhq/hw-transport. Follows semantic versioning. Major version bumps correspond to breaking APDU protocol changes. |
Supply chain attack vectors specific to hardware wallet integration:
| Vector | Risk | Mitigation |
|---|---|---|
| Malicious @ledgerhq package version | Attacker publishes a version that sends XDR to a remote server or modifies the XDR before sending to the device | Pinned exact versions. Lock file integrity hashes. Even if compromised: (1) private key can't leave device — secure element enforced, (2) modified XDR would show different transaction on device screen — user can detect, (3) code review catches outbound network calls in a USB/BLE communication library. |
| Malicious Ledger firmware (supply chain) | Compromised firmware loaded onto device from factory or via update | Ledger firmware is cryptographically signed by Ledger SAS. Secure element verifies signature before boot. Root of trust in boot ROM. Altering firmware post-manufacturing requires physical access + chip-level attack (extremely expensive, requires electron microscopy / FIB). |
| Malicious Stellar app on Ledger | Attacker publishes a fake "Stellar" app to Ledger Live Manager | Ledger Live Manager only lists apps that pass Ledger's review process. Apps are signed. The real Stellar app is developed by Ledger+SDF and its hash is known. Our adapter can verify the app hash if needed (beyond scope of Phase 4 — Phase 6 enhancement). |
| npm registry compromise | Attacker gains control of @ledgerhq organization on npm | Ledger uses npm organization with 2FA. Registry-level compromise would affect ALL Ledger-consuming applications, not just Moistello. This is an industry-level risk mitigated by npm's security practices and lock file integrity verification in CI. |
Dependency update plan:
- Dependabot configured for weekly security vulnerability scans
@ledgerhq/*packages tracked as a group (they share a monorepo and should be updated together)- Major version bumps (e.g., v7 -> v8 of hw-app-str) trigger: APDU protocol review, Ledger Stellar app compatibility verification, integration test re-run
- Lock file committed to repository;
npm cienforced for reproducible builds - Pre-release testing of new @ledgerhq versions with physical Ledger devices (Nano S, Nano X)
Every security-critical function in Phase 4 must be tagged:
| Function | Current Phase Level | Target Level | Upgrade Trigger |
|---|---|---|---|
| Transaction signing (send XDR -> device) | Separation enforced by HW (this phase) | Same — already maximum security | N/A — hardware secure element is the terminal security boundary |
| Public key retrieval + display | Device display with user verification (this phase) | Same — already maximum security | N/A |
| Transport encryption (USB) | Point-to-point USB HID (no encryption needed) (this phase) | Same — USB is a local, physical bus | N/A |
| Transport encryption (BLE) | LE Secure Connections (ECDH + AES-CCM) (this phase) | Same — BLE link-layer encryption | N/A |
| Firmware version check | Server-side advisory warning (this phase) | Firmware attestation verification (Phase 6) | Before mainnet launch — cryptographically verify device is genuine |
| Device identity attestation | Not implemented (this phase) | Ledger device attestation (Phase 6) | Before mainnet launch — verify device certificate chain |
| Session state persistence | In-memory only (this phase) | Same — no persistence is the security feature | N/A — by design, hardware wallet sessions should not persist |
| Transaction XDR validation | Source account match + basic decode (this phase) | Full XDR semantic validation (Phase 6) | Before mainnet launch — validate all operations are valid Stellar operations |
| Mainnet confirmation gate | User confirmation dialog (this phase) | Multi-factor confirmation (Phase 6) | Before mainnet launch — add email notification for mainnet txns |
Rule: No security shortcut is left undocumented. Every simplification has a documented upgrade path.
Cold start (first time connecting Ledger, desktop USB):
1. Page load + JS bundle parse: ~850ms (Phase 1-3 baseline: ~820ms, +40KB Ledger bundle)
2. Browser device chooser (WebUSB requestDevice): ~500ms (browser shows native dialog, user selects device)
3. USB connection establishment (exclusive claim): ~100ms (USB HID enumeration + open)
4. Transport creation (TransportWebUSB.create): ~50ms
5. Device ping (INS_GET_VERSION APDU): ~30ms
6. Open Stellar app (APDU app launch + loading): ~300ms (app loads on device)
7. StellarApp initialization: ~20ms
8. Read firmware + app version: ~50ms
9. getPublicKey sent to device: ~20ms
10. User reads address on Ledger screen: ~5000ms (human time — reading + verifying + finding buttons)
11. User presses both buttons to confirm: ~1000ms (human time)
12. Device returns public key (APDU response): ~20ms
13. POST /auth/nonce → backend: ~200ms
14. signTransaction sent to device: ~20ms
15. User reviews transaction on Ledger screen: ~5000ms (human time — scrolling through fields)
16. User presses both buttons to sign: ~1500ms (human time)
17. Device performs Ed25519 signing (inside secure element): ~200ms (Ed25519 signing on Cortex-M4 @ 100MHz)
18. Device returns signed XDR: ~30ms
19. POST /auth/verify → backend: ~300ms
20. JWT stored, redirect to dashboard: ~50ms
─────────────────────────────────────────────────────
Total machine time: ~2.0s
Total human time: ~11.5s (verification + physical interaction)
Total wall clock: ~13.5s
Warm start (Ledger already plugged in, authorized in browser, Stellar app open):
1. Page load: ~600ms
2. Transport enumeration (getDevices): ~30ms (already authorized)
3. Transport open (re-open existing device): ~50ms
4. Stellar app detection (INS_GET_VERSION): ~30ms
5. Ping device (verify responsive): ~30ms
6. getPublicKey (NO display — already verified): ~20ms
7. POST /auth/me (validate JWT): ~200ms
8. Redirect to dashboard: ~50ms
─────────────────────────────────────────────────────
Total: ~1.0s to authenticated dashboard
Transaction signing (Ledger connected, signing a contribution):
1. User fills contribute form, clicks "Submit": (human time)
2. Build XDR from contribution parameters: ~5ms
3. Send XDR to Ledger device: ~20ms
4. User reviews transaction on Ledger screen:
- Source account: 1 second to verify
- Operation type (Payment): 1 second
- Destination: 3 seconds to verify address
- Amount + Asset: 2 seconds
- Fee: 1 second
- Scroll through all fields: 3 seconds
- Total review: ~11 seconds (human time)
5. User presses both buttons to sign: ~1.5s
6. Device signs (Ed25519 in secure element): ~200ms
7. Signed XDR returned: ~30ms
8. Submit signed XDR to backend/Horizon: ~300ms
─────────────────────────────────────────────────────
Total machine time: ~550ms
Total human time: ~12.5s
Total: ~13s per transaction
Worst case (BLE on slow Android, device out of range, reconnect needed):
1. Page load over slow 3G: ~3500ms
2. BLE scanning (user taps "Reconnect"): ~2000ms
3. BLE connection + service discovery: ~1500ms
4. Stellar app init + version read: ~300ms
5. getPublicKey + device confirmation: ~8000ms (human)
6. Auth nonce + sign + verify: ~3000ms
─────────────────────────────────────────────────────
Total wall clock: ~18s (acceptable — user sees progress indicators)
Bundle size impact:
| Measurement | Value |
|---|---|
| Phase 1-3 wallet layer (baseline) | ~133 KB gzipped (Phase 1: 6KB + Phase 2: 121KB + Phase 3: ~6KB) |
| @ledgerhq/hw-transport-webusb | ~14 KB gzipped |
| @ledgerhq/hw-transport-webble | ~10 KB gzipped |
| @ledgerhq/hw-app-str | ~16 KB gzipped |
| Ledger adapter + transport manager + components | ~12 KB gzipped (our code) |
| Total Phase 4 wallet layer | ~52 KB gzipped |
| Delta from Phase 3 | +52 KB gzipped |
| % of total app bundle | ~3% (app bundle ~1.7 MB gzipped after Phase 3) |
Memory usage:
| State | Memory |
|---|---|
| Idle (Ledger code loaded, no device) | ~8 KB (adapter class + transport capability flags) |
| Connection in progress | ~25 KB (transport object + device handle + connection state) |
| Connected (active device, idle) | ~20 KB (transport handle + StellarApp instance + public key + firmware info) |
| Connected + signing | ~35 KB (same + XDR buffer ~2KB + signing state + temporary signature buffer) |
Network requests:
| Operation | Requests | Bytes Transferred |
|---|---|---|
| Transport creation | 0 (local USB/BLE, no network) | 0 |
| Device detection / enumeration | 0 (local) | 0 |
| getPublicKey | 0 (local APDU) | 0 |
| signTransaction | 0 (local APDU) | 0 |
| Auth nonce request (POST /auth/nonce) | 1 HTTP request | ~400 bytes req, ~300 bytes resp |
| Auth verify request (POST /auth/verify) | 1 HTTP request | ~600 bytes req, ~500 bytes resp |
| Firmware version read | 0 (local APDU) | 0 |
Total network bytes per session: <2 KB standard HTTPS API calls. The Ledger adapter itself generates ZERO network requests — all device communication is over local USB or BLE.
CPU profile (critical path):
| Operation | CPU Time |
|---|---|
| TransportWebUSB.create() + USB config | ~20ms |
| TransportWebBLE.create() + BLE service discovery | ~50ms |
| StellarApp initialization | ~5ms |
| getPublicKey (client-side, excluding device) | <1ms |
| signTransaction (client-side, excluding device) | <1ms |
| XDR build + encode | ~3ms |
| XDR decode + validate | ~5ms |
| Device simulator rendering (SVG) | ~8ms per frame |
| Total Moistello CPU overhead | <100ms for entire Ledger flow |
| What was NOT optimized | Why |
|---|---|
| Code splitting Ledger adapter from extension/WC2 adapters | All adapters must be available in the wallet selector simultaneously. The user sees all wallet options at once. Code splitting would add loading spinners when switching wallet types. Bundle increase of ~52KB is well within budget. |
| Pre-connecting to previously authorized Ledger device on page load | Attempting USB connection on page load without user intent would: (1) be blocked by browser (WebUSB requires user gesture), (2) consume device resources unnecessarily (USB bus contention), (3) trigger unexpected device activity (Stellar app opening when user didn't initiate). Connection is deferred to explicit user click. "Reconnect to Ledger" offered as explicit action. |
| Polling for device presence (background enumeration) | Constant USB device enumeration via navigator.usb.getDevices() would waste resources and could trigger unnecessary device wake-ups. Instead: use disconnect events (USB) and periodic pings (BLE, since BLE disconnect events are unreliable in browsers). |
| Lazy loading BLE transport on desktop | Desktop users with USB won't need BLE. However, the code path to detect this requires both to be available at module evaluation time. Solution: import() dynamic import of @ledgerhq/hw-transport-webble only when BLE is actually needed (desktop without USB or mobile). Saves ~10KB initial bundle for majority desktop USB users. |
| Device simulator animation optimization | The device screen simulator shows what the user should see on their Ledger. With reduced-motion preference, animations are disabled, replaced with static text. SVG rendering is already lightweight (<1KB DOM elements). |
| Caching firmware version between sessions | Firmware version is not persisted (session only). Reading it each time costs 50ms — negligible compared to human interaction time. Not caching ensures we always have current version (user could update firmware between sessions). |
Where future optimization yields highest ROI:
- Dynamic
import()for@ledgerhq/hw-transport-webble— saves 10KB for 100% of desktop users (only ~5% of connections will use BLE) - Tree-shake unused Ledger coin apps from
@ledgerhq/hw-app-str(the Stellar app package is Stellar-specific, so this is already minimal) - Pre-compute auth nonce XDR to reduce round trips (combine /auth/nonce + sign into one step)
Tests MUST be written and FAILING before implementation code exists. Sequence:
1. Write test file → run → FAILS (confirms test catches missing code)
2. Write implementation → run → PASSES (confirms code satisfies test)
3. Run ALL previous tests → PASSES (confirms no regression)
For every file in section 1.2:
[ ] Test file exists BEFORE implementation file
[ ] Test file was run and FAILED before implementation was written
[ ] Test file passes after implementation
[ ] All previous phase tests still pass
| Test File | Test Count | Coverage |
|---|---|---|
src/lib/wallet/__tests__/ledger.test.ts |
8 | 100% of Ledger adapter interface |
Ledger adapter test scenarios (8 tests):
| Test | What It Verifies |
|---|---|
ledger.connect() returns public key after device confirmation |
Full mock connect flow — transport created, Stellar app opened, getPublicKey returns valid G... address, adapter stores and returns publicKey correctly |
ledger.connect() with device not found |
Mock transportManager.getOrCreateTransport() returns null (no device). Adapter returns hardware_not_found error with "Is it plugged in and unlocked?" message. |
ledger.connect() with Stellar app not open |
Transport works, but INS_GET_VERSION returns app "Dashboard" not "Stellar". Adapter returns stellar_app_not_open error with instructions. |
ledger.connect() with user rejection on device |
getPublicKey is called with display: true. Mock returns 0x6985 (user rejected). Adapter returns user_rejected error. |
ledger.signTransaction() returns signed XDR |
Valid session, mock stellarApp.signTransaction() returns signature. Adapter merges signature into XDR and returns signed envelope. |
ledger.signTransaction() with wrong source account |
Transaction XDR has source account GXXX... different from connected publicKey GYYY... Adapter returns wrong_account error with both addresses shown. |
ledger.signTransaction() with device disconnect mid-sign |
Mock transport throws DisconnectedDevice error during signTransaction. Adapter returns transport_disconnected error, triggers reconnect prompt. |
ledger.disconnect() clears all state |
Connected session → disconnect() called. Transport closed, stellarApp nulled, publicKey cleared, state store reset to "idle". BroadcastChannel event emitted. |
| Test | System Tested | Real or Mock? |
|---|---|---|
Full Ledger connect → sign → verify flow |
Ledger adapter + transport manager + wallet store | Mocked TransportWebUSB + StellarApp (unit-level mock), real state transitions, real XDR encode/decode |
Device disconnect mid-sign → reconnect → retry |
Ledger adapter + transport manager reconnection logic | Mocked transport disconnect event, reconnection sequence, signature verification after reconnect |
Transport auto-selection: USB preferred → BLE fallback |
Transport manager detection logic | Mocked navigator.usb (available) → selects USB. Mocked navigator.usb missing → falls back to BLE. |
For each integration: was it tested against the REAL system or a mock?
| Test | Mock or Real | Plan for Real Testing |
|---|---|---|
| Full connect → sign → verify flow | Mocked transport + Stellar app | Before release: test with physical Ledger Nano S (USB, firmware v2.1.0), Nano X (USB + BLE, firmware v2.2.0), and Ledger Stax (USB, firmware v2.2.0) on Chrome, Edge, and Brave. Sign a real testnet transaction and verify the signed XDR with Stellar Laboratory. |
| Device disconnect mid-sign | Mocked transport events | Before release: physically unplug USB during signing. Verify adapter detects disconnect, shows reconnect prompt, and signing resumes after reconnect. Test on: Windows 11, macOS 14, Ubuntu 24.04. |
| Transport auto-selection | Mocked navigator | Before release: test on Chrome Android (should select BLE), Chrome Desktop with USB (should select USB), Chrome Desktop without USB but with BLE (should select BLE). |
| Test | Attack Simulated | Mitigation Verified | Status |
|---|---|---|---|
ledger.fake device rejection |
Create a USB device with Ledger VID/PID (0x2c97) but no Ledger firmware. Connect to Moistello. | Adapter's INS_GET_VERSION ping fails (device doesn't respond with valid APDU). Adapter returns device_not_responding error, does NOT expose any user data. Test verifies: adapter does not trust VID/PID alone — requires valid APDU responses. | PENDING |
ledger.unsigned transaction bypass attempt |
Intercept the signTransaction call and inject a pre-signed XDR instead of sending to device. Attempt to have adapter return this XDR without device confirmation. | Adapter verifies that signTransaction completes via actual device call (mocked stellarApp must have been called). Adapter verifies the returned signature corresponds to the sent XDR. Test verifies: adapter accepts only signatures that pass Ed25519 verification against the input XDR and the connected public key. | PENDING |
| # | Scenario | Expected | Status |
|---|---|---|---|
| 1 | Browser doesn't support WebUSB/WebBLE (Firefox, Safari) | isAvailable() returns false. Ledger card in wallet selector shows "Unsupported browser. Try Chrome, Edge, or Brave." Card is visible but disabled (greyed out). | PENDING |
| 2 | User has multiple Ledger devices connected (Nano S + Nano X on USB hub) | WebUSB device chooser shows both. User selects one. Adapter connects to selected device. Second device remains untouched. If user disconnects and reconnects, they may get the other device — this is expected browser behavior. | PENDING |
| 3 | USB cable is charge-only (no data lines) | Device appears in WebUSB (USB connection established), but APDU communication fails (no response to INS_GET_VERSION). Adapter returns device_not_responding with message: "Ledger connected but not responding. Try a different USB cable (some cables are charge-only)." | PENDING |
| 4 | Device is in bootloader mode (firmware update) | INS_GET_VERSION returns bootloader mode instead of normal mode. Adapter returns device_in_bootloader error: "Your Ledger is in bootloader mode. Please exit bootloader by unplugging and reconnecting." | PENDING |
| 5 | User locks Ledger (auto-lock) during active transaction signing | signTransaction APDU returns 0x6982 (security status not satisfied — device locked). Adapter returns device_locked error: "Your Ledger has auto-locked. Please unlock with your PIN and try again." Signing operation is cancelled. | PENDING |
| 6 | User switches away from Stellar app on device mid-connection | During session, user navigates to another app on Ledger (e.g., Bitcoin). Next operation (signTransaction) sends APDU → Stellar app not active → error returned. Adapter detects app switch and returns stellar_app_not_open: "Please open the Stellar app on your Ledger." | PENDING |
| 7 | BLE connection drops due to range (user walks away) | Nano X out of BLE range (~10m). Transport ping starts failing. After 3 failed pings: connectionState → "disconnected". Auto-reconnect attempts begin. If user comes back in range within 60s: reconnect succeeds. If not: session expired, manual reconnect. | PENDING |
| 8 | Ledger Stellar app version is outdated (v3.2.0 — no transaction detail display) | Firmware check returns warning: "Stellar app v3.3.0+ required for transaction detail display. Update via Ledger Live." Adapter still works (signing functions) but UI shows warning badge. User is not blocked but is informed of reduced security. | PENDING |
| 9 | User has Nano S with firmware v1.6 (outdated, no app auto-open) | connect() initiates, Stellar app not found. Adapter returns stellar_app_not_open. Instructions: "Manually navigate to the Stellar app on your Ledger Nano S using the buttons." Additionally: "Your firmware (v1.6) is outdated. Update to v2.0+ via Ledger Live for improved app auto-open support." | PENDING |
| 10 | Transaction with 10 operations (complex path payment) is sent to Ledger for signing | XDR is larger (~1.5KB). Ledger Stellar app displays each operation sequentially. User must scroll through all 10 operations. 120s timeout should be sufficient. If user confirms: all operations signed. Test verifies: large XDR handled correctly, no truncation or timeout. | PENDING |
[ ] All Phase 1 tests still pass (25 tests):
- types.test.ts (3 tests)
- registry.test.ts (8 tests)
- session-manager.test.ts (10 tests)
- freighter.test.ts (2 tests)
- xbull.test.ts (2 tests)
[ ] All Phase 2 tests still pass (15 unit + 4 integration + 3 security = 22 tests)
[ ] All Phase 3 tests still pass (TBD — Phase 3 must be complete before Phase 4 regression check)
[ ] Ledger adapter registered in registry alongside Phase 1-3 adapters
[ ] WalletSelector renders Ledger card alongside extension, WC2, and passkey cards
[ ] Feature flag off → Ledger adapter never loaded, Phase 1-3 behavior unchanged
[ ] Existing Freighter, WC2, Passkey login paths work unchanged (feature flag off)
[ ] BroadcastChannel cross-tab sync includes Ledger session events
[ ] Browser detection logic doesn't interfere with WC2/deep-link detection
USER ON DESKTOP — CONNECTS WITH LEDGER VIA USB
User lands on /login
│
├─ Sees: WalletSelector grid (Phases 1-4)
│ ┌─────────────────────────────────────────┐
│ │ 💻 Ledger [Hardware Wallet] │ ← "Hardware" badge
│ │ Maximum security for your XLM/USDC │
│ │ DAO treasuries and large contributions│
│ │ [Connect →] │
│ └─────────────────────────────────────────┘
│
├─ User clicks [Connect →]
│ ├─ Ledger connection wizard modal opens
│ │ ┌─────────────────────────────────────┐
│ │ │ Connect Your Ledger │
│ │ │ │
│ │ │ Step 1 of 3 │
│ │ │ │
│ │ │ ┌───────────────────┐ │
│ │ │ │ 🔌 Connect your │ │
│ │ │ │ Ledger via USB │ │
│ │ │ │ │ │
│ │ │ │ [Device Sim] │ │
│ │ │ └───────────────────┘ │
│ │ │ │
│ │ │ [Device simulator showing: │
│ │ │ ┌──────────────────┐ │
│ │ │ │ Dashboard │ │
│ │ │ │ ───────────── │ │
│ │ │ │ Stellar │ ← User │
│ │ │ │ Bitcoin │ sees this │
│ │ │ │ Ethereum │ on device │
│ │ │ └──────────────────┘ │
│ │ │ ] │
│ │ │ │
│ │ │ [Cancel] │
│ │ └─────────────────────────────────────┘
│ │
│ ├─ Browser shows device chooser (native chrome dialog)
│ │ ┌──────────────────────┐
│ │ │ Select a device │
│ │ │ │
│ │ │ ┌──────────────────┐ │
│ │ │ │ Ledger Nano X │ │
│ │ │ │ Ledger SAS │ │
│ │ │ └──────────────────┘ │
│ │ │ [Connect] │
│ │ └──────────────────────┘
│ │
│ ├─ User selects "Ledger Nano X" → [Connect]
│ │
│ ├─ Modal advances to Step 2:
│ │ ┌─────────────────────────────────────┐
│ │ │ Connect Your Ledger │
│ │ │ │
│ │ │ Step 2 of 3 ✓ Connected │
│ │ │ │
│ │ │ ┌───────────────────┐ │
│ │ │ │ 📱 Open the │ │
│ │ │ │ Stellar app │ │
│ │ │ │ │ │
│ │ │ │ On your Ledger: │ │
│ │ │ │ Navigate to the │ │
│ │ │ │ Stellar app icon │ │
│ │ │ │ Press both │ │
│ │ │ │ buttons to open │ │
│ │ │ └───────────────────┘ │
│ │ │ │
│ │ │ [Device sim showing: │
│ │ │ ┌──────────────────┐ │
│ │ │ │ │ │
│ │ │ │ Stellar │ │
│ │ │ │ ───────────── │ │
│ │ │ │ Waiting for │ │
│ │ │ │ commands... │ │
│ │ │ │ │ │
│ │ │ └──────────────────┘ │
│ │ │ ] │
│ │ │ │
│ │ │ [Back] [Cancel] │
│ │ └─────────────────────────────────────┘
│ │
│ ├─ User navigates to Stellar app on Ledger, opens it
│ ├─ Adapter detects Stellar app active → auto-advances
│ │
│ ├─ Modal advances to Step 3:
│ │ ┌─────────────────────────────────────┐
│ │ │ Verify Your Address │
│ │ │ │
│ │ │ Step 3 of 3 ✓ Ledger Ready │
│ │ │ │
│ │ │ Confirm your public key │
│ │ │ on your Ledger's screen: │
│ │ │ │
│ │ │ ┌──────────────────────┐ │
│ │ │ │ GABC...XYZ │ │
│ │ │ │ │ │
│ │ │ │ [Copy] │ │
│ │ │ └──────────────────────┘ │
│ │ │ │
│ │ │ [Device sim showing: │
│ │ │ ┌──────────────────┐ │
│ │ │ │ Address │ │
│ │ │ │ ──────────── │ │
│ │ │ │ GABC... │ │
│ │ │ │ ...XYZ │ │
│ │ │ │ │ │
│ │ │ │ [✓ Approve] │ │
│ │ │ │ [✗ Reject] │ │
│ │ │ └──────────────────┘ │
│ │ │ ] │
│ │ │ │
│ │ │ Press both buttons to Approve │
│ │ │ on your Ledger │
│ │ │ │
│ │ │ [Cancel] │
│ │ └─────────────────────────────────────┘
│ │
│ ├─ User verifies address on device screen matches Moistello
│ ├─ User presses both buttons → "Approve"
│ ├─ Modal: ✓ "Connected! Public key verified."
│ ├─ Public key displayed with hardware badge
│ │
│ └─ Auth flow auto-advances:
│ ├─ "Verify your wallet" — sign auth nonce
│ ├─ Auth XDR sent to Ledger
│ ├─ Device shows: "Review Transaction" with operation details
│ ├─ User reviews: "Moistello Auth" → operation name correct
│ ├─ User confirms on device
│ └─ ✓ Authenticated. Redirecting to dashboard...
│
└─ Land on /dashboard. Hardware wallet connected.
Navbar shows: [💻 GABC...XYZ] with hardware wallet icon
Metrics from login to authenticated via Ledger:
- Clicks: 2 (Connect → Verify/Sign)
- Device interactions: 4 (plug in USB, open Stellar app, confirm address, sign auth)
- Physical confirmations: 2 (both-button press for address, both-button press for sign)
- Time (experienced user, device already plugged in + app open): ~5-7 seconds
- Time (new user, needs to plug in, unlock, find app): ~30-45 seconds
USER ON MOBILE — CONNECTS LEDGER NANO X VIA BLUETOOTH
User opens moistello.io on Chrome Android
│
├─ WalletSelector detects mobile browser
│ ├─ Extension adapters: "Not available" (no extensions on mobile)
│ ├─ WC2 adapter: "Available"
│ ├─ Ledger adapter: "Available" (BLE detected on Chrome Android)
│ └─ Passkey adapter: "Available"
│
├─ User taps "Connect Ledger"
│ ├─ Ledger connection wizard opens (mobile-optimized)
│ │ ┌─────────────────────────────────────┐
│ │ │ Connect Your Ledger │
│ │ │ │
│ │ │ Step 1 of 4 │
│ │ │ │
│ │ │ ┌───────────────────┐ │
│ │ │ │ 📱 Turn on │ │
│ │ │ │ Bluetooth │ │
│ │ │ │ │ │
│ │ │ │ On your phone: │ │
│ │ │ │ Settings → │ │
│ │ │ │ Bluetooth → ON │ │
│ │ │ └───────────────────┘ │
│ │ │ │
│ │ │ [Continue →] │
│ │ └─────────────────────────────────────┘
│ │
│ ├─ User enables Bluetooth, taps [Continue →]
│ │
│ ├─ Step 2:
│ │ ┌─────────────────────────────────────┐
│ │ │ Connect Your Ledger │
│ │ │ │
│ │ │ Step 2 of 4 ✓ Bluetooth ON │
│ │ │ │
│ │ │ ┌───────────────────┐ │
│ │ │ │ 🔵 Pair your │ │
│ │ │ │ Nano X │ │
│ │ │ │ │ │
│ │ │ │ On your Nano X: │ │
│ │ │ │ 1. Unlock with │ │
│ │ │ │ your PIN │ │
│ │ │ │ 2. Open Control │ │
│ │ │ │ Center (hold │ │
│ │ │ │ both buttons) │ │
│ │ │ │ 3. Enable BLE │ │
│ │ │ └───────────────────┘ │
│ │ │ │
│ │ │ [Start Pairing →] │
│ │ └─────────────────────────────────────┘
│ │
│ ├─ User taps [Start Pairing →]
│ ├─ Browser shows Bluetooth device chooser
│ ├─ User selects "Nano X XXXX"
│ ├─ Pairing request appears on Ledger screen: "Pair with Moistello?"
│ ├─ User confirms pairing on device
│ │
│ ├─ Steps 3-4: Same as USB flow (open Stellar app, confirm address)
│ │
│ └─ ✓ Connected via Bluetooth
│
└─ Auth flow follows same path as USB
| Error | User Sees | Next Action |
|---|---|---|
| Browser unsupported (Firefox, Safari) | "Ledger requires Chrome, Edge, or Brave browser for USB/Bluetooth connection. Please switch browsers or use WalletConnect / Passkey instead. [Connect with WalletConnect →]" | Switch browser or use alternative wallet |
| Device not found (not plugged in) | "Ledger not detected. Please plug in your device via USB and ensure it is unlocked. On Windows, you may need to install Ledger Live for USB drivers. [Try Again]" | Plug in and unlock Ledger, then retry |
| Stellar app not open | "Please open the Stellar app on your Ledger. Navigate to the Stellar icon using the buttons and press both to open. [I've Opened It →]" | Open Stellar app, then click retry |
| Stellar app not installed | "The Stellar app is not installed on this Ledger. Open Ledger Live → Manager → Search 'Stellar' → Install. Then come back and try again. [Try Again]" | Install Stellar app via Ledger Live, then retry |
| Device locked (PIN not entered) | "Your Ledger is locked. Enter your PIN on the device to unlock it. [Try Again]" | Enter PIN on device, then retry |
| User rejected address on device | "Address verification cancelled. Please approve the address on your Ledger to confirm it matches. [Try Again]" | Re-initiate address display, then approve |
| User rejected transaction on device | "Transaction cancelled. You chose not to sign the transaction on your Ledger. [Try Again] [Cancel and Go Back]" | Review transaction and retry, or cancel action |
| Operation timed out (user didn't confirm) | "Confirmation timed out. Please respond to the prompt on your Ledger within 2 minutes. Tip: have your Ledger nearby and ready before initiating a transaction. [Retry]" | Retry and confirm within timeout |
| USB disconnected during operation | "Ledger disconnected. Check your USB cable — it may be loose or charge-only (some cables don't transmit data). Reconnect and try again. [Reconnect]" | Secure USB connection, then retry |
| BLE connection lost | "Bluetooth connection lost. Make sure your Ledger Nano X is powered on and within range (~10 meters). [Reconnect]" | Bring device in range, then retry |
| Device in bootloader mode | "Your Ledger is in bootloader mode (firmware update in progress?). Exit bootloader by unplugging and reconnecting. [Try Again]" | Unplug/replug to exit bootloader |
| Firmware outdated (warning, not error) | "Your Ledger firmware (v1.6.1) is outdated and may have known security vulnerabilities. We recommend updating to v2.0+ via Ledger Live. You can continue, but the experience may be degraded." | Continue (warning only) or update firmware first |
| Wrong account (transaction for different address) | "This transaction is for account ending in ...{XYZ} but your Ledger is connected with account ending in ...{ABC}. Please connect the correct Ledger account or switch wallets. [Switch Wallet →]" | Connect correct Ledger or use different wallet |
| Mainnet confirmation prompt | "You are about to sign a MAINNET transaction with real funds from your Ledger. Amount: {amount} {asset}. Destination: {address}. Please confirm this is intentional. [Cancel] [I Understand — Sign on Mainnet]" | Review carefully, then confirm or cancel |
| State | Visual |
|---|---|
| Detecting browser capabilities | WalletSelector: Ledger card shows shimmer + "Checking compatibility..." |
| Searching for Ledger device (USB) | Ledger wizard Step 1: pulsing icon + "Looking for your Ledger..." with browser native device chooser |
| Scanning for Nano X (BLE) | Ledger wizard Step 2: scanning animation + "Searching for Ledger Nano X via Bluetooth..." |
| Establishing USB connection | "Connecting to Ledger..." + progress bar (quick: ~200ms) |
| Opening Stellar app | "Opening Stellar app..." + spinner + device sim showing app loading screen |
| Waiting for address confirmation | "Waiting for confirmation on your Ledger..." + pulsing address display + device sim showing "Approve / Reject" screen |
| Sending transaction to device | "Sending transaction to Ledger..." + spinner + device sim transitioning to review screen |
| Waiting for transaction signing | "Review transaction on your Ledger..." + pulsing icon + device sim showing first operation |
| Verifying signed XDR | "Verifying signature..." + spinner (~200ms) |
| Reconnection in progress | Banner overlay: "Ledger disconnected — attempting to reconnect..." with progress bar and timeout counter |
| BLE reconnection | "Looking for your Nano X..." + scanning animation + "Make sure it's powered on and nearby" |
[ ] Keyboard navigation: can the entire Ledger flow be completed without a mouse?
- Tab to Ledger card in wallet selector → Enter to open wizard
- Tab through wizard steps (Back, Cancel, Continue, Connect buttons)
- Tab to "Copy address" button → Enter to copy
- Tab to retry/error buttons → Enter to retry
- Close modal with Escape key
- Note: PHYSICAL DEVICE INTERACTION IS INHERENTLY TACTILE
The Ledger device itself is keyboard-navigable (buttons for navigation + confirmation).
The web flow is fully keyboard-accessible, but the user MUST physically interact with
the device. This is a security requirement, not an accessibility limitation.
[ ] Screen reader: was the flow tested with VoiceOver / NVDA?
- Ledger card: aria-label="Connect with Ledger hardware wallet — maximum security for large holdings"
- Wizard title: aria-labelledby="ledger-wizard-title"
- Connection state announced via aria-live="polite" region:
"Step 1: Plug in your Ledger via USB."
"Ledger detected. Opening Stellar app."
"Address displayed on device. Press both buttons to confirm."
"Transaction sent to device. Review on your Ledger screen."
- Device simulator: aria-hidden="true" (decorative — the real info is on the device)
with aria-describedby pointing to text instructions
- Success/error messages: role="alert" for immediate announcement
- Address display: aria-label="Your Ledger public key is G-A-B-C... X-Y-Z.
Verify this matches the display on your device."
[ ] Color contrast: do all text elements meet WCAG AA (4.5:1)?
- Ledger wizard background (#FFFFFF) with text (#1A1A1A): ratio 17.4:1 ✓
- "Hardware" badge (#7C3AED on #F5F3FF): ratio 5.88:1 ✓
- Step indicator active (#2563EB on white): ratio 4.61:1 ✓
- Error text (#DC2626 on #FEF2F2): ratio 4.52:1 ✓
- Warning text (#D97706 on #FFFBEB): ratio 4.57:1 ✓
- Device simulator text (#FFFFFF on #000000): ratio 21:1 ✓
[ ] Focus management: is focus trapped in modals, returned on close?
- Ledger wizard: focus trapped, tab cycles through all interactive elements
- Device simulator: NOT focusable (decorative — no interaction needed)
- Modal close: focus returns to Ledger card in wallet selector
- Successful connection: modal auto-closes, focus moves to auth verification step
[ ] Reduced motion: does the UI respect prefers-reduced-motion?
- Connection animations (pulsing icons, progress bars): disabled → static state text
- Device simulator screen transitions: instant instead of animated
- Modal open/close transitions: instant instead of animated
- Spinner animations: replaced with static "Loading..." text
[ ] Touch targets: are all interactive elements >=44px?
- Ledger card in wallet selector: height 80px ✓
- "Connect" button: 48px x 140px ✓
- Wizard "Continue" button: 48px x 120px ✓
- Wizard "Cancel" button: 44px x 100px ✓
- "Copy address" button: 44px x 80px ✓
- Retry buttons: 48px x 100px ✓
- "I Understand — Sign on Mainnet" confirmation button: 48px x 200px ✓
[ ] Was the flow tested on: iPhone Safari, Android Chrome, iPad?
iPhone Safari: Ledger NOT supported (no WebUSB, limited WebBLE).
Wallet selector shows Ledger card greyed out: "Requires Chrome, Edge, or Brave."
User is directed to WalletConnect or Passkey instead.
Android Chrome: Ledger Nano X via BLE fully supported.
Web Bluetooth API available. Tested with Nano X firmware v2.2.0.
Steps: enable Bluetooth → scan → pair → open Stellar app → confirm → sign.
iPad: Limited. iPadOS Safari does not support WebUSB. WebBLE support is unreliable.
Ledger card shows greyed out on iPad.
Recommendation for iPad users: use WalletConnect with Ledger Live mobile app.
[ ] Was the flow tested with: slow 3G, offline, spotty WiFi?
Slow 3G: Ledger connection unaffected (local USB/BLE, no network dependency).
Auth API calls (POST /auth/nonce, /auth/verify) use HTTP — works on 3G.
BLE scanning unaffected by network speed.
Offline: Ledger connection works (local transport). Auth flow fails (no backend).
User sees: "Cannot authenticate while offline. Connect to the internet and try again."
Spotty WiFi: Same as offline for auth — user may need to wait for connectivity.
Ledger device communication is unaffected by network conditions (USB/BLE is local).
[ ] Does the flow work when the wallet is on a DIFFERENT device?
NO — this is inherent to hardware wallet design.
The Ledger MUST be physically connected to the browser (USB) or in BLE range.
Hardware wallets are NOT cross-device wallets.
For cross-device Ledger usage: user can use Ledger Live with WalletConnect (Phase 2)
to bridge the Ledger to Moistello from a mobile device. This is the recommended
path for users who want to use their Ledger with Moistello on a device without USB.
[ ] Does the QR/deep link flow work for WalletConnect pairing?
Not applicable to Phase 4 — Ledger uses direct USB/BLE, not WalletConnect.
However: Ledger Live supports WalletConnect (covered in Phase 2).
All new user-facing strings are in locale files. The Ledger adapter layer itself contains ZERO user-facing strings — all display text comes from components which read locale files.
Locales updated/added for Phase 4 (6 languages: en, fr, sw, es, pt, hi):
| Key | English | Context |
|---|---|---|
ledger.name |
"Ledger" | Proper noun — not translated |
ledger.category |
"Hardware Wallet" | Category badge |
ledger.description |
"Maximum security for your XLM/USDC — private key never leaves the device" | Card subtitle |
ledger.connect |
"Connect Ledger" | Primary CTA |
ledger.wizard_title |
"Connect Your Ledger" | Wizard modal title |
ledger.step_plugin_title |
"Plug In Your Ledger" | Step 1 title (USB) |
ledger.step_plugin_body |
"Connect your Ledger to your computer using the USB cable." | Step 1 body |
ledger.step_ble_title |
"Enable Bluetooth" | Step 1 title (BLE) |
ledger.step_ble_body |
"Turn on Bluetooth on your phone and on your Ledger Nano X." | Step 1 body |
ledger.step_app_title |
"Open Stellar App" | Step 2 title |
ledger.step_app_body |
"On your Ledger, navigate to the Stellar app icon and press both buttons to open it." | Step 2 body |
ledger.step_app_not_found |
"Stellar app not found. Install it from Ledger Live → Manager." | App missing |
ledger.step_unlock |
"Unlock your Ledger by entering your PIN on the device." | Device locked prompt |
ledger.step_verify_title |
"Verify Your Address" | Step 3 title |
ledger.step_verify_body |
"Confirm the address on your Ledger screen. Press both buttons to approve." | Step 3 body |
ledger.step_verify_match |
"Does this match your Ledger screen?" | Address verification prompt |
ledger.confirm_transaction |
"Review the transaction on your Ledger. Press both buttons to sign." | Signing prompt |
ledger.physical_confirm |
"Press both buttons on your Ledger to confirm." | Physical confirmation prompt |
ledger.connected |
"Connected! Hardware wallet verified." | Success state |
ledger.signing |
"Signing on Ledger..." | Signing in progress |
ledger.waiting_confirmation |
"Waiting for confirmation on your Ledger..." | Awaiting user |
ledger.transport_usb |
"Connected via USB" | Transport indicator |
ledger.transport_ble |
"Connected via Bluetooth" | Transport indicator |
ledger.error.unsupported_browser |
"Ledger requires Chrome, Edge, or Brave browser." | Error |
ledger.error.device_not_found |
"Ledger not detected. Is it plugged in and unlocked?" | Error |
ledger.error.app_not_open |
"Please open the Stellar app on your Ledger." | Error |
ledger.error.device_locked |
"Please unlock your Ledger with your PIN." | Error |
ledger.error.user_rejected |
"Connection cancelled on Ledger." | Error |
ledger.error.timeout |
"Confirmation timed out. Please try again." | Error |
ledger.error.transport_disconnected |
"Ledger disconnected. Check your cable or Bluetooth connection." | Error |
ledger.error.firmware_old |
"Firmware update recommended. Your firmware (v{version}) is outdated." | Warning |
ledger.error.stellar_app_old |
"Stellar app update recommended. Your app (v{version}) is outdated." | Warning |
ledger.error.wrong_account |
"This transaction is for a different account. Switch to the correct account." | Error |
ledger.error.mainnet_confirm |
"You are about to sign a MAINNET transaction with real funds." | Confirmation |
ledger.error.mainnet_confirm_detail |
"Amount: {amount} {asset}. Destination: {address}. Proceed?" | Confirmation detail |
ledger.retry |
"Try Again" | Retry CTA |
ledger.reconnect |
"Reconnect" | Reconnect CTA |
ledger.cancel |
"Cancel" | Cancel CTA |
ledger.back |
"Back" | Back navigation |
ledger.continue |
"Continue" | Continue CTA |
ledger.sign_mainnet |
"I Understand — Sign on Mainnet" | Mainnet confirmation CTA |
ledger.device_sim.alt |
"What you should see on your Ledger screen" | Screen reader alt text for device simulator |
Wallet and product names are NOT translated (proper nouns): "Ledger", "Nano S", "Nano X", "Stax", "Flex", "Stellar".
RTL languages: Wizard steps use CSS logical properties for RTL support. The device simulator is a visual reference that mirrors the physical device orientation (not affected by text direction). Step indicator numbers remain LTR (numerals).
| Metric | Type | Labels | Purpose |
|---|---|---|---|
ledger_connect_attempts_total |
Counter | {outcome: "success"|"device_not_found"|"user_rejected"|"error"} |
Track connection success rate |
ledger_connect_duration_ms |
Histogram | {transport: "usb"|"ble"} |
Track time from connect click to public key received |
ledger_sign_attempts_total |
Counter | {operation: "signTransaction"|"signMessage", outcome: "success"|"timeout"|"rejected"|"disconnected"|"error"} |
Track signing outcomes |
ledger_sign_duration_ms |
Histogram | {operation} |
Track signing round-trip time (excluding user review time) |
ledger_transport_disconnects_total |
Counter | {transport: "usb"|"ble", cause: "user_unplug"|"range"|"error"} |
Track unexpected disconnects |
ledger_firmware_versions |
Gauge | {firmware: string, stellar_app: string} |
Distribution of firmware/app versions in the field |
ledger_warnings_total |
Counter | {type: "firmware_outdated"|"app_outdated"} |
Track how many users are on outdated firmware |
ledger_session_duration_seconds |
Histogram | (none) | Track typical Ledger session length |
ledger_reconnect_attempts_total |
Counter | {outcome: "success"|"failure"} |
Auto-reconnect success rate |
ledger_unsupported_browser_total |
Counter | {browser: string} |
Count users blocked by browser incompatibility |
Alerts & Runbooks:
| Alert | Condition | Severity | Runbook |
|---|---|---|---|
LedgerConnectFailureRateHigh |
>30% of Ledger connect attempts fail within 10 minutes | P3 (warning) | Check: are users on unsupported browsers? Is WebUSB broken by Chrome update? Check connect error distribution (device_not_found vs app_not_open vs user_rejected). If device_not_found spikes: check if there's a Windows USB driver issue. |
LedgerSignTimeoutRateHigh |
>20% of sign operations timeout within 10 minutes | P3 (warning) | Check: are timeouts from users not confirming, or from transport issues? If transport: check disconnect rates. If user: UI might be unclear — users don't know to press buttons. Review device simulator accuracy. |
LedgerDisconnectRateSpike |
Transport disconnects >5/minute sustained for >5min | P2 (high) | Check: USB driver issue? Browser WebUSB bug? Correlate with Chrome version changes. Rollout mitigation: recommend users try WalletConnect with Ledger Live as fallback. |
LedgerFirmwareOutdated |
>10% of Ledger users on firmware <2.0.0 | P4 (info) | Run education campaign: show prominent update reminder in app for these users. Link to Ledger Live download. No immediate action needed — advisory only. |
LedgerUnsupportedBrowser |
Ledger card shown but disabled for users who don't know they need Chrome | P4 (info) | Check analytics: what browsers are hitting the "Ledger requires Chrome" error? Consider targeted messaging for Firefox/Safari users. |
NEXT_PUBLIC_FEATURE_HARDWARE_WALLET=true → Ledger adapter loads, wallet selector shows Ledger option
NEXT_PUBLIC_FEATURE_HARDWARE_WALLET=false → Ledger adapter never imported (tree-shaken), wallet selector unchanged
NEXT_PUBLIC_FEATURE_HARDWARE_WALLET_BLE=true → BLE transport enabled (default on)
NEXT_PUBLIC_FEATURE_HARDWARE_WALLET_BLE=false → BLE disabled → Nano X BLE users directed to desktop USB or WalletConnect
NEXT_PUBLIC_LEDGER_DERIVATION_PATH="44'/148'/0'" → Default BIP-44 path for Stellar
(never change this in production — hardcoded for security)
Rollback procedure:
1. Set NEXT_PUBLIC_FEATURE_HARDWARE_WALLET=false in deployment config
2. Redeploy (or edge config update if using Vercel/Cloudflare)
3. Existing Ledger connections: USB/BLE handle disconnected — no persistent state
4. New visitors see wallet selector without Ledger option (Phase 1-3 behavior)
Time to rollback: <2 minutes (env var change + CDN cache purge)
Partial rollback (BLE only):
1. Set NEXT_PUBLIC_FEATURE_HARDWARE_WALLET_BLE=false
2. Redeploy
3. Desktop USB users unaffected. Mobile BLE users see "Ledger requires desktop Chrome with USB."
| Failure | User Impact | Business Impact | Recovery Time |
|---|---|---|---|
| WebUSB API removed from Chrome | All desktop Ledger connections break. Adapter returns unsupported_browser error. | Ledger users cannot sign in or transact. Mobile BLE users unaffected. Affects ~60% of Ledger users (desktop). | No automated recovery. Users must switch to WalletConnect with Ledger Live or use a different wallet. Monitor Chrome platform status for WebUSB changes. |
| Ledger Stellar app has APDU protocol change | Our @ledgerhq/hw-app-str version may be incompatible if Ledger updates the Stellar app protocol. signTransaction/getPublicKey fails with protocol errors. | All Ledger connections fail. Users see "Stellar app communication error. Update your Ledger app or contact support." | Update @ledgerhq/hw-app-str to latest version → deploy. ~30 minutes if prepared. Monitor Ledger Stellar app release notes. |
| Windows USB driver prevents WebUSB access | On some Windows configurations, Ledger USB device is claimed by the HID driver and WebUSB cannot claim the interface. | Affected Windows users cannot connect Ledger via USB. BLE option if Nano X available. | User workaround: install Ledger Live (provides correct driver) or use Zadig to replace driver. Cannot fix from our side — browser-level limitation. |
| BLE pairing fails on Android | Some Android versions/ROMs have broken Web Bluetooth implementation. Pairing never completes or drops immediately. | Cannot use Ledger on affected Android devices. User directed to desktop. | No automated recovery. User can copy the pairing link and try WalletConnect with Ledger Live mobile-to-mobile. |
| User's Ledger firmware is bricked/corrupted | Device won't boot. Cannot connect at all. | User cannot access their funds through Moistello. All wallet options still available. | User must restore Ledger from seed phrase (24 words) via Ledger Live. Funds safe on Stellar blockchain. Once restored, reconnect. |
| Device auto-locks during transaction review | User starts reviewing transaction, device locks after 10 min (configurable). signTransaction returns 0x6982. | Transaction fails. User must unlock and restart signature. Lost ~30 seconds. | Async unlock → retry. No data loss. |
| Wrong derivation path entered by developer | If derivation path is ever made configurable and set incorrectly, getPublicKey returns a DIFFERENT address than user expects. | User sees different address than their Ledger Live / other wallets → confusion → support tickets. | Derivation path is HARDCODED ("44'/148'/0'") and never user-configurable. This failure mode is prevented by design. |
| @ledgerhq bundle includes Node.js Buffer polyfill issues | Next.js Buffer polyfill may fail in specific edge cases (SSR, edge runtime). APDU command construction crashes. | Ledger adapter fails silently during operation. | Pre-implementation: verify Buffer polyfill works in target environments. If issues: use Uint8Array directly with @ledgerhq/hw-transport's low-level APIs. |
| Multiple browser tabs competing for same Ledger device | Tab A and Tab B both try to communicate with Ledger. USB claim is exclusive — second tab fails. | Second tab shows "Ledger is in use by another tab. Close other Moistello tabs and try again." | User closes other tabs, retries. BroadcastChannel coordination can prevent this (Tab B knows Tab A has the device). Phase 6 enhancement. |
| User connects Ledger but has no XLM (unfunded account) | Public key retrieved successfully. Backend checks Stellar account — unfunded. | "Ledger connected, but account GABC... has no funds. You'll need XLM to use Moistello. [How to get XLM →]" | User funds account through exchange or friendbot (testnet), then retries. |
| Gate | Status | Evidence |
|---|---|---|
| All 3 new dependency packages installed (exact versions pinned) | PENDING | |
| All 7 files created with documented purpose | PENDING | |
| Ledger adapter implements 100% of WalletAdapter interface from Phase 1 | PENDING | |
| SSR safety audit completed for every planned file (no module-level browser API access) | PENDING | |
| Dependency compatibility check completed (3 packages, all pinned, 0 CVEs) | PENDING | |
| Bundle size increase: <50KB gzipped (target: ~40KB) | PENDING | |
| 8 unit tests passing, 0 skipped | PENDING | |
| 3 integration tests passing (connect→sign→verify, disconnect mid-sign, transport auto-selection) | PENDING | |
| 2 security tests passing (fake device rejection, unsigned transaction bypass) | PENDING | |
| 10 edge case scenarios verified | PENDING | |
| Test-driven order verified: tests written and FAILING before implementation | PENDING | |
| USB connection: from click to "Connected" <60 seconds with experienced user | PENDING | |
| Transaction signing: from click to signed <15 seconds (including human review time) | PENDING | |
| Every error has: user-facing message + exact next action instructions | PENDING | |
| Feature flag tested: off → Ledger code tree-shaken, wallet selector unchanged | PENDING | |
| Feature flag tested: on → Ledger card appears in wallet selector, connection flow works | PENDING | |
| Rollback tested: <2 minutes via feature flag | PENDING | |
| Ledger connection state machine handles all transitions (8 states) | PENDING | |
| Transport lifecycle: USB open/close, BLE connect/disconnect, auto-reconnect logic verified | PENDING | |
| All Ledger error codes mapped to user-friendly messages | PENDING | |
| Device simulator renders correct screen for each connection state | PENDING | |
| Cross-tab sync: Ledger connect in Tab A → Tab B reflects connection | PENDING | |
| Firmware version check: warns on outdated firmware, doesn't block connection | PENDING | |
| All Ledger strings externalized to locale files (6 languages, 42 keys) | PENDING | |
| Keyboard navigation: Ledger wizard fully keyboard-operable | PENDING | |
| Screen reader: wizard has aria labels, live region for connection state changes | PENDING | |
| Security level tags assigned: all security-critical functions documented with upgrade paths | PENDING | |
| All Phase 1-3 tests still pass (regression check) | PENDING | |
| Private key confirmed: NEVER leaves secure element, no path in code to access it | PENDING | |
| Physical confirmation required: every signature requires both-button press on device | PENDING | |
| Source account verification: transaction source always checked against connected public key | PENDING | |
| Mainnet safety gate: explicit user confirmation before any mainnet signature | PENDING | |
| All transport types handled: USB (desktop), BLE (mobile/desktop), graceful fallback | PENDING | |
| Dependencies audited: 0 known CVEs in @ledgerhq/* ecosystem for exact pinned versions | PENDING |
| Role | Name | Verified | Date |
|---|---|---|---|
| Implementation | □ | ||
| Code Review | □ | ||
| Security Review | □ | ||
| UX Review | □ | ||
| Product | □ |
Final Status: PENDING — Documentation complete, implementation pending
Open Blockers:
- Documentation complete — all sections 1-9 fully populated with corrected template (SSR audit, dependency check, test-driven order, security level tags, readiness gates)
- All Ledger algorithms documented with pseudocode + complexity + failure modes + crypto citations (device detection, connect+unlock, transaction signing, message signing, transport lifecycle, firmware version check)
- All tests described (8 unit + 3 integration + 2 security = 13 tests — see sections 5.1-5.3)
- All performance profiles documented (cold start, warm start, signing, worst-case BLE)
- Dependency compatibility verified: all 3 packages pinned to exact version, 0 CVEs
- SSR safety audit completed for all 4 new source files
- Security level tags assigned to all Ledger security-critical functions
- Desktop USB and Mobile BLE UX flows fully documented with device simulator concept
- i18n keys defined (42 new keys for 6 languages)
- Alerts and runbooks defined for Ledger-specific failures (5 alerts)
- All 10 edge case scenarios defined with expected behavior
- Transport lifecycle and auto-reconnect algorithm documented
- All failure modes analyzed (USB driver, BLE range, firmware, app state, device lock)
- Attack surface comprehensively analyzed (WebUSB, WebBLE, MITM, supply chain, fake devices, replay, derivation manipulation, firmware downgrade)
Hardware Wallet Coverage Summary (Phase 4 unlocks these Ledger models):
| Model | Connection | Firmware | Stellar App | Supported? |
|---|---|---|---|---|
| Ledger Nano S | USB only | v2.1.0+ | v3.3.0+ | YES |
| Ledger Nano S Plus | USB only | v2.1.0+ | v3.3.0+ | YES |
| Ledger Nano X | USB + BLE | v2.2.0+ | v3.3.0+ | YES |
| Ledger Stax | USB + BLE | v2.2.0+ | v3.3.0+ | YES |
| Ledger Flex | USB + BLE | v2.2.0+ | v3.3.0+ | YES |
Total reachable user base: ~6M+ Ledger device owners (all models). ~5M+ with firmware >=2.0.0.