Seed: hermes-proton prototype — research, architecture, and project scaffold
This commit is contained in:
commit
44e75a77fa
GPG key ID:
159D6AD58C8E55E9
1 changed files with 191 additions and 0 deletions
191
README.md
Normal file
191
README.md
Normal file
|
|
@ -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
|
||||
Loading…
Add table
Add a link
Reference in a new issue