amethyst/desktopApp/plans/2026-08-11-new-account-key-onboarding-plan.md

First-Run "Save Your Keys" Onboarding — Plan (Desktop)

Date: 2026-08-11 Branch: feat/key-backup-nsec-exposure Supersedes: the single NewKeyWarningCard for freshly-generated accounts.

Why

New-account key backup is the highest-stakes moment in a Nostr client: the nsec is shown once and can never be reset. Current impl crams warning + npub + nsec + encrypted-copy + checkbox + continue into one NewKeyWarningCard. Inside the 480px add-account dialog it has no scroll, so it clips — labels above and the Continue button below are cut off → reads as "no label / no way forward". Even un-clipped, one dense card is confusing.

Decision (user): guided multi-step full-screen flow, soft checkbox gate.

What already exists (reuse — don't rebuild)

• Split generation (just built): AccountManager.buildNewAccount() creates the keypair WITHOUT activating it; activateAccount(state) flips account state. This is what lets a backup step render before the account switch tears the screen down. Keep.
• Entry points that generate a key:
  • Cold start: LoginScreen (onGenerateNew → buildNewAccount()).
  • Logged-in: AddAccountDialog (onGenerateNew → buildNewAccount()), confirmed via onNewAccountConfirmed on the App scope.
• Pieces to lift out of NewKeyWarningCard: CopyKeyButton, EncryptedCopyRow (NIP-49 password → ncryptsec1), SelectableKeyText, the warning strings (new_key_*). The nsec→hex decode (decodePrivateKeyAsHexOrNull) + Nip49.
• QR: QrCodeCanvas(data) — npub only, never nsec.
• Settings backup card (BackupKeysCard) already covers "view my keys later".

Design — NewKeyOnboardingScreen (stepper, 3 steps)

A full-window composable (NOT a dialog). Rendered while buildNewAccount() result is held and before activateAccount. Fixed max content width (~560dp), centered, each step vertically scrollable so nothing clips.

Step 1 — Why this matters (education)

• Headline "Save your keys" + plain-language explainer: npub = your public identity (shareable); nsec = a password that can never be reset or recovered — lose it and the account is gone. No inputs. [Next].

Step 2 — Your keys (the actual backup)

• Public key (npub): monospace, Copy, optional Show QR.
• Secret key (nsec): monospace (shown — this is the one moment we intentionally reveal it), Copy (primary, prominent) + best-effort clipboard auto-clear.
• Copy encrypted (recommended): collapsible/secondary — password field → ncryptsec1. Keep out of the way so the primary Copy is obvious.
• Strong "never share the nsec" inline warning. No nsec QR. [Back] [Next].

Step 3 — Confirm & continue (soft gate)

• Recap one line ("Stored somewhere safe? A password manager is ideal.").
• Soft checkbox "I have saved my keys somewhere safe" → enables Continue. (Honor-system, matches the Android nudge decision. No copy/verify enforcement.)
• Continue → activateAccount(state) + persist + proceed into the app.

Progress indicator (e.g. "Step 2 of 3" or dots). [Back] on 2/3.

Integration

• New file: desktopApp/.../ui/auth/NewKeyOnboardingScreen.kt (stepper + step composables; reuse the extracted Copy/Encrypt pieces).
• Cold start: in LoginScreen, when generatedAccount != null render the onboarding screen full-bleed instead of the inline card. onFinish = activateAccount + onLoginSuccess.
• Add-account: when a key is generated, DON'T keep it inside the small dialog. Either (a) dismiss the dialog and show the onboarding screen at the App level (preferred — full space, survives the later account switch), or (b) let the onboarding screen be the dialog's content at a larger, scrollable size. Pick (a) for consistency with the cold-start path: hoist a top-level pendingNewAccount: AccountState.LoggedIn? in the App composable; both entry points set it; one NewKeyOnboardingScreen renders when non-null; onFinish activates + persists on the App scope. This unifies both flows through one screen and removes the dialog-clipping problem entirely.
• Retire NewKeyWarningCard (and its Preview) once both paths use the stepper.

Testing (add to the manual sheet)

• Cold start: log out → Generate → 3-step screen, no clipping, Copy works, encrypted copy → ncryptsec1, checkbox gates Continue, Continue lands in app.
• Add account (already logged in): Add → Generate → same screen at App level (not a cramped dialog), Continue switches to the new account + persists (survives restart).
• Back/Next preserve state; window resize keeps everything reachable (scroll).
• NIP-49 round trip (encrypted copy → login elsewhere → same npub).

Non-goals / follow-ups

• Android first-run guided screen (Android already has AccountBackupScreen + post-signup nudge; a matching stepper is a separate follow-up).
• Hard copy/verify enforcement (explicitly declined — soft gate).
• Mnemonic (NIP-06) backup.

Unanswered questions

• Add-account path: hoist to App-level full-screen (recommended) vs enlarge the dialog to host the stepper? (Plan assumes hoist.)
• Does generating from the logged-in state and cancelling mid-onboarding need an explicit "discard this new key" confirm, or is silent discard fine?
• Show the nsec revealed by default on Step 2 (it's first-run, user must save it) — or masked-with-reveal like the Settings card? (Plan assumes shown, since the whole point is to save it now.)
• Progress UI: numbered "Step X of 3" vs dots vs a top wizard bar?
• Keep the NewKeyWarningCard as a fallback anywhere, or fully delete?