Implementation Plan: PIN Storage Security Remediation

Overview

Replace the persisted Argon2id/PIN-derived vault-key wrapper with a hardware-backed Android Keystore envelope. Keep the existing 4–12 ASCII-digit PIN UX only when the device can enforce limited-use Keystore keys in secure hardware; prefer StrongBox and fall back to a verified TEE key. Record the investigation evidence and the device-tier guarantees plainly.

Architecture Decisions

• The vault key is encrypted directly by a non-exportable Keystore AES-256 key; ordinary app storage contains only the ciphertext and IV.
• PIN verification uses Argon2id followed by an HMAC under a non-exportable Keystore key. Ordinary storage cannot validate guesses without the device Keystore key.
• Each PIN attempt first consumes one hardware-limited, single-use HMAC gate. The app exposes PIN setup only when Android reports hardware support for limited-use keys.
• StrongBox is requested where available; StrongBoxUnavailableException falls back to a hardware-backed TEE key. Key security level is checked after generation.
• Legacy peach_pin_salt / peach_pin_wrapped_key material is removed when the new store is initialized; users re-enable PIN with the master password on supported hardware.

Task List

Phase 1: Investigation and design

• [x] Confirm the current PIN storage, KDF, PIN policy, Keystore inventory, and vault-key path.
• [x] Measure the current Argon2id cost and calculate the 4–12 digit offline search space.
• [x] Verify StrongBox, hardware security-level, authentication, and limited-use-key APIs against official Android documentation.

Phase 2: Remediation

• [x] Replace the ordinary-storage PIN wrapper with the hardware-backed envelope and attempt gates.
• [x] Add migration behavior, support gating, and user-facing lockout/recovery behavior.
• [x] Add focused tests for policy and storage shape; device-only gate behavior remains part of real-device validation.

Checkpoint: Remediation

• [x] Focused tests pass.
• [x] Debug lint has no new errors.
• [x] Release builds for arm64-v8a and x86_64 succeed.
• [x] Code review confirms no PIN-derived decryptable vault-key wrapper remains.

Phase 3: Validation and documentation

• [ ] Validate StrongBox and TEE-only behavior on real supported hardware.
• [ ] Validate unsupported/no-limited-use behavior on a representative device.
• [x] Document actual device-tier guarantees and the remaining pre-upgrade-copy limitation.

Checkpoint: Complete

• [ ] Real-device evidence is captured for StrongBox, TEE-only, and unsupported tiers.
• [x] Version, continuity notes, and security documentation are updated.
• [x] Koh diff reviewed and the complete logical change saved.

Risks and Mitigations

Risk	Impact	Mitigation
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
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
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
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

Open Questions

• Real hardware device models and OS versions for StrongBox, TEE-only, and unsupported-tier validation are UNCONFIRMED.