feat(settings): read-only Key backup row in Settings → Identity - #1821

… a plugin session, kgoose reads, link/unlink, backup, saved communities — and its dev seed

All of first run's network logic, no UI. Nothing on main calls it yet; the
Welcome flow (PR 07) is the caller.

`src/bundled/builderlab/oauth/first-run.ts` (new): binds a `Host` to the
Builderlab plugin's own bundled native grant (`block.builderlab`/`bundled`,
granted at build time from `BUZZ_BUILDERLAB_URL` and the tenant table) and
exposes `firstRunCredential(signal, origin?)`, the plugin's
`browserCredential` run before any plugin session exists. That credential
is separate from the Settings session and is never persisted.

`src/features/identity/builderlab-account.ts` (new): `FirstRunAccount`, the
kgoose reads and writes first run needs, every request a POST with `{}` or
a body, `X-BB-Session-Credential` from the first-run session and `Origin`
set to the login origin that signed the user in, through `bundledHost.request`:
- `linkedKey` (`/v1/buzz/nostr-identities/current`): a 2xx with `identity`
  null or absent is *not linked* (kgoose never sends `MISSING_MAPPING` on
  this route); a present identity whose `pubkey_hex` is not 64 lowercase
  hex fails — a linked account must never be given a second key.
- `ownedCommunities` (`/v1/buzz/communities/list`, archived and insecure
  hosts excluded) and `knownCommunities`
  (`/v1/buzz/known-communities/list`, read with the Builderlab plugin's own
  `listedAddress`, exported from `known-communities/client.ts` for this; a
  row this client cannot read rejects the whole list).
- `bind(pubkey)`: reads `current` first and returns when the account already
  holds this key, else challenge → native `identity_sign_builderlab_binding`
  → verify, which must confirm this key. 409 `identity_already_bound` /
  `pubkey_already_bound` take the hosted-communities card's copy.
- `unbind(old, new)` (`/nostr-identities/delete`): the route takes no key
  and deletes whatever is bound, so it sends the delete only while `current`
  still answers the old key, counts as done when the delete echoes the old
  key or a re-read shows none or the new key, and fails without Try again
  if the old key is still bound. The real fix is an `expected_pubkey_hex`
  on the delete, noted in a comment.
- `backUp(pubkey)`: refuses with `BackupError("unavailable")` unless
  `backupOfferedFor(backup, origin)` holds — this build's uploader backs up
  to Builderlab and the sign-in is at the build's own portal (a tenant's
  credential is never handed to the native uploader) — then `backUpWith`.
- `backupStatus()` (`/v1/buzz/nsec-backups/status`): the listed hex keys;
  "unavailable" without a request unless offered, and on a 404; other
  answers map to the backup failure kinds.
- `recovery`: the native recovery driver, so the dev seed can replace it.
- `saveCommunity(url)` (`/v1/buzz/known-communities/add`,
  `wss://host[:port]`).
- Shared `call`/`post`: transient failures (no status, 429, 5xx) are
  retryable, 4xx refusals and rejected shapes are not; any HTTP 401 is
  "Your Builderlab sign-in is no longer valid."; failure copy names the
  step and status, never a response body; kgoose codes the card's table
  lacks get first-run copy (`invalid_origin`, `invalid_challenge`,
  `challenge_*`, `too_many_attempts`; `challenge_expired/consumed/not_found`
  retryable since Try again fetches a fresh challenge); the correlation ID
  stays off the page and goes to a development-only `console.warn`.

