🤖 Invite redesign — short links, server-blind key delivery

Status: Phase 1 (link + QR). Phase 2 (spoken word-code via PAKE) is parked.

Goal

Short, single-use, revocable invites with multi-device support and admin re-issue — without the server ever storing anything that could recover the group key. Same hard guarantee as today ("compromise the server, get nothing"), but nicer onboarding and manageable invites.

Crypto (load-bearing)

• Invite secret T = 128-bit random → ~22 base64url chars, carried in the URL fragment: …/join/<label>#<T>. The fragment is never sent to the server.
• The client derives two values from T (HKDF-SHA256, domain-separated): - id = HKDF(T, "lchat-invite-id") — the server's lookup handle. - wrapKey = HKDF(T, "lchat-invite-wrap") — an AES-GCM key.
• Minting (admin's browser, which holds the group key via the master link): wrapped = AES-GCM(groupKeyRaw, wrapKey). The browser POSTs only {id, wrapped}.
• The server stores {id, wrapped} and never sees T → it can't unwrap. A stolen DB yields {hash-like id, ciphertext}; recovering the key needs the 128-bit T, which never left the client.

The path segment (<label>) is cosmetic (server-visible, guessable) — all entropy lives in T.

Data model (additive — old invites/tokens keep working)

• users(id, label, created_at) — a person.
• key_invites(id, user_id, wrapped, created_at, expires_at, used_at) — server-blind wrapped key per invite; id is the HKDF handle.
• device_tokens(token_hash, user_id, label, created_at) — ongoing transport credential (hashed, like the admin token), one per device.

Messages remain opaque blobs; author_hash (already present from message editing) keeps working per device. Full "messages attributed to users" UI is out of Phase 1 scope — the model just makes it possible later.

Flows

Mint (admin): browser generates T, derives id/wrapKey, wraps the group key → POST /api/admin/invites {label, id, wrapped, expires}. Server creates the user (if new) + key_invite. Browser shows the link …/join/<label>#<T> + a QR.

Join (new device):

1. Open …/join/<label>#<T> → T from the fragment.
2. GET /api/invite/<id> → wrapped; unwrap with wrapKey → group key (stored locally, same session shape as today: {token, key, name}).
3. POST /api/invite/<id>/claim → server marks it used (single-use) and issues a device token. Ongoing auth (messages/WebSocket/push) uses that token; T is one-time and never sent.

Add another device / re-issue a lost one: mint a fresh invite (new T, new wrapped blob) from any device that holds the key — admin, or your own existing device. QR is the clean desktop→mobile path.

Transport auth (additive)

tokenOK(token) accepts either a current non-revoked invite token (old model) or a valid device token (new model). So existing members are unaffected and new joiners use device tokens.

Migration

Fully additive — no data loss, nothing forced:

• Old #k=<key> links and existing tokens keep working.
• The existing group key is reused (the admin's browser wraps it) — no key regeneration, no re-onboarding.
• Old-style links age out as people move to new invites.

The join page handles both: fragment k=<key> → old flow; raw <T> → new flow.

Phase 2 (parked): spoken word-code

Four-ish words via PAKE/SAS (Magic-Wormhole style): the server relays an ephemeral key exchange it can't read; the words authenticate the live exchange against MITM; the key goes device-to-device. Low entropy is cryptographically safe in that construction. Documented now, built later.