# 🤖 Onboarding & the home server — design

Status: **shipping, not proposed** — for the machinery. The home server,
enrolment, and the signed-out-root restore flow are built (see the inline
*Implemented* markers); silent multi-device sync (phase 3c) is the main piece
still landing. This doc is the single place for how that machinery works.
Builds on `invite-redesign.md` (invite secret `T` in the URL fragment,
server-blind claim).

> **The identity invariants were revised 2026-07-16.** "Passkey-only sign-in,
> no email, no social login, ever" was field-falsified by real lockouts within
> a week of the native apps leaning on it. The successor design — anchored
> ownership, anonymous membership, and the identity-vs-keys split — is
> **`accounts-and-recovery.md`**, which supersedes the Invariants section
> below. The invariants that survive unchanged are restated there.

## Goals

It should be nearly seamless to:

a) **join a chat** from an invite link,
b) **get the app**, and
c) **get the chat into the app** —

and it should be hard to *lose* access: the server list (and optionally the
credentials behind it) should be restorable on a fresh device and kept in sync
across devices. All without usernames, passwords, or weakening the one rule:
**a compromised server yields nothing**.

## Invariants (revised — see `accounts-and-recovery.md`)

> **Superseded 2026-07-16.** This section originally declared "No social or
> third-party login, ever" and "no email" as permanent decisions. The
> replacement invariants — membership stays anonymous, ownership is anchored,
> providers attest but are never the identity, the server never holds a
> readable key — live in **`accounts-and-recovery.md`** together with the
> rationale (including the updated App Store guideline 4.8 analysis). The
> invariants below survive unchanged and remain non-negotiable:

- **Membership enters via invites.** Identity stays per-instance keypairs;
  no federation. (Joining a space still requires no identifier, ever.)
- **The home server is strictly additive.** A client with no enrolment record
  makes **no requests to any home server, ever** — no passive pings, no
  "check for a backup" lookups. Enrolment is created only by an explicit user
  action. A web-only user who declines never appears in any home-server log.
- **This is not a Matrix homeserver.** It holds no messages, no roster, no
  identity any instance recognises. It disappearing inconveniences you exactly
  once (you lose the backup, not the chats).
- Invite fragments are never sent to any server, including the home server.

## Who sees what (the whole model in one table)

| Party | Sees |
|---|---|
| An instance | your per-instance public key + ciphertext (unchanged from today) |
| The home server (if enrolled) | one WebAuthn credential public key per passkey, one opaque **padded** blob, device link tokens, IPs/timing |
| A stolen device link token | ciphertext reads + overwrites (server keeps version history; destructive ops need a fresh ceremony) |
| A compromised enrolled device | the blob — but it already holds live sessions to every instance in it, so nothing new |
| Nobody | the relationship between your identities on different instances, except your own devices |

---

## 1. The welcome page (deferred claim)

Today `/join/<label>#<T>` claims immediately on load. The one-time secret gets
burned by whichever context loads it first — the source of the
"This link doesn't work" bug class (hidden Mac webviews, browser-then-app).

New behaviour: `/join/...` renders a **welcome card** (group name + icon via the
public `/api/group`) and does nothing else. The fragment sits untouched in the
URL bar. Claim happens only on an explicit choice.

**Golden path** (sign-in is explicit, never implicit):

1. Click the invite link → welcome page: *"You've been invited to Campbell
   Family."* Primary nudges: **Get the app** and **Sign in at
   home.elevenmessenger.com**. Secondary: **Continue on the web** — with a
   caveat shown ("your access will live only in this browser").
