Skip to content

Commit 4185c2e

Browse files
klopez4212Terp
andcommitted
Apply reviewed onboarding flow and copy
Offer explicit backup consent after key creation and replacement, persist declined backup, simplify recovery states, and require a name to complete onboarding joins. Co-authored-by: Terp <5856f6900e8e0a4e0ea1f4f8d2ee33e4753d2119bc122f94ecafc660b46c0511@buzz.block.builderlab.xyz> Signed-off-by: klopez4212 <[email protected]>
1 parent 261d1a4 commit 4185c2e

19 files changed

Lines changed: 876 additions & 576 deletions

‎docs/buzz-help.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,11 @@ the interface unless an available tool actually supports that action.
2626
community policy links open separately.
2727
On Mac, the welcome entrance plays once per app storage profile; Reduce Motion
2828
skips it, and pressing a key finishes it immediately.
29+
The key-import field displays the entered key as plain text for checking.
2930
Setup then creates a new key or takes an existing private key, and may link
30-
it to the signed-in account and back it up; a returning account may restore
31+
it to the signed-in account. **Back it up** explicitly enables online backup;
32+
**Not now** continues with automatic backup disabled. A name is required to
33+
finish joining a community; an avatar is optional. A returning account may restore
3134
its backed-up key where the build and account allow it. If the older Buzz app
3235
was used on this computer, a **Continue with your Buzz identity?** dialog
3336
brings that identity over without signing in; **Not now** keeps the welcome

‎docs/identity.md‎

Lines changed: 55 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -54,8 +54,8 @@ the address;
5454
signed in, continues from there with no link step and no backup offer; **Back**
5555
returns to the welcome screen with the address kept.
5656

