Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 41 additions & 17 deletions docs/buzz-help.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,14 +94,15 @@ mention anyone. Explicit agent watches on that room can still receive them.
without Builderlab sign-in do not upload a backup during setup. Later, while
signed in to Builderlab on a build with backup, a key with no backup choice is
backed up automatically if you belong to a Builderlab-hosted community;
otherwise Buzz asks **Sync your identity with Builderlab?**, again on the
next launch or sign-in if the dialog is closed. **Settings → Buzz → Identity
→ Identity sync** shows the sync status and, while backup is off, offers
**Sync with Builderlab**. When the key isn’t linked to your Builderlab
account, or the account holds a different key, its **Builderlab** link opens
**Settings → Plugins → Builderlab**, where **Connect Buzz identity** links
this key, or **Switch to this device’s identity** replaces the account’s key
(this permanently unlinks the old one). After signing in to the
otherwise Buzz asks **Back up your key?**, again on the
next launch or sign-in if the dialog is closed. In **Settings → Buzz → Identity**,
the ID card shows backup status. Open **More options** at the top-left of its
container for **Retry backup** or, while backup is off, **Back up key**, which
opens the consent dialog. When the key isn’t linked to your Builderlab
account, or the account holds a different key, the notice’s **Builderlab** link
opens **Settings → Plugins → Builderlab**, where **Connect Buzz identity**
links this key, or **Switch to this device’s identity** replaces the account’s
key (this permanently unlinks the old one). After signing in to the
public Builderlab, **Connect to a community** also offers **Create a
community** when that account is linked to this device’s key and may create one.
Choose an available address, then **Create community** joins it right away,
Expand Down Expand Up @@ -134,12 +135,34 @@ mention anyone. Explicit agent watches on that room can still receive them.
This lets the key direct your Buzz coding agents to run commands as you.
Authorize only keys you recognize: the proof has no time or event-kind limits. Your private key stays
in Buzz. This does not join the agent to a community or sign it in to an organization.
- The back of your Identity badge shows known backup and recovery details below
the private-key strip and scrolls when its details run long. Buzz starts checking
when the Identity page opens. The back always explains that the key is stored
securely on this device. It names the backup account when a configured service
confirms a backup and the account lookup has not failed. A failed lookup hides
that account sentence until recovery. Initial status loading stays quiet; a
failed check shows **Backup status unknown** with **Retry backup** in the
bottom action space on the back. This rereads local status and then starts a
backup attempt for the current key
when the read succeeds. It stays disabled and shows a spinner through both steps.
The private-key menu contains
the **Private key** heading above Copy and Reveal. If a confirmed backup’s
latest backup attempt fails, **Check backup** flips the card while the back
keeps the confirmed-backup explanation. Unconfirmed failures also show
**Check backup**. A spinner appears only while a backup attempt is running.
**Retry backup** uses that same space above **Remove from device** on the
back and shows a disabled loading button during an attempt. A confirmed, settled backup
shows **Backed up** with a destination tooltip. Only one recovery button
appears at a time. Initial status loading shows no pill.
**Remove from device** opens a confirmation before removing Buzz’s saved key
from this device’s secure storage and signing out. Account backups and copies
saved elsewhere stay. Other local data stays unless erasing is also selected.
- **Settings → Buzz → Identity → Copy private key** lets someone make their own
backup, for example in a password manager. They should handle it privately.
When Builderlab backup is on, the same page shows the account's linked key
when it is backed up, with when it was last active in the current community;
until the organization is signed in, that row asks them to sign in instead.
Backups of other keys are not shown, and the row is read-only.
when it is backed up and differs from this device’s key.
Account lookup failures use the card’s **Backup status unknown** caption and
**Retry backup** action. Backups of other keys are not shown, and the row is read-only.
Backup and restore options depend on the build and account; do not promise
recovery or assume automatic backup is on. Losing every copy of the private
key can mean losing the identity.
Expand Down Expand Up @@ -177,15 +200,16 @@ mention anyone. Explicit agent watches on that room can still receive them.
**Not now** opens Buzz anyway, but that organization's communities stay
unavailable until you sign in. Sign-in, sign-out and when the current
sign-in ends also live under
**Settings → Buzz → Identity → Organization sign-in**.
**Settings → Buzz → Identity → Community sign-ins**.
- When a community requires organization sign-in, the sidebar or join dialog
explains why and offers **Sign in with** the organization’s name or server
address. Complete sign-in to reconnect; in the join dialog, choose **Continue**.
- Signed in to more than one organization server? **Organization sign-in**
lists each one you're signed in to, with the communities that require it, and
each **Sign out** ends only that server's sign-in. Your organization's own
server stays listed with **Sign in** until you sign in to it. **Sign out of
Buzz** still ends them all.
- The **Community sign-ins** cards show each configured server, its account
and the saved communities that require its sign-in. Each **Sign out** asks for
confirmation and ends only that server’s sign-in. Signed-out servers keep **Sign in**.
**Renew sign-in** and the expiry date appear within seven days of expiry;
its caret menu offers **Sign out**. A Builderlab connection link opens its
existing settings. Removing the Buzz key still ends all server sign-ins.
- Buzz apps on this computer that use the same organization server, such as
Buzz and Buzz Staging, share its sign-in, like the private key. After you sign
in in one, **Sign in** in the other finishes without the browser. Signing out
Expand Down
109 changes: 80 additions & 29 deletions docs/identity.md
Original file line number Diff line number Diff line change
Expand Up @@ -330,18 +330,20 @@ open. Quitting with a key on the device but no saved community ends first run:
the next launch restores the key and, with setup idle, lifts the gate straight
into the in-app **Join a community** landing (`CommunityLanding`), the page a
key without a community has always opened on. The key stays on the device, and
the **Identity sync** row in Settings → Identity shows the backup state. A
the ID card in Settings → Identity shows the backup state. A
link or backup step still running at quit ends with the process: the native
uploader's pass is retired, and whether the link committed on kgoose is unknown
to the client. Both are safe to run again — the link reads the account's current
key first and does nothing when it already holds this one, and the uploader runs
again when the user next signs in to Builderlab in Settings — but nothing
re-runs the link on its own, and Settings has no row for it; the Identity
sync row reports only what the uploader's last pass found. Below it, a **Backed-up key**
row shows the account's linked key when `nsec-backups/status` (read with the
bundled Builderlab session as first run reads it) lists it, marked This device
when it is, with when it was last active in a channel on the current
community's relay. Backups of other keys are left out and the row is
card reports what the uploader's last pass found. Below it, a **Backed-up key · Linked**
row appears only when the account's linked key differs from this device's and
`nsec-backups/status` (read with the bundled Builderlab session as first run reads
it) lists it. The same-key summary and community activity lookup are omitted.
Account lookup failures share the card's **Backup status unknown** caption and
**Retry backup** action; retry refreshes the account lookup as well as starting
the native backup attempt. Backups of other keys are left out and the row is
read-only: making another key the account's would unlink the current one, and
kgoose never links a key again once it is unlinked.

