From 44e75a77fa2f13cacee9bbfe47c3a6486a74a49c Mon Sep 17 00:00:00 2001 From: Vigilio Desto Date: Mon, 8 Jun 2026 18:19:01 +0200 Subject: [PATCH] =?UTF-8?q?Seed:=20hermes-proton=20prototype=20=E2=80=94?= =?UTF-8?q?=20research,=20architecture,=20and=20project=20scaffold?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 191 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 191 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..5139052 --- /dev/null +++ b/README.md @@ -0,0 +1,191 @@ +# hermes-proton + +> Hermes Agent runtime + Proton product suite integration — skills, plugins, and MCP tools for Proton Mail, Drive, Pass, VPN, Calendar. + +## Project Seed + +This is a prototype project exploring how to integrate the **Hermes Agent runtime** (nousresearch/hermes) with **Proton's product suite** (Mail, Drive, Pass, VPN, Calendar, Wallet) to give agents native access to Proton services. + +**Goal:** Enable any Hermes-based agent to read/send email, manage passwords, store/retrieve files, and control VPN — all through the agent's natural tool-use interface. + +--- + +## Research Summary + +### Key Finding: Proton Has No Public REST API + +Proton does **not** publish a public developer API. All APIs are internal — used by Proton's own clients (web, desktop, mobile, Bridge). The API surface has been reverse-engineered from open-source clients. Authentication uses **SRP-6a** (not OAuth2), and all products share the same session via `login.proton.me`. + +### Available Official Libraries + +| Library | Lang | Purpose | Status | +|---------|------|---------|--------| +| `go-proton-api` | Go | REST client (Mail, Drive, Calendar, Contacts) | **Active** — primary SDK | +| `gopenpgp` | Go | OpenPGP crypto library (X25519, RSA) | **Active** | +| `proton-python-client` | Python | Python client | **Abandoned** (2021) | +| `proton-bridge` | Go | Local IMAP/SMTP/gRPC daemon for Mail | **Active** | +| `protonmail-bridge` (CLI) | Go | Headless Bridge (`-c` flag) | **Active** | +| `pass-cli` | Rust | Official Pass CLI with JSON output | **Active** | +| `proton-vpn-cli` | Python | Official Linux VPN CLI | **Active** | +| `Drive SDK` | TS/C#/Kt | Preview SDK for Drive | **Preview** | +| `go-crypto` | Go | Proton's fork of Go crypto | **Active** | + +### Key Third-Party Projects + +| Project | Lang | What | Stars | Notes | +|---------|------|------|-------|-------| +| **openclaw-protonmail-skill** | TS | OpenClaw skill for Mail via Bridge | 16 | Directly relevant — Hermes skill analogue | +| **hydroxide** (emersion) | Go | Third-party Bridge (CardDAV/IMAP/SMTP) | 2.1k | SRP auth, no official Bridge needed | +| **rclone protondrive** | Go | Drive as rclone backend | (57k) | Most-used third-party Drive client | +| **proton-webdav-bridge** | Go | Drive as WebDAV | 28 | Daemon pattern for agent integration | +| **proton-cli** (roman-16) | Go | Multi-product CLI (Mail, Drive, Calendar) | 17 | New, comprehensive | +| **pm-cli** (bscott) | Go | CLI via Bridge, `--json` everywhere | 14 | Agent-friendly design pattern | +| **proton-tui** (cdump) | Rust | Terminal UI for VPN | ~50 | Rust VPN auth flow reference | + +### Per-Product Integration Paths + +| Product | Recommended Path | Maturity | +|---------|-----------------|----------| +| **Mail** | Proton Bridge → local IMAP/SMTP | Proven | +| **Pass** | Official `pass-cli` → subprocess | Mature | +| **Drive** | rclone protondrive backend or Drive SDK | Beta | +| **VPN** | Official `proton-vpn-cli` → subprocess | Mature | +| **Calendar** | go-proton-api (has calendar endpoints) | Exploratory | +| **Wallet** | No API exists yet | None | + +--- + +## Proposed Architecture + +### Hybrid Multi-Layer Integration + +``` +┌────────────────────────────────────────────────────────────┐ +│ HERMES AGENT │ +│ (DeepSeek/Claude/etc. via Hermes runtime) │ +├────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ KOMODO PLUGIN: hermes-proton │ │ +│ │ (Hermes plugin — manages auth, session, config) │ │ +│ │ │ │ +│ │ Auth Layer: SRP-6a session management │ │ +│ │ Token cache, refresh, re-auth │ │ +│ └──────────┬──────────────────────────────┬────────────┘ │ +│ │ │ │ +│ ┌───────┴────────┐ ┌──────────┴────────────┐ │ +│ │ HERMES SKILLS │ │ MCP TOOLS (opt.) │ │ +│ │ │ │ │ │ +│ │ proton-mail │ │ proton-mail-read │ │ +│ │ proton-pass │ │ proton-drive-sync │ │ +│ │ proton-drive │ │ proton-vpn-connect │ │ +│ │ proton-vpn │ └───────────────────────┘ │ +│ └────────┬───────┘ │ +│ │ │ +└──────────────┼──────────────────────────────────────────────┘ + │ + ┌──────────┴──────────┬──────────┬──────────────┬──────┐ + ▼ ▼ ▼ ▼ +┌──────────┐ ┌─────────────┐ ┌──────────┐ ┌──────────┐ +│ Proton │ │ Proton Pass │ │ Proton │ │ Proton │ +│ Bridge │ │ CLI (rust) │ │ Drive │ │ VPN CLI │ +│ (IMAP/ │ │ subprocess │ │ rclone/ │ │ (python) │ +│ SMTP) │ │ │ │ SDK │ │ │ +└──────────┘ └─────────────┘ └──────────┘ └──────────┘ +``` + +### Why This Architecture + +1. **Bridge for Mail** — Proven by openclaw-protonmail-skill. Bridge handles all OpenPGP encryption transparently. Mail becomes standard IMAP/SMTP. No crypto complexity. + +2. **pass-cli for Pass** — Official Proton CLI with `--json` output, mature (v2.1.2), modular Rust crates. Subprocess calls map directly to Hermes tools. No auth management needed — pass-cli handles its own session. + +3. **rclone/Drive SDK for Drive** — Two options: + - **rclone protondrive backend** — Battle-tested (rclone's most-used third-party backend). Shell out like pass-cli. + - **Drive SDK** (TypeScript) — Newer, more direct, but preview stage with breaking crypto changes coming. + +4. **VPN CLI for VPN** — Official `protonvpn-cli` or `proton-tui`. Subprocess to connect/disconnect/status. + +5. **Komodo Plugin as Container** — A Hermes plugin (komodo plugin) owns the shared auth session, credential management, and lifecycle. Skills underneath are product-specific tool collections. + +6. **MCP Tools as Alternative** — Each product feature could also be exposed as an MCP (Model Context Protocol) tool for environments that use MCP over skills. + +### Auth Strategy + +Proton uses SRP-6a across all products. One login covers all products under the same account. + +**Option A: Plugin-managed auth** +- Plugin handles SRP login once → stores encrypted tokens +- All skills share the same session via plugin state +- Token refresh handled by plugin + +**Option B: Per-tool auth** +- Each skill/tool handles auth independently +- Simpler for isolated skills, redundant for multi-product workflows + +**Recommended: Option A** — One login, shared session, plugin manages token lifecycle. + +--- + +## Implementation Phases + +### Phase 1: Foundation (this seed) +- Research complete ✓ +- Project scaffold (this repo) +- Architecture design +- Kanban board seeded + +### Phase 2: Mail skill +- Proton Bridge install and configure +- Hermes skill: proton-mail (list, read, search, send, reply) +- IMAP + SMTP via node-imap/nodemailer or Python imaplib/smtplib + +### Phase 3: Pass skill +- proton-pass-cli install +- Hermes skill: proton-pass (list vaults, get secrets, inject env vars) +- SSH agent support + +### Phase 4: Drive skill +- rclone + protondrive backend config +- OR Drive SDK integration +- Hermes skill: proton-drive (list, read, upload, search) + +### Phase 5: VPN skill +- proton-vpn-cli install +- Hermes skill: proton-vpn (connect, disconnect, status, server list) + +### Phase 6: Auth plugin +- Komodo plugin: hermes-proton-auth +- SRP-6a login flow +- Encrypted token storage +- Token refresh lifecycle +- Shared session for all skills + +--- + +## Integration Vehicles (Hermes) + +The project should explore **all three** Hermes extension mechanisms for comparison: + +1. **Hermes Skill** — For self-contained tool collections (proton-mail skill, proton-pass skill). Best for most use cases. Skills are the primary extension mechanism. + +2. **Hermes Komodo Plugin** — For shared state, auth lifecycle, and cross-product coordination. A plugin can provide auth services that skills consume. + +3. **MCP Tool** — For environments that use MCP protocol. Each Proton product as an MCP server exposing tools. Good for cross-platform compatibility. + +--- + +## Related Projects + +- `rvacyber/openclaw-protonmail-skill` — OpenClaw skill for Proton Mail via Bridge +- `emersion/hydroxide` — Third-party ProtonMail bridge (SRP auth, no official Bridge) +- `henrybear327/Proton-API-Bridge` — Drive encryption bridge (archived Feb 2026) +- `rclone/rclone` — protondrive backend (active) +- `bscott/pm-cli` — Agent-friendly CLI via Bridge with `--json` output +- `roman-16/proton-cli` — Multi-product Go CLI (May 2026) + +--- + +## License + +MIT — Trentuna imprint