Dev seed (`first-run-seed.ts`, new; `seededAccount`):
`BUZZ_DEV_FIRST_RUN_ACCOUNT` — `unlinked`, or `{"npub","communities",
"known","backups","recovery","backup":"<kind>"|"fail-once","unlink":<status>}`
— replaces the kgoose reads, the binding, the unlink, the backup and backup
recovery, and nothing else, on a dev server. `vite.config.ts` validates it
(explicit `.ts` imports so Node's native config loader stays warning-free)
and defines `VITE_BUZZ_FIRST_RUN_ACCOUNT` for `serve` only; builds define it
empty. Bad values are rejected without being echoed. A developer's real
account binding never changes under a seed.

Docs: `docs/configuration.md` (the seed row and "First-run account seed
(development)" section), `.env.example`, the Builderlab README's first-run
paragraph.

Tests: `builderlab-account.test.ts` (1,337: every route's exact request at
a tenant and at the build URL; linked/not-linked readings; the bind
sequences incl. the already-bound no-op and 409 from verify; unbind's
current-then-delete with echo and re-read outcomes; backUp's tenant guard
and handoff; backupStatus mappings; saveCommunity; the retryability, 401
and correlation-ID rules; the seeded account), `first-run-seed.test.ts`
(268: every field, rejections without echo, the seeded backup/unlink/
recovery behaviours), `oauth/first-run.test.ts` (the bundled grant request
shape with and without an origin), and the seed lines of
`browser-host/vite-config.test.mjs` (serve vs build define, rejections).

Stack: PR 05 of the onboarding stack, on 04; imports 02 (`destination`),
03 (`backup`, `backup-failure`, `service`) and 04 (`oauth/browser`). 06–08
build on it.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Signed-off-by: Matt Toohey <[email protected]>

…ion follows in the next PR)

The stateless building blocks of the first-run flow, reviewable as
components against DESIGN.md and Kenny's onboarding layouts. Nothing
imports them until PR 07 (`Welcome.tsx`); the repo has no unused-export
check, so lint and typecheck pass with them standing alone.

Setup store and steps (`setup.ts`): `createSetup()` with `start(steps,
then)`, `retry()` (re-runs only the failed step, then the rest) and
`reset()`, over snapshots `idle` / `running{label}` / `paused{at}` /
`failed{error, retryable, skipsLink}` / `done`; a step's `run` may resolve
to a resting state that overrides the caller's `then`. Step factories:
`checkAccount(account, onLinked, onKnown)` (the linked-key and
known-communities reads in parallel under one label; the list read never
fails setup), `checkBackup(account, onListed)` (never fails setup),
`createKey`, `importKey`, `linkKey`, `unlinkKey(account, old, new)`,
`restoreCommunities(known, communities, decide)` and `finish()`.
`restore-communities.ts`: `restoreKnown(known, communities, { concurrency:
3, startBy: 45_000 })` — the same signed profile read the Join Community
page uses, at most three at once, nothing started after 45 s, each admitted
destination saved through `communities.joined`; outcomes `admitted` /
`denied` / `unavailable` in list order; never throws. `key-import.ts`:
`classifyKeyImport` (empty / `ncryptsec` refused with a clear message /
`nsec` with its npub preview / invalid) and `readKeyFile` (1 KiB cap, first
non-blank line).

Pages (all `src/features/identity/`, stateless, props-driven):
`CommunityUrlField` (bare host, `wss://`/`https://`, or an invite link —
`https://<host>/invite/<code>`, `buzz://join?relay=…&code=…` — via
`enteredCommunity`; Continue stays enabled while empty/invalid and shows one
inline error), `InviteCodeField`, `JoinCommunity` (owned rows named "Join
{host}" for assistive technology, the URL field, the disabled "Scan a QR
code" / "Create a community — Coming soon" buttons, on the onboarding
layout), `KeyChoice` (Create my key / I already have a key / Use a
different account, the signed-in address, the backed-up-key sentence only
when the lookup listed none), `KeyImport` (masked field, Reveal/Hide, file
drop/picker, npub preview, `expectedPubkey` mismatch refused in the page,
"Importing your key…" on the same screen), `KeyLost`, `KeyRestore` (the K3
column; "Your key is stored securely on this device." only while the
restore may still install the key; the unavailable/refused page),
`BackupOffer`, `ConnectChoice` ("Connect to your community" with the host
on its own mono line), `WelcomeBack` (the linked npub with Copy, Restore
from backup when listed, Enter your private key, I lost this key, Use a
different account), `PublicKeyPanel`, `SetupProgress`, `Wireframe`
(`WireframeScreen` on Kenny's frame, `WireframePanel` as the one stacking
group), `ProfileStep` (a pure form over `ProfileFields`: Continue hands the
trimmed draft out, Skip for now leaves). Every `h1` carries `tabIndex={-1}`
and the Back triggers `data-return-focus`, for the heading-focus handoff
`Welcome` performs. Shared owners only: `Button`, `Field`, `Input`,
`Checkbox`, `Avatar`, `LoadingRegion`, `OnboardingScreen` and Kenny's
`IdentitySetup.module.css` classes (unchanged); role colours and type roles
only, no new tokens or variants.

Tests: `setup.test.ts` (retry/rest/idle semantics, `checkAccount` and
`checkBackup` never failing setup, `unlinkKey` sending nothing while the
old key is on the device), `restore-communities.test.ts` (three reads at
once, outcomes in list order, dedupe and insecure skip, throwing `joined`,
the 45 s cutoff under fake timers), `key-import.test.ts`,
`CommunityUrlField.test.ts` (8 accepted and 10 refused forms),
`ProfileStep.test.tsx`. The pages' rendered checks (Chromium/WebKit, light/
dark, 480/1100 px, 150 % text) were done on the branch in scratch fixtures
and are recorded in the branch's commit history; mount a page with stub
props to repeat them.

