What this is
The node is the FAU process that runs on the user’s Mac. It is the only component that:- holds Gmail credentials,
- decrypts the mail store,
- decides grants,
- speaks MCP to agents,
- verifies phone signatures,
- writes the audit log.
fedagent under node/. Supervised by the macOS client via launchd in production.
Goals
- Answer narrow, granted questions from local mail.
- Never mint an inbox token for an agent.
- Make every access explainable in the audit log.
- Stay reachable via one outbound tunnel.
Non-goals
- Being a multi-tenant SaaS mail host.
- Replacing the approval UX (that is the phone).
- Guaranteeing answers when the Mac is off and the offline queue is unused/full.
Process topology
NodeRuntime constructs dependencies inward: crypto keys → store → grants/audit/approvals → gateway/engine → transports. Transports must not own policy.
Path invariant: FAU_HOME and the runtime must not live under Documents/Desktop/Downloads (macOS TCC will break launchd/IMAP in confusing ways).
Channels, indexes, and actuators are node-local ports inside fedagent; they are not part of the fau/1 wire contract. See Product architecture (non-normative).
Surfaces
1. Agent data plane (node terminates TLS)
Optional hold:
X-FAU-Wait-Approval: 1 with timeout capped by approval TTL and 90 s.
2. Phone API
/papi/* — Phone API, Device signing.
3. Dashboard API (loopback only)
http://127.0.0.1:8765/api/* + X-FAU-Local. Used by macOS UI and embedded dashboard. Must not be exposed on the relay hostname.
Gateway rule: retrieve before the model
If you “let the model search then filter,” prompt injection becomes an access-control bug. FAU refuses that shape. Tiers (summary):State ownership
Approvals and push
On access/send prompt creation the node:- Inserts approval with match code and safe detail (no needless mail exfil in push).
- Best-effort Expo Push to all non-empty device tokens.
- Completes when
/papi/decideverifies, or dashboard decide (recorded as local), or expiry.
data fields only: approval_id, agent_domain, match_code, kind.Dead tokens (
DeviceNotRegistered, …) cleared from Expo tickets/receipts.Ops:
POST /api/settings/test-push.
Invariant: losing Expo must not lose the approval row; phones poll.
End-to-end: tool call with approval
- Verify RFC 9421 signature; reject bad nonce/skew.
- Resolve agent keys (HTTPS JWKS or local enrollment).
- Authorize via grant; else create approval and return
approval_required(or hold). - After allow: persist grant when appropriate; on retry, retrieve permitted messages; run engine; redact; audit; respond.
Failure modes
Concurrency
- Dashboard, MCP, phone, and sync share one store with SQLite locking — keep transactions short.
- Approval decide is single-winner; concurrent decides: one succeeds.
- Sync must not bypass gateway filters for agent-visible retrieval.
Security notes
- Output checks redact OTPs, card numbers, passwords, then length-cap answers.
security_codescategory is never granted.- Replay: agent nonces recorded inside expiry window.
- CT log watch on the node hostname detects unexpected certificates.
Develop and test
NodeRuntime, not system Python.
Extend safely
Design decisions
Decision: single-user node on the laptop.Why: custody and encryption under the user’s OS account.
Tradeoff: availability coupled to the Mac; multi-user households need multiple nodes or shared Mac hygiene. Decision: Biscuit capabilities exist but many flows use stored grants + retry.
Why: phones and agents already have round-trips; fewer tokens to leak.
Tradeoff: agents must understand retry-without-Bearer.
Open questions
- How aggressively to compact audit storage at multi-year retention.
- Whether dashboard-originated decides should ever be disabled in “phone-only” mode.