tutabridge/README.md

# TutaBridge

A local IMAP/SMTP bridge for [Tuta](https://tuta.com) encrypted email. It runs a
local IMAP+SMTP server that ordinary mail clients (Thunderbird, Apple Mail, mutt,
…) connect to, while talking to Tuta's API and handling the end-to-end
encryption transparently.

Available as a **CLI** and a **desktop GUI** (Tauri).

> ⚠️ **Unofficial & unsigned.** TutaBridge is an independent project — not
> affiliated with, endorsed by, or supported by Tuta. It logs into your account
> and decrypts your mail locally, outside Tuta's official apps; use it at your
> own risk. The released binaries are **not code-signed**, so macOS and Windows
> warn on first launch — see [Install](#install) for how to get past that.

## Features

- **IMAP + SMTP** servers on localhost (TLS), so any standard mail client works.
- **Realtime sync** over Tuta's WebSocket event bus — new mail, reads, moves and
  deletes show up without polling. A heartbeat + idle-timeout detect dead
  sockets and reconnect automatically.
- **Attachments** both ways — incoming mail is served as `multipart/mixed`;
  attachments composed in your client are uploaded to Tuta on send.
- **Drafts**, **custom / nested folders**, **move**, **trash**, and read/unread
  flags.
- **2FA (TOTP)** login.
- **Encrypted local cache** — metadata in SQLCipher, bodies as individually
  encrypted `.eml.enc` files. Subsequent launches load from cache and only fetch
  the delta, so the client is usable immediately.
- **Complete mailbox backup** to portable `.eml` files (see below).
- **Full mailbox + search** — the whole account is listed over IMAP and
  searchable by subject, sender, date and (full-text) body from your mail client.

## Install

Download the latest build from the [**Releases**](../../releases) page. Every
platform ships two flavours:

- a **desktop app** — a normal double-click GUI, recommended for most people;
- a **CLI binary** — a single executable you run from a terminal, for
  headless / server use.

| Platform | Desktop app | CLI binary |
|----------|-------------|------------|
| **macOS** (Apple Silicon) | `TutaBridge_*_universal.dmg` | `tutabridge-macos-arm64` |
| **Windows** (x64) | `TutaBridge_*_x64-setup.exe` (or `.msi`) | `tutabridge-windows-x86_64.exe` |
| **Linux** (x64) | `*.AppImage` / `*.deb` / `*.rpm` | `tutabridge-linux-x86_64` |

Because the binaries aren't signed, each OS needs a one-time nudge to run them:

### macOS

Open the `.dmg` and drag TutaBridge to Applications. On first launch macOS says
the app "cannot be opened because the developer cannot be verified" — **right-click
the app → Open → Open**, which whitelists it permanently. (Plain double-click
won't offer the override.)

### Windows

Run the `.exe` / `.msi`. SmartScreen shows "Windows protected your PC" — click
**More info → Run anyway**.

### Linux

```bash
chmod +x TutaBridge_*_amd64.AppImage && ./TutaBridge_*_amd64.AppImage
# or:  sudo dpkg -i TutaBridge_*_amd64.deb     (Debian/Ubuntu)
# or:  sudo rpm -i  TutaBridge-*.x86_64.rpm     (Fedora/RHEL)
```

### CLI binary (any OS)

The CLI files have **no extension**, so double-clicking does nothing useful (your
OS may even open them in a text editor). Run them from a terminal:

```bash
chmod +x tutabridge-macos-arm64                          # make it executable
xattr -d com.apple.quarantine tutabridge-macos-arm64     # macOS only: clear Gatekeeper
./tutabridge-macos-arm64                                  # run
```

## Getting started

1. **Launch** the app (or run the CLI). On first run it asks for your Tuta email,
   then your password and TOTP code if there's no saved session. The session is
   stored in your OS keychain, so later launches resume automatically.
2. TutaBridge shows the **local connection details**. Note the **bridge password** —
   this is generated by TutaBridge for local IMAP/SMTP auth and is **not** your
   Tuta password. (CLI: it's printed in the logs; GUI: it's on the main screen.)
3. **Add the account** in your mail client with these settings:

   | | Server | Port | Security | Auth |
   |---|---|---|---|---|
   | **IMAP** (incoming) | `127.0.0.1` | `1143` | SSL/TLS | normal password |
   | **SMTP** (outgoing) | `127.0.0.1` | `1025` | SSL/TLS | normal password |

   - **Username**: your Tuta email
   - **Password**: the **bridge password** from step 2
   - Accept the **self-signed certificate** when the client prompts.

Keep TutaBridge running while you use your mail client — it's the local server
the client talks to.

### Client-specific notes

- **Thunderbird**: add the account manually (don't let auto-config probe public
  servers). Set both servers to `127.0.0.1` with SSL/TLS + "Normal password",
  and accept the certificate exception on first connect.
- **Apple Mail**: add an "Other Mail Account", then in *Server Settings* turn
  **off** "Automatically manage connection settings" so you can pin host
  `127.0.0.1`, the ports above, and TLS.

### Notes & limitations

- **Search** runs in your mail client and is honest: subject / sender / date
  search covers the whole mailbox; **body** (full-text) search covers messages
  whose body has been **downloaded**. Keep "every message body offline" enabled
  (or raise the offline-bodies limit) for full-mailbox body search.
- **Self-signed cert** is expected — the bridge only listens on `127.0.0.1`, so
  traffic never leaves your machine.

## Architecture

Syncer-driven, store-backed:

```
Tuta API  ←──  Syncer (background)  ──→  MailStore (in-memory)  ←──  IMAP server  ──→  mail client
                                                                ←──  GUI (stats)
```

- The **syncer** pulls from the Tuta API and populates an in-memory `MailStore`,
  backed by the on-disk encrypted cache.
- The **IMAP server** only ever *reads* from the store — it never makes API
  calls for reads.
- The only IMAP→network calls are mutations: mark read/unread (`STORE \Seen`)
  and trash (`EXPUNGE`). Sending goes through SMTP → Tuta's `DraftService` +
  `SendDraftService`.

The storage encryption key is derived from your Tuta session, so there's no extra
password to manage; the cache is encrypted at rest.

## Build from source

Requires the Rust toolchain and the `tuta-repo` submodule
(`git clone --recursive`, or `git submodule update --init --recursive`).

```bash
cargo build                      # CLI + core
cargo build -p tutabridge-core   # core library only
cargo run                        # run the CLI from source
./dev.sh                         # GUI in dev mode (cargo tauri dev)
```

## Files & locations

Config and cache live under your platform's app-data directory — on macOS
`~/Library/Application Support/tutabridge/`:

```
config.toml          account + ports + bridge_password + sync_limit
store.db             SQLCipher metadata + full-text body index
mails/<id>.eml.enc   per-mail encrypted bodies
```

`sync_limit` controls how many recent message **bodies** are kept offline; the
full mailbox is always listed and metadata-searchable regardless. Set it to `0`
(or tick "keep every message body offline" in the GUI) to download everything.

## Backup

Export **every** email to a folder of plain `.eml` files — one file per message,
in a directory tree mirroring your IMAP folders. This is a *complete* backup: it
enumerates all mail from the server, not just the messages currently synced, so
nothing is silently left out.

```
<output>/
├── INBOX/
│   ├── 20260528-144935_OtjDuDU--3-9.eml
│   └── …
├── Sent/
├── Trash/
└── Café/Projets/…
```

CLI:

```bash
tutabridge backup ~/TutaBackup
```

GUI: the **Backup** tab — pick a folder, watch the per-folder progress, done.
(The bridge must be running; the backup reuses its signed-in session.)

Notes:

- **Format**: `.eml` (RFC 2822). Opens natively in Thunderbird / Apple Mail /
  Outlook, survives Windows filesystems, and one corrupt file never takes down
  the whole archive. Filenames are date-prefixed so a listing sorts
  chronologically.
- **Resumable / incremental**: re-running into the same folder skips messages
  already on disk, so an interrupted backup resumes and a periodic re-backup only
  fetches new mail.
- **Speed**: messages already in the local cache export instantly; the rest are
  fetched from the server with a small politeness delay, so a first full backup of
  a large mailbox can take several minutes. Subsequent runs are fast.
- **Scope**: every folder, including Trash and Spam. Labels aren't separate
  folders, so a labelled mail is backed up once, in its real folder.

## Testing

```bash
cargo test --workspace        # unit + integration tests

python3 scripts/test_imap.py  # integration test against a running bridge
```

The IMAP integration test connects to the local server and verifies TLS, auth,
folder list, mail count, body fetch and search. It reads the bridge password from
`config.toml` automatically.

## SDK

TutaBridge depends on a few additions to Tuta's Rust SDK, vendored as the
`tuta-repo` submodule. Each change is kept as its own single-commit branch off
upstream for easy review / upstreaming — see [`SDK_PRS.md`](SDK_PRS.md) for the
status of each.

## License

[GPL-3.0-or-later](LICENSE). TutaBridge links Tuta's Rust SDK (part of the
GPLv3-licensed [tutanota](https://github.com/tutao/tutanota) project), so it is
distributed under the same license.