ChatApp/docs/superpowers/specs/2026-05-15-encryption-ux-simplification-design.md

Encryption UX Simplification — Design

Date: 2026-05-15 Scope: Desktop (Electron/Tauri) first. Mobile follows in a subsequent spec. Status: Approved by user (sections 1–5).

Problem

The current end-to-end-encryption flow is too complex for non-technical users:

1. Re-login locks them out. Each device has its own X25519 keypair, and conversation keys (conversation_keys) are wrapped per-device. When a user signs in on a fresh install (or after clearing app data), they get a new device row → no peer has wrapped the conv-key for that new device → they can neither read old chats nor send new messages until another online peer of theirs (or another member of the conversation) re-wraps the conv-key for the new device. This frequently strands users.
2. Backup restore must be done twice. Restoring from BackupRestoreDialog in Settings reseeds the local vault, but on a clean re-login the device-registration screen still requires another restore — most often because the secret-store backend probe (setSecretStoreUser) and the restore write race, or because users lose the cached localStorage device-id between sessions.
3. Backup string + passphrase + recovery code is too much. Users are asked to manage a long base64 blob, a passphrase, and a 24-char recovery code. Most never export a backup at all.

Goals

• Re-login on a fresh device must be a single-step action ("enter PIN") that restores full read+write access immediately, with no dependency on peers being online.
• The user manages one secret (a 6-digit PIN) plus an optional one-time recovery code.
• No more raw "backup strings" to copy around.
• Existing chat history remains readable after the migration.
• Compromise of a single device still requires user action to fully revoke (rotate user key) — but per-device fine-grained revocation is intentionally dropped in favor of UX.

Non-Goals

• Mobile rollout. Tracked in a follow-up spec; the schema and shared crypto primitives are designed to be reusable on React Native.
• Forward secrecy / Double Ratchet. Out of scope; we keep the Sender-Key model.
• Multi-account on a single OS user.
• A web-only (no Electron/Tauri) variant. We assume an OS-keychain-backed Stronghold/safeStorage is available; the localStorage fallback path remains as today's escape hatch.

Architecture

Identity model: per-user instead of per-device

Today: one X25519 keypair per (user_id, device_id); conversation_keys rows are keyed by recipient_device_id.

New: one X25519 keypair per user_id, stored as a PIN-sealed blob in a new user_keys table. Devices remain only for telemetry / push / last-seen — they no longer carry cryptographic identity. Each device unlocks the same user key with the PIN and caches the cleartext private key in the OS keychain (Stronghold / safeStorage).

conversation_keys is rekeyed: recipient_device_id → recipient_user_id, sender_device_id → sender_user_id. Sender-key (symmetric XSalsa20-Poly1305 conv-key) and the wrapping primitive (crypto_box) stay unchanged.

Trade-offs

• Lost: clean per-device revocation. If a single device is compromised, the user must rotate the whole user key (re-wrap conv-keys for every member of every conversation). For a friends-chat app with no enterprise revocation requirement, acceptable.
• Lost: "device fingerprint per session" trust signal.
• Gained: zero-friction re-login, zero peer dependency for new installs, single secret to remember, no manual backup string.

Threat model

• Server (Supabase) is honest-but-curious. It must never see plaintext private keys or conv-keys.
• A 6-digit PIN is not brute-force resistant on its own. It is protected by:
  • Argon2id KDF (moderate preset) raises per-attempt cost to ~hundreds of ms.
  • Server-side lockout counter (failed_attempts, locked_until in user_keys) gates ciphertext delivery: after 10 failed attempts a 24h lock is applied. The client cannot brute-force locally because it must request the ciphertext from the server, which the server rate-limits.
  • Recovery code (~120 bits) is the strong factor; PIN is the convenience factor.