Stack: PR 06 of the onboarding stack, on 05; imports 02 (`destination`,
`find-community` types, `api`, `ProfileFields autoFocus`), 03 (`service`,
`RestoreIdentity` `expectedPubkey`/`onImport`, `BackupError`) and 05
(`builderlab-account` types). 07 composes these.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Signed-off-by: Matt Toohey <[email protected]>

…e (FOUNDATION: App.tsx)

The composition and the product flow. On native desktop with no human key
in the credential store, the app now opens on `Welcome` instead of the
"Your Buzz identity" key import/create screen, and stays there until a key
exists and setup has nothing left to do.

FOUNDATION edit (`src/app/App.tsx`), the three approved lines: import
`Welcome` from `../features/identity/Welcome` instead of `IdentitySetup`,
and wrap `ConnectedApp` in `<Welcome identity={services.identity}
communities={services.communities} invites={services.invites}>`. No other
FOUNDATION file (`services.ts`, `main.tsx`, `communities/service.ts`,
`plugins/api.ts`) is touched. `IdentitySetup` stays for the credential-free
browser fixture and gets a one-line comment.

`Welcome.tsx` (new, 940 lines) owns the flow; its state (`finding`,
`inviteCode`, `entered`, `reads`, `known`, `linked`, `owned`, `backups` and
the `setup` store) is shared by every lane, which is why it lands whole:
- Landing: "Buzz" on Kenny's onboarding screen — Sign in with email,
  Community URL (bare host, origin or invite link; Continue starts the
  lookup) and Scan a QR code — Coming soon.
- A typed address is looked up before any sign-in (`FindCommunity`, two
  unauthenticated GETs) and fails fast; a found community decides the
  portal through `discoverAuthentication`: a tenant's relay signs in at that
  tenant's portal, an unmatched one pauses on "Connect to your community"
  (Sign in with email at the build portal, or I already have a key, which
  imports without any account and lands on Join Community).
- After sign-in: Checking your account… (linked key + saved destinations in
  parallel) → Checking for a backed-up key… → Set up your key (Create my
  key: Creating → Linking → Backing up; I already have a key: Importing →
  Linking → Back up this key?; Use a different account) or, for a linked
  account, Welcome back (Restore from backup when listed, Enter your private
  key accepting only the linked key, I lost this key → Start over with a new
  key: Creating → Unlinking the old key → Linking → Backing up, Use a
  different account). Both post-sign-in pages show the signed-in address.
- Couldn’t finish setup: Try again for retryable failures; once a key
  exists a failed backup offers Continue without backup, a failed link or
  unlink blocks with Try again only (nothing links the key later); before a
  key exists, Back to the landing. The key choice and reveal pages never
  show hex; nothing is signed to a relay before the user chooses to join.
