Security model
Airpost's trust boundaries: who can reach the engine socket, what agents can do, how browsers are paired, where credentials are kept, and the privacy defaults.
The engine holds everything sensitive: your mail, your account credentials and the ability to send as you. Airpost’s security model is mostly about who can reach the engine and what they can do once they have.
The short version: any program running as your user on your computer has full access, because that’s the trust check. Agents get the access level you choose. Remote devices get in only through the gateway, after you pair them, and with a reduced set of methods unless you grant more.
Trust boundaries
| Boundary | Who is on the other side | What protects it |
|---|---|---|
| Engine socket | Processes on this computer | File permissions and a peer user id check |
| MCP | AI agents | The access level and visible accounts in mcp.json, a bearer token for HTTP |
| Gateway | Browsers and remote devices | One-time pairing codes, device cookies, scopes |
| Secret store | Anyone reading the disk | OS keychain, or AES-256-GCM with a separate key |
| Your provider | The network | TLS, OAuth where the provider supports it |
The engine socket
The engine is never on the network. It listens on a Unix domain socket, <profile>/run/engine.sock, and three things keep it private:
- File modes. The engine runs with a umask of
077, so every file and directory it creates (the database, logs, attachments, the socket) is readable by your user only. Therun/directory is0700and the socket0600. - Peer check. On every connection the engine asks the OS for the peer’s user id (
SO_PEERCREDon Linux) and refuses anyone who isn’t the user it runs as. - No secrets back. Credentials go into the engine and never come out over the socket. A client can set or delete a secret by name, and ask whether one exists, but not read it.
Inside that boundary there are no further checks: every local connection acts as you, with the same power as the app. This is deliberate. Another program running as you could already read your files, so a password on the socket wouldn’t add much. It does mean that malware running as your user can use the engine, and that the airpost CLI isn’t limited by the MCP access level.
MCP access levels
airpost-mcp is the boundary between AI agents and your mail. It connects to the engine with full access and then decides, per call, what the agent may do. The policy is in <profile>/mcp.json, edited in Preferences > MCP.
| Level | accessLevel | Adds |
|---|---|---|
| Read mail | read-only (default) | Listing, searching and reading mail, attachments, events and contacts |
| Read and draft | read-write | Drafts, archive, trash, move, labels, snooze, reminders, undo, events without guests |
| Read, draft and send | read-write-send | Sending, scheduling, unsubscribe, RSVPs and events with guests |
Unsubscribe and events with guests are in the send level because they can send mail on your behalf.
- Fails closed. An unknown level is treated as
read-only. Amcp.jsonthat doesn’t parse makes every tool fail, so a typo can’t widen access. The file is read again on every call. - Hidden accounts and folders aren’t listed, and their ids answer “not found”, the same as if they didn’t exist.
- Transports. stdio is for apps on this computer that start
airpost-mcpthemselves, such as Claude Desktop or Claude Code. HTTP (airpost-mcp http, off by default, on127.0.0.1) needsAuthorization: Bearer <token>with the token in<profile>/mcp-token, created owner-only on first use. - Audit log. Every tool call and resource read is appended to
<profile>/mcp-audit.log: time, client, account, tool, outcome (ok,errorordenied) and a summary of the arguments with message bodies replaced by their length and credential-like keys dropped.
See Access levels and Audit log.
Gateway pairing and tokens
The gateway is the only part that puts the engine on a network. It serves the web client and relays requests to the engine socket for devices you’ve paired.
- Codes are 12 characters, work once, and expire after 10 minutes by default (at most an hour). Attempts are rate limited per client address and overall.
- Cookies are
HttpOnlyandSameSite=Strict, andSecurewith the__Host-prefix over HTTPS. The gateway stores only hashes of codes and tokens, in<profile>/gateway/devices.json. Unused devices are dropped after 180 days, admin devices after 30. - Scopes. A device paired without
--admincan read mail, triage it and work on drafts. Account, secret and engine methods, and tasks that write to a local path, need theadminscope. AI provider settings (core.ai.*) can’t be changed from any remote device, admin or not, because that would let a remote device point the engine at any URL. - Checked twice. The gateway checks each request against the policy in
airpost-ipc, and the engine checks it again for every connection whosehellosaysrelayed. - Origin and Host checks on every request, and plain HTTP refused off loopback unless you opt in.
See Pairing browsers and Self-hosting security.
Credential storage
| Where | Backend | Notes |
|---|---|---|
| macOS | Keychain, service Airpost Engine | One item for the whole keyset, so you’re asked at most once. |
| Linux desktop | Secret Service | Same keyset in one item. |
| Server, or no keyring | secrets.enc, AES-256-GCM | Key from AIRPOST_ENGINE_KEY_FILE or systemd’s $CREDENTIALS_DIRECTORY. |
There’s no plaintext fallback. accounts.json holds account settings without passwords or tokens. Gmail and Microsoft sign in with OAuth, so Airpost holds a refresh token and never sees your password; IMAP accounts store the password you enter. Authentication payloads are never written to the logs, even with --verbose.
The file store keeps credentials out of a leaked profile or backup, as long as the key isn’t stored with it. In the server image the key is on a volume only the engine’s container mounts, so the gateway and MCP containers can read the profile (they need the socket) but can’t decrypt credentials.
What this doesn’t protect against
- Root, or malware running as you. Either can use the socket, read the database, or read the key file.
- A compromised gateway or MCP process. It can act through the socket as the profile’s owner, beyond its own policy.
- A paired device that’s stolen. Its cookie works until you revoke it or it expires. Revoke it with
airpost-gateway devices revoke <id>. - A key file stored next to
secrets.enc. Then anyone with the backup has both. - Your provider. The provider already has your mail; Airpost doesn’t add encryption at rest on the server side.
Privacy defaults
Nothing goes to an Airpost service unless you connect an Airpost server. The defaults:
| Protection | Default |
|---|---|
| Remote images blocked until you load them | On |
| Tracking pixels from known trackers removed | Always on |
| Contact photos from Gravatar | Off |
| AI features | Off |
| Integrations (translation, grammar, contact details) | Off |
| MCP access for agents | Off until you allow it, then read-only |
| Web access (gateway) | Off; when on, bound to 127.0.0.1:5180 |
| MCP over HTTP | Off; when on, bound to 127.0.0.1 |
| Drafts saved to the server | On, per account |
What is sent where when you turn something on is listed in Privacy.
Related
- The engine: the socket and protocol.
- Profiles and data: where secrets and logs are stored.
- Security: reporting a vulnerability.