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

# Protocol overview

> How relay, node, and clients realize fau/1 — boundaries, flows, state, and failure.

This page is the map of **how the Federated Agent Use protocol is realized** in
running software. Normative byte contracts: [Wire specification](https://docs.fau.run/developer/protocol/spec.md).
Threat model: [Security model](https://docs.fau.run/developer/protocol/security.md).

If you have not read [Concepts](https://docs.fau.run/developer/concepts.md), read that first — especially goals,
non-goals, and invariants.

## Central abstraction

**A user-owned node is the only place mail is decrypted and policy is enforced.**
Everything else exists to reach that node safely (relay), supervise it (macOS client),
or authorize human decisions (approval app).

## Component diagram

```mermaid theme={null}
flowchart TB
  subgraph agents [Agent hosts]
    AG[Agent process]
  end
  subgraph relay_box [Relay operators]
    RL[Relay Go service]
  end
  subgraph mac [User Mac]
    MB[macOS menu bar]
    ND[Node fedagent]
    ST[(Encrypted SQLite)]
    IM[Gmail IMAP]
  end
  subgraph phone [User phone]
    AP[Approval app]
  end
  AG -->|HTTPS control| RL
  AG -->|TLS data plane SNI| RL
  RL -->|WSS tunnel frames| ND
  AP -->|TLS /papi| RL
  MB -->|HTTP loopback /api| ND
  ND --> ST
  ND --> IM
```

## Responsibilities and state

### Relay

| Owns | State | Inputs | Outputs |
| - | - | - | - |
| Rendezvous | HMAC(email)→node\_id, tunnels, queue blobs, rate limits | resolve, register, WSS, ACME, queue POST/GET | hostname, forwarded TCP, 202 queue ids |

**Does not own:** mail plaintext, grants, approval decisions, node TLS private keys,
Expo credentials.

Details: [Relay](https://docs.fau.run/developer/protocol/relay.md).

### Node

| Owns | State | Inputs | Outputs |
| - | - | - | - |
| Policy + mail | encrypted messages, grants, devices, approvals, audit chain, agent key cache | IMAP, `/mcp`, `/papi`, dashboard `/api`, tunnel | tool results, prompts, Expo pushes, audit entries |

**Does not own:** agent product UX, public APNs keys, relay directory secrets.

Details: [Node](https://docs.fau.run/developer/protocol/node.md).

### macOS client

| Owns | State | Inputs | Outputs |
| - | - | - | - |
| Lifecycle UX | launchd plist, Keychain-sealed store key refs, UI prefs | user actions, `/api` JSON | start/stop node, pair QR, stay-awake |

**Does not own:** IMAP, grant logic, `/papi` as a device.

Details: [macOS client](https://docs.fau.run/developer/protocol/client-macos.md).

### Approval app (iOS / Android)

| Owns | State | Inputs | Outputs |
| - | - | - | - |
| Human decisions | device keypair, session (host, device\_id), Expo token | pair QR, `/papi`, push | signed decide/pause, token register |

**Does not own:** mail store, dashboard local token, agent RFC 9421 keys.

Details: [Mobile clients](https://docs.fau.run/developer/protocol/client-mobile.md), [Apps](https://docs.fau.run/developer/apps/overview.md).

## End-to-end flows

### A. First contact (agent asks, phone allows)

1. **Agent** `POST /v1/resolve` `{address}` → `hostname`, `box_pubkey`, `queue_endpoint`.
2. **Agent** `GET https://<hostname>/.well-known/fau-node` (unsigned) — liveness.
3. **Agent** opens MCP: signed `initialize`, then `tools/call` (e.g. `ask`).
4. **Node** gateway: no grant → creates **approval** `ap_…`, **match code** `47`, pushes Expo wake (if tokens exist), returns `approval_required` to the agent (unless wait header holds the call).
5. **Phone** receives push (optional) → signed `GET /papi/pending` → shows domain + `47`.
6. **User** taps Allow → signed `POST /papi/decide`.
7. **Node** stores grant (for many tools) → agent **retries** the same tool call → answer + audit entry.

State transitions: `approval: pending → decided|expired`; often `grant: created`.

### B. Pair a new phone

1. Mac client `GET /api/pair/start` → code + QR `fau://pair?host&code&fp`.
2. Phone generates Ed25519 key → `POST /papi/pair` (unsigned; code is the capability).
3. Phone stores `device_id` + secret; registers Expo token via signed `POST /papi/push-token`.

### C. Mac asleep (offline queue)

1. Live TLS to hostname fails.
2. Agent seals an HTTP replay to `box_pubkey`, enqueues on relay with `reply_pubkey`.
3. Node later pulls `QUEUED` frames, executes, seals reply to agent’s reply key.
4. Agent claims reply with possession proof (`X-FAU-Queue-Claim`).

See [Offline queue](https://docs.fau.run/developer/connect/offline-queue.md). Limits: 64 KiB envelope, 32 per node, 24 h TTL.

### D. Register a node on a relay

1. Node (via Mac setup) `POST /v1/register` with email + pubkeys.
2. User confirms emailed code → `hostname`, `node_token`, ACME creds.
3. Node obtains TLS cert for hostname; opens `wss://relay…/tunnel`; AUTH with Ed25519.

## Trust boundaries

```mermaid theme={null}
flowchart LR
  subgraph untrusted [Untrusted network]
    AG[Agent]
    RL[Relay]
    EX[Expo]
  end
  subgraph trusted_user [User trust domain]
    ND[Node]
    PH[Phone secure storage]
    MB[Mac Keychain]
  end
  AG --> RL
  AG --> ND
  PH --> ND
  EX -.->|wake only| PH
  MB --> ND
```

| Boundary | Rule |
| - | - |
| Internet → node TLS | Node validates agent signatures; relay only forwards |
| Phone → node | Device signatures; no dashboard token on phone |
| Mac UI → node | Loopback + `X-FAU-Local` only |
| Node → Expo | Content-free push; Expo compromise ≠ mail compromise |
| Node → IMAP | Credentials never leave the Mac toward agents |

**Authenticated ≠ authorized ≠ encrypted ≠ trusted.**\
Example: an agent can be *authenticated* as `assistant.example` and still *unauthorized* for `raw_read` until a grant exists.

## Data model (entities that matter)

| Entity | Id shape | Lifecycle | Notes |
| - | - | - | - |
| Node directory entry | `node_id` / hostname | Created at register confirm; deleted on deregister | Email plaintext discarded after confirm; HMAC remains |
| Device | `dv_…` | Pair → use → remove | One `push_token` per device |
| Approval | `ap_…` | pending → decided/expired (\~300 s default) | Match code 00–99 |
| Grant | `g_…` | created on allow; revoked/expired | Tier + categories + bounds |
| Audit entry | sequential | append-only hash chain | Verify detects gaps |
| Queue request | `request_id` | enqueued → answered/expired | Idempotent; terminal replies cached |

## Failure modes

| Failure | Behavior | Recovery |
| - | - | - |
| Node tunnel down | TLS to hostname fails handshake / hangs | Agent retries; or offline queue |
| Relay down | resolve + data plane fail | Operational; nodes reconnect with backoff |
| Phone offline | Approval sits until TTL | Agent sees expiry; user opens app later if still pending |
| Push fails | Approval still in DB | Polling; dashboard still works |
| Duplicate `/papi/decide` | Second decide fails closed | Client treats as already decided |
| Duplicate agent nonce | Rejected | Agent must new nonce |
| Decoy hostname contacted | TLS never completes | Indistinguishable from offline real node — by design |
| Two tunnels same node\_id | Newer AUTH replaces older | Only one live tunnel |
| Partial queue POST | Ambiguous 202 | Client-generated `request_id` + local outstanding store before POST |

## Concurrency and delivery

| Path | Semantics |
| - | - |
| Tunnel streams | Relay-initiated; backpressure windows; at-most-one live tunnel per node |
| Offline queue | **At-least-once** to the node; agents must tolerate duplicate execution unless `request_id` hits terminal cache |
| Approvals | One decision wins; expires unanswered (deny-by-default product stance) |
| Clocks | Agent sig skew ≤ 60 s created; expiry window ≤ 300 s live; queued sig age vs **queue receive time** |

## Security summary

See [Security model](https://docs.fau.run/developer/protocol/security.md) for the full threat model. Essentials:

* No inbox token to agents.
* Retrieve-before-model.
* Hash-chained audit.
* CT watch on node hostname (detect relay MITM attempts).
* Weakest link: malware on the user’s Mac with the user’s privileges.

## Extensibility

| Stable | Replaceable |
| - | - |
| `fau/1` wire contracts | LLM backend behind the gateway |
| `/mcp` tool names once published | macOS / phone UI skins |
| Blind relay property | Relay hosting (Fly vs VPS) |
| Device signing scheme | Push provider *only if* phone+node change together |

If you break an invariant to ship a feature, you are no longer implementing FAU — document a fork.

## Open questions

Labeled so they are not mistaken for product law:

* **Unknown / product:** per-app push filtering when multiple approval apps pair to one node (today: fan-out to all tokens).
* **Unknown / product:** self-service device deregister from phone (today: clear token + Mac remove).
* **Assumption:** public docs describe `fau/1` as shipped; experimental flags in source may lag this site after a release.

## Next

* [Relay](https://docs.fau.run/developer/protocol/relay.md) — operate or reimplement the rendezvous
* [Node](https://docs.fau.run/developer/protocol/node.md) — extend policy, tools, store
* [Wire specification](https://docs.fau.run/developer/protocol/spec.md) — normative `fau/1` contracts


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