Closer/docs/crypto/key-storage-migration-design.md

Key-storage migration — design (DESIGN ONLY, not yet approved)

Status: proposal for owner review. No code ships from this doc until the owner signs off — it touches the E2EE root of trust, where a mistake means permanent, unrecoverable content loss. Batch 5.1 of the roadmap (make-a-plan-for-recursive-spindle.md).

Context / problem

All on-device secrets go through data/local/SecurePreferencesFactory, which uses androidx.security:security-crypto:1.0.0 (EncryptedSharedPreferences + MasterKeys). That library is deprecated and unmaintained by Google (no fixes, no target-SDK updates). Six stores depend on it:

Store	Holds	If lost…
crypto/CoupleKeyStore	the couple AES-256 keyset (Tink, JSON) + recovery phrase	all E2EE content unreadable — the crown jewel
crypto/UserKeyManager	per-user ECIES P-256 private key	sealed-answer/keybox flows break until re-published
crypto/PendingAnswerKeyStore	one-time per-answer keys, pre-reveal	a pending answer can't be revealed
data/local/RecoveryPhraseStore	the recovery phrase	falls back to partner copy
data/local/PendingInviteStore	inviter's code + phrase during pairing	pairing restart
data/repository/SharedPreferencesLocalAnswerRepository	local answer drafts	drafts lost

The load-bearing hazard to fix along the way

SecurePreferencesFactory.encryptedSharedPreferences() catches any failure opening the store and calls reset() — which deletes the file — then recreates it empty. For draft/pending stores that's an acceptable "start over." For CoupleKeyStore it is silent, permanent couple-key destruction: a transient Keystore hiccup, an OS upgrade that invalidates the master key, or a botched migration would wipe the couple key with no prompt. The couple is partner-recoverable today (the partner holds the same key + phrase), so it's not total loss — but it turns a recoverable blip into a full re-pair/restore. Any migration must remove this auto-wipe for the couple-key store and replace it with a fail-closed path that preserves ciphertext and asks the user to recover, never deletes.

Goals

1. Move off androidx.security:security-crypto to a maintained primitive.
2. Never lose the couple key during or after migration — the overriding constraint.
3. Zero user-visible disruption for the happy path (transparent, lazy migration).
4. Keep the wire/at-rest format of server-stored data unchanged (this is purely on-device storage; Firestore enc:v1: ciphertext and the recovery-phrase-wrapped wrappedCoupleKey are untouched).

Non-goals

• No change to the E2EE scheme itself (Tink AEAD, Argon2id recovery wrap, ECIES keyboxes) — see SECURITY.md / docs/Engineering_Reference_Manual.md.
• No change to server storage or Firestore rules.
• Not couple-key rotation / forward secrecy (separate roadmap item).

Target design (recommended)

Tink's Android-Keystore-backed keyset storage (AndroidKeysetManager + AndroidKeystoreKmsClient), replacing EncryptedSharedPreferences:

• A single app master key in the AndroidKeyStore (AndroidKeystoreKmsClient, alias e.g. closer_master_key) wraps each stored Tink keyset; keysets persist in a plain SharedPreferences as Tink-encrypted blobs. This is Tink-native (we already depend on tink-android), maintained, and removes the androidx.security dependency.
• Secrets that are raw strings (recovery phrase, invite phrase, local drafts) are wrapped with a dedicated Tink AEAD whose keyset is itself Keystore-master-wrapped (same mechanism), so nothing is stored in cleartext.
• Fail-closed, not fail-wiped: if a keyset can't be decrypted, surface a recover-this-device flow (existing partner-assisted restore / recovery-phrase paths) — never delete.

Alternative considered: raw AndroidKeyStore AES-GCM + manual IV/blob management. Rejected — more bespoke crypto code to get wrong; Tink already gives us the KMS-client wrapper.

Migration strategy

Transparent, lazy, per-store, one direction. For each key on read:

1. Dual-read window. New SecureStoreV2 tries the new (Tink-Keystore) location first; on miss, falls back to reading the old EncryptedSharedPreferences value.
2. Re-wrap on read. When a value is found only in the old store, decrypt it via the old lib and write it to the new store, then return it. (Lazy migration — no big-bang pass, no startup stall.) The old value is left in place until the migration is confirmed durable (see below).
3. Confirm, then clean. Only after the new value has been successfully read back from the new store (a verify-read) is the old entry deleted. A crash between steps 2 and 3 is safe: next read re-does the re-wrap idempotently.
4. Never-lose-the-couple-key rule. For CoupleKeyStore specifically: the old-store delete in step 3 is gated on a successful new-store round-trip AND is a no-op if the new value is absent. The reset()/auto-wipe path is removed for this store; a decrypt failure raises a typed KeyUnavailable that routes to recovery UI, not deletion.

Failure matrix

Situation	Behavior
New store has the value	Use it (fast path).
Only old store has it	Re-wrap → new store → verify → (later) delete old.
Neither has it, key expected	KeyUnavailable → recovery flow (partner/phrase). No wipe.
New-store write fails mid-migration	Keep old value; return decrypted value from old; retry next read.
Keystore master invalidated (OS upgrade / biometric change)	Detect, treat as KeyUnavailable → recovery; do NOT recreate empty.

Consumer ordering (lowest → highest risk)

1. PendingInviteStore, SharedPreferencesLocalAnswerRepository, PendingAnswerKeyStore — ephemeral/rebuildable; a wipe here is tolerable, so migrate first to shake out the mechanism.
2. UserKeyManager (ECIES) — recoverable by re-publishing a fresh public key; medium risk.
3. RecoveryPhraseStore — partner-recoverable; medium risk.
4. CoupleKeyStore last — only after the mechanism is proven on the others, and only with the fail-closed (no-wipe) behavior in place.

Staged rollout + telemetry

• Behind a Remote Config flag key_storage_v2_enabled (build the RC wrapper first — see Future.md, currently no wrapper exists). Default off; enable to a small % first.
• Content-free telemetry only (respecting the analytics consent toggle): migration attempted / succeeded / fell-back / KeyUnavailable counts per store — never key material. Watch the KeyUnavailable-on-couple-key rate like a hawk; any nonzero blip is a rollback trigger.
• Kill switch: flag off → SecureStoreV2 reads new-then-old but stops writing new (freezes migration) without breaking either store.

Test plan (before any staged rollout)

• Instrumented (real Keystore, can't be JVM-unit-tested): write via old lib → read via V2 → re-wrap → new-store round-trip → old entry cleaned only after verify.
• Fresh-device / process-death: kill between re-wrap and cleanup; assert idempotent recovery, no loss.
• Keystore-invalidation simulation: force a decrypt failure; assert KeyUnavailable + recovery route, assert the file is NOT deleted.
• Full E2EE round-trip after migration (encrypt/decrypt a message, reveal a daily answer) on a migrated device — extends the existing QA "content is ciphertext at rest" pass.
• Backward-compat: a device that never migrates (flag off) keeps working on the old store.

Open questions for the owner

1. Acceptable rollout %/duration for the couple-key store, given partner-recoverability as the safety net?
2. Keep the old androidx.security dependency for a full release cycle as the dual-read source, then remove — or remove sooner?
3. Do we take the opportunity to also remove the reset() auto-wipe from the other stores now (independent, small, strictly-safer change), or bundle it all?

Recommendation

Ship the reset()-auto-wipe removal for CoupleKeyStore as a small, standalone, pre-migration fix (it's strictly safer and independent of the library swap), then do the Tink-Keystore migration lazily behind the RC flag in the consumer order above, couple key last. Nothing here is implemented until this design is approved.