199 lines
10 KiB
Markdown
199 lines
10 KiB
Markdown
---
|
|
title: hermes-proton
|
|
description: Hermes Agent runtime + Proton product suite integration — skills, plugins, and MCP tools for Proton Mail, Drive, Pass, VPN, Calendar
|
|
state: prototype
|
|
created: 2026-06-08
|
|
updated: 2026-06-08
|
|
---
|
|
|
|
# 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
|