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

# Security

> Promises, non-promises, enforcement points, and residual risk.

What this system promises, what it does not, and where the promises are enforced in code.

## The promise

Your mail stays on your computer. A remote assistant can obtain answers you have allowed,
and nothing else. Every access is recorded in a log you can read and verify.

## What an assistant cannot do

| Attack | What stops it |
| - | - |
| Use a stolen inbox token | There is no inbox token. The node holds the IMAP credential; assistants only ever call tools. |
| Read a category you did not grant | The gateway filters by grant before retrieval (`policy/gateway.py`). The model receives a pre-filtered list. |
| Widen its own access with a prompt injection in an email | Access is decided before the model runs. An injected instruction can at worst produce a bad answer, never a wider retrieval. Detected injections are flagged on the answer and in the audit log. |
| Read raw email text without asking | `get_excerpt` is a raw-read tier: always a phone approval, never auto-granted. |
| Send mail on your behalf | `send_draft` requires a phone approval every time. Compose only ever produces a draft. |
| Replay a captured request | Signed requests carry a nonce the node records; a second use is refused (`crypto/signatures.py`). |
| Tamper with a request in flight | RFC 9421 signature covers method, target, host, and a digest of the body. |
| Impersonate another assistant | Identity is the domain, verified against the keys that domain publishes. Prompts show the verified domain, never a name the agent supplied. |
| Exhaust you with approval prompts | Rate-limited per domain; repeated denials auto-block; one-tap mute. |
| Make the node hammer a third-party domain | Key refetches for unknown key ids have a minimum interval, and fall back to cached keys. |
| Exfiltrate a code or card number inside a legitimate answer | Output checks redact one-time codes, card and account numbers, and passwords, then cap length (`engine/checks.py`). |
| Quietly answer a question it cannot actually answer | The extractive path requires a genuine match and otherwise refuses. A confident wrong answer is treated as a security bug, not a quality one. |

## What the relay can see

The relay is blind to content but not to metadata. Stated plainly because the honest
version belongs in public:

* A keyed hash (HMAC) of your email address, so it can route to your node.
* Your node's random hostname and its IP address.
* Connection timing and byte volume.

It cannot see mail, questions, answers, or grants: it forwards TLS it cannot terminate.
It holds no decryption keys and makes no access decisions. Node hostnames are random
rather than derived from your email, because SNI is visible on the network and an email
hash can be brute-forced.

The node watches Certificate Transparency logs for certificates issued on its own
hostname, so a relay that tried to terminate TLS would be visible.

## At rest

The SQLite store is encrypted per column with AES-GCM under a key sealed by the macOS
Keychain (Secure Enclave where available). Search works without decrypting the index: it
is a blind index of keyed hashes, so the index reveals no plaintext. Attachment bytes are
never stored, only their metadata.

If no keychain is available the key is written to a file named `.insecure` and the node
says so out loud, rather than pretending.

## The audit log

Hash-chained: each entry commits to the previous entry's hash, so an entry cannot be
removed or altered without breaking the chain. `GET /api/audit/verify` re-walks it and
reports the first broken link. Every agent request records the agent, the grant, the
query, the decision, the ids of the emails touched, and the full output that was
returned. Your own decisions — approve, deny, revoke, block, mute, pause — are recorded
too, because "who allowed this?" is as much a question as "what did it read?".

## Approvals

Approvals are signed on your phone by a device key created at pairing and held in the
device keystore behind biometrics where the device supports it. The relay cannot forge
them and neither can the node: the signature is checked against the key registered at
pairing. Prompts carry a 2-digit match code shown by both the assistant and the phone, so
a prompt arriving out of the blue is recognisable as such. The pattern follows OpenID
CIBA: initiated by the client, approved on a separate device, no redirect.

Requests are signed over the full request target including the query string, so a
parameter cannot be rewritten in flight. Both sides are pinned to
`[Device signing vectors](/reference/device-signing)`.

## Where it is weakest

Stated because a threat model that only lists strengths is marketing:

* **The node's own machine.** Anything running as you can read the dashboard token and
  reach loopback. Encryption at rest protects a stolen disk, not a compromised session.
* **The local model's judgement.** Output checks are patterns; a novel encoding of a
  secret could pass. This is why retrieval is filtered first — the model's mistakes are
  bounded by what it was allowed to see.
* **Capability tokens** are a compatible implementation of Biscuit's properties, not the
  Biscuit library, which needs a Rust toolchain. Swappable, and worth swapping.
* **Relay metadata under India's DPDP Act** needs legal review before launch, and the
  transparency page above needs publishing.

## Reporting

Security issues: open an issue marked security, or mail the address in the repository
metadata. Please include what you could reach and how.


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