MailDigest 0.3.1

Install

# Debian 13+, Kali, Ubuntu 26.04+
curl -fsSL https://kpafi.github.io/maildigest/apt/maildigest-archive-keyring.gpg | sudo tee /usr/share/keyrings/maildigest-archive-keyring.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/maildigest-archive-keyring.gpg] https://kpafi.github.io/maildigest/apt stable main" | sudo tee /etc/apt/sources.list.d/maildigest.list
sudo apt update && sudo apt install maildigest

# Fedora 43+
sudo dnf copr enable kpafi/maildigest && sudo dnf install maildigest

# anything else
pipx install maildigest

# Docker (amd64 and arm64)
docker pull ghcr.io/kpafi/maildigest:0.3.1

The attached .deb is the same package the repository serves; the wheel and
sdist are for pip and pipx.

Changes in 0.3.1

Added

• Docker image ghcr.io/kpafi/maildigest for amd64 and arm64, built by the release
  workflow from the same commit as the packages (edge from main on every push). It
  runs as an unprivileged user, holds no configuration and no secret, and the
  docker-compose.yml in the repository applies the hardening of the systemd unit:
  read-only root filesystem, no capabilities, no-new-privileges, 120 s stop grace for
  a clean end of the running cycle. docs/OPERATIONS.md section 7 describes the setup.
• The README opens with a picture of what arrives on the phone: a summarised mail, a
  phishing warning and the daily low-priority digest.

MailDigest 0.3.0

Install

# Debian 13+, Kali, Ubuntu 26.04+
curl -fsSL https://kpafi.github.io/maildigest/apt/maildigest-archive-keyring.gpg | sudo tee /usr/share/keyrings/maildigest-archive-keyring.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/maildigest-archive-keyring.gpg] https://kpafi.github.io/maildigest/apt stable main" | sudo tee /etc/apt/sources.list.d/maildigest.list
sudo apt update && sudo apt install maildigest

# Fedora 43+
sudo dnf copr enable kpafi/maildigest && sudo dnf install maildigest

# anything else
pipx install maildigest

The attached .deb is the same package the repository serves; the wheel and
sdist are for pip and pipx.

Changes in 0.3.0

Added

• PyPI: every release now also lands on PyPI through trusted publishing, so
  pipx install maildigest works everywhere the distribution packages do not reach. The
  package metadata carries keywords and classifiers for the first time, and the project
  page at kpafi.github.io/maildigest is a landing page with an example digest and the
  security model instead of a bare list of package repositories.
• A self-hosted mirror mailbox: maildigest selfhost-mail --domain mirror.example.org
  (F-ING-4, ADR-089). For people who run MailDigest on a server of their own and would
  rather host the mirror mailbox there than rent one. The command generates and checks,
  it never installs: it writes the Postfix settings, the Dovecot drop-in, the DNS
  records, an apply script and a checklist into selfhost-mail/, and the person runs the
  few privileged steps themselves with their own sudo. MailDigest keeps needing no
  privileges, and it writes no secret — apply.sh asks for the mailbox password once and
  stores only its BLF-CRYPT hash.
• maildigest selfhost-mail --check verifies the finished setup over the network and
  reads no system file: DNS A/AAAA and MX, the SMTP banner, a refused open-relay attempt,
  the mirror address being accepted, the IMAPS certificate (with a warning below 14 days
  left), the IMAPS login through MailDigest's own client, and that cleartext IMAP on 143
  is closed. With --wait-for-mail it additionally waits for a real forwarded mail and
  prints its sender and subject — that, and nothing before it, is the proof that the
  internet can deliver. Every failing line carries the one sentence that says what to do.
• The MX check needs dnspython, which stays optional: without it the line reads
  skipped and the run continues. The distribution packages list Postfix, Dovecot,
  certbot and dnspython under Suggests/weak dependencies only — MailDigest itself needs
  none of them.
• Two hard requirements, said plainly in the checklist and in the documentation: a domain
  of your own (a subdomain is demanded unless --allow-apex is given) and port 25
  reachable from the internet, which rules out nearly every home connection. Supported are
  Debian 13 and newer and Fedora 43 and newer, the same reach as the packages, because the
  generated Dovecot configuration uses the 2.4 syntax.