2. After home sign-in (popup on desktop; full redirect on mobile, with the
   fragment parked in the instance origin's `sessionStorage` across the trip),
   return to a **second variant** of the welcome page:
   - **Open in Eleven** (app), or
   - **Continue on the web** — no caveat this time, because the browser now
     holds the DEK + link token, so the join that follows lands in the blob in
     the same breath. The reassurance is true by construction.
3. Joiners who skipped sign-in get a post-join nudge instead ("Don't lose
   access to this chat — save a passkey"), Apple-style, after they've arrived.

🤖 *Shipped 2026-07-31 (signup-first join):* the sign-in-first ordering above
now exists as the join page's **lead card** — fresh joiners see "Sign in with
Eleven" before the app/web choice, with "Continue without signing in" as small
print (a quiet link, not a competing button — one path, plus an escape hatch;
Paul, 2026-08-06). The round trip differs from the sketch in two details:
it's always a same-tab navigation (never a popup — Safari blocks WebAuthn in
cross-origin popups), and the fragment parks in the instance origin's
`localStorage` (nonce-stamped, expiring), not `sessionStorage`, so a mobile
OAuth app-switch can't orphan it. On return the welcome card renders
caveat-free, and after the claim the session auto-saves to the account via a
hands-free `/enroll` bounce (`payload.auto` — the live-session fast path
only). Decision logic: `web/static/prejoin.js`; the home-side return guard:
`home/web/static/joinreturn.js`. Design:
`docs/superpowers/specs/2026-07-31-signup-first-join-design.md`.

**Signed-out server root** (e.g. visiting `chat.paulca.com` with no session) is
currently a dead end. It becomes the same card: **Restore with passkey** /
**Open in the app** / *"I have an invite link"*. During restore the instance
passes its origin and an ephemeral public key; after the passkey unlocks the
blob, the home server returns **only the entry matching that origin** (never the
whole list), ECIES-wrapped to the ephemeral key so the credentials are never
plaintext in the return URL. A one-time nonce ties the return to a restore the
instance actually started. *(Implemented: phase 3b.)*

**App Store round trip:** invites stay valid until claimed, so "install, come
back, tap the link again" works today; the QR flow (shipped on iOS) covers
cross-device. Deferred deep-linking via pasteboard is a possible later polish,
not phase-one (it triggers a paste-permission prompt).

## 2. The home server

A tiny, deployable-like-an-instance service (single Go binary, SQLite, one
table that matters). Default `home.elevenmessenger.com`; the welcome page's
cog lets a joiner point at a different one. Every instance gets it for free
because instances aren't involved at all — the only relationship is
**client ↔ home**.

### What it stores

Per user: WebAuthn credential public key(s), one **opaque padded blob**
(fixed size, e.g. 16 KB — length leaks nothing), a version counter, and
device link tokens. No email, no username, no display name. The credential ID
*is* the identity.

**Blob schema (the decrypted plaintext — the contract every client reads).**
`{ v: 1, servers: [{ url, name?, starred? }] }`. The `servers` **array order is
the display order**; each entry may carry `starred: true`. Rendering (web and
native) partitions it into a **Starred** list and the rest, *each keeping its
array-order* — so the two lists sort independently: reordering one never
disturbs the other. Native apps map this straight through — starred spaces
populate the rail, the rest live behind a "more" affordance. The pure helpers
(`web/static/serverlist.js`, unit-tested) are the canonical partition/star/move
logic; keep the native implementations behaviourally identical. Merges on a
version race are last-writer-wins per `url` (the list is tiny), which can drop a
concurrent reorder — acceptable until per-entry ordering earns a CRDT.

### Crypto

- Passkey at RP `home.elevenmessenger.com`, created with the **PRF extension**.
  The PRF output (only ever visible client-side) derives a KEK.
- **Envelope encryption:** a random long-lived DEK encrypts the blob (AES-GCM);
  the DEK is wrapped once per enrolled passkey's KEK. Adding a second passkey
  (e.g. 1Password alongside iCloud) = wrapping the DEK again = recovery
  redundancy. The DEK is stable across blob updates — that's what makes silent
  sync possible.
- **Blob contents — the one open decision.** Recommendation: the server list
  **plus per-instance credentials** (session token + private key per
  instance), so restore = fully signed in everywhere with one Face ID.
  The list-only alternative shrinks the blast radius of a compromised passkey
  fabric but reduces "restore" to "here's a map, now do an add-device dance
  per server" — and makes the signed-out-root flow above nearly useless.
  Either way the server sees ciphertext; this decision is about what a stolen
  passkey unlocks, and enrolment is opt-in for exactly that reason.
- No PRF support (old browser/manager)? Then no enrolment on that device —
  add-device links remain the universal fallback. Losing **all** passkeys means
  the blob is cryptographically gone; that's the design working. Recovery
  paths are your other enrolled devices, add-device links, or fresh invites.
  (The full recovery ladder — including the non-passkey key anchors that
  soften this — is `accounts-and-recovery.md § What recovery restores`.)

### API sketch

```
POST /api/register        WebAuthn create (attestation) → credential stored
POST /api/challenge       issue challenge for an assertion (with PRF eval)
POST /api/devices         after a verified ceremony → device link token
GET  /api/blob            bearer: link token (If-None-Match: version)
PUT  /api/blob            bearer: link token (If-Match: version → 409 on race;
                          clients merge the small list client-side and retry)
DELETE /api/devices/<id>  requires a FRESH ceremony, not a token
DELETE /api/blob          requires a fresh ceremony
```

The asymmetry is deliberate: a link token can read and update, but anything
that *reduces* access (revoking devices, removing passkeys, deleting the blob)
requires a live passkey ceremony — a stolen token can't lock you out.

### Devices & silent sync

After one enrolment ceremony a device caches the **DEK** (Keychain / secure
storage) and holds a **link token**. From then on it syncs in the background
with no Face ID: poll on launch/foreground (the Mac app also periodically or
via a watch connection), see the version bump, decrypt with the cached DEK,
adopt changes. On the **web** the default is session-only DEK caching — a
"Trust this browser" checkbox opts into persistence, so sign-in on a shared
computer doesn't durably enrol it.

**Enrolment / auto-add flow** (the payoff): from a chat (the fragility banner's
"Back up with a passkey", or later the welcome page) the instance opens the home
server's `/enroll` popup with the new entry `{instance URL, name, credentials}`
in the **popup's URL fragment** — client-to-client, never through a server in
the clear (same model as invite secrets). The handoff is deliberately one-way:
the home server ships **no inbound `postMessage` receiver** (that was an
injection surface — any site can `window.open` the popup), so there is nothing
cross-origin to spoof. The popup shows exactly what's being added (name + host)
as the confirmation gate, runs one Face ID (create a backup passkey, or sign in
to an existing one), merges the entry into the blob, and posts **only a boolean
result** back to the opener (never blob contents), which the opener accepts only
when `event.origin === HOME_ORIGIN`. Later, your Mac and iPhone poll, decrypt,
and the server **appears in the rail on its own** — the Mac app seeds the
instance webview's session, iOS adopts the credentials natively. *(Implemented
phase 3a: enrolment + fragility banner. Silent multi-device sync is phase 3c.)*