• A network attacker with a stolen Supabase session token cannot decrypt anything without the PIN/recovery code.
• A local attacker with full disk access can read the cached cleartext key from Stronghold (same threat as today's per-device key model).

Components

packages/shared

File	Change
crypto/userKey.ts	NEW. generateUserKeyPair(), sealUserKey({privateKey, pin, salt}), openUserKey({sealed, pin, salt}). Argon2id (moderate preset) + XSalsa20-Poly1305.
auth/userKey.ts	NEW. DB wrappers: fetchUserKeyBlob(client, userId), uploadUserKeyBlob(...), recordPinAttempt(...), tryUnlockUserKey(...) (calls SECURITY DEFINER RPC), resetUserKeyWithRecovery(...).
chat/convKeys.ts	Refactor: recipient_device_id → recipient_user_id, sender_device_id → sender_user_id. listDeviceKeys() becomes listMemberPublicKeys() (joins conversation_members → user_keys). OwnDeviceCtx → OwnUserCtx { userId; privateKey }.
auth/device.ts	Strip cryptographic functions: remove provisionNewDevice, restoreDeviceFromServerRecord, saveDevicePrivateKey, loadDevicePrivateKey, forgetDevicePrivateKey. Keep telemetry helpers (registerDevice, listOwnDevices, touchDeviceLastSeen); they no longer take/store public_key.
crypto/index.ts	Re-export userKey.

apps/desktop/src/lib

File	Change
userIdentity.ts	NEW. loadOrUnlockUserKey({pin}), setupNewUserIdentity({pin, withRecovery}), cachedUserKey(), clearUserKeyCache(). Caches cleartext key in Stronghold under chatapp.userpriv.<userId>.
secretStore.ts	Unchanged interface. Stores chatapp.userpriv.<userId> instead of chatapp.priv.<userId>.<deviceId>.
device.ts	Strip findExistingDevice, registerCurrentDevice. Keep platform detection only.
deviceBackup.ts	DELETE.

apps/desktop/src/components

File	Change
UserKeySetup.tsx	NEW. PIN entry + confirm + "Recovery-Code anzeigen" + "Habe ich gespeichert" / "Überspringen (riskant)" buttons.
UserKeyUnlock.tsx	NEW. Numeric PIN pad. Surfaces remaining attempts + lockout countdown. Switches to "Recovery-Code eingeben" tab.
DeviceRegistration.tsx	Becomes onboarding wrapper that routes to UserKeySetup or UserKeyUnlock based on fetchUserKeyBlob result. Drop the device-name prompt (auto from hostname; editable in Settings).
DeviceRestore.tsx	DELETE.
BackupExportDialog.tsx	DELETE.
BackupRestoreDialog.tsx	DELETE.
BackupPromptBanner.tsx	DELETE.
SettingsPage.tsx	Replace backup section with: "PIN ändern", "Recovery-Code neu erzeugen", "Identität zurücksetzen".

Supabase schema

CREATE TABLE user_keys (
  user_id                       UUID         PRIMARY KEY REFERENCES auth.users(id) ON DELETE CASCADE,
  public_key                    BYTEA        NOT NULL,         -- 32 bytes X25519
  sealed_private_key            BYTEA        NOT NULL,         -- nonce(24) || ciphertext
  salt                          BYTEA        NOT NULL,         -- 16 bytes
  kdf_params                    JSONB        NOT NULL,         -- { algo: 'argon2id', preset: 'moderate', opslimit, memlimit }
  recovery_sealed_private_key   BYTEA        NULL,             -- present only if user kept recovery code
  recovery_salt                 BYTEA        NULL,
  failed_attempts               INT          NOT NULL DEFAULT 0,
  locked_until                  TIMESTAMPTZ  NULL,
  failed_recovery_attempts      INT          NOT NULL DEFAULT 0,
  recovery_locked_until         TIMESTAMPTZ  NULL,
  key_version                   INT          NOT NULL DEFAULT 1,
  created_at                    TIMESTAMPTZ  NOT NULL DEFAULT now(),
  updated_at                    TIMESTAMPTZ  NOT NULL DEFAULT now()
);

-- RLS: a user reads/writes only their own row.
ALTER TABLE user_keys ENABLE ROW LEVEL SECURITY;
CREATE POLICY user_keys_self_rw ON user_keys
  USING (user_id = auth.uid()) WITH CHECK (user_id = auth.uid());

-- Anyone authenticated may read peer public_key only (separate policy on a view or column-level).
CREATE VIEW user_public_keys AS
  SELECT user_id, public_key, key_version FROM user_keys;
GRANT SELECT ON user_public_keys TO authenticated;

conversation_keys:

• ADD recipient_user_id UUID, sender_user_id UUID (nullable during migration).
• After migration cutoff: drop recipient_device_id, sender_device_id.
• New unique constraint: (conversation_id, recipient_user_id, key_version).

RPCs (SECURITY DEFINER):

• try_unlock_user_key(p_user_id UUID) → returns { sealed, salt, kdf_params, locked: bool, locked_until }. Honors lockout. Caller must already be auth.uid() = p_user_id. Does NOT decrement attempts (decryption is offline; client reports outcome via record_pin_attempt).
• record_pin_attempt(p_user_id UUID, p_success BOOL, p_recovery BOOL) → updates counters & lockout. Server-authoritative, atomic.
• share_conv_keys(...) → existing RPC, signature changes from p_recipient_device_id to p_recipient_user_id per bundle entry.
• migrate_user_key_recipients(p_conv_id, p_user_id, p_old_device_id, p_new_bundles) → bulk INSERT new recipient_user_id rows from re-wrapped bundles, idempotent via ON CONFLICT (conversation_id, recipient_user_id, key_version) DO NOTHING.

Data Flow

First-time setup

1. User signs in (magic link / password). fetchUserKeyBlob(userId) → null.
2. Routes to UserKeySetup. User chooses 6-digit PIN.
3. Client generates X25519 keypair + 16-byte salt; derives KEK via Argon2id; seals the private key.
4. Client generates a 24-char recovery code (32-symbol alphabet, ~120 bits) and seals the same private key with a recovery-derived KEK + separate salt.
5. UI shows recovery code once. User picks "Habe ich gespeichert" or "Überspringen". Skip leaves recovery_sealed_private_key NULL.
6. UPSERT user_keys row.
7. Cleartext private key cached in Stronghold (chatapp.userpriv.<userId>).

Re-login on a fresh / wiped device

1. Sign-in OK. fetchUserKeyBlob(userId) returns row → routes to UserKeyUnlock.
2. User enters PIN. RPC try_unlock_user_key returns ciphertext+salt (or locked: true).
3. Client derives KEK + opens sealed key. On success: record_pin_attempt(success=true) resets counter; cleartext key cached in Stronghold; navigate to /chats.
4. On failure: record_pin_attempt(success=false) increments counter. UI shows remaining attempts.
5. On lockout: UI offers "Recovery-Code verwenden" tab. Same flow against recovery_sealed_private_key + failed_recovery_attempts.

Sending a message (existing conversation)

1. getOrCreateConvKey(convId, ownUserCtx) looks up conversation_keys by recipient_user_id = me.
2. Bundle exists → unwrap with user private key → encrypt plaintext → send.
3. Re-login works immediately: the user's public_key is unchanged across sessions, so all existing wrapped conv-keys remain valid.

New user joins a conversation

1. Existing member loads public_key from user_public_keys.
2. Calls shareConvKeyToUser(convId, newUserId, newUserPubKey, ownCtx) → wraps active conv-key, INSERT bundle.

Migration of legacy conversation_keys

Triggered automatically the first time a user signs in after the upgrade and has both an old device-key in Stronghold and no user_keys row yet:

1. Setup flow runs (PIN, generate user keypair, upload user_keys).
2. Migration pass:
   • List all conversation_keys rows where recipient_device_id belongs to one of the user's old devices.
   • Unwrap with the old device private key.
   • Re-wrap for recipient_user_id = me with the new user public key.
   • Bulk-insert via migrate_user_key_recipients (ON CONFLICT DO NOTHING).
3. Old rows remain untouched; other members migrate independently in their own passes.
4. Cross-member rewrap: when any member opens a conversation, the client lists members lacking a recipient_user_id bundle and proactively wraps for them in the background.
5. After all active users have migrated (telemetry-tracked), a follow-up migration drops recipient_device_id / sender_device_id.

PIN change (Settings)

1. Prompt for current PIN → unlock locally (without server round-trip; we already have ciphertext+salt cached or can fetch).
2. Generate new salt; reseal with new PIN-derived KEK.
3. UPSERT user_keys row (same public_key, no conv-key rewrap).

Identity reset

Hard "burn it down" path. Generates new user keypair, replaces user_keys, deletes the user's conversation_keys bundles. Friends will see fingerprint-change in the future trust UI (not in MVP).

Error Handling

Case	Behavior
Wrong PIN	Offline crypto fails → record_pin_attempt(success=false) → counter increments. Cooldown schedule: attempts 1–4 none, 5–9 backoff (5s, 30s, 2m, 10m, 1h), 10 → locked_until = now() + 24h. Counter resets on success. UI shows remaining attempts and any active cooldown.
Lockout active	try_unlock_user_key returns {locked: true, locked_until} without ciphertext. UI surfaces "Recovery-Code verwenden" tab.
Recovery-code attempts	Independent counter failed_recovery_attempts; same backoff schedule, threshold 20 → permanent lock requiring identity reset.
Forgot PIN, no recovery code	UI shows hard warning, then runs Identity-Reset flow (lose all old chats; fingerprint changes for friends).
Stronghold cache lost (reinstall, wipe)	Identical to "Re-login on fresh device".
user_keys row missing server-side but Stronghold has key	UI offers "Identität wieder hochladen": re-uploads using cached key + a fresh PIN entry. Telemetry-logged.
Concurrent setup race	INSERT … ON CONFLICT (user_id) DO NOTHING + re-fetch. Loser unlocks the winner's blob with the same PIN. Mismatched PINs → loser sees "use the PIN chosen on the other device".
Concurrent migration race	migrate_user_key_recipients inserts are idempotent; both clients converge to identical state.
Conv-key bundle missing despite membership	As today: getOrCreateConvKey throws "Awaiting conversation key". Background sweep on conversation-open triggers proactive rewrap from any online member. The new model makes this strictly rarer (one bundle per user, not per device).
Stronghold init fails	Existing fallback to localStorage retained. User-key lands in localStorage cleartext (same risk as today's dev-fallback path).

Testing

Unit (packages/shared):

• crypto/userKey.test.ts: roundtrip seal/open with correct PIN; wrong PIN throws; wrong salt throws; KDF preset is reproducible.
• auth/userKey.test.ts: fetch returns null vs. row; UPSERT behavior; record_pin_attempt increments; lockout transitions.
• chat/convKeys.test.ts: tests refactored to recipient_user_id. New: bootstrap with two members (each unwraps OK); share to new user works; awaiting-key path throws.

Integration (apps/desktop):

• userIdentity.migration.test.ts: fixture with legacy recipient_device_id rows. Run migration pass. Assert: new recipient_user_id rows exist with same plaintext conv-key; legacy rows untouched.
• Race test: two parallel migration runs converge without duplicate inserts.

Component (apps/desktop):

• UserKeySetup.test.tsx: PIN-mismatch error; recovery-code rendered exactly once; "Skip" path leaves recovery_sealed_private_key NULL.
• UserKeyUnlock.test.tsx: wrong PIN increments attempts; lockout countdown rendered; recovery tab functional.

E2E (Playwright via e2e-testing skill, optional in first cut):

• Happy path: login → setup PIN → send chat → sign-out → sign-in → PIN → old chats readable, new chats sendable.
• Cross-context: User1 device A ↔ User2 conversation. User1 signs out, signs in fresh context, enters PIN, can read+write without User2 being online.

Manual smoke list (pre-release):

1. Fresh install, setup with recovery save.
2. Fresh install, setup with recovery skip.
3. Existing user with legacy conv-keys → silent migration → old chats readable.
4. Existing user on second device: setup on A, sign-in on B with same PIN.
5. Forgot PIN → recovery-code → unlock OK.
6. PIN change in Settings.
7. Identity reset → old chats unreadable for me, new chats functional.
8. Lockout: 10 wrong PINs → lock + recovery tab.

Out of Scope (future work)

• Mobile (React Native) port — separate spec.
• Trust-on-first-use fingerprint banner when peer rotates key_version.
• Linked-device pairing flow (Signal-style) as a third recovery vector.
• Forward-secret message keys (Double Ratchet).
• Hardware-backed PIN entry (Secure Enclave / TPM bound).

Migration Cutoff

After ≥95% of MAU have a user_keys row (server telemetry), schedule a follow-up migration to drop recipient_device_id and sender_device_id columns.