• The step by step, what apply.sh changes and how to undo each change, certificate
  renewal, rotating the address and every limit in plain words:
  docs/OPERATIONS.md §6. The contract is
  docs/SPEC-CLI.md §4, the reasoning
  docs/PLAN-SELFHOST-MAIL.md.
• The generated files are not guesses: the seven steps of the plan were run by hand in a
  Debian 13 VM and are run in CI on debian:trixie, applying the configuration for real,
  delivering a mail and letting --check pass — plus a negative case that reopens port 143
  and must fail. That round corrected three defects that would have broken the feature on
  every Debian 13 machine (an unreadable /etc/dovecot/users, Debian's own
  auth_username_format in protocol lmtp throwing the domain away, and a reload that
  reports success over a configuration Dovecot never read).
• A white-box and a black-box review round followed, and the feature came back changed
  where they were right. What is different from the first build: state.json is treated
  as foreign text — the mirror address is validated in full instead of only at both ends,
  and every line derived from it passes the character allowlist, so a hand-edited state
  file can no longer smuggle an SMTP command, an IMAP command or an escape sequence
  anywhere. No check can raise any more; whatever a counterpart does, the line is printed
  and the command ends with an exit code instead of a traceback, and so does Ctrl-D at
  the mailbox-password prompt. The generated files are written with O_NOFOLLOW, and an
  existing non-empty --out directory is refused instead of adopted and re-permissioned.
  The printed steps and the checklist name the files that were really written, repeat
  --out DIR where it was given, quote paths that a shell would read differently, and
  offer the dnf line next to the apt one. apply.sh now restarts Postfix, because
  postfix.sh sets inet_interfaces and a reload would have left a "Local only"
  installation listening on loopback with every check still green. And
  message_size_limit follows [limits] max_mail_bytes instead of a hard-coded 25 MiB,
  so a mail that is too large bounces to the forwarder rather than vanishing later.

Repository

• OpenSSF Scorecard runs on every push to main and weekly
  (.github/workflows/scorecard.yml); the score is public at
  scorecard.dev, the findings land under Security → Code scanning. Preparing for it:
  every GitHub Action is pinned to a commit hash, every workflow token is read-only
  except in the two release jobs that publish, and Dependabot keeps the pins and the
  Python dependencies current with one grouped pull request a week.
• CONTRIBUTING.md, a bug-report issue form in the finding format of docs/TESTING.md
  §3, and docs/SECURITY.md §8 on how to report a vulnerability privately.

Changed

• README shortened by a quarter and reordered. Installation and quickstart now come
  right after the security model; the provider table, the app-password note and the
  alternative install routes are collapsed sections; the max_tokens and "why no key"
  explanations moved into the FAQ. Badges for CI, release and licence at the top. Nothing
  was dropped that the program does not also explain itself.

• PLAN.md moved to docs/PLAN.md, so the repository root holds only README,
  changelog, licence and pyproject.toml; references in code, tests and README follow.
  docs/README-ENTWURF.md, the superseded draft of the mirror-mailbox section that
  connect-mail now prints itself, is deleted.

Fixed

• The container probe of selfhost-mail failed on the CI runner with "nothing listens
  on 993": it started Postfix and Dovecot side by side, and Dovecot binds its LMTP socket
  below /var/spool/postfix/private, a directory Postfix creates only on its first start.
  The probe now waits for Postfix before starting Dovecot. Under systemd the race never
  showed, which is why the VM runs were green; a systemd-free run in the VM reproduced the
  failure and confirms the fix. The probe's "last log lines" on failure were also lost to
  a redirection in the wrong order and now appear.
• The package page on GitHub Pages claimed Ubuntu 24.04 and newer; it is 26.04 and newer,
  as the README, the changelog and the package dependencies say. Template and live page
  corrected.
• pyproject.toml spelt "summarizes" where every other description says "summarises".

MailDigest 0.2.1

Full Changelog: v0.2.0...v0.2.1

Install

# Debian 13+, Kali, Ubuntu 26.04+
curl -fsSL https://kpafi.github.io/maildigest/apt/maildigest-archive-keyring.gpg | sudo tee /usr/share/keyrings/maildigest-archive-keyring.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/maildigest-archive-keyring.gpg] https://kpafi.github.io/maildigest/apt stable main" | sudo tee /etc/apt/sources.list.d/maildigest.list
sudo apt update && sudo apt install maildigest