Revocation: lost phone → any enrolled device (fresh ceremony) revokes its link
token; per-instance measures (admin roster) unchanged.

### Abuse controls

Open blob store on the internet: hard size cap, per-credential quota (one
blob), rate limits on register/challenge, optionally proof-of-work on register.

## 3. The fragility banner

Members without a backup should *know* their access is fragile. The
**client** decides — the instance is never told (it couldn't verify a
self-report anyway, it leaks cross-instance metadata, and it goes stale):
chat.js shows the banner when a session exists and there's **no local
enrolment record**. "If this browser session is lost, your access to this chat
is lost."

Dismissal is a **double dismiss**: first dismiss = "remind me later"
(returns after ~7 days); second requires a confirm-state click — the control
changes to *"I understand — I can lose access to this chat"* and you click
that. Persisted locally (it's a per-device warning). Enrolling clears it
everywhere, genuinely.

**UI rule (product-wide): never show a toast that floats over the UI.**
Nudges, warnings, and status belong *inline*, occupying layout space (like
this banner, above the thread list) — not overlaying content someone may be
reading or about to tap. The floating `#toast` pill is retired as a pattern:
existing uses (e.g. "Copied") move to inline/adjacent feedback as they're
touched. This rule is also recorded in CLAUDE.md conventions.

**This replaces the existing backup toast.** chat.js currently shows a
one-shot toast to single-device members (`maybeNudgeBackup()`, keyed on
`lchat_backup_nudged`) pointing at ⋮ → "Add a device" (renamed from "Add a device / back up" in the 2026-07-22 sign-in language sweep). Once the
onboarding flow owns back-up messaging, that toast is **removed** — one voice,
not two competing nudges. The banner is strictly better: it's driven by real
state (enrolment) rather than a fire-once flag, it can come back, and its
call-to-action is the actual fix (save a passkey) rather than a menu pointer.
The ⋮ add-device link stays where it is as the manual/no-passkey path.

## 4. Opening in the app

Two mechanisms, deliberately ranked:

- **Universal links (primary).** Every instance is the same binary, so each
  serves `/.well-known/apple-app-site-association`. Invite links on associated
  domains open straight into the app — full URL, fragment included — and fall
  back to the web welcome page when the app's absent. Limitation: the
  associated-domains entitlement is a static list (`*.example.com` + named
  custom domains); arbitrary custom domains can't join it. (WebAuthn Related
  Origin Requests could stretch things later; parked.)