Expand Down Expand Up @@ -778,10 +780,54 @@ principals; plugin JavaScript can invoke `identity_export` directly. Not registe
a plugin key service is an API ownership choice, not a sandbox. The main-webview
command permission is not proof of a human gesture.

The Identity page checks key management when it opens. Builds with a backup
service show a front pill once the key's state is known: **Backed up**, with a
destination tooltip, **Check backup** for a failed attempt (including a confirmed
backup's latest attempt), or a spinner only while an attempt runs.
**Check backup** flips to the explanation and retry.
The pill sits inside the artwork, so loading cannot move the card or its controls.
Builds without a service reserve no pill space. The back uses the same concise
storage and recovery explanation for self-managed and organization-managed keys.
The local-storage explanation appears immediately and consistently calls local
secure storage **this device**. When a backup is confirmed and the current account
lookup has not failed, the same paragraph names the configured account destination,
matching the front tooltip. A failed account lookup hides that sentence until the
lookup recovers; the device-storage explanation stays visible. Native confirmation
metadata is retained, so a failed later upload alone does not erase a known backup.
The private-key menu’s save-a-copy guidance follows it.
Backup attention and retry feedback sit in the bottom action stack, with the
full **Retry backup** CTA directly above **Remove from device**. The CTA stays
disabled with a loading spinner while an attempt runs. Failure hints use centered
caption text and omit redundant retry instructions; the inline backup retry row
is removed.
The **Backed up** pill appears only on the front.
Unknown backup state shows no backup claim; a failed check offers a quiet
**Backup status unknown** caption and **Retry backup** in that same bottom action
space.
One recovery control owns the status read and upload retry. With unknown
management, it rereads native state, then automatically starts a native backup
attempt when the returned management matches the current key. A read failure or
key mismatch leaves status unknown and starts no upload; an already-running
attempt is not queued again. The common recovery component owns both steps so
the CTA stays busy across the transition and card flips. Closing Settings or changing
keys before the read completes prevents starting the upload. A refused start
shows recovery feedback; native consent and sign-in checks remain authoritative.
Retrying returns focus to **Back** while the check
runs. Long back content scrolls inside the front face’s existing bounds instead of
stretching both faces. A failed later attempt preserves the confirmed account
backup explanation while the front shows **Check backup**. Only a running attempt
shows a spinner. There is no red retry action on the front. The key
menu and removal confirmation dismiss independently of Settings.
At 390px width with 200% text, the full bottom CTA labels (**Retry backup**
and **Remove from device**) can overflow the card. This shares the accepted
layout limit at that size; body copy, vertical scrolling and keyboard access
remain checked.

## Sign out of Buzz

Settings → Buzz → Identity → **Sign out of Buzz** removes the private key from this
device only; the npub and its history stay on relays. The dialog presents two
Settings → Buzz → Identity → **Remove from device** removes Buzz’s saved private
key from this device’s secure storage and signs out. Account backups, exported
copies, and the npub and its history on relays stay. The dialog presents two
layers: the key always goes, and settings, agents and other Buzz data stay unless
the user erases them. It embeds the private-key controls above. Confirm stays
disabled until the user reveals or copies the key and ticks "I have my key".
Expand Down Expand Up @@ -999,21 +1045,23 @@ Membership in any community this build's Builderlab hosts, by the welcome
screen's `builderlab-hosted.ts` list matched on the saved relay host alone (no
relay is read for its `self`), saves automatic backup with no prompt, unless
a choice was saved since it was read: the save checks under the choice lock.
Otherwise **Sync your identity with Builderlab?** asks: **Sync with
Builderlab** and **I will manage my own key** save the answer, which a hosted
Otherwise **Back up your key?** asks: **Back up key** and **I will manage my own
key** save the answer, which a hosted
membership arriving while it is saved does not override; closing it saves
nothing, and it asks again on the next launch or Builderlab sign-in. A build
whose Builderlab hosts no listed community, including an FI build, always asks.
Settings → **Identity sync** explains what syncing is for and shows the
uploader's status: **Syncing…** while a pass runs, **Synced with Builderlab**
only once an upload is confirmed, and loading, sign-in and failure feedback
below the description. While it waits for consent, **Sync with Builderlab**
opens the same prompt, which closes if the wait settles without its answer.
Settings → Identity's card shows the uploader's status and keeps recovery on
its back. While it waits for consent, **Back up this key to Builderlab** appears
above a prominent **Back up key** action in the bottom stack. It opens the same
consent prompt before any choice is saved; the prompt closes if the wait settles
without its answer. Cancel restores the action's focus; saving consent or an
externally settled wait returns focus to **Back**. **Retry backup** and the
consent action share that slot, so retry never bypasses consent.
When the key isn’t linked to the account, or the account holds a different
key, both of which native reports only after consent, the sentence’s
**Builderlab** opens Settings → Plugins → Builderlab, whose **Connect Buzz
identity** or **Switch to this device’s identity** is the next step. The
sign-in wait stays plain text: Organization sign-in is on Identity itself.
key, the notice’s **Builderlab** opens Settings → Plugins → Builderlab, whose
**Connect Buzz identity** or **Switch to this device’s identity** is the next
step. Both states arise only after consent. The link is available only while
Builderlab’s Settings card is registered; the sign-in wait stays plain text.
Settings does not turn automatic backup off. A successful restore, and a
welcome-back import of a key the account already backs up, save automatic
backup the same way, only when the key has no saved choice.
Expand Down Expand Up @@ -1225,21 +1273,24 @@ sends them to the Apps control plane paired with the server's identity origin
directory, which native reads and uploads itself, with the same checks as a
plugin upload. A 401 is handled as for API calls.