- Restoring your communities…: the account's saved destinations are read
  with the signed profile read and admitted ones saved; setup rests on Join
  Community (typed URL) or Join a community when nothing was admitted,
  enters the app on the first admitted one otherwise, and hands a typed
  address or invite code that was not among them to the rail's
  Add-a-community dialog through `invites.open`, the intent OS deep links
  already use.
- Join Community joins through `admitCommunity`/`completeJoin` (journal
  before any effect, read before reclaim, `accept-policy` → `claim` with an
  invite code, the signed read); a denied read opens "This community needs
  an invite" with the npub, Copy, an invite-code field, Back and Try again;
  a user with no profile anywhere gets the Set up your profile step before
  the membership is saved; a join after a Builderlab sign-in is also saved
  to the account (`saveCommunity`, best effort).
- Invariants: every return to the landing goes through `backToLanding`
  (clears discovery, the account reads and the first-run session; keeps the
  typed address); `enterApp()` fires a pending handoff, clears what `Welcome`
  kept and resets setup. Each page change moves focus to the new page's
  heading, or back to the choice that opened it on Back.

Tests: `identity.test.tsx` (whole file, +4,837/−109 vs main: the landing,
discovery, Connect, Join/profile/invite, key import, Welcome back/restore,
Start over/owned, failure and seed journeys over a `nativeRelay` fixture
with a real keypair, `relay_sign`, per-origin `relay_http` and a real
`createCommunities`; the exact `invoke`/`relay_http` sequences are asserted
throughout). This PR's `Welcome.tsx` is the `19df106d5` version, which
turns these six journeys green — they are red against the earlier
`572d69398` Welcome: "a link that fails after the key is created blocks
setup with only Try again…", "a link that keeps failing after a key is
imported…", "a transient unlink failure after Start over…", "an unlink
refused after Start over offers only Try again…", "a transient link failure
after a successful unlink…", "a development seed's unlink status fails Start
over's unlink…". `src/app/first-run-join-handoff.test.tsx` (new): the real
`App` + `createServices()` under mocked Tauri commands, the gate lifting
with the Add-a-community dialog open on a typed address or invite link, the
dialog's claim with the code, and Cancel. `src/app/first-run-navigation.test.tsx`
(new): proves PR 01's deadline rule through the real first-run gate.

Docs: `docs/identity.md` first-run block (every page, what is signed and
what is not, where Back lands, the failed page), `docs/communities.md`
(`Welcome` as the second caller of the join owner and the invite intent),
`docs/deep-links.md`.

Stack: PR 07 of the onboarding stack, on 06; depends on 01–06. 08 is based
on it only to keep the stack linear.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Signed-off-by: Matt Toohey <[email protected]>

…t today's rollout

Review follow-up on PR 1820, thread 3 (deployment rollout details in
public docs). Three sentences in `docs/identity.md` said which deployments
enable a feature today. Each now states what the build and service must
provide, and keeps the fallback:

- The backed-up-key lookup: kgoose answers `404` wherever backups are not
  configured. Dropped "which today is everywhere but staging's public
  Builderlab".
- Welcome back's restore: the unavailable page applies where recovery is
  unavailable for the deployment or refused for the account (public
  organizations are refused by design). Dropped "no tenant enables it
  today".
- Automatic backup: anywhere else (a tenant sign-in, or a build without
  backup configured) the step fails at once. Dropped "which today is".

`grep today docs/identity.md` now returns nothing. The tenant example rows
in `docs/configuration.md` stay; the reviewer excluded them. Docs only, no
behaviour change.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: Matt Toohey <[email protected]>

…eated denial

Review follow-up on PR 1820, thread 4 (Try again loses focus on a
repeated denial). `Failure` disabled Try again while its read ran. Both
Chromium and WebKit move focus off a focused button when it becomes
natively disabled. If the relay refused the key again, the page key
(`done:join-error:<title>`) did not change, so `Welcome`'s focus effect
did not run and keyboard users were left on `body`.

