λgitsite

~ober/jerboa-protonmail

Imported from ~/mine/jerboa-protonmail

download snapshot

about

# jerboa-protonmail

Read-only Proton Mail access experiments in Jerboa.

The stable first target is a local IMAP client for Proton Mail Bridge. Bridge
handles Proton authentication, key management, and local decryption; this tool
will initially list folders, list messages, fetch raw messages, decode common
email formats, and export `.eml` files without mutating mailbox state.

The native direct-Proton track is documented in `plan.md`, but it is not the
first implementation path.

## Current Status

Phase 7 is in progress:

- CLI entry point.
- Environment config helper.
- Bridge IMAP connectivity probe.
- Structured IMAP response parser.
- Folder listing.
- Header-only message listing.
- Raw message fetch.
- `.eml` export.
- Decoded `show` output through `jerboa-mail`.
- Search by from, subject, and since.
- Config validation and opt-in integration checks.
- Smoke tests.
- Makefile.
- Project plan.

Live Proton Bridge checks are attempted only when Bridge credentials are set.

## Development

```sh
make run ARGS='--help'
make doctor
make test
make release-evidence
make integration-test
bin/protonmail-read doctor
```

By default the Makefile uses `../jerboa/dist/jerbuild`, a local
`.jerboa/bin/jerbuild`, or a `jerbuild` on `PATH`. If no toolchain exists,
`make test` fetches the pinned Jerboa release into `.jerboa/bin`.
Override with:

```sh
make JERBUILD=/path/to/jerbuild test
```

The Bridge transport uses `../jerboa-ssl` by default. Override with:

```sh
make JERBOA_SSL_DIR=/path/to/jerboa-ssl test
```

Email parsing uses `../jerboa-mail` by default. Override with:

```sh
make JERBOA_MAIL_DIR=/path/to/jerboa-mail test
```

## Bridge Configuration

Later phases will read Bridge IMAP settings from environment variables:

```sh
export PROTON_BRIDGE_HOST=127.0.0.1
export PROTON_BRIDGE_PORT=1143
export PROTON_BRIDGE_USER='bridge-generated-user'
export PROTON_BRIDGE_PASSWORD='bridge-generated-password'
export PROTON_BRIDGE_TLS=loopback-plain
```

Use Bridge-generated IMAP credentials, not your Proton account password.
The default transport is `tls` and certificate or handshake failures are fatal.
Because the common Bridge listener on port 1143 is plaintext, it requires the
explicit mode `loopback-plain`; that mode accepts only literal `127.0.0.1` or
`::1`. There is no opportunistic plaintext fallback and DNS names are rejected
for plaintext.

## Commands

```sh
bin/protonmail-read doctor
bin/protonmail-read folders
bin/protonmail-read list --folder INBOX --limit 20
bin/protonmail-read show --folder INBOX --uid 123
bin/protonmail-read raw --folder INBOX --uid 123 > message.eml
bin/protonmail-read export-eml --folder INBOX --uid 123 --output message.eml
bin/protonmail-read search --folder INBOX --from person@example.com
bin/protonmail-read search --folder INBOX --subject invoice
bin/protonmail-read search --folder INBOX --since 2026-01-01
```

## Safety

The implemented IMAP fetches use `BODY.PEEK[...]` so reads should not mark
messages as read. The tool does not issue `STORE`, `EXPUNGE`, `COPY`, `MOVE`,
`APPEND`, `CREATE`, or `DELETE`.

Exported `.eml` files contain plaintext mail after Bridge has decrypted it
locally. `export-eml` refuses existing destinations, symlinks, and untrusted
group/world-writable parent directories; it creates a verified `0600` file and
publishes complete content atomically. Treat exports as sensitive.

Normal folder, summary, header, body, greeting, and error output filters ANSI,
OSC, C0/C1, DEL, and bidirectional terminal controls. `raw` is intentionally
unfiltered for exact RFC 5322 output and refuses a terminal unless the user
passes `--unsafe-terminal`; piping it is preferred.

IMAP input is bounded before allocation: 16 KiB per line, 32 MiB per message
literal, 64 MiB per command response, 4096 response entries, 64 literals, and a
60-second total response deadline in addition to socket idle timeouts.

Credential and plaintext-mail handling are documented in
[`docs/credential-handling.md`](docs/credential-handling.md). Dependency
provenance is documented in
[`docs/dependency-provenance.md`](docs/dependency-provenance.md), and local
release evidence is documented in
[`docs/release-evidence.md`](docs/release-evidence.md). Production release
requires `make release-evidence` plus live Bridge credential and plaintext
export review.

recent commits