> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fau.run/developer/llms.txt
> Use this file to discover all available pages before exploring further.

# Relay

> Blind rendezvous — what it stores, how SNI routing works, APIs, failures, and how to operate it.

## 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](https://docs.fau.run/developer/protocol/spec.md).

## 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

```mermaid theme={null}
sequenceDiagram
  participant N as Node
  participant R as Relay
  participant A as Agent
  N->>R: WSS /tunnel HELLO…AUTH
  R-->>N: AUTH_OK hostname
  A->>R: TCP+TLS ClientHello SNI=n….relay
  R->>N: STREAM_OPEN + STREAM_DATA
  N-->>A: TLS Finished + HTTP (via pipe)
```

### Two listeners, one port

| SNI | Behavior |
| - | - |
| `relay.<domain>` | Relay **terminates** TLS; serves `/v1/*` HTTP JSON |
| `<node-label>.relay.<domain>` | Relay **does not** terminate; pipes bytes to that node’s tunnel |

**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

| State | Purpose | Retention |
| - | - | - |
| Directory: HMAC-SHA256(relay\_secret, lower(email)) → node\_id | Resolve routing | Until deregister |
| Node pubkey, box\_pubkey, hostname, node\_token hash | Tunnel auth + queue seal target | Until rotate/delete |
| Live tunnel connection | Forwarding | While connected |
| Offline queue envelopes | Async delivery | TTL **24 h**, max **32**/node, **64 KiB**/envelope |
| Rate-limit counters | Abuse control | Short windows |
| ACME TXT challenges | DNS-01 for node certs | Ephemeral |

**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:

```json theme={null}
{
  "relay": "relay.fau.run",
  "hostname": "n….relay.fau.run",
  "box_pubkey": "<base64url>",
  "queue_endpoint": "https://relay.fau.run/v1/queue"
}
```

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

| Step | API |
| - | - |
| Enqueue sealed request | `POST /v1/queue/{hostname}` → `202 {request_id, expires_at}` |
| Claim reply | `GET /v1/queue/reply/{request_id}?wait=N` with `X-FAU-Queue-Claim` |

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](https://docs.fau.run/developer/connect/offline-queue.md).

### 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

| Failure | Symptom | What to do |
| - | - | - |
| CDN terminates `*.relay` | Agents get wrong cert / HTTP from CDN | DNS-only; remove proxy |
| Tunnel down | Resolve OK, TLS fails | Check node process, stay-awake, relay logs `nodes_connected` |
| AUTH loop | Flapping connections | Two Macs same registration; rotate/deregister |
| SMTP missing | Register never emails | Codes in relay logs only — fine for solo ops, not for users |
| Queue full | `429` / reject | Wait for TTL drain; reduce fan-out |
| Claim without key | `401 claim_required` | Agent must complete sealed-nonce challenge |

## 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

| Knob | Effect |
| - | - |
| `domain` / public IP | Hostnames agents dial |
| SMTP | Registration emails |
| Relay/decoy HMAC secrets | Directory + anti-enumeration (treat as critical) |
| Heartbeat seconds | Tunnel liveness sensitivity |
| Queue TTL / caps | Offline durability vs abuse |

## 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

| Safe | Unsafe without protocol bump + threat review |
| - | - |
| Metrics, SMTP providers, DNS backends | Decrypting node SNI traffic |
| Tuning rate limits | Different resolve shapes for unknown emails |
| Queue retention policies | Storing plaintext email after confirm |

## Related

* [Wire specification](https://docs.fau.run/developer/protocol/spec.md) — frames and AUTH canonical strings
* [Protocol overview](https://docs.fau.run/developer/protocol/overview.md) — how relay fits the whole system
* [Relay HTTP API](https://docs.fau.run/developer/reference/relay-api.md) — agent-oriented endpoint index


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.