docs: encryption-UX spec + plan from 2026-05-15 brainstorming session

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

@@ -0,0 +1,248 @@
+# 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
+
+```sql
+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.