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

# Concepts

> What Federated Agent Use is, why it exists, and the mental model you need before reading anything else.

## One sentence

**Federated Agent Use (FAU) lets a remote AI assistant answer narrow questions about a person's email without ever receiving their inbox credentials — mail stays on their laptop; permission is granted per request on their phone.**

## The problem

Today, “connect Gmail to my AI” usually means: give the product an OAuth token (or an app password), sync mail to *their* servers, and hope policy and logging are good enough.

That fails three ways:

1. **Credential blast radius.** A stolen inbox token is the whole mailbox.
2. **Data gravity.** Once mail is copied off-device, revocation is theater.
3. **Opaque access.** Users cannot see *which* messages an agent touched for *which* question.

FAU inverts the usual shape: the assistant comes to the mail, under a grant, and leaves with an answer — not a corpus.

## Mental model

Think of three parties and a blind post office:

```
  ASSISTANT                         PERSON
  (anywhere)                        (Mac + phone)
       │                                 │
       │  1. “Where is user@gmail?”      │
       ▼                                 │
   RELAY ───────────────────────────────┘
   (public, blind)          2. TLS to a random hostname
                            that only that Mac can answer
       │
       │  3. Signed tool call: “when is my next flight?”
       ▼
   NODE (on the Mac)
       │  4. If not already allowed → phone prompt
       │     (domain + 2-digit match code)
       ▼
   ANSWER (short, logged) — never the mailbox
```

**One-line refinement:** the relay is a blind doorbell; the node is the house; the phone is the door lock.

| If you are used to… | In FAU… |
| - | - |
| OAuth “Sign in with Google” for an AI product | There is no inbox OAuth for the assistant |
| Webhooks into your backend | The Mac must be reachable (or use the offline queue) |
| Storing mail in your DB for RAG | Retrieval happens on the node; you get tool results |
| API keys identifying your app | Your **domain** (or a one-time enrollment) identifies you |
| User clicks “Allow” in a browser redirect | User confirms on a **paired phone** with a match code (CIBA-like) |

## Goals

* Assistants can get **useful, narrow answers** from mail the user already has.
* The user keeps **custody of mail and credentials** on their own machine.
* Every access is **scoped, revocable, and auditable** in language a person can read.
* The public rendezvous (**relay**) learns **as little as possible** and never decrypts node traffic.
* Anyone can attempt contact (open addressing); **permission** stays local (closed authorization).

## Non-goals

FAU deliberately does **not**:

* Replace Gmail, IMAP, or the user’s mail client.
* Host mail, embeddings, or full-text search in the cloud for agents.
* Provide a global registry of “approved” AI vendors (except optional claim enrollment on the user’s node).
* Guarantee the Mac is online 24/7 without the offline queue (and even then, envelopes are size-limited).
* Stop a compromised Mac from reading its own mail (the node’s host is inside the trust boundary).
* Make the relay unable to see **metadata** (timing, byte volume, HMAC of email, hostname). Blind ≠ invisible.

## Terminology

Use these words exactly. Do not invent synonyms mid-document.

| Term | Meaning |
| - | - |
| **Node** | The FAU process on the user’s Mac. Owns IMAP credentials, encrypted store, grants, MCP, phone API, audit log. Terminates TLS for its hostname. |
| **Relay** | Public Go service. Resolves email → hostname; peeks TLS SNI; forwards ciphertext into the node’s tunnel. Does not hold mail or node TLS keys. |
| **Agent** | Remote assistant software. Identified by a **publisher domain** (JWKS) or an **enrolled** id after a claim code. Calls `POST /mcp`. |
| **Approval app** / **device** | Phone (or other) client paired to the node. Signs `/papi/*`. Shows prompts; optional push wake. |
| **macOS client** | Menu bar app that installs and supervises the node. Does not sync mail or evaluate grants. |
| **Grant** | Stored permission on the node: which agent, which tier/categories, until when. |
| **Approval** | One pending phone prompt (`ap_…`) with a **match code**. |
| **Match code** | Two digits (`00`–`99`) shown by agent and phone so the human knows they are looking at the same request. |
| **Capability token** | Optional Biscuit token issued by the node after some approvals. Many flows store a grant and retry **without** returning a Bearer to the agent. |
| **Tunnel** | Outbound WebSocket from node → relay that carries multiplexed TLS streams. |
| **Protocol** | Version string **`fau/1`**. Breaking changes bump it. |

## How the system is decomposed

```mermaid theme={null}
flowchart LR
  subgraph public [Public network]
    A[Agent]
    R[Relay]
  end
  subgraph user [User machines]
    N[Node on Mac]
    P[Approval app]
    M[macOS menu bar]
  end
  A -->|resolve / queue| R
  A -->|TLS SNI = node hostname| R
  R -->|ciphertext via tunnel| N
  P -->|TLS /papi| R
  R --> N
  M -->|loopback /api| N
```