57-
Success continues to a **Setting up Buzz** page that shows the current step
58-
beside a spinner. It first runs **Checking your account**, a real read of the
57+
Success continues to **Getting ready**, with an animated bee. Detailed operation
58+
status remains available to screen readers without a visible second line. It first runs **Checking your account**, a real read of the
5959
Nostr key bound to the signed-in Builderlab account
6060
(`POST /api/goose/v1/buzz/nostr-identities/current` at the portal that signed
6161
the user in, authenticated with the first-run session credential and sent
@@ -88,56 +88,26 @@ leaves the lookup unavailable rather than empty, and never fails setup: it only
8888
decides whether Welcome back offers a restore and whether an import needs the
8989
backup offer.
9090

91-
**Not linked** then pauses on **Set up your key**: when the lookup listed no
92-
backups, it says no backed-up key was found for this account, so Buzz will
93-
make one (an unavailable or failed lookup says nothing either way, nor does
94-
one that lists backups, which outlive an unlink), and it says that an
95-
encrypted copy is backed up to the account, which Block can use to restore the
96-
key on the user's other devices. Under the body it says who is signed in
97-
(*Signed in as {email}.*, or *Signed in.* when the portal sent no address), so
98-
a wrong account is visible before any key exists. Like the welcome screen, it
99-
stacks its choices at the bottom: **Create my key** (primary) above a quieter
100-
**I already have a key** and **Use a different account**, which signs the
101-
first-run session out and returns to the welcome screen with the typed address
102-
kept and no key created. The browser may still hold the portal's own cookie
103-
session, so the next **Sign in with email** can re-select the same account
104-
unless the user signs out of the portal in the browser first; first run cannot
105-
end that session. Choosing Create my key is the backup consent (see
106-
[consent hooks](#automatic-backup-consent-hooks)). It runs **Creating keys**,
107-
which generates a Nostr key through the same native create command as the key
108-
setup screen, so the next launch opens as a returning user; then **Linking your key**, which
109-
binds that key to the signed-in account at the same portal (kgoose's binding
110-
challenge, signed natively as a kind-24243 event, then verified — the flow the
111-
hosted-communities card drives), sending nothing more when the account already
112-
holds the key; then **Backing up your key**, which waits for the native
113-
uploader to confirm the backup
114-
([automatic backup](#automatic-backup-and-optional-recovery)). First run never
115-
shows the new key; Settings → Identity can reveal it later.
116-
117-
**I already have a key** opens **Enter your private key** while setup stays
118-
paused, laid out as the onboarding import screen (centred heading and body,
119-
**Continue with this key** above **Back** at the bottom): a masked private-key
120-
field —
121-
paste or type an `nsec1…` key,
122-
or drop or choose a text file of at most 1 KiB whose first line is one — with
123-
**Reveal private key**, a live *Public identity* npub preview under a valid key
124-
(never hex), and classified messages for anything else: a NIP-49 `ncryptsec1…`
125-
backup is refused as *Password-protected backups aren’t supported here yet*
126-
(the app has no NIP-49 decryption), other text as *That doesn’t look like a
127-
valid nsec*. **Back** returns to Set up your key with the typed key discarded;
128-
**Continue with this key**, enabled only for a valid nsec, stores it through the
129-
same native import command as the key setup screen (`identity_import`, which
130-
takes the nsec as typed) behind *Importing your key…*, shown on the same
131-
screen. A native refusal — an
132-
invalid key, or a key already saved in this slot — appears under the field with
133-
the form kept. An imported key is then linked to the account like a created
134-
one and pauses on **Back up this key?**, since importing never uploads
135-
silently: Buzz can keep an encrypted copy in the account, which Block can use
136-
to restore this key, including anywhere else it is used. **Not now** carries on without a
137-
backup; **Back it up**, the backup consent for that key, runs **Backing up your
138-
key**. An import from **Connect to {host}**, with no Builderlab sign-in, has
139-
no account to link the key to or back it up in, so it skips the link and the
140-
offer and continues at once.
91+
**Not linked** pauses on **Get started with Buzz**. **Create my key** creates
92+
and links a key; **Use an existing key** opens **Enter your private key**. **Use a different
93+
account** signs out the first-run session and returns to the welcome screen.
94+
The browser may retain its portal session. This choice page intentionally omits
95+
the signed-in email line.
96+
97+
Creation does not authorize backup. After creating and linking, Buzz asks
98+
**Back up your key?**, with the disclosure that Block can restore the encrypted
99+
copy, including anywhere else the key is used. **Back it up** enables automatic
100+
backup and waits for the uploader. **Not now** persists automatic backup as off
101+
when the build supports backup, then continues. A failed upload can also be
102+
skipped with automatic backup disabled. First run never reveals a newly created
103+
key; Settings → Identity can reveal it later.
104+
105+
**Enter your private key** accepts a plain-text `nsec1…` key or a text file up to 1 KiB.
106+
The public identity preview uses npub. NIP-49 encrypted backups are not supported;
107+
invalid input stays on the form. **I lost my key** sits under the input. **Back**
108+
discards the draft. A successful account-backed import links the key and offers
109+
backup unless that key already has a backup. An import without Builderlab
110+
sign-in skips linking and backup. Importing alone never authorizes an upload.
141111

142112
**Linked** pauses on **Welcome back**: the account is already linked to a Buzz
143113
identity — the key on the user's other device — shown as the full npub under
@@ -150,44 +120,30 @@ same import page, which here accepts only the linked key: any other valid nsec
150120
is refused under the field with *That isn’t the key linked to this account. It
151121
expects npub1…*, and **Back** returns to Welcome back. **Recover from another
152122
device** is *Coming soon* (device pairing is its future entry). Last in the
153-
stack, **Use a different account** is the same exit as on Set up your key: it
123+
stack, **Use a different account** is the same exit as on Get started with Buzz: it
154124
signs the session out and returns to the welcome screen without importing,
155125
restoring or replacing the linked key. The imported
156126
key is already the account's, so nothing is linked. Unless the lookup already
157-
lists it, a successful import then pauses on **Back up this key?** as on a new
127+
lists it, a successful import then pauses on **Back up your key?** as on a new
158128
account; a listed key continues without the offer.
159129

160-
**Restore from backup** runs native recovery (see
161-
[optional recovery](#automatic-backup-and-optional-recovery)), which opens its
162-
own browser sign-in: the first-run one is not reused. Above the recovery, the
163-
page centres its heading and, only while it waits for that sign-in or offers
164-
the linked key, *Your key is stored securely on this device.*: an outcome that
165-
restores nothing drops the line, and the unavailable copy below replaces it. Of
166-
the keys it recovers, only the linked one is offered; a recovery without it
167-
says *None of your backups holds the key linked to this account, so nothing was
168-
restored.*, installs nothing and offers **Enter your private key**, which opens
169-
the import page. Installing the key continues as an import does, without the
170-
backup offer: the key is already backed up. Where recovery is unavailable for
171-
the deployment or refused for the account (public organizations are refused by
172-
design), the page says *Backup restore isn’t available for this account* and
173-
offers **Enter your private key**, which opens the import page, never a retry.
174-
Any other failure offers **Try recovery again**. **Back** cancels the recovery
175-
and returns to Welcome back.
176-
177-
On Welcome back, **I lost this key** (quieter) runs **Finding communities**, a real read of the
178-
communities the account owns
179-
(`POST /api/goose/v1/buzz/communities/list`), and shows **Start over with a new
180-
key**: a new key loses everything the old one could reach; *Communities you
181-
own* lists their hostnames (*None* when empty, or that the list could not be
182-
loaded), and memberships in other people's communities cannot be listed and are
183-
lost too. The page also says that starting over unlinks the old key, then
184-
creates a new key, links it to the account and keeps an encrypted copy that
185-
Block can use to restore it, so choosing it is the new key's backup consent.
186-
**Back** returns to Welcome back; **Start over with a new key** (destructive)
187-
runs **Creating keys**, then *Unlinking your old key*, which deletes the old
188-
key's binding (`POST /api/goose/v1/buzz/nostr-identities/delete`), then
189-
**Linking your key** and **Backing up your key** for the new key, with no key
190-
choice between. The old key stays linked until the new one is on the device,
130+
**Restore your key** opens native recovery in a separate browser sign-in.
131+
Only the account’s linked key can be installed. While waiting, **Cancel** cancels
132+
the attempt; during installation, navigation is disabled. A successful install
133+
continues without a backup offer. Failure shows **Couldn’t restore your key**,
134+
with **Enter my private key**, **I lost my key**, optional **Try again**, then Back.
135+
Retry is available for transient errors and partially retrieved backups, but not
136+
for unavailable/refused recovery, a complete empty result or complete mismatch.
137+
Leaving or retrying cancels the native attempt first. Nothing claims the key is
138+
saved before installation succeeds.
139+
140+
**I lost my key** opens **Lost your key?**, which first suggests checking another
141+
signed-in device or a usable backup. Starting over replaces the linked key;
142+
old messages and profiles are not deleted, but access does not carry over.
143+
Owned community hostnames appear only when present; a failed lookup still shows
144+
its error. **Go back** returns to the prior screen. **Start over with a new key**
145+
creates a key, unlinks the old key, links the new one, then offers optional backup.
146+
The old key stays linked until the new one is on the device,
191147
and binding never overwrites, so the unlink comes after creation and before
192148
the link. The unlink checks the bound key first: it sends nothing more when
193149
the account holds no key or the new one, fails when it holds a third key, and
@@ -383,29 +339,24 @@ claim or the read — shows the lookup's unreachable copy; a device that will
383339
not keep the join's record shows the journal's storage message. Both offer
384340
**Back**. An existing relay profile seeds the empty local default.
385341

386-
When no profile exists anywhere — the relay held no kind 0 for the key and the
387-
device's local default has no name (read before the join, since `joined` adopts
388-
a relay profile into an empty default) — the gate stays up for **Set up your
389-
profile** (`src/features/identity/ProfileStep.tsx`): the shared profile
390-
fields — avatar, required display name, optional description — prefilled with
391-
the local part of the Builderlab email as the name (blank when the key was
392-
imported without a Builderlab sign-in). The same rule applies after
393-
*Restoring your communities*: if none of the admitted destinations held a
394-
profile and the local default has none, the step is shown for the selected
395-
one, and a handed-off address opens in the dialog only after it, so the
396-
dialog's own profile step starts from the name given here. A relay that
397-
already holds the key's profile, or a local default with a name, skips the
398-
step. **Continue** is the dialog's profile step (`completeJoin`): the draft is
342+
When the admitted relay profile has no trimmed nonempty name, the gate stays up
343+
for **Set up your profile** (`src/features/identity/ProfileStep.tsx`). The shared
344+
fields show an optional avatar and required name, suggested from the Builderlab
345+
email when there is no existing relay profile. The same prompt follows community
346+
restoration when the selected relay profile has no name. A named relay profile
347+
skips it. Restored memberships are already saved: this prompt is not a persistent
348+
relaunch gate for those existing memberships. **Continue** uses the dialog's
349+
profile completion (`completeJoin`): the draft is
399350
recorded in the join journal, the profile is read afresh, the kind 0 is
400351
published to that one relay through the same signed `relay_sign` +
401352
`POST /events` route Settings → Profile uses when the draft differs from what
402353
the relay holds, and it is read back; only a readback that is current saves the
403354
membership (and the result as the device's local default for later joins) and
404355
enters the app on the community. A rejected publish, or a readback the relay
405356
has since superseded, stays on the step with the error inline and the draft
406-
intact. **Skip for now** saves the membership alone, publishes nothing, and
407-
enters the app; Settings → Profile remains the
408-
editor. Denied/unavailable/corrupt storage is not first run: like the page
357+
intact. **Go back** returns to community selection without completing the join.
358+
A trimmed nonempty name is required; the avatar is optional. Settings → Profile
359+
remains the editor. Denied/unavailable/corrupt storage is not first run: like the page
409360
shown while the saved identity opens, it is titled **Your Buzz identity**, and
410361
it keeps the **Retry secure storage access** path.
411362

@@ -799,12 +750,9 @@ The native identity service exposes `getBackupChoice()` and
799750
`setBackupChoice(pubkey, automatic)`. These APIs expose public metadata and do not
800751
change identity readiness. Reading a choice does not contact a server; saving
801752
automatic backup wakes the existing native uploader if a session is connected.
802-
First run's selections are **Create my key**, **Start over with a new key** and,
803-
for an imported key, **Back it up**: each page discloses that Block can restore
804-
the key (an imported one including anywhere else it is used) before **Backing
805-
up your key** saves `automatic: true`. Account sign-in, the key setup screen,
806-
an import without Builderlab sign-in and **Not now** do not imply consent, and Settings has no
807-
selection.
753+
First run's backup consent is **Back it up**, after creating, replacing or
754+
importing a key. Creating or linking the key does not authorize an upload.
755+
**Not now** persists automatic backup as disabled when backup is available.
808756

809757
The choice is bound to the current public key and trusted build-configured backup
810758
service and namespace. Missing or mismatched metadata returns no choice;

‎src/app/first-run-join-handoff.test.tsx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -234,7 +234,9 @@ async function firstRunWithAddress(
234234
await screen.findByRole("button", { name: "Other options" }),
235235
);
236236
await user.type(
237-
await screen.findByRole("textbox", { name: "Community URL" }),
237+
await screen.findByRole("textbox", {
238+
name: "Community address or invite link",
239+
}),
238240
`${address}{Enter}`,
239241
);
240242
await user.click(
@@ -243,6 +245,7 @@ async function firstRunWithAddress(
243245
await user.click(
244246
await screen.findByRole("button", { name: "Create my key" }),
245247
);
248+
await user.click(await screen.findByRole("button", { name: "Back it up" }));
246249
const dialog = await screen.findByRole("dialog", {
247250
name: "Join a community",
248251
});

‎src/features/identity/BackupOffer.tsx‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { Button } from "../../shared/design-system/ui/Button";
22

33
/**
4-
* Pause after an imported key, on either lane. Importing must never upload
4+
* Pause after creating, replacing or importing a key. None may upload
55
* silently: the backup is offered, and the key continues either way. The key
66
* may be used elsewhere, so the copy discloses that Block can restore it there
77
* too; choosing Back it up is the backup consent.
@@ -21,12 +21,15 @@ export function BackupOffer({
2121
tabIndex={-1}
2222
className="text-heading text-standard"
2323
>
24-
Back up this key?
24+
Back up your key?
2525
</h1>
2626
<p className="mt-2 text-body text-subtle">
27-
Buzz can keep an encrypted copy in your account so you can skip this
28-
step on your next device. Block can use that copy to restore this key,
29-
including anywhere else you use it.
27+
Save an encrypted copy of your private key online with your Builderlab
28+
account. You can use it when setting up Buzz on another device.
29+
</p>
30+
<p className="mt-2 text-body text-subtle">
31+
Block can use that copy to restore this key, including anywhere else
32+
you use it.
3033
</p>
3134
</div>
3235
{/* Footer order: secondary first, primary last. */}

‎src/features/identity/CommunityUrlField.tsx‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -55,15 +55,17 @@ export function CommunityUrlField({
5555
<div className="flex flex-col gap-12">
5656
<div className="min-w-0 w-full">
5757
<Field
58-
label="Community URL"
59-
error={invalid ? "Please enter a valid community URL" : undefined}
58+
label="Community address or invite link"
59+
error={
60+
invalid ? "Enter a community address or invite link." : undefined
61+
}
6062
disabled={disabled}
6163
>
6264
<Input
6365
inputMode="url"
6466
autoComplete="off"
6567
spellCheck={false}
66-
placeholder="relay.example.com"
68+
placeholder="community.example"
6769
value={url}
6870
disabled={disabled}
6971
onChange={(event) => {

0 commit comments

Comments
 (0)