FEN — Identity, Key Management & Recovery (§8)

Part of the FEN design set. Overview, index, and the legacy-terminology map: fen.md.

8. Identity, Key Management & Recovery

FEN is a local-first, E2EE app: no server ever holds a user's private key, and the app cannot reset or recover it on the user's behalf. The private key is the root of trust — it is needed to unwrap all group keys, decrypt all historical data, and prove identity to existing groups. Losing it without a backup means losing access permanently. This section defines what backup paths the app must provide, what is mandatory versus optional, and how the restore flow works on a new device.

8.1 Key Hierarchy

Key	Type	Scope	Held by
Identity key	Ed25519 keypair	Lifetime of the user's FEN identity	Device secure enclave (Secure Enclave / Android Keystore)
Group key	Symmetric (XChaCha20-Poly1305)	Per group	Encrypted to remaining epoch members' keys via KeyEpochUpdate; one per group
Device key	Per-device ephemeral	Session	Used to wrap group keys for multi-device delivery

For restore, the user needs either (a) their identity private key, or (b) a trusted group admin who can re-authorise a new identity key and re-wrap group keys to it.

8.2 Backup Methods

Method A — Platform Keychain Sync (recommended on iOS)

The identity private key is stored in the OS secure enclave and synced via the platform's E2EE cloud keychain.

iOS: iCloud Keychain provides genuine E2EE (Apple cannot decrypt it). New-iPhone restore is one tap. Trust boundary: the user's Apple account and Apple's implementation of iCloud Keychain encryption.

Android: No equivalent story exists today. Android Keystore does not sync by default; Google Backup API is opaque; OEM layers vary. Do not fake it. On Android, Method B (recovery phrase) is mandatory.

	iOS	Android
Cross-device same platform	✅ seamless	⚠️ fragmented / unreliable
Cross-platform (iOS → Android)	❌ dead	❌ dead
Works without internet	❌	❌
Trust boundary	Apple account	Varies by OEM

Disclosure copy (shown in Settings → Backup):

"iCloud Keychain stores an encrypted copy of your key that only your Apple account can decrypt. FEN never sees your key. Apple's encryption means they cannot read it either — but you are trusting Apple's implementation of that claim."

Method B — Recovery Phrase (mandatory to offer; mandatory to complete on Android)

A 12-word BIP39 mnemonic encodes the identity private key. The user writes it down; enters it on a new device.

• Fully platform-independent — the only option that works for iOS → Android migration
• Works offline
• Verification step required: after displaying 12 words, ask the user to enter words #3, #7, and #11 before marking the backup as confirmed. Do not allow skipping.
• Warn explicitly against: screenshot (ends up in cloud photo backup), password manager that syncs to the same account being protected, storing in notes

Method C — Encrypted Key File (power-user, optional)

The identity private key is encrypted with Argon2id from a user-chosen passphrase and exported as a file to iCloud Drive, a personal cloud, a local file, or AirDrop. Security depends on passphrase strength. Offered in Settings → Backup → Advanced; not shown in the primary onboarding flow.

Method D — Group-Based Social Recovery (complementary, not a substitute)

Because FEN is a group app, a trusted group admin can re-authorise a new identity key after out-of-band identity verification, then re-wrap group keys to the new device.

Important constraint: social recovery restores group access only — it does not restore the original identity keypair. The user generates a new keypair on the new device; the admin authorises it. Past events signed by the old key are annotated ("re-authorised by [Admin]"). Old key revocation must propagate to all group members.

This is useful as a fallback when all other methods fail, but it requires a cooperative admin and cannot help if all group members lose their keys simultaneously.

8.3 What Is Mandatory vs. Optional

Hard gate: before creating or joining a group, the user must complete at least one backup method and confirm it. This cannot be skipped or deferred.

	iOS	Android
Platform keychain sync	✅ default on, counts as one method	❌ not offered
Recovery phrase setup (with verification)	✅ optional additional method	✅ mandatory
Encrypted file export	Optional, buried in Settings → Backup → Advanced	Optional
"I understand I can lose access" bypass	❌ not offered before first group	❌ not offered before first group

After completing setup, Settings → Backup shows a status panel with green / amber / red indicators for each active method.

8.4 Onboarding Flow

"Your expense data is protected by a private key stored only on your device.
To access it on a new device, you need at least one recovery method."

[iOS]
  [A]  ✅ Back up with iCloud Keychain          ← auto-enabled, one tap to confirm
  [B]     Create a Recovery Phrase               ← optional additional method
  [C]     Do both (recommended)

[Android]
  [B]  ⚠️ Create a Recovery Phrase              ← required before continuing

[i]  "FEN cannot recover your data for you. There is no password reset."

Verification step for recovery phrase: show words → ask user to enter words #3, #7, #11 → mark confirmed. Only then does the Continue button activate.

8.5 Lost-Device Restore Flow

"Restore your FEN account?"

[A]  Restore from iCloud              ← Finds identity key AND Cold Archives; password/biometric to decrypt
[B]  Enter recovery phrase            ← cross-platform, offline
[C]  Import encrypted key file        ← cross-platform, needs passphrase
[D]  I didn't set up a backup
       → explains what is and isn't recoverable
       → option to create a new identity
       → option to ask a group admin to re-authorise the new identity

Note on Cold Archives: Restoring the identity from iCloud automatically reconnects the app to any Cold Archived groups stored in that same cloud container. Because the Garage server has purged the closed groups, the identity key simply decrypts the offline archives pulled from iCloud, instantly restoring full historical access.

8.6 Edge Case Matrix

Scenario	Keychain	Phrase	Social recovery
iPhone → new iPhone (same Apple ID)	✅ seamless	✅ manual	✅ admin re-auth
iPhone → Android	❌	✅	✅
Lost phone, no internet	❌	✅ offline	❌ needs contact
iCloud account compromised	⚠️ key exposed	✅ unaffected	✅ unaffected
Lost Apple ID access	❌ locked out	✅	✅
App deleted on iOS	⚠️ keychain item may survive; local data gone	✅	✅
Enterprise MDM device (keychain disabled)	⚠️ may be blocked	✅	✅
User changes Apple ID	❌ old blob orphaned	✅	✅
All group members lose keys	n/a	✅ independent	❌ total loss
Group member rotates identity	n/a	n/a	⚠️ verify out-of-band; do not silently trust same display name + new key

8.7 Identity Rotation Protocol

When a user establishes a new identity key (after a restore via Method D or a deliberate key rotation):

1. User announces new key to each group via a MemberKeyRotated event signed by an authorising admin
2. Old key is marked revoked in the group state; subsequent events from the old key are rejected
3. Past events signed by the old key remain valid (they were legitimate at time of signing)
4. No silent trust of a new key claiming the same display name — admin must explicitly co-sign the rotation

---