Vigo/hermes-proton
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hermes-proton/README.md

10 KiB
Raw Permalink Blame History

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