The last mile: a loopback tab that sees its own fleet

[karngyan]

Install flue on Mac A, deploy the relay, pair a phone, install flue on Mac B, run the join line — and B's sessions are now in A's own tab, A's in B's, and clicking one attaches in place. This is the last mile: the browser. The relay-origin path healed in #44 and the daemon side landed in #45.

What a loopback tab could not do, and why

A tab on http://127.0.0.1:7717 was three records and one read short of being on a fleet at all:

• No fleet key. It never ran a ceremony, because it never needed one — the session cookie is its credential.
• No device certificate. Which is the only thing a machine it has never met will admit it on (spec/fleet-trust.md, rule 2).
• No machine records. Only the relay branch of the pairing page writes those.
• And the directory read was blocked. GET /directory is cross-origin from loopback and the Worker answers without Access-Control-Allow-Origin, so the browser discarded it before readDirectory saw a byte — and readDirectory reports every fault as "no machines", so the tab quietly showed a fleet of one on a fully joined laptop.

None of it was fixable by pairing: the ceremony's link lands on the relay's origin, a different storage partition, so it would have admitted a browser that is not this one.

Enrolment on boot

The fleet posts this browser's device public key at POST /api/fleet/enrol on the machine that served the page, and keeps what comes back: the fleet public key, pinned, and the certificate this machine signs for that key. Once per fleet epoch, gated strictly to the loopback origin — the flag comes from src/main.tsx, where "how was this page served" is already answered, through the router's context to the provider, so nothing below sniffs location and no scripted client in a test posts a device key at whatever answers.

The enrolment and the daemon's welcome race, and both orders end in one rebuild: with no relay origin yet there is nothing to expand into and the welcome finds the records already in the store; with the welcome first the expansion ran blind and the enrolment's own rebuild repairs it, through the same once-per-epoch gate the welcome re-supply path uses.

The exemption comment, and why this is not a regression

crypto/keys.ts forbids learning a fleet key over the wire, and that rule is untouched — adoptFleetKey is exactly as strict as it was. The argument for the narrow exemption is written out at the top of web/src/fleet/enrol.ts, and it is three things:

• There is no intermediary to be. The "wire" is a socket to 127.0.0.1, which the OS routes to one process on this computer: the process that owns the fleet key, wrote it to relay.json and served this page. The rule exists to stop an unknown party choosing the anchor every machine certificate hangs from; here there is no such party.
• No authority is created. A caller that can open /ws on loopback can spawn a shell, and a shell can read the fleet seed out of relay.json — so it could already mint a certificate for any key it liked, valid on every machine. The endpoint collapses three steps into one for the honest case and changes nothing for the dishonest one. For the same reason it must never become a wire message: a relay-origin device cannot read that file, so a wire.Enrol would be an escalation.
• The browser still checks what it stores. The certificate must verify under the key it arrived beside and must name this browser's own device key. Consistency rather than trust — the trust is the origin — and it keeps the browser from storing a blob it could only ever be refused for presenting.

The pin is replaced here, unlike on a welcome, and the comment says why: the certificate arrives with the key from the process that minted both, so the pair is coherent on arrival, and a loopback tab has no ceremony to be sent back to. spec/fleet-trust.md gains a "third delivery" section carrying the same argument, beside the second-delivery rule it deliberately leaves alone.

The directory, through the daemon

fleetSources' existing directoryFetch seam now carries /api/fleet/directory on a loopback tab and stays the plain cross-origin read on a relay tab. The daemon forwards the relay's bytes unchanged, so every blob is still verified under the pinned fleet key: transport, not trust. 409 (this machine holds no fleet key) is never retried — one attempt per epoch, because the cure is a change on the machine — and 502 (relay unreachable) costs machines this browser does not learn of and nothing else.

Live discovery

The expansion was one-shot per epoch, so a machine that joined at lunchtime never appeared in a tab opened at breakfast. It re-runs every 60s and on window focus, with a 5s floor so alt-tabbing is not a directory read per switch. Additive only: adoptRemotes adds ids it does not already hold and removes nothing, so an empty read, a 502, or a key store that will not open drops no machine, no rows and no client.

The reload-after-deploy trap

A tab that deploys a relay from the Remote screen cannot use it, and no amount of polling gets out of that: the page's Content-Security-Policy is built from relay.json when the daemon serves the document (LocalCSPFor), so a page served without a relay names none and the browser blocks both the relay socket and the directory read. Two more facts settle at the same moment — relayInfo() reports nothing while the leg is off and nothing broadcasts a change, and this browser's enrolment was answered 409 by a machine that then held no fleet key. One reload fixes all three, so the deploy's own result says so and offers the button. A button rather than an automatic navigation: the steps above it are the reader's only account of what was just done to their Cloudflare account, and every other flow on that card is careful not to navigate away from its own receipt. Setup only — a tab looking at the configured card was served with the relay already named.

The gap band

Both of FleetGapBand's loopback-facing sentences told that tab to pair from the relay, which it cannot act on. The no-fleet-key one now names the only local answer (this machine has none to give — check flue status, then reload), and the uncertified one names both doors, including the one that works on a machine's own address. In the healthy case the band does not render on loopback at all, because enrolment closes both gaps. #44's pinned count is what tells those cases apart and is kept.

Test evidence

cd web && pnpm vitest run → 1165 passed (59 files), three consecutive clean runs. pnpm run lint (tsc) clean. make web relay builds. go test ./... and go vet ./... clean — no Go changed.

The one that is the point, in fleet.test.ts: a loopback tab with an empty store, a scripted daemon answering POST /api/fleet/enrol, and a directory naming two machines ends up holding both — pinning the fleet key and the certificate, listing this machine once (the twin is dropped rather than dialled a second time), and dialling wss://relay.example/client/loft-9f9f with message A sealed to the key B's certificate names and the enrolled certificate in the payload. That client is what TerminalRoute resolves from /d/<machineId>/s/<id>, which is the href SessionTable writes for every row.

Alongside it: both orders of the enrolment/welcome race; enrolment idempotent across reloads, with no second directory read on a load that gains nothing; 409 leaves a working one-machine tab (no directory read, one POST, this machine's rows unchanged); 502 keeps the machine the tab is on; the directory read targets the proxy on loopback and https://relay.example/directory when nothing supplies a fetch; discovery adds a late machine, never drops one on an empty or failed read, asks again on focus but not on every glance, and reads nothing on a tab whose daemon has named no relay. enrol.test.ts covers the refusals — a certificate that does not verify under the key beside it, one for another device, a machine certificate where a device one belongs, a key that is not 32 bytes, a body that is not JSON — and the stale-pin replacement. provider.test.tsx pins that only the loopback tab posts anything at all.

Every new case was run against un-fixed code: removing the enrolment call fails the five loopback cases, removing the discovery interval fails the late-machine case, removing the focus listener fails the focus case.

🤖 Generated with Claude Code