docs(security): document and test threat model for Freighter and Ledger flows (#841)

[CathyZaks]

Header

• Issue: [2026 Security] Document and test threat model for Freighter and Ledger flows #841
• Target area: security docs and e2e wallet fixtures
• Branch: fix/issue-841-threat-model-freighter-ledger

Problem

The dashboard previously lacked formal threat model matrices and end-to-end fixture coverage for browser extension (Freighter) and hardware wallet (Ledger) flows. Crucial attack vectors—such as wallet provider spoofing, DOM API tampering, derivation path manipulation, deceptive phishing memos/origins, and cross-network signature replays—were not documented or systematically guarded against across input sanitization, unsupported runtime detection, and failure recovery.

Solution

1. Threat Model Documentation:
   • Published comprehensive Freighter Threat Model Matrix and Ledger Hardware Wallet Threat Model Matrix in SECURITY.md covering wallet spoofing, phishing, malicious dApps, and failure states.
   • Authored dedicated technical architecture and developer guidance in docs/security/wallet-threat-model.md detailing trust boundaries, invalid input handling, unsupported browser behavior (WebUSB/WebHID in Chromium vs Firefox/Safari), and failure recovery.
2. Defensive Validation & Threat Assessment:
   • Enhanced src/lib/wallet/freighter.ts to defensively validate provider public keys via StrKey.isValidEd25519PublicKey and reject empty or invalid XDR inputs.
   • Enhanced src/lib/wallet/ledger.ts to enforce BIP-44 Stellar derivation paths (^44'/148'/\d+'?$) and validate public keys returned by devices.
   • Added validateWalletPublicKey, validateDerivationPath, and evaluateWalletThreatModel in src/lib/wallet/security.ts.
3. E2E Wallet Fixtures:
   • Extended tests/e2e/fixtures/freighter-mock.js with simulation hooks for wallet spoofing (simulateSpoofedPublicKey), network mismatches (simulateNetworkMismatch), hostile DOM providers (simulateHostileProvider), and unsupported environments (simulateUnsupportedEnvironment).
   • Added deterministic tests/e2e/fixtures/ledger-mock.js supporting WebUSB device simulation, PIN locks (0x6b0c), app-closed state (0x6d00), user rejection (0x6985), and firmware vulnerability checks.
4. Automated Testing:
   • Added unit test suite tests/unit/lib/wallet/walletSecurityThreatModel.test.ts covering primary, boundary, and failure cases for all threat vectors.
   • Expanded tests/unit/lib/wallet/freighter.test.js and src/lib/wallet/__tests__/ledger.test.ts.
   • Added wallet spoofing, network mismatch boundary, and unsupported environment tests in tests/e2e/freighter.spec.js.

Changes

• SECURITY.md: Added Freighter and Ledger threat model matrices and referenced detailed architecture docs.
• docs/security/wallet-threat-model.md: Detailed threat model documentation, attack matrices, runtime compatibility, failure paths, and developer integration guidance.
• src/lib/wallet/freighter.ts: Validates public keys against StrKey specifications and sanitizes XDR input parameters.
• src/lib/wallet/ledger.ts: Enforces BIP-44 Stellar specification on derivation paths and validates returned device public keys.
• src/lib/wallet/security.ts: Implemented validateWalletPublicKey, validateDerivationPath, and evaluateWalletThreatModel.
• tests/e2e/fixtures/freighter-mock.js: Added threat simulation controls for spoofed keys, hostile providers, network mismatches, and environment degradation.
• tests/e2e/fixtures/ledger-mock.js: Created mock fixture for browser-level Ledger hardware wallet testing.
• tests/e2e/freighter.spec.js: Added E2E tests for wallet spoofing rejection, network mismatch boundary case, and unsupported environment handling.
• tests/unit/lib/wallet/freighter.test.js: Added unit tests for connection, signing, spoofed public key rejection, user rejection, and locked state.
• src/lib/wallet/__tests__/ledger.test.ts: Added tests for high BIP-44 account index boundaries, derivation path manipulation, device lock (0x6b0c), app closed (0x6d00), and rejection (0x6985).
• tests/unit/lib/wallet/walletSecurityThreatModel.test.ts: Added unit test suite verifying primary, boundary, and failure cases across spoofing, phishing, and replay vectors.

Testing

• npx vitest run tests/unit/lib/wallet/freighter.test.js src/lib/wallet/__tests__/ledger.test.ts tests/unit/lib/wallet/walletSecurityThreatModel.test.ts
  • Result: 3 test files passed, 38/38 tests passed.
  • Verified primary flow (valid connect & sign for Freighter and Ledger).
  • Verified boundary cases (high account indices 44'/148'/255', network normalization, account change events).
  • Verified failure and threat cases (wallet spoofing key rejection, derivation path injection rejection, phishing cues, user denial 0x6985, locked device 0x6b0c, app closed 0x6d00, missing extension).
• npx eslint passed on all touched files with 0 errors and 0 warnings.
• npx prettier --check passed on all touched files.

Unrelated Findings for Follow-up

• Upstream PR feat: Verify contract source metadata and attestation #1018 (e9c77037) introduced syntax errors in src/components/dashboard/Contracts.tsx and src/lib/tests/contractInvoker.test.ts.
• Upstream commit ee0d2f3a introduced duplicate exports of LogLevel in src/utils/logger.ts.
• Upstream PR chore(sdk): upgrade stellar-sdk to 17 and migrate SorobanRpc → rpc (#970) #1049 (9a32317b) upgraded @stellar/stellar-sdk to ^17.1.0 in package.json without updating pnpm-lock.yaml.

Closes #841

[drips-wave]

@CathyZaks Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[vercel]

@CathyZaks is attempting to deploy a commit to the nanle-code's projects Team on Vercel.

A member of the Team first needs to authorize it.