From c3455aee90323956cc2cb37f9e46aba69d0349fc Mon Sep 17 00:00:00 2001 From: "Bernd (Hermes)" Date: Tue, 5 May 2026 21:47:53 +0200 Subject: [PATCH] =?UTF-8?q?init:=20Hermes=20ProtonMail=20Plugin=20?= =?UTF-8?q?=E2=80=94=20structure,=20README,=20plan,=20LICENSE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- IMPLEMENTATION_PLAN.md | 96 ++++++++++++++++++++++++++++++++++ LICENSE | 24 +++++++++ README.md | 114 +++++++++++++++++++++++++++++++++++++++++ lib/__init__.py | 9 ++++ plugin.yaml | 48 +++++++++++++++++ 5 files changed, 291 insertions(+) create mode 100644 IMPLEMENTATION_PLAN.md create mode 100644 LICENSE create mode 100644 README.md create mode 100644 lib/__init__.py create mode 100644 plugin.yaml diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md new file mode 100644 index 0000000..eecc562 --- /dev/null +++ b/IMPLEMENTATION_PLAN.md @@ -0,0 +1,96 @@ +# Hermes ProtonMail Plugin — Implementierungsplan + +**Ziel:** Ein natives Hermes-Plugin für ProtonMail — direkte REST/gPRC API, kein Bridge, kein GUI. Headless auf Debian VPS. End-to-End-Verschlüsselung in Python, vollständig in Hermes integriert. + +**Zeithorizont:** Langfristig, iterativ. Keine Eile, aber saubere Fundamente. + +--- + +## Architektur + +``` +┌─────────────────────────────────────────┐ +│ Hermes Gateway (Agent Core) │ +│ └── Platform Adapter: ProtonMail │ +│ ├── Auth Manager (SRP-6a) │ +│ ├── Crypto Engine (OpenPGP) │ +│ ├── Sync Engine (Mail-Sync) │ +│ └── Notifier (Push → Hermes) │ +└─────────────────────────────────────────┘ + │ + ▼ HTTPS +┌─────────────────────────────────────────┐ +│ ProtonMail API (mail.proton.me) │ +│ ├── REST: Auth, Messages, Labels │ +│ ├── gRPC: Events (neue Mail-Push) │ +│ └── Key Server: Public Key Discovery │ +└─────────────────────────────────────────┘ +``` + +--- + +## Phase 1: Auth POC — "Kann ich mich anmelden?" + +1. **Setup** — `python3-venv`, dependencies (`bcrypt`, `python-gnupg`, `requests`) +2. **SRP-Auth** — `proton-python-client` oder `proton-srp`, Login mit Credentials +3. **Erste API-Calls** — `GET /core/v4/users`, `GET /mail/v4/messages` + +**Erfolg:** Script auf VPS meldet sich an, API antwortet. + +--- + +## Phase 2: Crypto — "Kann ich lesen?" + +1. **Private Key Export** — Via Web/Bridge einmalig exportieren +2. **PGPy Integration** — Key laden, mit Passphrase entsperren +3. **Entschlüsselung** — Mail-Body + Attachments testen + +**Erfolg:** Verschlüsselte Mail wird lesbar entschlüsselt. + +--- + +## Phase 3: Sync Engine — "Wie Gmail-API, aber für Proton" + +1. **SQLite-Index** — Schema: `conversations`, `messages`, `attachments`, `labels` +2. **Message Sync** — Inkrementell mit `last_sync_time` +3. **Composer** — Draft erstellen, verschlüsseln, senden via `POST /mail/v4/messages` +4. **Push/Poll** — gRPC Events oder intelligentes Polling (2-Min-Intervall) + +**Erfolg:** Hermes kann Mails lesen und schreiben. + +--- + +## Phase 4: Hermes Plugin — "Der Agent sieht Proton" + +1. **Plugin-Struktur** — `plugin.yaml`, `__init__.py`, `adapter.py` +2. **Gateway-Integration** — `BasePlatformAdapter` implementieren +3. **Daemon/Cron** — `systemd --user` Service + Hermes-interner Cronjob + +**Erfolg:** ProtonMail erscheint als aktive Plattform in Hermes. + +--- + +## Phase 5: Produktion — "Läuft monatelang" + +1. **Resilienz** — Token-Refresh, Retry, Backoff +2. **State Management** — Persistent in `~/.local/share/hermes-proton/` +3. **Security** — Private Key nur im RAM, Memory-Clear +4. **Logging** — JSON nach `~/.hermes/logs/proton.log` + +**Erfolg:** 30 Tage Dauerbetrieb ohne manuellen Eingriff. + +--- + +## Risiken + +| Risiko | Mitigation | +|--------|------------| +| Proton ändert API | Version-Pinning der Client-Lib | +| PGPy unterstützt Key-Format nicht | Fallback auf `python-gnupg` + `gpg` | +| Rate-Limits | Backoff, Batching, Business-Tarif | +| Kein gRPC Events | Polling-Fallback (Rocket.Chat-Muster) | +| 2FA TOTP headless | Einmal-Setup, RefreshToken ist langlebig | + +--- + +*Plan erstellt am 2026-05-05. Nächste Aktualisierung nach Abschluss Phase 1.* diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..fdddb29 --- /dev/null +++ b/LICENSE @@ -0,0 +1,24 @@ +This is free and unencumbered software released into the public domain. + +Anyone is free to copy, modify, publish, use, compile, sell, or +distribute this software, either in source code form or as a compiled +binary, for any purpose, commercial or non-commercial, and by any +means. + +In jurisdictions that recognize copyright laws, the author or authors +of this software dedicate any and all copyright interest in the +software to the public domain. We make this dedication for the benefit +of the public at large and to the detriment of our heirs and +successors. We intend this dedication to be an overt act of +relinquishment in perpetuity of all present and future rights to this +software under copyright law. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR +OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. + +For more information, please refer to diff --git a/README.md b/README.md new file mode 100644 index 0000000..e2aca4b --- /dev/null +++ b/README.md @@ -0,0 +1,114 @@ +# Hermes ProtonMail Plugin + +> Nützliches Add-on für [Hermes Agent](https://hermes-agent.nousresearch.com/) +> um ProtonMail als E-Mail-Plattform zu nutzen — direkt über die Proton REST API, ohne Bridge, ohne GUI, Headless. + +Stellt einen nativen Mail-Client für das Hermes Agent Gateway bereit — mit end-to-end-verschlüsseltem Senden & Empfangen, lokalem Mail-Index und Event-gesteuertem Sync. + +--- + +## Warum dieses Plugin? + +| Anforderung | Lösung | +|-------------|--------| +| 🔐 End-to-End-Verschlüsselung | OpenPGP in Python (PGPy / python-gnupg) | +| 🖥️ Headless-Betrieb auf VPS | Keine GUI, kein WireGuard, keine Bridge | +| 🚀 Echtzeit-Push | gRPC Events oder intelligentes Polling | +| 📦 Mail-Sync | Lokaler SQLite-Index mit inkrementellem Sync | +| ✍️ Mail verfassen | Verschlüsselter Versand via Proton API | + +--- + +## Status + +| Phase | Fortschritt | Beschreibung | +|-------|-------------|--------------| +| 1 — Auth POC | 🔲 | SRP-6a Login + API-Zugriff | +| 2 — Crypto POC | 🔲 | OpenPGP Entschlüsselung + Attachment-Handling | +| 3 — Sync Engine | 🔲 | SQLite-Index + Senden/Empfangen | +| 4 — Hermes Plugin | 🔲 | Gateway-Integration + Daemon | +| 5 — Produktion | 🔲 | Resilienz + Tests + Monitoring | + +> **Aktuell:** Phase 1 — Implementierungsplan steht, Setup-Phase läuft. + +--- + +## Schnellstart (später) + +> Hinweis: Dieses Plugin befindet sich noch in der Entwicklung. +> Die ersten Releases erscheinen nach Abschluss der Phase 3 (Sync Engine). + +```bash +# (Später verfügbar) +git clone https://gitea.thomander.de/andreas/Hermes_ProtonMail_Plugin.git +cd Hermes_ProtonMail_Plugin +./install.sh +``` + +--- + +## Features (geplant) + +| Feature | Beschreibung | +|---------|-------------| +| 🔐 SRP-6a Auth | Sicheres Login ohne Passwort-Übertragung | +| 🔑 OpenPGP Crypto | End-to-End Entschlüsselung im Agent | +| 📨 Mail-Sync | Lokaler SQLite-Index mit Konversationen | +| 📤 Mail senden | Automatisch verschlüsselter Versand | +| 📎 Attachments | Verschlüsselte Anhänge senden & empfangen | +| 🔔 Push / Poll | Echtzeit-Benachrichtigung oder intelligentes Polling | +| 🏷️ Labels & Ordner | Proton-Labels synchronisieren | +| 👥 Kontakte | Public-Key-Discovery für Empfänger | + +--- + +## Architektur + +``` +┌─────────────────────────────────────────┐ +│ Hermes Gateway (Agent Core) │ +│ └── Platform Adapter: ProtonMail │ +│ ├── Auth Manager (SRP-6a) │ +│ ├── Crypto Engine (OpenPGP) │ +│ ├── Sync Engine (SQLite) │ +│ └── Notifier (Push → Hermes) │ +└─────────────────────────────────────────┘ + │ + ▼ HTTPS +┌─────────────────────────────────────────┐ +│ ProtonMail API (mail.proton.me) │ +│ ├── REST: Auth, Messages, Labels │ +│ ├── gRPC: Events (neue Mail-Push) │ +│ └── Key Server: Public Key Discovery │ +└─────────────────────────────────────────┘ +``` + +--- + +## Was ist im Paket? + +``` +Hermes_ProtonMail_Plugin/ +├── README.md ← Diese Datei +├── IMPLEMENTATION_PLAN.md ← 5-Phasen Entwicklungsplan +├── plugin.yaml ← Plugin-Metadaten +├── install.sh ← Interaktives Setup (später) +├── lib/ +│ ├── __init__.py +│ ├── auth.py ← SRP + Token Management +│ ├── crypto.py ← PGP Wrapper +│ ├── api.py ← HTTP Client +│ ├── sync.py ← SQLite Sync Engine +│ └── models.py ← Dataclasses +├── scripts/ +│ └── proton_daemon.py ← Long-running Sync + Push +├── tests/ +│ └── ... ← Unit + Integration Tests +└── LICENSE ← Unlicense (Public Domain) +``` + +--- + +## Lizenz + +[Unlicense](LICENSE) — Public Domain diff --git a/lib/__init__.py b/lib/__init__.py new file mode 100644 index 0000000..0ce4454 --- /dev/null +++ b/lib/__init__.py @@ -0,0 +1,9 @@ +""" +Hermes ProtonMail Plugin +======================== +Native Hermes platform adapter for ProtonMail via REST API. +Headless · End-to-end encrypted · Zero GUI dependencies. +""" + +__version__ = "0.0.1" +__author__ = "Andreas Thomander" diff --git a/plugin.yaml b/plugin.yaml new file mode 100644 index 0000000..9b6560b --- /dev/null +++ b/plugin.yaml @@ -0,0 +1,48 @@ +name: hermes-protonmail +version: 0.0.1 + +description: > + Hermes Platform Plugin for ProtonMail. + End-to-end encrypted email via Proton REST API — no Bridge, no GUI, headless. + +author: Andreas Thomander +platform: protonmail + +dependencies: + python_packages: + - requests + - bcrypt + - python-gnupg + - pgpy + - srp + system_packages: + - python3 + - python3-pip + - python3-venv + +entrypoint: + module: lib.adapter + class: ProtonMailAdapter + +configuration: + env_prefix: PROTON_ + required: + - username + - password + optional: + - twofa_secret + - refresh_token_path + - data_dir + - polling_interval + - rate_limit_max + - gpg_binary + +files: + - lib/__init__.py + - lib/adapter.py + - lib/auth.py + - lib/crypto.py + - lib/api.py + - lib/sync.py + - lib/models.py + - scripts/proton_daemon.py