Skip to main content
This page is the map of how the Federated Agent Use protocol is realized in running software. Normative byte contracts: Wire specification. Threat model: Security model. If you have not read Concepts, 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

Responsibilities and state

Relay

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

Node

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

macOS client

Does not own: IMAP, grant logic, /papi as a device. Details: macOS client.

Approval app (iOS / Android)

Does not own: mail store, dashboard local token, agent RFC 9421 keys. Details: Mobile clients, Apps.

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

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)

Failure modes

Concurrency and delivery

Security summary

See Security model 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

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 — operate or reimplement the rendezvous
  • Node — extend policy, tools, store
  • Wire specification — normative fau/1 contracts