# 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.*