Try again now uses the shared Button's loading state while its own read
runs (`loading={busy === "read"}`). Base UI keeps it focusable with
`aria-disabled` and `aria-busy`, and the Button still blocks activation.
While an invite code is being claimed it stays plainly disabled. The
label stays "Try again": DESIGN.md's Button rule keeps the label's
geometry and accessible name while loading, so "Trying again…" is gone.
Back and the invite code field are unchanged.

Test: the invite-page Try again journey now holds a retry that the relay
refuses again. While the read is pending, Try again is focused,
`aria-busy` and `aria-disabled`, has no native `disabled`, and Enter
starts nothing. After the refusal, focus is still on Try again. Enter
then retries and is admitted, and the relay calls show each attempt is
the same signed read. jsdom keeps focus on a disabled button, so on the
previous `Welcome.tsx` the journey fails at the `aria-busy` check, not
at the focus check. Browser focus loss was confirmed with a standalone
Playwright probe (plain buttons, not the app): native `disabled` sent
focus to `body` in both engines, `aria-disabled` kept it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: Matt Toohey <[email protected]>

… landing

Review follow-up on PR 1820, thread 2 (preserve the explicit legacy-key
migration entry point). Replacing the key-setup gate with `Welcome` left
`identity.legacyAvailable()` / `identity.importLegacy()` reachable only
from `IdentitySetup`, which only the browser fixture still mounts. Someone
upgrading from old Buzz could no longer bring its identity over in one
click.

The offer comes back as an alert dialog over the Welcome landing. The
landing, its actions, the pages, the steps and the setup store are
unchanged; no FOUNDATION file is touched.

`LegacyIdentityOffer.tsx` (new) exports `useLegacyIdentityOffer(identity,
open)`. `Welcome` calls it with its other hooks and renders the result
only in the landing JSX, so the folder check and a dismissal outlive a
visit to another page (+6 lines in `Welcome.tsx`):
- `identity.legacyAvailable()` runs once per entry into `missing`, with
  `.catch(() => false)` and an `active` guard, as in `IdentitySetup`. The
  landing's buttons never wait for it.
- The dialog opens only when the check answered true, the landing is the
  current page (so setup is idle), no sign-in is pending, and it was not
  dismissed during this entry. A check that answers off the landing or
  during a sign-in waits until the landing is back.
- It uses the shared `AlertDialog` and `Button`, with no new tokens or
  variants. Title **Continue with your Buzz identity?**, then **Not now**
  and the prominent **Continue with your Buzz identity**, which calls
  `identity.importLegacy()`. While the import runs, Continue shows the
  Button's loading state, Not now is disabled, and `pending` blocks Escape
  and Close.
- A failed import shows its error inside the dialog (role alert), and
  Continue tries again. Only errors after the click are shown, so a setup
  error from another page never appears in the dialog.
- Success lifts the gate into the app with no sign-in, link or backup,
  where `LegacyCommunityImport` takes over as on main.
- Not now and Escape close it for this entry. `finalFocus` returns focus
  to the landing heading, since launch focuses nothing. Base UI's deferred
  initial focus still wins over `Welcome`'s heading-focus effect when the
  dialog opens as the landing returns.
- After Sign out, the next launch is a new entry into `missing`, so the
  offer returns while old Buzz's folder exists.

Tests (`identity.test.tsx`): the `IdentitySetup` migration journey moves
onto the live `Welcome` gate:
- no dialog when the check answers false or fails;
- no import before the click; Continue imports, stays pending, and
  enters the app with `connect` and `account` never called;
- Not now and Escape keep the landing, focus its heading, import nothing,
  and the offer stays closed after a failed sign-in and Back;
- a failed import shows its alert in the dialog, and Continue retries;
- no dialog while a sign-in is pending or setup runs; after a failed
  Create my key and Back it opens with focus and without the create error;
- the offer returns on the launch after Sign out.

