init: Hermes ProtonMail Plugin — structure, README, plan, LICENSE
This commit is contained in:
Bernd (Hermes)
@@ -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.*
|
||||||
@@ -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 <https://unlicense.org>
|
||||||
@@ -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
|
||||||
@@ -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"
|
||||||
+48
@@ -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
|
||||||
Reference in New Issue
Block a user