| Component | Owns | Does not own |
| - | - | - |
| **Relay** | Directory HMAC→node, tunnels, optional sealed queue, ACME DNS helper | Mail, grants, approvals, node private keys |
| **Node** | Mail sync, store, policy gateway, MCP, `/papi`, audit, Expo *send* of tokens it was given | Agent UX, Expo/APNs account credentials, global identity provider |
| **macOS client** | launchd, Keychain sealing, pair QR, stay-awake, local dashboard chrome | IMAP, grant evaluation |
| **Approval app** | Device key, prompt UX, push registration | Mail corpus, agent signatures |

## Two planes

**Control plane** — TLS terminated by the relay at `relay.<domain>`:

* Agents: resolve, offline queue
* Nodes: register, ACME, tunnel WebSocket, self-service

**Data plane** — TLS terminated by the **node**, hostname `<random>.relay.<domain>`:

* Agents: `GET /.well-known/fau-node`, `POST /mcp`
* Phones: `/papi/*`

The relay peeks the ClientHello **SNI**, finds the matching tunnel, and pipes bytes. It must **not** terminate TLS for node hostnames (no CDN “orange cloud” on `*.relay.`).

## Permission model (the part people get wrong)

1. **Open addressing.** Anyone can `POST /v1/resolve` with an email. Unknown addresses get a **decoy** hostname with the same JSON shape (anti-enumeration).
2. **Closed authorization.** Tool calls are signed as an agent identity. The node’s **gateway** checks grants and may require a phone approval **before** retrieving mail for the model.
3. **Retrieve before the model.** The gateway filters which messages exist in the candidate set *first*. A prompt injection in an email cannot widen retrieval, because retrieval already happened under the grant.
4. **Phone is the human factor.** Raw read and send are always prompted. Structured tools may auto-pass once a grant exists.

## What each party can observe

| Party | Can see | Cannot see |
| - | - | - |
| **Relay** | HMAC(email), node hostname, IPs, timing, byte counts, queue ciphertext | Mail, questions, answers, grants, `/mcp` plaintext |
| **Node** | Everything on that Mac for this user | Other users’ nodes |
| **Agent** | Tool results you return; match codes when approval is required | IMAP password; full mailbox; other agents’ traffic |
| **Approval app** | Prompt payloads (`summary`, draft for send, …) | Store encryption keys; other devices’ secrets |
| **Expo / APNs** | Push title/body/data you put there (FAU puts domain + match code only) | Mail content (if you keep the contract) |

## Invariants (always true)

1. Assistants never receive an inbox OAuth token or app password from FAU.
2. The relay never decrypts data-plane TLS for a node hostname.
3. A phone decision is accepted only with a signature from a paired device key (or an explicit local dashboard decide, recorded as such).
4. Push notification payloads must not carry mail content; they are wake signals.
5. `/v1/resolve` responses for unknown emails are shape-compatible with known ones.
6. Device signatures cover the full request target **including query string**.
7. Agent signatures cover method, target URI, authority, and body digest; nonces are single-use inside the expiry window.

## Design posture (why it looks like this)

| Decision | Why | Tradeoff |
| - | - | - |
| Mail on the Mac, not in our cloud | Custody and blast radius | Mac must be online (or queue); laptop sleep matters |
| Blind relay with SNI routing | Reachability without trusting the relay with content | Relay sees metadata; ops must not put TLS-terminating CDN in front |
| Domain identity + phone match codes | Phish-resistant “who is asking” without a central agent App Store | Agents need HTTPS JWKS or claim enrollment |
| Separate `/mcp` vs `/papi` | Agents and phones have different auth and UX | Two protocols to implement |
| Expo Push from the node | Simple fan-out; app vendors keep their own APNs keys | Node depends on Expo availability; polling remains mandatory |

## How to read the rest of these docs

| You want to… | Start here |
| - | - |
| Connect an assistant to the network | [For agents](https://docs.fau.run/developer/agents.md) → [Connect your agent](https://docs.fau.run/developer/agents/getting-started.md) |
| Run a node/relay or build clients | [For protocol developers](https://docs.fau.run/developer/developers.md) |
| Understand components deeply | [Protocol overview](https://docs.fau.run/developer/protocol/overview.md) |
| Pin codecs / vectors | [Wire specification](https://docs.fau.run/developer/protocol/spec.md) → [Device signing](https://docs.fau.run/developer/reference/device-signing.md) |

Protocol version throughout: **`fau/1`**.


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