🤖 The home server

A tiny, anonymous, content-blind, passkey-gated blob store — the optional backup half of the onboarding design (docs/onboarding-and-home-server.md in the design repo). It lets a member keep an encrypted list of their chat servers (and, later, credentials) restorable on a fresh device with one passkey ceremony.

It is not a Matrix-style 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.

The additive-only invariant (non-negotiable)

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 on this page. A web-only user who declines never appears in any home-server log. Instances are not involved at all; the only relationship is client ↔ home.

Who sees what

| Party | Sees | |---|---| | An instance | your per-instance public key + ciphertext (unchanged — instances don't know this server exists) | | The home server (if enrolled) | one WebAuthn credential public key per passkey, one opaque padded blob, device link tokens (hashed), IPs/timing | | A stolen device link token | ciphertext reads + overwrites (the server keeps the last 5 versions; 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 |

What it stores (per user)

• users — a random id. No email, no username, no display name; the credential is the identity.
• credentials — WebAuthn credential public keys (+ sign count/flags).
• one blob — opaque client-encrypted bytes. The plaintext is padded to a fixed 16 KiB before encryption so length leaks nothing; the last 5 versions are retained as overwrite protection.
• device link tokens — bearer tokens minted after a verified ceremony, stored hashed (like the messenger's device tokens).
• ceremony proofs — 5-minute hashed proofs minted by a verified ceremony; the only credential destructive ops accept.

Crypto (all client-side, web/static/crypto.js)

Passkey PRF output → HKDF → per-credential KEK. A random long-lived DEK encrypts the blob (AES-GCM); the DEK is wrapped once per enrolled passkey's KEK (envelope encryption — a second passkey is recovery redundancy). The PRF output never leaves the client; the serializer strips PRF results before anything is sent. No PRF support = no enrolment on that device; add-device links remain the universal fallback.

API

POST /api/register/begin      WebAuthn attestation options (rate-limited).
POST /api/register/finish     verify; create user + credential; mint link token
                              + ceremony proof. With a FRESH ceremony proof on
                              begin, adds a passkey to that account instead
                              (a link token is refused — see below).
POST /api/login/begin         discoverable assertion options (rate-limited).
POST /api/login/finish        verify; mint link token + ceremony proof.
GET  /api/blob                bearer link token; If-None-Match: "<version>" → 304.
PUT  /api/blob                bearer link token; If-Match required, 409 on race;
                              hard size cap.
GET  /api/devices             bearer link token; ids + timestamps only.
DELETE /api/devices/<id>      X-Ceremony-Proof (fresh ceremony) — NOT a link token.
DELETE /api/credentials/<id>  X-Ceremony-Proof; refuses to remove the last
                              passkey (that would orphan the blob).
DELETE /api/blob              X-Ceremony-Proof (fresh ceremony).

The asymmetry is deliberate: a link token authorises exactly blob read/write and the devices listing — nothing else. Anything that changes who can get in (adding a passkey, removing one, revoking devices, deleting the blob) requires a live passkey ceremony — a stolen token can't lock you out, and it can't enrol an attacker's passkey to escalate itself into ceremony power either.

Build, run, deploy

go build ./home                    # single static binary, UI embedded
LCHAT_HOME_ORIGIN=http://localhost:1748 ./home &   # env: ADDR, LCHAT_HOME_DB
go test ./home

LCHAT_HOME_ORIGIN is the public origin (the WebAuthn RP identity) — pick the hostname once; changing it orphans existing passkeys. In production it runs as the lchat-home systemd service on the router box (unix socket, fronted by the router): build the home binary, copy it up, systemctl restart lchat-home — data-safe; the DB at /data/home.db is never touched by a redeploy.

Optional: serving the planet-scale guide at /infrastructure/

LCHAT_HOME_INFRASTRUCTURE_DIR=<path> serves the operator guide (docs/planet-scale-guide/ in this repo) at /infrastructure/, read straight from that directory on disk — unset (the default) means the route 404s. The guide's source stays in the repo; only a deploy step copies its built files onto the box:

scp -r docs/planet-scale-guide/* root@<box>:/data/infrastructure/
# then set LCHAT_HOME_INFRASTRUCTURE_DIR=/data/infrastructure in home's
# environment and restart

Re-run the scp (it overwrites in place) whenever the guide changes; no restart is needed for guide-only content updates since it's read from disk on every request, not cached in the process. A restart is only needed the first time LCHAT_HOME_INFRASTRUCTURE_DIR is set.