Authentication & Encryption — Complete Flow Guide

Updated: March 17, 2026 Status: ✅ Implemented (PR #289, branch copilot/integrate-seamless-migration) Related: ZERO_KNOWLEDGE_ENCRYPTION.md

---

Table of Contents

1. Overview
2. Architecture
3. Scenario A: Phone+PIN Signup (Primary)
4. Scenario B: Passphrase Signup (Legacy)
5. Scenario C: Phone+PIN Login
6. Scenario D: Passphrase Login (Legacy)
7. Scenario E: Key Cache Auto-Restore
8. Scenario F: Biometric Unlock
9. Scenario G: Migration from Passphrase to Phone+PIN
10. Scenario H: Account Recovery via Recovery Phrase
11. Scenario I: Phone Number Reclaim (Carrier Recycling)
12. Scenario J: Account Deletion
13. Data Model
14. Security Model
15. Edge Cases & Error Handling
16. File Reference

---

Overview

Lantern supports two authentication/encryption schemes:

	Phone + PIN (Default)	Passphrase (Legacy)
Auth method	Firebase Phone Auth (SMS)	Firebase Email/Password Auth
Key derivation	Two-layer (entropy + wrapping key)	Single-layer (passphrase → key)
Recovery	12-word BIP39 phrase	None (lost = gone)
Biometric unlock	Supported (WebAuthn)	Not available
Key caching	IndexedDB entropy cache	Not available
Route	#/signup, #/login	#/signup/passphrase, #/login/passphrase

Privacy guarantee is identical for both: Lantern cannot decrypt user data. The encryption key is derived client-side from secrets only the user knows (PIN or passphrase) and never leaves the device.

---

Architecture

Phone+PIN: Two-Layer Key Derivation

The phone+PIN scheme uses a two-layer design that separates the encryption key from the user's PIN, enabling recovery without the PIN.

                          ┌─────────────────────────────────────────────┐
                          │          12-word BIP39 Mnemonic             │
                          │       (shown once, user writes down)        │
                          └───────────────────┬─────────────────────────┘
                                              │
                                      mnemonicToEntropy()
                                              │
                                              ▼
                                   ┌───────────────────┐
                                   │  16-byte entropy   │  ← NEVER stored in
                                   │                    │    plaintext anywhere
                                   └────┬──────────┬────┘
                        ┌───────────────┘          └────────────────┐
                        │                                           │
           PBKDF2(entropy, phoneSalt, 600K)            Encrypted with wrapping key
                        │                                           │
                        ▼                                           ▼
              ┌─────────────────┐                        ┌───────────────────┐
              │ Encryption Key  │                        │  encryptedSeed    │ ← Stored in
              │  (AES-256-GCM)  │                        │  (in Firestore)   │   Firestore
              └─────────────────┘                        └───────────────────┘
                                                                    ▲
                                                         PBKDF2(phone+":"+pin,
                                                           phoneSalt, 600K)
                                                                    │
                                                         ┌───────────────────┐
                                                         │  Wrapping Key     │ ← NEVER stored
                                                         └───────────────────┘

Layer 1 — Encryption Key: PBKDF2(entropy, phoneSalt, 600K iterations, SHA-256) → AES-256-GCM key. This key encrypts/decrypts all user data.

Layer 2 — Wrapping Key: PBKDF2(phone + ":" + pin, phoneSalt, 600K iterations) → AES-256-GCM wrapping key. This key encrypts the entropy → encryptedSeed, which is stored in Firestore.

Why two layers? The recovery phrase encodes the same entropy. If the user forgets their PIN, the phrase can regenerate the encryption key directly (Layer 1), bypassing the wrapping key (Layer 2) entirely.

Legacy Passphrase: Single-Layer Key Derivation

passphrase + salt → PBKDF2(600K iterations, SHA-256) → AES-256-GCM encryption key

No recovery path — if the passphrase is lost, data is permanently unrecoverable.

---

Scenario A: Phone+PIN Signup (Primary Path)

Screen: PhonePinSignup — 6 steps Route: #/signupFiles: PhonePinSignup.jsx, encryption.js, keyCache.js, biometrics.js

Step 1 — Phone Number + Age Verification

1. User enters phone number and birth date.
2. normalizePhoneNumber(phone) validates and converts to E.164 format (e.g., +15551234567).
3. Age check: must be 18+ based on birth date.
4. Invisible reCAPTCHA (RecaptchaVerifier) initialized on the container div.
5. signInWithPhoneNumber(auth, normalized, recaptchaVerifier) triggers SMS.
6. confirmationResult stored in component state.

Errors: auth/too-many-requests (SMS rate limit), auth/invalid-phone-number (bad format).

Step 2 — SMS Verification Code

1. User enters the 6-digit SMS code.
2. confirmationResult.confirm(code) → returns credential.user (Firebase Auth user now exists).
3. The phoneUser object is stored in state for later use.
4. Resend option available — clears and recreates the reCAPTCHA verifier.

Errors: Invalid/expired code, SMS not received.

Step 3 — PIN Creation

1. User enters a 6-digit PIN and confirms it.
2. Real-time validation checks:
   • Exactly 6 digits (/^\d{6}$/)
   • Not in WEAK_PINS set (40+ blocked patterns like 123456, 000000, 112233)
   • PINs match
3. validatePIN(pin) performs the final check before proceeding.

Step 4 — Email Capture (Optional)

1. EmailCaptureStep component shows email input with confirmation field.
2. User can enter an email (for recovery notifications) or skip.
3. Triggers createAccount(email) or createAccount(null).

Step 5 — Account Creation (Background) + Recovery Phrase Display

Account creation happens automatically when moving to step 5:

1. initializeEncryptionWithPIN(normalized, pin, user.uid):

   • Generates 128-bit entropy → 12-word BIP39 recovery phrase.
   • Extracts 16-byte entropy bytes from the mnemonic.
   • Generates 32-byte random phoneSalt.
   • Layer 1: PBKDF2(entropy, phoneSalt, 600K) → AES-256-GCM encryption key.
   • Layer 2: PBKDF2(phone + ":" + pin, phoneSalt, 600K) → wrapping key → encrypts entropy → encryptedSeedBase64.
   • SHA-256(normalizedPhrase) → recoveryPhraseHash.
   • Caches encryption key + entropy in module-level variables.
   • Returns { phoneSaltBase64, encryptedSeedBase64, recoveryPhrase, recoveryPhraseHash }.

2. Encrypts user data:

   • encryptData(birthDate) → encryptedBirthDate.
   • createEncryptionCanary() → encrypts "LANTERN_CANARY_V1" for corruption detection.

3. Generates identity: generateLanternName(user.uid) → anonymous display name.

4. Writes Firestore document users/{uid}:

   phone, phoneVerified: true, phoneSalt, encryptedSeed,
   recoveryPhraseHash, lanternName, encryptedBirthDate,
   encryptionCanary, interests: [], mood: null,
   locationTracking: false, authMethod: "phone_pin",
   createdAt, updatedAt, [email if provided]

5. Updates Firebase Auth displayName to the lantern name.

6. Server-side email encryption (if email provided):

   • Calls encryptUserEmail Cloud Function → stores encryptedEmail field.
   • Calls sendRecoveryBackupEmail Cloud Function → sends recovery notification.

7. Caches entropy in IndexedDB via cacheEntropy(userId, entropy) (convenience mode — no biometric protection yet).

8. Recovery phrase is displayed via RecoveryPhraseDisplay:

   • User must reveal the 12 words and confirm they've saved them.
   • Optional: RecoveryBackupModal — user sets a password, encrypts the phrase with PBKDF2(password) → AES-GCM, and emails the encrypted blob via sendEncryptedBackupEmail Cloud Function.

Step 6 — Terms Confirmation + Biometric Prompt

1. User checks "I've saved my recovery phrase" and agrees to terms.
2. BiometricPrompt modal appears (if entropy is available):
   • isBiometricAvailable() — checks for WebAuthn platform authenticator.
   • hasBiometricRegistered(userId) — skips if already registered.
   • "Enable": registerBiometric(userId, displayName) → WebAuthn credentials.create() → HKDF(credentialId) → 256-bit device key → cacheEntropy(userId, entropy, deviceKeyRaw) re-caches with biometric protection (device key NOT stored in IndexedDB).
   • "Not now": proceeds without biometric.
3. onComplete(accountData) → App navigates to #/onboarding/profile.

---

Scenario B: Passphrase Signup (Legacy)

Screen: SignupFlow — 3 steps Route: #/signup/passphraseFiles: SignUp.jsx, auth.js, encryption.js

1. Email + Age: Email validation + birth date + 18+ check.
2. Passphrase Creation: 12+ chars, uppercase, lowercase, number, special character. Confirm match.
3. Terms Confirmation: Agree → signUp(email, passphrase, birthDate):
   • createUserWithEmailAndPassword(auth, email, passphrase) — Firebase Auth.
   • initializeEncryption(passphrase, userId):
     • Generates 32-byte random salt.
     • PBKDF2(passphrase, salt, 600K) → AES-256-GCM key.
   • Encrypts birth date + creates canary.
   • Writes users/{uid}: { email, salt, lanternName, encryptedBirthDate, encryptionCanary, ... }.
   • No phoneSalt, encryptedSeed, authMethod, recoveryPhrase, or key caching.

---

Scenario C: Phone+PIN Login (Returning User)

Screen: PhonePinLoginRoute: #/loginFiles: PhonePinLogin.jsx, phoneLookup.js (Cloud Function), encryption.js, pinAttempts.js

1. User enters phone number + 6-digit PIN.
2. normalizePhoneNumber(phone) + validatePIN(pin).
3. Lockout check: getAttemptState() — if locked, shows countdown timer and blocks submission.
4. Cloud Function lookup — lookupPhoneUser({ phone: normalized }):
   • Server-side (Admin SDK): queries users collection where phone == normalized.
   • Returns { exists, userId, phoneSalt, encryptedSeed, lanternName, authMethod }.
   • If !exists → "No account found with this phone number."
   • If no phoneSalt/encryptedSeed → "This account uses passphrase login."
5. unlockEncryptionWithPIN(normalized, pin, phoneSalt, encryptedSeed, userId):
   • Derives wrapping key: PBKDF2(phone + ":" + pin, phoneSalt, 600K).
   • Decrypts encryptedSeed → entropy bytes.
   • Derives encryption key: PBKDF2(entropy, phoneSalt, 600K).
   • Caches key + entropy in module variables.
   • If PIN is wrong: AES-GCM tag mismatch → throws error.
6. On success:
   • resetAttempts() clears the failure counter.
   • Caches entropy in IndexedDB via cacheEntropy(userId, entropy).
   • BiometricPrompt shown (same as signup step 6).
   • onComplete(result).
7. On failure:
   • recordFailedAttempt() increments counter.
   • After STALE_CLAIM_THRESHOLD (3): shows "Not your phone number?" reclaim link.
   • After MAX_ATTEMPTS (5): locked for LOCKOUT_DURATION_MS (15 minutes) with countdown.

Important: Phone+PIN login does NOT re-authenticate with Firebase Auth. It relies on the Firebase Auth session cached via browserLocalPersistence from the original SMS-verified signup. The lookupPhoneUser Cloud Function is an unauthenticated callable — it only returns encryption parameters, not personal data.

---

Scenario D: Passphrase Login (Legacy)

Screen: LoginFlowRoute: #/login/passphraseFiles: Login.jsx, auth.js, encryption.js

1. User enters email + passphrase.
2. signInWithEmailAndPassword(auth, email, passphrase) — Firebase Auth.
3. Fetches users/{uid} from Firestore.
4. unlockEncryption(passphrase, userData.salt, uid):
   • PBKDF2(passphrase, salt, 600K) → AES-256-GCM key.
5. Canary verification:
   • If encryptionCanary exists: decrypts and checks against "LANTERN_CANARY_V1".
   • Else if encryptedBirthDate exists: decrypts and validates date format (legacy fallback).
   • If corrupted: sets encryptionCorrupted: true in Firestore.
6. Updates lastLoginAt (fire-and-forget).
7. Maps Firebase error codes to user-friendly messages.

---

Scenario E: Key Cache Auto-Restore (Zero-Friction Return)

Location: App.jsx → onAuthStateChanged handler Files: App.jsx, keyCache.js, encryption.js

Triggered on page load when Firebase Auth has a cached session but the encryption key is not in memory (e.g., after a page refresh):

1. Firebase onAuthStateChanged fires → user exists.
2. Loads publicProfile from Firestore.
3. Checks !hasEncryptionKey() && publicProfile.phoneSalt (only for phone+PIN users).
4. hasCachedKey(userId) → checks IndexedDB for keyCache/{userId} record.
5. If cached and biometric-protected:
   • hasBiometricRegistered(userId) → verifies credential exists.
   • verifyBiometric(userId) → WebAuthn credentials.get() → HKDF(credentialId) → device key.
   • getCachedEntropy(userId, deviceKeyRaw) → unwraps entropy using device key.
6. If cached and NOT biometric-protected (convenience mode):
   • getCachedEntropy(userId, null) → unwraps entropy using stored device key.
7. restoreEncryptionFromEntropy(entropy, phoneSalt, userId):
   • PBKDF2(entropy, phoneSalt, 600K) → encryption key. Cached in module.
8. Attempts to decrypt profile fields if present.
9. On failure: logs warning — user must enter PIN manually on next interaction.

Result: User opens Lantern → biometric prompt (or nothing) → fully decrypted. Zero PIN entry.

---

Scenario F: Biometric Unlock

Subset of Scenario E. This documents the biometric subsystem.

Files: biometrics.js, keyCache.js, BiometricPrompt.jsx

Registration (registerBiometric)

1. WebAuthn navigator.credentials.create():
   • authenticatorAttachment: 'platform' (fingerprint, Face ID, Windows Hello only — no USB keys).
   • userVerification: 'required' (must prove presence with biometric).
2. Credential ID stored in IndexedDB (lantern-biometrics DB, credentials store).
3. Device key derived: HKDF(credentialIdBytes, "lantern-biometric-device-key", "aes-256-gcm") → 256-bit key.
4. Entropy re-cached: cacheEntropy(userId, entropy, deviceKeyRaw) — wraps entropy with device key, device key is NOT persisted in IndexedDB (only accessible via WebAuthn assertion).

Verification (verifyBiometric)

1. WebAuthn navigator.credentials.get() with stored credential ID.
2. Same HKDF from assertion's credential ID → identical device key.
3. Device key unwraps entropy from IndexedDB.

Availability

• isBiometricAvailable() checks PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable().
• If unavailable (older browser, no hardware): falls back to convenience mode (device key stored in IDB alongside wrapped entropy).
• Browser support: Chrome 109+, Safari 16+, Edge 109+, Firefox 119+.

---

Scenario G: Migration from Passphrase to Phone+PIN

Files: encryptionMigration.js, encryption.js

Detection

needsMigration(userData) returns true when userData.salt exists (legacy) but userData.phoneSalt does not.

Flow

1. User logs in with passphrase (legacy signIn() — encryption key is now in memory).
2. getEncryptionKeyForMigration() captures the current CryptoKey.
3. UI collects new phone number + new 6-digit PIN.
4. migrateToPhoneAndPIN(userId, phone, pin, oldKey):
   • initializeEncryptionWithPIN(normalized, pin, userId) → generates new recovery phrase, phoneSalt, encryptedSeed. Module now holds the new encryption key.
   • Captures new key via getEncryptionKeyForMigration().
   • For each field in ENCRYPTED_FIELDS (['encryptedBirthDate', 'encryptionCanary']):
     • reEncryptData(ciphertext, oldKey, newKey) — decrypt with old, re-encrypt with new.
   • Updates Firestore atomically:

     + phoneSalt, encryptedSeed, recoveryPhraseHash, encryptionMigratedAt
     + re-encrypted fields (encryptedBirthDate, encryptionCanary)
     - salt: deleteField()  ← removes legacy field

   • Returns { recoveryPhrase } — must be shown to user.
5. If any field fails re-encryption: keeps legacy salt, sets migrationPartial: true + migrationFailedFields array.

Firestore Rules Support

The security rules allow migration updates when resource.data.salt != null && !('phoneSalt' in resource.data) — i.e., legacy user who hasn't migrated yet. Allowed fields are restricted to the migration set.

---

Scenario H: Account Recovery via Recovery Phrase

Files: encryption.js (unlockEncryptionWithRecoveryPhrase, reWrapSeed)

When Needed

• User forgot their PIN.
• Biometric + key cache unavailable (new device, cleared browser data).
• Only the 12-word recovery phrase can restore access.

Flow

1. User enters 12-word BIP39 phrase.
2. unlockEncryptionWithRecoveryPhrase(phrase, phoneSaltBase64, userId):
   • Normalizes phrase (trim, lowercase, collapse whitespace).
   • mnemonicToEntropy(phrase, wordlist) → 16-byte entropy.
   • PBKDF2(entropy, phoneSalt, 600K) → encryption key (bypasses Layer 2 entirely).
   • Key + entropy cached in module.
3. User creates a new PIN.
4. reWrapSeed(phrase, phone, newPin, phoneSaltBase64):
   • Extracts entropy from phrase.
   • Derives new wrapping key: PBKDF2(phone + ":" + newPin, phoneSalt, 600K).
   • Encrypts entropy → new encryptedSeedBase64.
   • Firestore updated with new encryptedSeed.

Validation

• verifyRecoveryPhrase(phrase) checks BIP39 format and checksum (12 words from standard wordlist, valid checksum byte).
• recoveryPhraseHash in Firestore can verify correctness via hash comparison but cannot regenerate the key.

Unrecoverable State

If the user has lost both their PIN and their recovery phrase, their data is permanently unrecoverable. This is by design — it's the zero-knowledge guarantee. They can create a new account with the same phone number (via reclaim if needed).

---

Scenario I: Phone Number Reclaim (Carrier Recycling)

Files: phoneReclaim.js, PhoneReclaimFlow.jsx, phoneRecycling.js (Cloud Function)

When Triggered

After 3+ failed PIN attempts on the login screen, shouldOfferReclaim() returns true, and "Not your phone number?" appears.

Flow

1. User clicks "This is my phone number now" → PhoneReclaimFlow modal opens.
2. Confirm step: UI explains the process (carrier recycled numbers, 48h grace period).
3. initiateReclaim(phoneNumber) → initiatePhoneReclaim Cloud Function:
   • Finds user by phone in users collection.
   • Checks if account is dormant (12+ months inactive based on lastActiveAt).
   • If active → failed-precondition error (can't reclaim active accounts).
   • Creates phoneReclaims/{id}: { phoneNumber, oldUserId, requestedBy, status: "grace_period", graceExpiresAt }.
   • Sends notification email to original owner (decrypts encryptedEmail if available).
4. Waiting step: Polls checkPhoneReclaimStatus every 30 seconds.
5. Completion (after 48h grace period): completeReclaim(reclaimId) → completePhoneReclaim Cloud Function:
   • Detaches phone from old account.
   • Old account becomes "orphaned" (recoverable only with recovery phrase).
6. User navigates to #/signup for fresh registration with that phone number.

Cancellation

Original account owner can cancel during the 48-hour grace period if they receive the notification email and still have access.

---

Scenario J: Account Deletion

Location: handleDeleteAccount in App.jsx, triggered from ProfileSettings

1. window.confirm() — double-check prompt.
2. clearCachedKey(userId) — removes IndexedDB entropy cache.
3. removeBiometric(userId) — removes stored WebAuthn credential from IndexedDB.
4. deleteUserProfile(userId) — deletes Firestore users/{uid} document.
5. currentUser.delete() — deletes Firebase Auth user.
6. signOut() — clears encryption key + entropy from module memory.
7. Navigates to #/.

---

Data Model

Firestore users/{uid} — Phone+PIN Accounts

Field	Type	Source	Description
phone	string	Client	E.164 normalized phone number
phoneVerified	boolean	Client	Always true after SMS verification
phoneSalt	string (base64)	Client	32-byte random salt for PBKDF2
encryptedSeed	string (base64)	Client	Entropy encrypted with phone+PIN wrapping key
recoveryPhraseHash	string (hex)	Client	SHA-256 of normalized recovery phrase (verification only)
authMethod	string	Client	"phone_pin"
lanternName	string	Client	Generated anonymous display name
encryptedBirthDate	string (base64)	Client	AES-GCM encrypted birth date
encryptionCanary	string (base64)	Client	Encrypted "LANTERN_CANARY_V1" for corruption detection
email	string or null	Client	Optional plaintext email
encryptedEmail	string	Server	Server-side AES-256-GCM encrypted email
emailEncryptedAt	timestamp	Server	When server encrypted the email
interests	array	Client	User interests
mood	string or null	Client	Current mood
locationTracking	boolean	Client	Location tracking preference
createdAt	timestamp	Client	Account creation time
updatedAt	timestamp	Client	Last profile update time
lastLoginAt	timestamp	Client	Last login (fire-and-forget)

Firestore users/{uid} — Legacy Passphrase Accounts

Field	Type	Description
email	string	Plaintext email (used for Firebase Auth)
salt	string (base64)	32-byte salt for passphrase PBKDF2
lanternName	string	Generated display name
encryptedBirthDate	string (base64)	AES-GCM encrypted birth date
encryptionCanary	string (base64)	Corruption detection canary
No phoneSalt, encryptedSeed, phone, authMethod		Absence of these fields identifies legacy accounts

Migration-Related Fields

Field	When Present	Description
encryptionMigratedAt	After successful migration	Timestamp
migrationPartial	Partial migration failure	true if some fields couldn't re-encrypt
migrationFailedFields	Partial migration failure	Array of failed field names
encryptionCorrupted	Corruption detected	true when canary check fails
encryptionCorruptedDetectedAt	Corruption detected	Timestamp

IndexedDB Stores (Client-Side)

lantern-keystore → keyCache object store:

• Key: keyCache/{userId}
• Value: { wrappedEntropy, iv, biometricProtected, cachedAt, [deviceKeyRaw] }
• deviceKeyRaw present only in convenience mode (no biometric). When biometric is enabled, the device key is derived at assertion time from the WebAuthn credential ID and is never persisted.

lantern-biometrics → credentials object store:

• Key: userId
• Value: { credentialId: Uint8Array, createdAt }

---

Security Model

What's Stored vs. What's Derived

Data	Stored Where	Purpose
phoneSalt	Firestore	Public; useless without PIN or entropy
encryptedSeed	Firestore	Entropy wrapped with phone+PIN key
recoveryPhraseHash	Firestore	SHA-256 for verification only (one-way)
encryptedBirthDate	Firestore	AES-GCM ciphertext
encryptionCanary	Firestore	Corruption detection
PIN	NOWHERE	Only in user's memory
Recovery phrase	NOWHERE	Only shown once at signup
Entropy (wrapped)	IndexedDB	Encrypted with device key
Device key (no biometric)	IndexedDB	Stored alongside wrapped entropy
Device key (biometric)	NOWHERE	Derived from WebAuthn credential ID via HKDF at assertion time
encryptedEmail	Firestore	Server-side AES-256-GCM (key in Cloud Secret Manager)

Threat Model

Attack Vector	Risk	Mitigation
SIM swap	Medium	Attacker gets SMS but still needs PIN to decrypt
Database breach	Low	Only ciphertext + salt exposed; PIN required
PIN brute force (online)	Low	5 attempts → 15-min lockout, client-side rate limiting
PIN brute force (offline)	Medium	600K PBKDF2 iterations; 10^6 search space ≈ 5.8 days on GPU
Phone number revealed	Low	lookupPhoneUser returns only encryption params, not personal data
IndexedDB extraction	Low	Entropy is wrapped with device key; biometric mode never persists device key
Recovery phrase theft	High	Full account access if phrase is stolen (by design)
Malware on device	High	Key in memory during session; mitigated by browser sandboxing

Server-Side Email Encryption

• Uses aes-256-gcm with a key from Google Cloud Secret Manager (EMAIL_ENCRYPTION_KEY).
• Lantern can decrypt emails (for sending notifications) — this is not zero-knowledge for email.
• A database breach alone exposes only email ciphertext.

---

Edge Cases & Error Handling

Locked Out (Too Many PIN Attempts)

• Client-side counter: resets on page reload (intentional — protection is UX friction, not hard enforcement).
• After 5 failures → 15-minute lockout with countdown timer.
• After 3 failures → phone reclaim link shown.
• applyServerLockout(ms) can enforce server-side lockout if implemented.

Wrong PIN

• unlockEncryptionWithPIN throws when AES-GCM authentication tag mismatch occurs during encryptedSeed decryption.
• recordFailedAttempt() increments the in-memory counter.
• No information leaked about why it failed — same error for wrong PIN or corrupt data.

Phone Number Existence Disclosure

The lookupPhoneUser Cloud Function returns { exists: true/false }, which reveals whether a phone number has an account. This is an intentional UX tradeoff — it provides immediate feedback rather than requiring SMS verification first. Only encryption parameters are returned (no personal data).

Firebase Auth Session Expiry

Phone+PIN login relies on browserLocalPersistence from the original SMS-verified signup. If the Firebase Auth session expires (cleared browser data, new device), the user would need to re-verify their phone via SMS. The current PhonePinLogin flow does not handle re-authentication — it assumes the session persists. On a new device, the user must go through the full signup flow again (or recovery).

Encryption Corruption Detection

• On login: verifyEncryptionCanary(encryptionCanary) decrypts and checks === "LANTERN_CANARY_V1".
• Fallback for pre-canary accounts: decrypts encryptedBirthDate and validates date format.
• If corrupted: sets encryptionCorrupted: true in Firestore. Security rules allow re-initialization when this flag is set.

Partial Migration

If re-encryption of some fields fails during passphrase → phone+PIN migration:

• Legacy salt is kept (not deleted).
• migrationPartial: true and migrationFailedFields array are written.
• Those fields remain decryptable only with the old passphrase key.
• This is a documented degraded state requiring manual intervention.

Emulator Mode

When VITE_USE_EMULATORS=true:

• Connects Auth (port 9099), Firestore (8080), Functions (5001).
• auth.settings.appVerificationDisabledForTesting = true — reCAPTCHA skipped for phone auth.
• No actual SMS sent; emulator auto-generates verification codes.
• See FIREBASE_EMULATOR_TESTING.md for setup.

Firebase Auth Double-Fire

onAuthStateChanged fires twice on load: once from IndexedDB cache, again after network validation. The app handles this by never re-setting authLoading(true) inside the callback — it only transitions to false.

PILOT_MODE / AccessGate

When PILOT_MODE = true in App.jsx:

• All non-auth routes are gated by AccessGate.
• Three states: Loading → Login prompt (not authenticated) → Denied (authenticated but not admin).
• Only admin-role users can access the app.
• Auth routes (#/login, #/signup, #/login/passphrase, #/signup/passphrase) bypass the gate.

Sign-Out Cleanup

• clearEncryptionKey() — clears in-memory key, userId, and entropy.
• Does NOT clear IndexedDB cache or biometric credentials — those persist for next login convenience.
• firebaseSignOut(auth) — clears Firebase Auth session.

---

File Reference

Frontend — Auth Screens

File	Purpose
apps/web/src/App.jsx	Root component, routing, onAuthStateChanged, key cache restore, account deletion
apps/web/src/screens/auth/PhonePinSignup.jsx	6-step phone+PIN signup flow
apps/web/src/screens/auth/PhonePinLogin.jsx	Phone+PIN login with rate limiting
apps/web/src/screens/auth/SignUp.jsx	Legacy passphrase signup
apps/web/src/screens/auth/Login.jsx	Legacy passphrase login
apps/web/src/components/BiometricPrompt.jsx	"Enable biometric unlock?" modal
apps/web/src/components/EmailCaptureStep.jsx	Optional email capture during signup
apps/web/src/components/RecoveryPhraseDisplay.jsx	Recovery phrase reveal + confirmation
apps/web/src/components/RecoveryBackupModal.jsx	Encrypted email backup of recovery phrase
apps/web/src/components/PhoneReclaimFlow.jsx	Phone number reclaim UI

Frontend — Libraries

File	Purpose
apps/web/src/lib/encryption.js	Core encryption: key derivation, encrypt/decrypt, canary, PIN unlock, recovery
apps/web/src/lib/encryptionMigration.js	Passphrase → phone+PIN migration logic
apps/web/src/lib/keyCache.js	IndexedDB entropy caching with device key wrapping
apps/web/src/lib/biometrics.js	WebAuthn platform authenticator registration/verification
apps/web/src/lib/pinAttempts.js	Client-side PIN attempt tracking and lockout
apps/web/src/lib/phoneReclaim.js	Phone reclaim state management
apps/web/src/lib/auth.js	Legacy passphrase auth (signUp, signIn, signOut)
apps/web/src/lib/emailBackup.js	Recovery phrase backup encryption + email sending
apps/web/src/firebase.js	Firebase init, emulator detection, persistence setup

Shared Package

File	Purpose
packages/shared/encryption/index.js	ENCRYPTION_CONFIG, PIN_ATTEMPT_CONFIG, WEAK_PINS, validatePIN, normalizePhoneNumber, ENCRYPTED_FIELDS

Cloud Functions

File	Function	Auth Required	Purpose
services/functions/firebase/modules/phoneLookup.js	lookupPhoneUser	No	Returns encryption params for a phone number
services/functions/firebase/modules/emailEncryption.js	encryptUserEmail	Yes	Server-side email encryption
services/functions/firebase/modules/recoveryBackup.js	sendRecoveryBackupEmail	Yes	Sends encrypted recovery phrase email
services/functions/firebase/modules/phoneRecycling.js	initiatePhoneReclaim, completePhoneReclaim, checkPhoneReclaimStatus	Varies	Phone number reclaim workflow

Security Rules

File	Purpose
firestore.rules	User create/update rules, migration field allowlists, corruption re-init
storage.rules	Firebase Storage access rules

---

Recovery Phrase System

What Is It?

A BIP39 mnemonic phrase — 12 random words that encode a 128-bit entropy seed.

Example: apple brave candle dragon eagle flame garden harbor island jungle kindle lunar

How It Works

┌────────────────────────────────────────────────────────────────────┐
│                    RECOVERY PHRASE SYSTEM                          │
├────────────────────────────────────────────────────────────────────┤
│                                                                    │
│  At Signup:                                                        │
│  ──────────                                                        │
│  1. Generate 128 bits of entropy                                   │
│  2. Convert to 12-word BIP39 mnemonic                              │
│  3. Entropy → PBKDF2 → same encryption key as phone+PIN path      │
│  4. Show words to user ONCE — they write them down                 │
│  5. Store SHA-256 hash of phrase (for verification only)           │
│                                                                    │
│  During Recovery:                                                  │
│  ────────────────                                                  │
│  1. User enters 12 words                                           │
│  2. mnemonicToEntropy() → 16-byte entropy                          │
│  3. PBKDF2(entropy, phoneSalt) → encryption key (Layer 1 only)    │
│  4. User creates new PIN → new wrapping key → new encryptedSeed    │
│                                                                    │
│  ══════════════════════════════════════════════════════════════    │
│                                                                    │
│  What's stored:      Hash of phrase (verification only)            │
│  What's NOT stored:  The phrase itself, the entropy                │
│  Who has the phrase: User only (written on paper or backed up)     │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

Security of Recovery Phrase

Threat	Protected?	Notes
Brute force	Yes	2^128 combinations = computationally impossible
Server breach	Yes	Phrase never stored (only one-way hash)
Shoulder surfing	Partial	Only shown once at signup
Physical theft of paper	No	User must secure the written phrase

---

References

• BIP39 Mnemonic Code
• OWASP Password Storage Cheat Sheet
• WebAuthn Guide
• ZERO_KNOWLEDGE_ENCRYPTION.md — legacy passphrase encryption details
• FIREBASE_EMULATOR_TESTING.md — emulator setup for local testing