README
¶
Proton Mail Bridge and Import Export app
Copyright (c) 2024 Proton AG
This repository holds the Proton Mail Bridge and the Proton Mail Import-Export applications. For a detailed build information see BUILDS. The license can be found in LICENSE file, for more licensing information see COPYING_NOTES. For contribution policy see CONTRIBUTING.
Description Bridge
Proton Mail Bridge for e-mail clients.
When launched, Bridge will initialize local IMAP/SMTP servers and render its GUI.
To configure an e-mail client, firstly log in using your Proton Mail credentials. Open your e-mail client and add a new account using the settings which are located in the Bridge GUI. The client will only be able to sync with your Proton Mail account when the Bridge is running, thus the option to start Bridge on startup is enabled by default.
When the main window is closed, Bridge will continue to run in the background.
More details on the public website.
Launchers
Launchers are binaries used to run the Proton Mail Bridge or Import-Export apps.
Official distributions of the Proton Mail Bridge and Import-Export apps contain both a launcher and the app itself. The launcher is installed in a protected area of the system (i.e. an area accessible only with admin privileges) and is used to run the app. The launcher ensures that nobody tampered with the app's files by verifying their signature using a hardcoded public key. App files are placed in regular userspace and are signed by Proton's private key. This feature enables the app to securely update itself automatically without asking the user for a password.
Keychain
You need to have a keychain in order to run the Proton Mail Bridge. On Mac or
Windows, Bridge uses native credential managers. On Linux, use secret-service freedesktop.org API
(e.g. Gnome keyring)
or
pass. We are working on allowing other secret
services (e.g. KeepassXC), but for now only gnome-keyring is usable without
major problems.
Environment Variables
Dev build or run
APP_VERSION: set the bridge app version used during testing or buildingPROTONMAIL_ENV: when set todevit is not using Sentry to report crashesVERBOSITY: set log level used during test time and by the makefile
Integration testing
TEST_ENV: set which env to use (fake or live)TEST_ACCOUNTS: set JSON file with configured accountsTAGS: set build tags for testsFEATURES: set feature dir, file or scenario to test
Folders
There are now three types of system folders which Bridge recognises:
| Windows | Mac | Linux | Linux (XDG) | |
|---|---|---|---|---|
| config | %APPDATA%\protonmail\bridge-v3 | ~/Library/Application Support/protonmail/bridge-v3 | ~/.config/protonmail/bridge-v3 | $XDG_CONFIG_HOME/protonmail/bridge-v3 |
| cache | %LOCALAPPDATA%\protonmail\bridge-v3 | ~/Library/Caches/protonmail/bridge-v3 | ~/.cache/protonmail/bridge-v3 | $XDG_CACHE_HOME/protonmail/bridge-v3 |
| data | %APPDATA%\protonmail\bridge-v3 | ~/Library/Application Support/protonmail/bridge-v3 | ~/.local/share/protonmail/bridge-v3 | $XDG_DATA_HOME/protonmail/bridge-v3 |
| temp | %LOCALAPPDATA%\Temp | $TMPDIR if non-empty, else /tmp | $TMPDIR if non-empty, else /tmp | $TMPDIR if non-empty, else /tmp |
Files
| Base Dir | Path | |
|---|---|---|
| bridge lock file | cache | bridge.lock |
| bridge-gui lock file | cache | bridge-gui.lock |
| vault | config | vault.enc |
| gRPC server json | config | grpcServerConfig.json |
| gRPC client json | config | grpcClientConfig_.json |
| gRPC Focus server json | config | grpcFocusServerConfig.json |
| Logs | data | logs |
| gluon DB | data | gluon/backend/db |
| gluon messages | data | gluon/backend/store |
| Update files | data | updates |
| sentry cache | data | sentry_cache |
| Mac/Linux File Socket | temp | bridge{4_DIGITS} |
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
bridge
Package bridge implements the Bridge, which acts as the backend to the UI.
|
Package bridge implements the Bridge, which acts as the backend to the UI. |
|
bridge/mocks
Package mocks is a generated GoMock package.
|
Package mocks is a generated GoMock package. |
|
constants
Package constants contains variables that are set via ldflags during build.
|
Package constants contains variables that are set via ldflags during build. |
|
cookies
Package cookies implements a persistent cookie jar which satisfies the http.CookieJar interface.
|
Package cookies implements a persistent cookie jar which satisfies the http.CookieJar interface. |
|
crash
Package crash implements a crash handler with configurable recovery actions.
|
Package crash implements a crash handler with configurable recovery actions. |
|
events/mocks
Package mocks is a generated GoMock package.
|
Package mocks is a generated GoMock package. |
|
focus
Package focus provides a gRPC service for raising the application.
|
Package focus provides a gRPC service for raising the application. |
|
focus/proto
Package proto provides the gRPC definition of the focus service.
|
Package proto provides the gRPC definition of the focus service. |
|
frontend/cli
Package cli provides CLI interface of the Bridge.
|
Package cli provides CLI interface of the Bridge. |
|
legacy/credentials
Package credentials implements our struct stored in keychain.
|
Package credentials implements our struct stored in keychain. |
|
locations
Package locations implements a type that provides cross-platform access to standard filesystem locations, including config, cache and log directories.
|
Package locations implements a type that provides cross-platform access to standard filesystem locations, including config, cache and log directories. |
|
services/imapservice/mocks
Package mocks is a generated GoMock package.
|
Package mocks is a generated GoMock package. |
|
services/userevents/mocks
Package mocks is a generated GoMock package.
|
Package mocks is a generated GoMock package. |
|
services/useridentity/mocks
Package mocks is a generated GoMock package.
|
Package mocks is a generated GoMock package. |
|
telemetry/mocks
Package mocks is a generated GoMock package.
|
Package mocks is a generated GoMock package. |
|
updater/mocks
Package mocks is a generated GoMock package.
|
Package mocks is a generated GoMock package. |
|
pkg
|
|
|
algo
Package algo provides some algorithm utils.
|
Package algo provides some algorithm utils. |
|
files
Package files provides standard filesystem operations.
|
Package files provides standard filesystem operations. |
|
keychain
Package keychain implements a native secure password store for each platform.
|
Package keychain implements a native secure password store for each platform. |
|
message
Package message contains set of tools to convert message between Proton API and IMAP format.
|
Package message contains set of tools to convert message between Proton API and IMAP format. |
|
port-blocker
port-blocker is a command-line that ensure a port or range of ports is occupied by creating listeners.
|
port-blocker is a command-line that ensure a port or range of ports is occupied by creating listeners. |