Skip to main content

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.
Mental model: a policy gateway in front of a personal mail archive, with a public TLS name borrowed through the relay. Package: Python 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:
  1. Inserts approval with match code and safe detail (no needless mail exfil in push).
  2. Best-effort Expo Push to all non-empty device tokens.
  3. Completes when /papi/decide verifies, or dashboard decide (recorded as local), or expiry.
Push 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

  1. Verify RFC 9421 signature; reject bad nonce/skew.
  2. Resolve agent keys (HTTPS JWKS or local enrollment).
  3. Authorize via grant; else create approval and return approval_required (or hold).
  4. 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_codes category is never granted.
  • Replay: agent nonces recorded inside expiry window.
  • CT log watch on the node hostname detects unexpected certificates.

Develop and test

User installs get CPython from the macOS app’s 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.