What this is
The relay is a public Go service that:- Maps an email address to a random node hostname (without storing the email after confirm).
- Accepts an outbound WebSocket tunnel from each online node.
- On inbound TCP/TLS to port 443, reads the ClientHello SNI, and if it names a connected node, forwards ciphertext into that tunnel.
fau/1. Full frame table: Wire specification.
Goals
- Make home NATs reachable to agents and phones without VPNs.
- Keep mail and tool payloads confidential from the relay operator.
- Avoid email enumeration via resolve (decoy hostnames).
Non-goals
- Terminating TLS for
*.relay.<domain>node names. - Evaluating grants or showing approval UI.
- Storing plaintext email long-term.
- Being a general-purpose message queue for arbitrary apps.
Architecture
Two listeners, one port
Operational invariant: nothing in front of the relay may terminate HTTPS for
*.relay.<domain> (no Cloudflare orange-cloud). If something else presents certificates for node hostnames, the blind property is gone.
Tunnel
- URL:
wss://relay.<domain>/tunnel, subprotocolfau.1 - Exactly one live tunnel per
node_id; a newer successfulAUTHdisplaces the old (replaced) - Multiplexing: binary frames (version, type, stream id, length, payload); max payload 256 KiB
- Auth: challenge–response Ed25519 over
fau/1 tunnel-auth\n<node_id>\n<nonce>\n<server> - Liveness: relay PINGs; two missed PONGs → drop
- Streams are relay-initiated when an external client connects with matching SNI
key_id is derived as k_ + first 12 hex chars of sha256(raw ed25519 pubkey) — rotation signal, not a secret.
State the relay stores
Must not store: mail, MCP JSON, approval bodies, node TLS private keys, device keys.
Control-plane APIs
Base URL:https://relay.<domain> (public: https://relay.fau.run).
Errors: {"error":"<code>","detail":"<human>"}.Rate limits: per IP and per target email; must not reveal which limit fired (
429 rate_limited only).
POST /v1/resolve (agents)
Request: {"address":"user@gmail.com"}
Response 200 — same shape whether or not the user has a node:
HMAC(decoy_secret, address) that accepts TCP but never completes TLS. Timing is equalized toward real lookups.
POST /v1/register / POST /v1/register/confirm (nodes)
Start email verification; confirm returns node_id, hostname, node_token, ACME basic auth. Registration responses look the same if the address was already registered (anti-oracle).
After confirm, plaintext email is discarded; only the HMAC directory entry remains.
Offline queue
Relay stores ciphertext +
reply_pubkey for claim challenges. It cannot read envelopes.Delivery to the node is at-least-once. Agents should create
request_id and persist the reply private key before POST (crash safety).
Details: Offline queue.
Node self-service (bearer node_token)
POST /v1/node/rotate-keyDELETE /v1/nodeGET /v1/node/status→ connected / queued counts
ACME helper
HTTP Basic scoped to_acme-challenge.<that node hostname> only. Relay never sees the certificate private key.
GET /v1/health / GET /v1/transparency
Liveness and an honest public statement of metadata observation.
Invariants
- Resolve known and unknown addresses return compatible JSON shapes.
- Data-plane bytes for node SNIs are forwarded without decryption.
- At most one live authenticated tunnel per
node_id. - Queue envelopes remain opaque to the relay.
- Rate-limit errors do not encode whether an email is registered.
Failure modes
Operate it (3 AM checklist)
curl -sS https://relay.<domain>/v1/health— process up?nodes_connected?- DNS:
relayand*.relayA records → relay IP; not proxied. - Node side: tunnel connected? (
fedagent relay status/ dashboard). - Packet path: can the Mac open outbound 443 WSS to the relay?
- Certs: control hostname cert valid; node ACME recent success.
- Logs: AUTH_FAIL, frame_too_large, rate_limited spikes.
relay/deploy/README.md (VPS), relay/deploy/fly.md (Fly + Porkbun DNS API).
Configuration that matters
Design decisions
Decision: SNI-based blind forward instead of relay-terminated HTTPS reverse proxy.Why: Relay must not hold node private keys or see MCP/phone JSON.
Alternative: Full proxy with per-node certs on the relay — simpler ops, destroys the threat model.
Tradeoff: Ops fragility (CDN mistakes); CT monitoring on nodes as backstop. Decision: Decoy resolve results.
Why: Prevent “is this person on FAU?” oracle.
Tradeoff: Agents cannot distinguish offline vs nonexistent without attempting TLS. Decision: At-least-once offline queue.
Why: Simple; node dedupes terminal
request_id.Tradeoff: Agents must be idempotent at the tool layer for non-cached retries.
Extending safely
Related
- Wire specification — frames and AUTH canonical strings
- Protocol overview — how relay fits the whole system
- Relay HTTP API — agent-oriented endpoint index