- **Custom scheme `elevenmessenger://` (explicit fallback).** One-line
  registration on iOS *and* the Mac app (`CFBundleURLTypes`); fired by the
  welcome page's "Open in Eleven" button, works from any domain. Deliberately
  non-generic (not `eleven://`) — schemes are a global namespace, so the less
  collision-prone the better. Which is also the caveat that keeps it in second
  place: schemes aren't exclusive — a squatting app could receive the URL and
  its invite secret. Acceptable for a user-initiated tap handing over a
  one-time secret that's about to be claimed; never used for long-lived
  secrets, never the default path.
- QR scanning (shipped on iOS) remains the cross-device path.

The web still can't detect "is the app installed" — by design the welcome page
*is* the fallback, so the button just tries and offers "Get the app" alongside.
Distribution: TestFlight link now (paid team is live), App Store later; Mac via
notarized direct download.

## 5. Invite links shared inside the app

An invite pasted into a chat should open the native add-chat flow, not a
browser. Our renderers control link handling; the missing piece is
*recognising* an invite deterministically (any site can have `/join/`). Give
links a versioned **fragment fingerprint** — `#e1.<T>` instead of `#<T>` — so
clients recognise invites offline and instantly; we mint the links, so this
costs nothing. Old-format links keep working via an `/api/group` probe.
OS-level interception (tap in iMessage) is the universal-links story above.

## 6. Direct invites to a group chat

An invite can carry a **target thread id**; the claim flow ships that thread's
key exactly the way the instance key ships today (the inviter is a member and
can wrap it). The joiner lands in the group, not an empty home screen.
Deliberate semantics: joining a group still means joining the **instance**
(roster is instance-wide, so all members can see the newcomer exists) —
"invite to group" = "invite to instance, pre-added to this group".

---

## Phasing

1. **Welcome page + deferred claim** — kills the burned-invite bug class; adds
   the fragment fingerprint, `eleven://`, and AASA universal links. No crypto
   changes. (Group-direct invites are independent and can ride along.)
2. **Home server MVP** — register/challenge/blob, enrol + restore flows, the
   post-join nudge, the fragility banner (and the old backup toast retires
   with it).
3. **Silent sync + auto-add** — device link tokens, DEK caching, app polling,
   the signed-out-root restore page, welcome-page sign-in variant.
4. **Distribution polish** — TestFlight/App Store buttons, Mac notarized
   download, deferred deep-linking if it earns its keep.

## Open decisions

- **Blob contents:** list-only vs list + credentials (recommendation:
  credentials in, documented blast radius, opt-in enrolment).
- Web DEK cache default (recommendation: session-only + "trust this browser").
- Banner "remind me later" interval (~7 days?).
- Custom-domain universal links via Related Origin Requests: later, if ever.