Encryption onboarding: detect missing setup, explain cross-signing and the recovery key (≤3 pages) #71

New issue

Open

opened 2026-10-06 21:26:47 +00:00 by robocub · 0 comments

robocub commented

2026-10-06 21:26:47 +00:00

Member

Goal: nobody loses their message history because they didn't understand encryption. When an account isn't fully set up, Vommet notices and walks the user through it in at most three short pages, with clear pictures, readable on phone and desktop, ending in the actual setup.

The key message: losing the recovery key after all your devices are signed out is the number one reason people lose their past encrypted messages. Save it in a password manager. If you don't have one, we recommend Bitwarden (free, open source, on every platform).

When to show it

Checked after sign-in and at startup, per account:

No cross-signing on the account (encryption.crossSigning.enabled == false): full flow, ending in setup.
Cross-signing exists, but this session is unverified (isUnknownSession): ask to verify with another device or enter the recovery key, before the room list opens. That's the fix for #32 (upstream #1046: rooms opened before keys arrive stay "failed to decrypt" for good).
No key backup (keys not stored on the server, encrypted): short version of page 2 + turn on backup.
Fully set up: never shown.
The user can skip, and gets a gentle reminder later (a banner on the home screen, not a blocking dialog on every start). The full explanation stays reachable from Settings › Security.

The three pages

Why your messages are locked. Encrypted messages can only be read with keys that live on your devices. Cross-signing is how your account vouches for each of your devices, so friends know it's really you and your devices can share keys with each other. Picture: your account at the top, signing your phone and laptop below it; a new device gets the keys once it's signed.
Your recovery key is the spare key. If you sign out of every device, the recovery key is the only way to get your old messages back. Nobody, not even your server admin, can recover them for you.
- Do you use a password manager? Yes: save the key there now. No: we recommend Bitwarden (link). Or: save an encrypted key file protected by a password you choose (the standard Matrix key export, which also imports into Element). You must not lose that password: without it the file is useless (see #72). Writing the key down somewhere safe also works. Screenshots in your photo gallery are not safe.
- Picture: the key as a spare house key, with "all devices signed out" + "no recovery key" = locked out.
Set it up (this page does it, not just explains):
- New setup: create cross-signing + key backup (encryption.bootstrap), show the recovery key with Copy / Save to file, and confirm it was saved (e.g. type the last 4 characters).
- Existing account: "Verify with another device" or "Enter recovery key", then restore the key backup, then re-try failed decryptions (#32, #16).

Figures

Draw the diagrams in the app (vector, theme-aware, dark/light) rather than as bitmap screenshots, so they stay sharp and readable at phone and desktop sizes. A short screenshot of the save-the-key step in Bitwarden could help but isn't required.

Building blocks that exist

Post-login setup pages (FirstTimeSetup / SetupMenu), the same mechanism as the welcome screen (feat/welcome-first-login). Order: welcome first, then encryption.
Cross-signing UI in Settings › Security (cross_signing_page.dart uses encryption.bootstrap; matrix_security_tab.dart already reads crossSigning.enabled and isUnknownSession).

#72: warning before signing out of the last device, plus the encrypted key export.

#32 / upstream #1046: ask for the recovery key at sign-in (this flow is the natural fix).
#16: messages stay "encrypted" after verifying until the room is reopened.
Upstream #852 (backup restore fails unless done right after verification), #707 (blank enable-cross-signing dialog), #616 ("reset cross signing → use existing keys" never completes), #752 (a permanent recovery-key button in Security). All open upstream, none with a PR (2026-10-06).

Goal: nobody loses their message history because they didn't understand encryption. When an account isn't fully set up, Vommet notices and walks the user through it in **at most three short pages**, with clear pictures, readable on phone and desktop, ending in the actual setup. **The key message:** losing the recovery key after all your devices are signed out is the number one reason people lose their past encrypted messages. Save it in a password manager. If you don't have one, we recommend **Bitwarden** (free, open source, on every platform). ## When to show it Checked after sign-in **and** at startup, per account: - **No cross-signing** on the account (`encryption.crossSigning.enabled == false`): full flow, ending in setup. - **Cross-signing exists, but this session is unverified** (`isUnknownSession`): ask to verify with another device *or* enter the recovery key, **before the room list opens**. That's the fix for #32 (upstream #1046: rooms opened before keys arrive stay "failed to decrypt" for good). - **No key backup** (keys not stored on the server, encrypted): short version of page 2 + turn on backup. - Fully set up: never shown. The user can skip, and gets a gentle reminder later (a banner on the home screen, not a blocking dialog on every start). The full explanation stays reachable from Settings › Security. ## The three pages 1. **Why your messages are locked.** Encrypted messages can only be read with keys that live on your devices. *Cross-signing* is how your account vouches for each of your devices, so friends know it's really you and your devices can share keys with each other. Picture: your account at the top, signing your phone and laptop below it; a new device gets the keys once it's signed. 2. **Your recovery key is the spare key.** If you sign out of every device, the recovery key is the *only* way to get your old messages back. Nobody, not even your server admin, can recover them for you. - Do you use a password manager? **Yes:** save the key there now. **No:** we recommend Bitwarden (link). **Or:** save an **encrypted key file** protected by a password you choose (the standard Matrix key export, which also imports into Element). You must not lose that password: without it the file is useless (see #72). Writing the key down somewhere safe also works. Screenshots in your photo gallery are not safe. - Picture: the key as a spare house key, with "all devices signed out" + "no recovery key" = locked out. 3. **Set it up** (this page *does* it, not just explains): - **New setup:** create cross-signing + key backup (`encryption.bootstrap`), show the recovery key with Copy / Save to file, and confirm it was saved (e.g. type the last 4 characters). - **Existing account:** "Verify with another device" or "Enter recovery key", then restore the key backup, then re-try failed decryptions (#32, #16). ## Figures Draw the diagrams in the app (vector, theme-aware, dark/light) rather than as bitmap screenshots, so they stay sharp and readable at phone and desktop sizes. A short screenshot of the save-the-key step in Bitwarden could help but isn't required. ## Building blocks that exist - Post-login setup pages (`FirstTimeSetup` / `SetupMenu`), the same mechanism as the welcome screen (`feat/welcome-first-login`). Order: welcome first, then encryption. - Cross-signing UI in Settings › Security (`cross_signing_page.dart` uses `encryption.bootstrap`; `matrix_security_tab.dart` already reads `crossSigning.enabled` and `isUnknownSession`). ## Related - #72: warning before signing out of the last device, plus the encrypted key export. ## Related bugs to fix along the way - #32 / upstream #1046: ask for the recovery key at sign-in (this flow is the natural fix). - #16: messages stay "encrypted" after verifying until the room is reopened. - Upstream #852 (backup restore fails unless done right after verification), #707 (blank enable-cross-signing dialog), #616 ("reset cross signing → use existing keys" never completes), #752 (a permanent recovery-key button in Security). All open upstream, none with a PR (2026-10-06).

robocub added the

feature

effort: large

labels

2026-10-06 21:26:47 +00:00

robocub referenced this issue

2026-10-06 21:27:16 +00:00

Warn before signing out of the last device, and offer an encrypted key export #72