1# Implementation Plan: PIN Storage Security Remediation23## Overview45Replace the persisted Argon2id/PIN-derived vault-key wrapper with a hardware-backed6Android Keystore envelope. Keep the existing 4–12 ASCII-digit PIN UX only when the7device can enforce limited-use Keystore keys in secure hardware; prefer StrongBox and8fall back to a verified TEE key. Record the investigation evidence and the device-tier9guarantees plainly.1011## Architecture Decisions1213- The vault key is encrypted directly by a non-exportable Keystore AES-256 key; ordinary14 app storage contains only the ciphertext and IV.15- PIN verification uses Argon2id followed by an HMAC under a non-exportable Keystore16 key. Ordinary storage cannot validate guesses without the device Keystore key.17- Each PIN attempt first consumes one hardware-limited, single-use HMAC gate. The app18 exposes PIN setup only when Android reports hardware support for limited-use keys.19- StrongBox is requested where available; `StrongBoxUnavailableException` falls back20 to a hardware-backed TEE key. Key security level is checked after generation.21- Legacy `peach_pin_salt` / `peach_pin_wrapped_key` material is removed when the new22 store is initialized; users re-enable PIN with the master password on supported23 hardware.2425## Task List2627### Phase 1: Investigation and design2829- [x] Confirm the current PIN storage, KDF, PIN policy, Keystore inventory, and vault-key path.30- [x] Measure the current Argon2id cost and calculate the 4–12 digit offline search space.31- [x] Verify StrongBox, hardware security-level, authentication, and limited-use-key APIs against official Android documentation.3233### Phase 2: Remediation3435- [x] Replace the ordinary-storage PIN wrapper with the hardware-backed envelope and attempt gates.36- [x] Add migration behavior, support gating, and user-facing lockout/recovery behavior.37- [x] Add focused tests for policy and storage shape; device-only gate behavior remains part of real-device validation.3839### Checkpoint: Remediation4041- [x] Focused tests pass.42- [x] Debug lint has no new errors.43- [x] Release builds for arm64-v8a and x86_64 succeed.44- [x] Code review confirms no PIN-derived decryptable vault-key wrapper remains.4546### Phase 3: Validation and documentation4748- [ ] Validate StrongBox and TEE-only behavior on real supported hardware.49- [ ] Validate unsupported/no-limited-use behavior on a representative device.50- [x] Document actual device-tier guarantees and the remaining pre-upgrade-copy limitation.5152### Checkpoint: Complete5354- [ ] Real-device evidence is captured for StrongBox, TEE-only, and unsupported tiers.55- [x] Version, continuity notes, and security documentation are updated.56- [x] Koh diff reviewed and the complete logical change saved.5758## Risks and Mitigations5960| Risk | Impact | Mitigation |61|---|---|---|62| App PIN is not an Android Keystore authentication type | PIN could not be hardware-authenticated directly | Use Keystore-only vault wrapping plus hardware-limited attempt gates; do not claim system-auth lockout for the app PIN |63| StrongBox is unavailable or lacks the requested primitive | PIN setup could fail on some devices | Prefer StrongBox, then verify and fall back to TEE; reject software-only keys |64| Limited-use keys are exhausted or unsupported | PIN UX could lock out or be unavailable | Bound attempts, require master password to regenerate gates, and disable new PIN setup when hardware support is absent |65| Existing storage was copied before upgrade | That historical copy remains vulnerable | State this limitation; the upgrade removes legacy material from the live app store but cannot revoke prior copies |6667## Open Questions6869- Real hardware device models and OS versions for StrongBox, TEE-only, and unsupported-tier validation are UNCONFIRMED.