init: Hermes ProtonMail Plugin — structure, README, plan, LICENSE

2026-05-05 21:47:53 +02:00
commit c3455aee90
5 changed files with 291 additions and 0 deletions
@@ -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.*