Skip to main content

What this is

The relay is a public Go service that:
  1. Maps an email address to a random node hostname (without storing the email after confirm).
  2. Accepts an outbound WebSocket tunnel from each online node.
  3. On inbound TCP/TLS to port 443, reads the ClientHello SNI, and if it names a connected node, forwards ciphertext into that tunnel.
Mental model: a NAT traversal box that never opens your envelopes. It knows which doorbell belongs to which house; it does not enter the house. Protocol version: 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, subprotocol fau.1
  • Exactly one live tunnel per node_id; a newer successful AUTH displaces 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:
Unknown addresses get a stable decoy hostname derived from 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-key
  • DELETE /v1/node
  • GET /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

  1. Resolve known and unknown addresses return compatible JSON shapes.
  2. Data-plane bytes for node SNIs are forwarded without decryption.
  3. At most one live authenticated tunnel per node_id.
  4. Queue envelopes remain opaque to the relay.
  5. Rate-limit errors do not encode whether an email is registered.

Failure modes

Operate it (3 AM checklist)

  1. curl -sS https://relay.<domain>/v1/health — process up? nodes_connected?
  2. DNS: relay and *.relay A records → relay IP; not proxied.
  3. Node side: tunnel connected? (fedagent relay status / dashboard).
  4. Packet path: can the Mac open outbound 443 WSS to the relay?
  5. Certs: control hostname cert valid; node ACME recent success.
  6. Logs: AUTH_FAIL, frame_too_large, rate_limited spikes.
Deploy notes: 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