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

# Node

> The Mac runtime — store, gateway, MCP, phone API, tunnel client, and how to extend it safely.

## 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](https://docs.fau.run/developer/protocol/client-macos.md) 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

```mermaid theme={null}
flowchart TB
  MB[macOS app]
  LD[launchd com.fau.node]
  RT[NodeRuntime]
  MB -->|install/start| LD
  LD --> RT
  RT --> API[127.0.0.1:8765 /api]
  RT --> TLS[127.0.0.1 tls port]
  RT --> TUN[WSS tunnel client]
  RT --> IMAP[IMAP sync]
  RT --> LLM[Optional local LLM]
  MB -->|X-FAU-Local| API
  RELAY[Relay] --> TUN
  TUN --> TLS
```

`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](https://docs.fau.run/developer/developers/product-architecture.md) (non-normative).

## Surfaces

### 1. Agent data plane (node terminates TLS)

| Endpoint | Auth | Role |
| - | - | - |
| `GET /.well-known/fau-node` | none | Liveness / protocol ad |
| `POST /mcp` | RFC 9421 (+ optional capability) | MCP Streamable HTTP |
| `POST /agent/enroll` | one-time claim code | Lane B identity |

Optional hold: `X-FAU-Wait-Approval: 1` with timeout capped by approval TTL and **90 s**.

### 2. Phone API

`/papi/*` — [Phone API](https://docs.fau.run/developer/apps/phone-api.md), [Device signing](https://docs.fau.run/developer/reference/device-signing.md).

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

```mermaid theme={null}
flowchart LR
  REQ[Signed tool call] --> AUTH[Verify agent]
  AUTH --> GRANT[Check grant / approval]
  GRANT --> RET[Select messages by grant]
  RET --> ENG[LLM / extractive answer]
  ENG --> OUT[Redact + audit + respond]
```

If you “let the model search then filter,” prompt injection becomes an access-control bug. FAU refuses that shape.

Tiers (summary):

| Tier | Typical tools | Phone |
| - | - | - |
| `structured_read` | travel / orders / bills helpers | Often grant-auto after first allow |
| `free_form_read` | `ask` | Often grant-auto |
| `raw_read` | `get_excerpt` | **Always** |
| `compose` | drafts | Often grant-auto |
| `send` | `send_draft` | **Always** |

## State ownership

| State | Where | Notes |
| - | - | - |
| Store master key | Keychain / Secure Enclave (or marked insecure file) | AES-GCM column encryption |
| Mail rows | SQLite | Blind index for search |
| Grants / revocations | SQLite | Checked every tool call |
| Devices + push tokens | SQLite | One token per device |
| Pending approvals | SQLite | TTL \~300 s default |
| Audit chain | SQLite | Hash-linked; verify endpoint |
| Agent JWKS cache | SQLite / memory | Min refetch interval |
| Node identity | files + Keychain patterns | Ed25519 + TLS material |
| IMAP password | Keychain | Never in config JSON |

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

| Failure | Node behavior | Operator / client action |
| - | - | - |
| IMAP auth fail | Sync error surfaced in status | Fix app password; retest Gmail |
| LLM down | Structured/extractive paths may still work; `ask` degrades | Check model backend config |
| Expo 5xx | Log; keep approval | Rely on poll; fix network |
| Bad device sig | 401/403 class errors | Re-pair |
| Audit break | `verify` reports first bad link | Treat as integrity incident |
| Tunnel replaced | Old streams reset | Ensure single Mac registration |
| Disk full | Writes fail | Free space under FAU home |

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

```bash theme={null}
# from repo with venv
cd node && pytest
python -m fedagent status
python -m fedagent approvals …
```

User installs get CPython from the macOS app’s `NodeRuntime`, not system Python.

## Extend safely

| Extension | Guidance |
| - | - |
| New structured tool | Add behind an existing tier; gateway first |
| New LLM | Implement behind `AnswerEngine`; do not move filtering into prompts |
| New dashboard widget | Loopback `/api` only |
| New approval field | Keep push payload content-free; phone fetches detail |
| Breaking wire change | Bump `fau/1`, relay+node+docs+vectors together |

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

## Related

* [Protocol overview](https://docs.fau.run/developer/protocol/overview.md)
* [Wire specification](https://docs.fau.run/developer/protocol/spec.md)
* [Approvals (agent view)](https://docs.fau.run/developer/tools/approvals.md)
* [Build an approval app](https://docs.fau.run/developer/apps/overview.md)


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