Security & Data Flow

How mail moves through Maru Mail, and every boundary it can cross.

The data flow, complete

Google Gmail API  (TLS, OAuth 2.0 + PKCE)
   │
   ▼
Maru process on your device
   │
   ├── encrypted local database  (mail, index, approvals, audit)
   ├── OS keychain               (OAuth tokens, encryption keys)
   ├── optional: Maru Sync ─────► encrypted vault ciphertext only
   │
   └── optional: local socket (0600) ──► agent process you connected
                                            │
                                            └── possibly that agent's
                                                hosted model provider
                                                (outside your device)

Maru Sync is optional. It stores an encrypted vault containing settings, account addresses, and refresh tokens. The account key stays in your device's keychain, so the service cannot read the vault. The agent hop happens only for agents you created, granted, and consented to.

Sign-in

• OAuth 2.0 for installed apps: your system browser, a loopback redirect bound to 127.0.0.1, and PKCE (S256). Maru never sees or asks for your Google password.
• Maru requests one Gmail scope, gmail.modify — the minimum that supports reading, labeling, and user-approved sending. Maru cannot permanently delete mail.
• Refresh tokens live in the OS keychain, bound to the client that issued them. Maru Sync can copy desktop-family refresh tokens inside the end-to-end encrypted vault.

Encryption

• Message content and attachment metadata are encrypted at rest in Maru's local store; one key per account, held in the OS keychain, never leaving your device. Attachment contents are fetched from Gmail on demand, not cached.
• Audit-log fields containing Google-derived content use per-account keys, destroyed when you remove the account — the log's structure survives, its restricted content does not.
• All Google traffic is TLS.

The agent gateway

• The gateway is a Unix socket (macOS/Linux, mode 0600 in a 0700 directory) or named pipe (Windows) — never a network port.
• Agents authenticate with a credential Maru issues; Maru stores only its SHA-256 digest.
• Capabilities are explicit per-agent grants. A new agent holds nothing.
• Each agent session requires fresh, time-bounded consent that names the agent, the data classes it may read, and the possibility of hosted-model processing.
• Message bodies and attachments are delivered to agents marked as untrusted content — prompt-injection text inside mail is data, not instructions, and Maru's own send gate is immune to it: no path exists from any tool call to a dispatched email without a human approving it in the Maru UI.
• Every connection, call, refusal, and approval is written to an append-only audit log you can read in the app.

Reporting a vulnerability

Maru is open source (AGPL-3.0). Report security issues to security@getmaru.app — see SECURITY.md for scope and expectations. The full permission model is specified in PERMISSION-MODEL.md.