Each guard was checked fail-before by mutation. Removing the render,
the pending-sign-in condition, `finalFocus`, the error scoping, `pending`,
or the dismissal each fails its targeted test. Mechanical updates: 36
exact command sequences gain `identity_legacy_available`; 29 `invoke`
mocks (including the shared `nativeRelay` and `landingRelay`) and five
`mockResolvedValueOnce` chains answer it `false`. So do the
`first-run-join-handoff`, `first-run-navigation` and `window-chrome`
fixture mocks.

Docs: `docs/identity.md` describes the dialog over the welcome screen:
when it opens, the click-only read, the error and retry, entering the
app with no Builderlab sign-in, link or backup, dismissal, and its return
after Sign out. The first-launch bullet in `docs/buzz-help.md` now
describes the Welcome flow and the offer.

Validation: lint, typecheck and `design:check` pass; the full Vitest
suite passes (854 files, 14,737 tests); `window-chrome.spec.mjs` passes
in Chromium. Rendered in a scratch fixture (not committed) in Chromium
and WebKit, light and dark, at 1100 and 480 px and with 150 % text. At
480 px with 150 % text the primary label is wider than the compact
dialog, and the shared footer scrolls horizontally. Not run: the native
app and a real keychain prompt.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: Matt Toohey <[email protected]>

The dialog's title already names the identity, and the long button label
wrapped the footer onto two rows at 1100 px and clipped at 480 px with
enlarged text. Not now and Continue now share one row at both sizes.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Signed-off-by: Matt Toohey <[email protected]>

First run leaves the automatic backup choice on after a failed backup, so a
later Builderlab sign-in may finish the backup in the background; this row
makes that visible. `BackupRow` (`src/app/IdentitySettings.tsx`) reads
`identity.backup` through `useSyncExternalStore`, as Settings reads its
other stores, and sits in the existing rows `SettingsGroup` above "Sign out
of Buzz" as a `PreferenceRow` with no trailing control; the sentence is
wrapped in `role="status"`.

One sentence per status — idle: "Buzz hasn’t checked your key’s backup
since it opened." (what a launch or reload reports, not "no backup");
running: "Backing up your key…"; complete: "Your key is backed up to
Builderlab."; waiting{no_consent}: "Automatic backup is off for this key.";
waiting{no_session}: "Sign in to Builderlab to back up your key.";
waiting{not_linked} and every failed kind: the entry from `BACKUP_FAILURES`
(`backup-failure.ts`), so it is the same copy as first run's failed page,
with the Settings tail "Buzz tries again when you next sign in to
Builderlab." for the causes a new sign-in clears (busy, unreachable,
unconfirmed, storage, signed_out). There is no second table. Read-only: no
consent toggle, no retry.

Hidden unless backup is offered, by the same rule first run uses:
`backupOfferedFor(backup)` (`builderlab-account.ts`) answers false unless
the build has a Builderlab URL, and then returns the status's `builderlab`;
any error answers false. Known differences, documented: the
row appears after the first status read, so "Sign out of Buzz" moves down
one row once the IPC answers; retryable messages end in "Try again." though
the row has no button; under the `BUZZ_DEV_FIRST_RUN_ACCOUNT` seed first run
offers backup while the row follows the real rule.

Tests: `IdentitySettings.test.tsx` drives the real `createBackupStatus`
store over a scripted native side with a mocked Tauri `Channel`: the
sentence for complete, running, waiting{no_session}, waiting{not_linked},
failed{unreachable} and the signed_out tail; hidden when the status says
`builderlab: false` and when the build has no Builderlab portal; following
pushes at seq 2, 3 and 4 with a late seq-2 push changing nothing; no button
or switch in the row. `Settings.test.tsx`'s identity case gains an inert
`backup` store. docs/identity.md describes the row.

Stack: on the Welcome flow to keep the stack linear, but it depends only on
the merged `backup.ts`, `backup-failure.ts` and `identity.backup` and the
account client's `backupOfferedFor` — it can be reviewed before the pages
and the Welcome flow.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Signed-off-by: Matt Toohey <[email protected]>