From 17502c829cabd571e1957228c4d540ae95393599 Mon Sep 17 00:00:00 2001 From: Anthony Date: Mon, 1 Jun 2026 14:44:13 +0200 Subject: [PATCH] README: end-user install + getting-started Add a download-and-run path for non-developers: per-OS install from the Releases page (desktop app vs CLI binary, with the Gatekeeper / SmartScreen one-time override each needs), a step-by-step getting-started with the IMAP/SMTP connection table and Thunderbird / Apple Mail notes, and an unofficial-&-unsigned disclaimer up top. Reframe the old cargo-centric sections as 'Build from source', and document that body search covers downloaded messages while metadata search covers the whole mailbox. --- README.md | 141 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 110 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index bc465e4..7044c2d 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,12 @@ 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. @@ -22,6 +28,96 @@ Available as a **CLI** and a **desktop GUI** (Tauri). 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 @@ -43,50 +139,33 @@ Tuta API ←── Syncer (background) ──→ MailStore (in-memory) ← 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 +## 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) ``` -GUI (Tauri + React) in dev mode: +## Files & locations -```bash -./dev.sh # cargo tauri dev — opens the desktop app -``` - -## Running the bridge - -CLI: - -```bash -cargo run # or: ./target/debug/tutabridge -``` - -On first run it prompts for your Tuta email; the session is then stored in the OS -keychain so later launches resume without a password (TOTP is prompted when -required). The bridge prints the local connection details: - -``` -IMAP server: 127.0.0.1:1143 (SSL/TLS) -SMTP server: 127.0.0.1:1025 (SSL/TLS) -Username: -Password: -``` - -Point your mail client at those, accept the self-signed certificate, and use the -**bridge password** (not your Tuta password) for IMAP/SMTP auth. - -Config and cache live under -`~/Library/Application Support/tutabridge/` (macOS): +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 index +store.db SQLCipher metadata + full-text body index mails/.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,