Settings → Identity → Organization sign-in is the same whichever community is
open. It lists each server you are signed in to, with its name and origin, the
account and expiry, **Used by:** the joined communities its hosts cover, and a
**Sign out** that ends that server's session only. A sign-out native could not
finish (for example, secure storage refused) stays below the list, naming the
Settings → Identity → Community sign-ins is the same whichever community is
open. It shows cards for each configured server, its name and origin, account,
and saved communities that require its sign-in. Static community artwork exposes
names and tooltips. **Sign out** confirms before ending that server’s session only.
Within seven days of expiry, **Renew sign-in** and the expiry date appear, with
**Sign out** in the renewal caret menu. The Builderlab connection row observes
the existing plugin session and opens its settings; it starts no account read.
A sign-out native could not finish (for example, secure storage refused) stays below the list, naming the
server, with **Try again**; so does an ended session whose saved record native
could not remove. A saved session native could not check, for example offline,
is kept and offers no **Try again**. Communities no server covers are not listed. While the build's Builderlab isn't signed in, its row to sign in
from comes first, named by its server beside other servers' rows, with its
expiry or recovery message.
is kept and offers no **Try again**. Communities no server covers are not listed.
While the build’s Builderlab isn’t signed in, its row to sign in from stays listed alongside the other configured servers, with its recovery
message when applicable.

When a community refuses a signed-in account (`authorization-denied` or
`binding-mismatch`), its prompt names the community's server and account, and
the other joined communities that server covers, and offers **Switch account**:
it signs out of that server only, signs in to it again, and retries. Other
the other joined communities that require its sign-in, and offers **Switch
account**: it signs out of that server only, signs in to it again, and retries. Other
servers' sessions are not touched. While it runs the prompt says so, with
**Cancel sign-in** during the browser step. A canceled sign-in leaves that
server signed out: the prompt says the sign-in was canceled and offers
Expand Down
Loading
Loading