🤖 Accounts, sign-in & recovery — the anchor model

Status: plan of record — phase 1 largely shipped (decided with Paul 2026-07-16; status refreshed 2026-07-22). Live today: the six sign-in doors on home (passkey, email code, Apple, Google, Microsoft, GitHub — the #1112 card), identity anchors + ceremony proofs (stateless.go), the Sign-in options management step, account combine/merge (#1098), sealed anchor sessions, and the native passkey/Apple/email doors. Merged but dark: the synced DEK (#1144, flag off pending the device matrix). Not built yet: the /invite link redesign (the phase-0 locked-card rungs shipped on the Mac 2026-07-22; native add-device mint/QR still open), owner anchoring at creation, approve-from-another-device, the recovery-passkey offer, and the native OIDC doors (server legs done, client work open) — see Phasing below, per-item. (The paper recovery kit that used to sit in this list was cut on 2026-07-25 — Paul: recovery is a passkey, never a passphrase or a printed code; the recovery-passkey section below replaces it.) This document supersedes the Invariants section of onboarding-and-home-server.md — the "no email, no social login, ever" line — after that invariant was field-falsified by real lockouts. Everything else in that doc (the welcome page, the home server machinery, the blob schema, enrolment, the fragility banner) remains accurate and in force; this doc is about what identifies a person and what brings their keys back.

Why we're revising a "permanent" decision

Passkey-only sign-in was declared a Day-1 invariant. Within a week of the native apps leaning on it, two of our first users were locked out:

• The macOS ceremony sheet only reaches iCloud Keychain (plus QR/security keys). A passkey living in a Chrome profile or a third-party manager is invisible to it — the user sees "a passkey window and no way to enter a password."
• 1Password's macOS provider returns a PRF that doesn't match its own browser extension's for the same credential, so even a present passkey can fail to decrypt (the browser-handoff workaround exists because of this).
• The locked-space card offered exactly one rung ("Sign In with Eleven…") and a destructive one ("Remove from This Mac"). One-rung ladders read as "the app is broken", not "the design is working".

The root cause is architectural, not cosmetic: the passkey was doing two different jobs at once, so any failure of the ceremony was total.

The two jobs

Every mechanism in this design does one or both of:

1. Identity — proving you're the same person who enrolled. Lets the home server return your record and gates destructive operations.
2. Keys — holding or deriving the client-side secret (the KEK) that unwraps the vault DEK. The DEK decrypts the blob, which holds live sessions + per-instance private keys. Nothing server-side can ever do this job — that's the one rule.

| Mechanism | Identity | Keys | Notes | |---|---|---|---| | Passkey + PRF | ✓ | ✓ | today's model; elegant, and why its failure is total | | Sign in with Apple | ✓ | — | stable team-scoped sub; can request no email at all | | Email code | ✓ | — | ecosystem-neutral; blind-indexed (below) | | iCloud-synced DEK item | — | ✓ | invisible; Apple-ecosystem only | | Device key + approval | — | ✓ | transfers keys to a new device, given identity | | Recovery passkey (manager / hardware key) | ✓ | ✓ | a second, independent credential; ecosystem-free | | Guardian wrap | — | ✓ | DEK/credentials wrapped to another member's key |

An identity anchor alone can never decrypt anything. That single sentence forbids the tempting shortcut (email-gated server escrow of the DEK) and shapes everything below.

The new invariants

What "no email, no social login, ever" weakens to — each line deliberate:

1. Membership stays anonymous. Joining a space requires no identifier, ever — invites remain the only membership door. No change from today.
2. Ownership is anchored. Every space's recovery chain must terminate at a member whose recovery survives total device loss — normally the owner. Practically: creating a space requires an anchor; joining one never does. The owner's anchor is a pair: an identity anchor (email, Sign in with Apple, or a successor — see the open slot) plus a key anchor (on Apple platforms the synced DEK rides along invisibly; otherwise a recovery passkey in a synced manager or on a hardware key).
3. Providers attest; they are never the identity. A third-party sign-in is at most a verifier of an anchor. Our record is a blind index (a hash) — there is no provider user-id column, no stored email address, and swapping providers never orphans an account.
4. The server never holds a readable key. No escrow of the DEK under any server-side or identity-gated key, ever — a compromised home server plus a passed email gate must still yield nothing. Recovery that "just works with an email" is only achievable by breaking the one rule; we don't.
5. The home server stays strictly additive (unchanged): no enrolment record → no requests to it, ever.
6. Copy stays human (unchanged rule): never "passkey", "PRF", "key", "escrow", or "backup" in UI. People sign in, save their spaces, and add ways back in.

Account classes

| Class | Identity (job 1) | Keys (job 2) | Lost everything | |---|---|---|---| | Owner (anchored) | SiwA / email / successor | synced DEK, or recovery passkey | full restore via anchor pair | | Member, anchored (optional) | same menu | same menu | same ladder as owner | | Member, identifier-less | the key is the identity | passkey(s) or nothing | re-invite floor | | Guardian-managed | none — guardian vouches | wrapped to guardian's key | guardian re-links, instantly |

• Owner. Whoever creates a space attaches the anchor pair at creation (or is nudged until they do — open decision). This lands the identifier exactly where accountability already lives: space creation is the abuse surface (quotas, reaping, billing), membership never was (invite-gated).
• Identifier-less member. Today's model, kept on purpose for privacy-maximalists: bootstrap by invite, optionally strengthen with a passkey (or several), accept the re-invite floor. This class is why the product can still truthfully say "no signup required".
• Guardian-managed — the family case. A child has no email and no passkey. The guardian's signed-in app mints the child's credentials (an add-device link / QR — machinery that exists today) and keeps a copy as a managed entry in the guardian's own vault. The child has no home account at all — no server record, no identifier, nothing collected (the right COPPA/GDPR-K posture by construction). Restore = guardian opens their app → managed member → "link this device" QR. The guardian's own recovery ladder is the redundancy: recover the guardian account and the managed entries come back with the vault. Disclosed honestly: a guardian holding a member's keys can read and act as that member — that is what guardianship is, and the UI says so at creation. (A later variant can give an older child their own home account with the DEK additionally wrapped to the guardian — the graduation path — but the vault-entry form is the v1.)

What recovery restores — the ladder

Top rung first; each rung only matters when everything above it is gone:

1. Any surviving signed-in device — everything, silently (the cached DEK; today's silent sync).
2. A synced key anchor — a passkey that synced, or the iCloud-synced DEK: new device + one identity ceremony = full restore, zero surviving devices needed.
3. Approve from another device — a new device signs in with an identity anchor; an enrolled device gets a push ("Approve this Mac?"); on approval the DEK is re-wrapped to the new device's ephemeral key. This is the add-device flow wearing mainstream clothes (WhatsApp/Signal/Apple trained everyone on it) and is the workhorse for web and non-Apple platforms.
4. A recovery passkey outside the ecosystem — a passkey in a cross-platform manager or on a hardware security key, enrolled as one more way in. This is what survives losing a whole vendor account: it is deliberately not parked where rung 2 lives.
5. Control-only recovery + the re-invite floor — identity anchor alone. The owner recovers control of the space (see below) and can re-admit anyone; a re-invited member gets the same stable thread keys re-wrapped to their new keypair by any live member's client, so full history decrypts. What this rung cannot do: if literally every member's key material is gone (a solo space; a whole family's devices at once), the history is cryptographically sealed. That is the design working — and the reason invariant 2 requires the owner's anchor to be a pair, not an email alone.

Sign in with Apple, precisely

The seamless path for the current (Apple-heavy) user base:

• Request no email scope. The stable team-scoped sub is the account key, stored as HMAC(pepper, sub) — nothing mailable, nothing to leak. Apple learns sign-in timing; we learn nothing new.
• Pair it with the synced DEK. The native DEK cache is deliberately device-local today (kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly, ios/LChatCore/.../Keychain.swift). Storing the DEK also as a synchronizable iCloud Keychain item makes the key travel invisibly — same trust anchor as an iCloud passkey, zero WebAuthn ceremonies, and the third-party-provider bug class (the 1Password PRF mismatch) disappears because credential managers are never in the loop. Built (issue #1089): ios/LChatCore/.../DEKSync.swift — a second item beside the device-local one (service com.lchat.client.dek-synced, added by addition, never delete-then-add), write-gated on the account holding a SiwA anchor. Build-flag gated, OFF by default until the device matrix passes.
• Job 1 gates job 2. A synced DEK alone would auto-unlock on any device signed into the same Apple ID (family iPad on a parent's account). The synced item is used only after a fresh SiwA assertion for the matching hashed sub. Face ID on the SiwA sheet is the one visible moment. In the built slice DEKSync.release is the item's only reader, called solely with the token a fresh SiwA verify just returned; release further requires the resolved account's anchor list to contain the very anchor the item was written under AND the DEK to actually open that account's blob.
• The honest trade, written down: the "zero surviving devices" recovery trust moves into Apple's ecosystem (Apple ID + iCloud Keychain escrow) rather than being eliminated. That is exactly what the seamless experience buys, and the identifier-less class is the opt-out.
• Web and non-Apple: SiwA's web flow exists but presumes an Apple ID. The web keeps passkey-PRF as its local mechanism and gains rung 3 (approve-from-phone). The email/successor anchor is the ecosystem-neutral spine when it lands.

Handoff: onboarding that travels

The goal (Paul, 2026-07-16): with identity at the front of onboarding, a person can start joining on the web and finish in the app — or the reverse — without losing any fidelity. Identity-first is what makes this nearly free:

• Today's order strands progress. Claim-first-save-later means the claimed credentials, chosen name, and onboarding position live in one browser until the person explicitly enrols — the "Open in Eleven" jump has to smuggle state across (the fragment parked in sessionStorage, the enrolment popup dance).
• Identity-first inverts it. Sign in is the first step (one Face ID via SiwA on Apple devices), so every artifact of onboarding lands in the vault as it is created: the claim writes the credential entry in the same breath (the old doc's "golden path", now the default because sign-in got cheap). The vault is the handoff bus.
• Fidelity is then free, not built. Once keys + session cross via the vault, the rest follows automatically: the onboarding conversation is messages in a thread and mini-app state snapshots, both of which sync to any device holding the keys. Jumping devices resumes the scripted onboarding at the exact message — no state machine to serialize, no "continue where you left off" feature to build. The jump itself carries nothing sensitive: "Open in Eleven" / universal link → app signs in with the same identity (same Apple ID: zero ceremony) → vault pull → the space and the conversation are already there.
• Reverse direction (native → web) is rung 3 of the ladder: the web signs in with the identity anchor and an enrolled device approves it — or a QR from the app, exactly the add-device mechanics.
• Identifier-less joiners keep today's mechanics (fragment rides the universal link; post-join nudge) — handoff fidelity is one of the things an anchor buys, stated as such in the nudge copy.

Invite links: pretty, and how short they can get

Today's link is …/join/join#e1.<T>~<encoded name>~<brandingKey> — and each ugly part exists for a different reason, so they improve on different schedules:

• /join/join — pure accident. The path label slot is cosmetic (invite-redesign.md) and every minter hardcodes it to "join". Free to fix: a single /invite path, doubling as the format version (old /join/join#e1. links parse forever).
• ~<name> — in the fragment on purpose. Member names are E2EE; a name in the path would hand it to the server (access logs included). So …/invite/Paul/<secret> as a default breaks the rule. The name can lead the fragment instead — …/invite#Paul/<secret> — which reads like a path (the # is the only tell) and stays server-blind. / is the right separator, not .: it's a legal, unescaped fragment character that browsers/linkifiers/QRs carry verbatim, and encodeURIComponent escapes / inside names (but leaves . alone), so the slots are collision-free by construction — a raw / can only be our delimiter. (Name-in-path could be offered as an explicit per-link "include my name in the address" opt-in — the space name of an unsealed instance is already public branding, so that variant leaks nothing — but the default stays blind.)
• ~<brandingKey> — the price of sealed instances. On a sealed instance nothing is public, so the link must carry the key that unlocks the welcome card. Unsealed instances don't need it. Unavoidable where it applies.
• <T> (22 chars) — load-bearing, for now. T is not a ticket; it offline-wraps the group key (wrapped = AES-GCM(groupKey, HKDF(T)) sits in the server's DB). A shorter T is brute-forceable offline by anyone who steals the DB — a 10-char secret falls to a GPU farm in days — which would break "compromise the server, get nothing". 128 bits (22 chars, re-encoded base58 so it at least looks less like line noise) is the floor while invites carry the key offline.
• Redirects can't shorten the secret. Browsers do carry a fragment through a redirect (that's how a short-domain bouncer could work), but a server can only put in a Location what it knows — and it must never know T. The secret travels in the link the person shares, full stop.

So there are two roads:

1. Cosmetic redesign (no crypto change): https://xyz.11ch.at/invite#Paul/2vXk9QmR4pTnWb8zJcHe6f — one path word, name up front, base58 secret, branding key as a third slot only where sealed (#Paul/<T>/<brandingKey>). Roughly half today's length, and honest about which half remains. Grammar notes: the name slot is always present (falling back to the space name) so a new link is never confusable with a legacy raw-T fragment; version detection is fragment-contains-/ → this format, e1. prefix → current, else legacy.
2. Genuinely short links = the parked PAKE phase (invite-redesign.md Phase 2). A low-entropy secret is only safe in a live exchange (Magic-Wormhole style): the server relays an exchange it can't read, the short code authenticates it against MITM, and the key travels device-to-device — no offline-crackable blob, nothing a compromised server can claim for itself. The historical blocker was needing a member online during the join; the sidecar bot dissolves it — it's a member, it holds keys, it's always on, so bot-attended spaces get instant short joins (and unattended ones degrade to "waiting for Paul to let you in", which is respectable UX in its own right). This is also where invite links become words — …/invite#Paul/coral-piano-42 — which is the least scary a secret can look.

Email (and the successor slot)

Email is one implementation of the terminal identity anchor — the slot is deliberately abstract because a stronger alternative is being designed (Paul, 2026-07-16; unspecified here). Whatever fills the slot must provide: a user-memorable claim ("this account is mine"), a reachable out-of-band channel to complete a challenge, and a blind-indexable identifier.

If plain email fills it:

• Blind index: store HMAC(pepper, normalize(email)) only. At recovery the user types their address; we hash, match, and send a code to what they typed. No plaintext address is ever stored. Normalization is lowercase only — plus-addressing and provider dot-games are respected, not stripped.
• Honest limits, for the copy and the threat model: email hashes are dictionary-reversible for anyone holding the pepper (tiny input space); the running server and the mail provider both see the plaintext address transiently at send time. The claim softens from "we can't spam what we don't have" to "we only see your address the moment you use it, and never keep it." Defensible; say it exactly like that.
• Fully native-able: a 6-digit code works in a plain text field — no WebAuthn sheet, no browser bounce, no provider roulette. The exact complaint that started this ("no way to enter a password") dissolves.
• Costs: outbound mail infrastructure (SES/Postmark, SPF/DKIM, bounces); the provider becomes a party who sees addresses and timing; per-address rate limits and disposable-domain policy become the abuse levers.

The recovery passkey

Decision (Paul, 2026-07-25): recovery is a passkey, never a passphrase or a printed code. The earlier paper-kit design (a client-generated PDF wrapping the DEK under a printed code, riding the vault's passphrase-wrap primitive #995–#997) is dead — that primitive was removed from the product the same day. One kind of key everywhere; nothing to type, transcribe, or find in a drawer.

• Mechanically it's just another enrolment. Home already wraps the DEK per enrolled credential, so "add a recovery passkey" is the existing add-a-passkey ceremony pointed at a different home for the credential: a cross-platform password manager (1Password, Bitwarden, Google Password Manager) or a hardware security key. No new crypto, no new server surface.
• What paper used to buy — surviving a lost vendor account — a hardware key or cross-platform manager buys instead. The offer's copy steers there: a second passkey parked in the same iCloud account as rung 2 adds nearly nothing; one on a YubiKey in a drawer, or in a manager that syncs everywhere, is the real ecosystem escape hatch.
• Losing it is survivable and revocable. A found hardware key is inert without its PIN, and the credential (plus its DEK wrap) can be removed from the account like any other — unlike a printed code, which could never be un-printed.
• Framing: never a sign-up speed bump — offered from settings and at space creation ("add another way back in"), in the same no-jargon voice as the rest (invariant 6: the word "passkey" stays out of the UI).
• Managed members need no kit of their own: their credentials live as entries in the guardian's vault (above), and the guardian's ladder is the redundancy.

Control-plane recovery (why the owner can always re-admit)

The admin token is authorisation, not decryption — its hash lives in the instance DB, and the cloud provisioner already knows which home account created which space. So "recover control" is a service-layer capability re-issue gated on the owner's identity anchor: verify the anchor, re-issue the admin link, and the owner is back to roster management — able to re-invite themselves and everyone else (rung 5). Self-hosters have the same power through /data on their own box. No key material is involved at any step, which is what makes this rung safe to gate on identity alone.

App Store guideline 4.8

• An own-account system (email code, passkey) does not trigger 4.8 at all — same exemption we rely on today.
• Sign in with Apple, offered alone, satisfies 4.8 by construction — it is the privacy-respecting option the rule demands — and future-proofs the day a second provider (Google-as-attester) is ever added, because the compliant option is already present.
• The order therefore stays: SiwA and/or email first; other providers only ever as additional attesters, never the primary.

Who sees what — the deltas

| Party | Sees (new, per class) | |---|---| | Apple | that a SiwA user signs in, and when | | Mail provider | addresses + timing, at send time only (email class) | | Home server | blind indexes; one extra wrapped copy of the DEK per anchor | | A guardian | everything their managed member can see (disclosed at creation) | | A found hardware key | nothing without its PIN — and the credential is revocable from the account | | A compromised home server | still nothing readable (invariant 4) |

Phasing

Status per item as of 2026-07-22:

1. Sweep (no model change): the locked-space card gains its missing rungs — "Link from your iPhone" (add-device QR) and "Ask for a new invite" — and failure copy that never dead-ends at a ceremony sheet. The cosmetic invite-link redesign (/invite#Name/<T>) also rides here: no crypto change, old links parse forever. — partially built (2026-07-22): the Mac locked pane now carries both rungs (each opens the Add-from-link sheet with contextual guidance — the consume side of add-device links already worked) plus signed-in-but-still-locked feedback. Still open: a native mint/QR for add-device links (minting is web-only today), and no /invite route exists.
2. SiwA + synced DEK on iOS/Mac; web gains approve-from-phone. Identity-first onboarding lands with it — the vault becomes the handoff bus and web↔native jumps stop losing fidelity. — partially shipped: SiwA is live on web + both natives; the synced DEK is merged behind an off flag (#1144, device matrix owed); approve-from-phone and the identity-first ordering are not built. The web doors overshot the plan — Google/Microsoft/GitHub ship too; natively their server legs (elevenmessenger://home-oidc) are done and the client halves are open.
3. Guardian-managed members + the recovery-passkey offer (the family story; settings + creation). — not built.
4. Owner anchoring at creation — email or the successor anchor; the provisioner starts requiring/nudging it. — not built (creation from home is effectively anchored via the home session; a bare setup link still claims anonymously).
5. Providers-as-attesters, if ever. Short/word-code invites (the PAKE phase, bot-attended) slot in whenever they earn their build. — not built.

Open decisions

• The successor identity anchor (Paul's design) — this doc holds the slot; email is the fallback filler.
• Anchor required at space creation vs nudged until attached.
• Synced DEK: default-on for SiwA accounts vs opt-in ("Keep me signed in on my other devices").
• What identity-only recovery may show before a key anchor confirms: recommendation nothing — the space list is metadata worth the same protection, so rungs 3–5 reveal it only after approval/passkey/re-invite.
• Invite links: whether "include my name in the address" (name-in-path) is offered as an explicit opt-in, or names stay fragment-only always.
• When the PAKE short-invite phase earns its build — and whether the sidecar bot is a sufficient counterparty for unattended spaces or the flow always needs a human approval option too.