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)
- Agent
POST /v1/resolve{address}→hostname,box_pubkey,queue_endpoint. - Agent
GET https://<hostname>/.well-known/fau-node(unsigned) — liveness. - Agent opens MCP: signed
initialize, thentools/call(e.g.ask). - Node gateway: no grant → creates approval
ap_…, match code47, pushes Expo wake (if tokens exist), returnsapproval_requiredto the agent (unless wait header holds the call). - Phone receives push (optional) → signed
GET /papi/pending→ shows domain +47. - User taps Allow → signed
POST /papi/decide. - Node stores grant (for many tools) → agent retries the same tool call → answer + audit entry.
approval: pending → decided|expired; often grant: created.
B. Pair a new phone
- Mac client
GET /api/pair/start→ code + QRfau://pair?host&code&fp. - Phone generates Ed25519 key →
POST /papi/pair(unsigned; code is the capability). - Phone stores
device_id+ secret; registers Expo token via signedPOST /papi/push-token.
C. Mac asleep (offline queue)
- Live TLS to hostname fails.
- Agent seals an HTTP replay to
box_pubkey, enqueues on relay withreply_pubkey. - Node later pulls
QUEUEDframes, executes, seals reply to agent’s reply key. - Agent claims reply with possession proof (
X-FAU-Queue-Claim).
D. Register a node on a relay
- Node (via Mac setup)
POST /v1/registerwith email + pubkeys. - User confirms emailed code →
hostname,node_token, ACME creds. - 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/1as 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/1contracts