# Fedora 43+
sudo dnf copr enable kpafi/maildigest && sudo dnf install maildigest

# anything else
pipx install git+https://github.com/kpafi/maildigest

The attached .deb is the same package the repository serves; the wheel and
sdist are for pip and pipx.

Changes in 0.2.1

Distribution

• Our own signed apt repository (ADR-088): MailDigest installs and, more to the point,
  updates through apt on Debian 13 and newer, Kali Rolling and Ubuntu 26.04
  LTS and newer. The repository
  lives on GitHub Pages, the packages are signed with a key used for nothing else, and
  signed-by binds that key to this one repository. The installation section of the README
  has the two commands. pipx stays the way on every other system.
• Package users get the manual page under /usr/share/man/man1 — man maildigest works
  without the copy step the README describes for the pipx route.
• The release runs itself off the git tag (.github/workflows/release.yml): it builds
  sdist, wheel and .deb, installs the package in Debian and Kali containers and runs it
  there, and only then signs and publishes. A failing step stops the run before anything is
  published, and the version is checked against pyproject.toml, __version__ and the
  manual page first. The plan behind it is docs/PLAN-PACKAGING.md.
• Fedora through dnf — built for Fedora 43, 44 and 45 (x86_64) and Rawhide, from a
  COPR project (kpafi/maildigest) that the release triggers by webhook. imap-tools is missing from Fedora and is built as a second package
  in the same project. Unlike dh_python3 on the Debian side, the Fedora macros carry the
  lower bounds over from pyproject.toml by themselves.
• Ubuntu 25.04 and older are not covered — 24.04 LTS carries
  pydantic 1.10 where the code needs pydantic 2, and 25.04 dropped python3-imap-tools;
  the dependencies in the package say so, so apt refuses the installation there instead of
  creating one that cannot start.

Fixed

v0.2,0

Erstes öffentliches Release. Seit 0.1.0 ist MailDigest erstmals gegen echte Gegenstellen gelaufen (ein Spiegelpostfach bei web.de, ein Modell über OpenRouter, ein Telegram-Bot) und hat zwei dokumentierte Prüfrunden durchlaufen (docs/TESTRUNDE-HOT-COLD.md und docs/TESTRUNDE-2.md, Abnahme in docs/ABNAHME-FIXRUNDE.md). Was offen blieb, steht in docs/TESTING.md §7 und unten unter „Bekannte Grenzen".

Funktionen:
Betrieb ohne Sprachmodell als Standard ([llm] provider = "none", ADR-076): MailDigest läuft ohne Anmeldung bei irgendeinem Anbieter und stellt einen beschrifteten Auszug samt aller deterministischen Warnungen zu. connect-llm bietet die Betriebsarten als Auswahlliste an, darunter drei Anbieter mit Gratis-Kontingent und die lokale Variante.

Fernauslösung per Telegram (ADR-077, Vorgabe geändert durch ADR-078): maildigest run reagiert auf /digest (sofortiger Abruf) und /status (Kurzbericht) — nur auf diese beiden Wörter und nur aus dem konfigurierten Chat. Jeder andere Text wird verworfen und erreicht nie ein Sprachmodell. Schalter [messenger.telegram] accept_commands, seit ADR-078 ab Werk an; für Gruppen-Chats auf false setzen.

Anbieter-Wissensbasis für die Einrichtung (ADR-075): connect-mail erklärt den Begriff IMAP-Host, übersetzt eine eingetippte Mailadresse in den Host und bricht bei Anbietern ohne Passwort-Anmeldung (Outlook.com, Proton) sofort mit Begründung ab.
maildigest instructions (ADR-086): zeigt die Custom-Instructions für den Summarizer oder ändert sie mit --set, --add, --edit (im $VISUAL/$EDITOR) und --clear — ohne die Stelle in der Konfigurationsdatei zu suchen. Mehrzeilig, bis 2000 Zeichen; Steuerzeichen werden abgewiesen. Der Kritiker sieht den Text weiterhin nie.

Hilfe und Handbuch (ADR-087): maildigest --help erklärt jedes Kommando mit Beschreibung und Beispielen, maildigest --help den typischen Ablauf. maildigest --man gibt eine Handbuchseite im troff-Format aus (| man -l -); man/maildigest.1 ist daraus erzeugt, ein Test hält sie mit dem Parser synchron.