protonlite 0.1.0__tar.gz

protonlite-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Wilamo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.

protonlite-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: protonlite
+Version: 0.1.0
+Summary: A small, unofficial Python client for Proton Mail, Calendar, Contacts and Drive -- no Bridge, no paid plan
+Author: William Wilamo
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Maytrella007/protonlite
+Project-URL: Issues, https://github.com/Maytrella007/protonlite/issues
+Keywords: proton,protonmail,proton-drive,proton-calendar,email,openpgp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PGPy13<0.7,>=0.6.1rc1
+Requires-Dist: bcrypt<6,>=4.0
+Requires-Dist: requests<3,>=2.28
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.2; extra == "mcp"
+Dynamic: license-file
+
+# protonlite
+
+A small, dependency-light Python client for **Proton Mail, Calendar, Contacts and Drive** --
+no Proton Mail Bridge, no paid plan.
+
+Proton has no IMAP or SMTP. The official way in is Proton Mail Bridge, which needs a paid
+plan. `protonlite` talks to Proton's web API directly, so it works on a free account, and the
+end-to-end crypto is ported from **Proton's own MIT-licensed Go libraries**
+([go-srp](https://github.com/ProtonMail/go-srp),
+[go-proton-api](https://github.com/ProtonMail/go-proton-api)). It stays MIT-licensed and
+dependency-light: just OpenPGP (`PGPy13`, a maintained fork of PGPy), `bcrypt` and `requests`. No CAPTCHA solver, no
+computer-vision stack -- a person completes Proton's verification page the same way Proton's
+own apps do.
+
+> **Unofficial.** This project is not affiliated with, endorsed by, or supported by Proton AG.
+> "Proton", "Proton Mail", "Proton Calendar" and "Proton Drive" are trademarks of Proton AG.
+> It talks to a private, undocumented API that can change at any time, and using it may be
+> subject to Proton's terms of service. Use it at your own risk, on accounts you own.
+
+## What it does
+
+- **Mail** -- read the inbox and any folder, decrypt messages (HTML flattened to text),
+  search, send (plain or HTML, attachments, replies in-thread, scheduled), save drafts,
+  mark read/unread, trash/delete, labels and folders, empty trash, storage usage.
+- **Calendar** -- read the agenda, create / edit / cancel events, send invitations, RSVP.
+- **Contacts** -- read, create, edit and delete contacts (signed/encrypted vCards).
+- **Drive** -- list, download, upload (encrypted), move, rename, trash, and create public
+  share links.
+
+All of it is end-to-end: keys are unlocked locally with the account password and messages,
+events, contacts and files are decrypted on your machine.
+
+## Install
+
+```bash
+pip install protonlite
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```python
+import os
+import datetime as dt
+
+from protonlite import ProtonMail
+
+# --- Signing in -------------------------------------------------------------
+# The recommended way is the CLI `protonlite login`, which reads the password
+# with getpass so it never lives in a script. For automation, read it from the
+# environment rather than hard-coding it. Proton usually asks a human to
+# complete a verification page; login raises HumanVerificationRequired with
+# that URL -- open it, then call again passing verification_token (see
+# "Signing in" below). Sign in each account once; every login saves its own
+# session file.
+ProtonMail.login(
+    "you@proton.me",
+    password=os.environ["PROTON_PASSWORD"].encode(),
+    session_path="you@proton.me.json",
+)
+
+# --- More than one account --------------------------------------------------
+# Reopen each saved session independently -- no password needed. The two
+# clients are fully independent mailboxes.
+client  = ProtonMail.from_session(session_path="you@proton.me.json")    # personal
+client1 = ProtonMail.from_session(session_path="work@proton.me.json")   # work
+# (after a CLI `protonlite login`, ProtonMail.for_account("work") finds it by name)
+print(client.addresses()[0]["Email"], "/", client1.addresses()[0]["Email"])
+
+# --- Mail -------------------------------------------------------------------
+for msg in client.list_messages(unread_only=True):
+    print(msg.time, msg.sender.address, msg.subject)
+full = client.read_message(msg.id)
+print(full.text)                                  # HTML flattened to prose
+client.send(to=["friend@example.com"], subject="Hi", body="Hello")
+client1.send(to=["teammate@work.com"], subject="Hi from work", body="Hello")
+
+# --- Calendar ---------------------------------------------------------------
+cal_id = client.list_calendars()[0]["ID"]
+begins = dt.datetime.now(dt.timezone.utc) + dt.timedelta(days=1)
+event = client.create_event(cal_id, summary="Demo",
+                            start=begins, end=begins + dt.timedelta(hours=1))
+for ev in client.list_events(cal_id, start=int(begins.timestamp()) - 3600,
+                             end=int(begins.timestamp()) + 86400):
+    print(dt.datetime.fromtimestamp(ev.start, dt.timezone.utc), ev.title)
+client.delete_event(cal_id, event["id"])
+
+# --- Contacts ---------------------------------------------------------------
+cid = client.create_contact(name="Ada Lovelace", emails=["ada@example.com"])
+for row in client.list_contact_emails():
+    print(row["name"], row["email"])
+client.delete_contacts([cid])
+
+# --- Drive ------------------------------------------------------------------
+drive = client.drive()
+with open("report.pdf", "rb") as fh:
+    drive.upload("", "report.pdf", fh.read(), "application/pdf")
+for entry in drive.list_folder(""):
+    print(entry["name"], entry["type"])
+link = drive.share_link("report.pdf")
+print(link["url"])                                # https://drive.proton.me/urls/...#password
+```
+
+### Command line
+
+A small CLI covers the mail basics:
+
+```bash
+protonlite login --user you@proton.me
+protonlite unread
+protonlite read <message-id>
+protonlite send --to friend@example.com --subject "Hi" --body "Hello"
+```
+
+## Signing in
+
+Proton logins from a server almost always trigger a human-verification page (hCaptcha). The
+login flow surfaces that URL so a person can complete it in a browser; `protonlite` never
+solves it and never asks for a password over any channel but your own code. The account
+password is used only to derive keys locally -- it is never stored; the saved session holds
+OAuth-style tokens and the derived key passphrase, nothing more. Two-factor (TOTP) is
+supported.
+
+## MCP server
+
+`protonlite` ships an optional [MCP](https://modelcontextprotocol.io) server so any MCP client
+(Cursor, Claude Code, Claude Desktop) can use Proton through it. Sign in once with the CLI,
+then run the server pointed at that session:
+
+```bash
+pip install "protonlite[mcp]"
+protonlite login --user you@proton.me          # one-time; saves a session file
+PROTONLITE_SESSION=~/you@proton.me.json protonlite-mcp
+```
+
+Wire it into an MCP client (e.g. Claude Desktop / Cursor `mcpServers` config):
+
+```json
+{
+  "mcpServers": {
+    "proton": {
+      "command": "protonlite-mcp",
+      "env": { "PROTONLITE_SESSION": "/home/you/you@proton.me.json" }
+    }
+  }
+}
+```
+
+The server never takes a password -- it reuses the saved session. It exposes `list_messages`,
+`read_message`, `search_messages`, `send_message`, `calendar`, `contacts`, `drive_list` and
+`drive_download`, and returns other people's content wrapped as untrusted data.
+
+## Status and limits
+
+The write paths (Drive upload, calendar event creation, share links) were reverse-engineered
+from Proton's Go and web clients and verified against live accounts, but the API is
+undocumented and may change. Calendar key generation shells out to `gpg` (Proton requires an
+Ed25519 key that `PGPy` cannot generate). Bug reports and PRs welcome.
+
+## Related
+
+`protonlite` is also the engine behind [hermes-proton](https://github.com/Maytrella007/hermes-proton), a Proton plugin for the
+[Hermes Agent](https://github.com/NousResearch/hermes-agent) that adds a recipient allowlist
+and a human-approval gate on every send.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

protonlite-0.1.0/README.md

@@ -0,0 +1,169 @@
+# protonlite
+
+A small, dependency-light Python client for **Proton Mail, Calendar, Contacts and Drive** --
+no Proton Mail Bridge, no paid plan.
+
+Proton has no IMAP or SMTP. The official way in is Proton Mail Bridge, which needs a paid
+plan. `protonlite` talks to Proton's web API directly, so it works on a free account, and the
+end-to-end crypto is ported from **Proton's own MIT-licensed Go libraries**
+([go-srp](https://github.com/ProtonMail/go-srp),
+[go-proton-api](https://github.com/ProtonMail/go-proton-api)). It stays MIT-licensed and
+dependency-light: just OpenPGP (`PGPy13`, a maintained fork of PGPy), `bcrypt` and `requests`. No CAPTCHA solver, no
+computer-vision stack -- a person completes Proton's verification page the same way Proton's
+own apps do.
+
+> **Unofficial.** This project is not affiliated with, endorsed by, or supported by Proton AG.
+> "Proton", "Proton Mail", "Proton Calendar" and "Proton Drive" are trademarks of Proton AG.
+> It talks to a private, undocumented API that can change at any time, and using it may be
+> subject to Proton's terms of service. Use it at your own risk, on accounts you own.
+
+## What it does
+
+- **Mail** -- read the inbox and any folder, decrypt messages (HTML flattened to text),
+  search, send (plain or HTML, attachments, replies in-thread, scheduled), save drafts,
+  mark read/unread, trash/delete, labels and folders, empty trash, storage usage.
+- **Calendar** -- read the agenda, create / edit / cancel events, send invitations, RSVP.
+- **Contacts** -- read, create, edit and delete contacts (signed/encrypted vCards).
+- **Drive** -- list, download, upload (encrypted), move, rename, trash, and create public
+  share links.
+
+All of it is end-to-end: keys are unlocked locally with the account password and messages,
+events, contacts and files are decrypted on your machine.
+
+## Install
+
+```bash
+pip install protonlite
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```python
+import os
+import datetime as dt
+
+from protonlite import ProtonMail
+
+# --- Signing in -------------------------------------------------------------
+# The recommended way is the CLI `protonlite login`, which reads the password
+# with getpass so it never lives in a script. For automation, read it from the
+# environment rather than hard-coding it. Proton usually asks a human to
+# complete a verification page; login raises HumanVerificationRequired with
+# that URL -- open it, then call again passing verification_token (see
+# "Signing in" below). Sign in each account once; every login saves its own
+# session file.
+ProtonMail.login(
+    "you@proton.me",
+    password=os.environ["PROTON_PASSWORD"].encode(),
+    session_path="you@proton.me.json",
+)
+
+# --- More than one account --------------------------------------------------
+# Reopen each saved session independently -- no password needed. The two
+# clients are fully independent mailboxes.
+client  = ProtonMail.from_session(session_path="you@proton.me.json")    # personal
+client1 = ProtonMail.from_session(session_path="work@proton.me.json")   # work
+# (after a CLI `protonlite login`, ProtonMail.for_account("work") finds it by name)
+print(client.addresses()[0]["Email"], "/", client1.addresses()[0]["Email"])
+
+# --- Mail -------------------------------------------------------------------
+for msg in client.list_messages(unread_only=True):
+    print(msg.time, msg.sender.address, msg.subject)
+full = client.read_message(msg.id)
+print(full.text)                                  # HTML flattened to prose
+client.send(to=["friend@example.com"], subject="Hi", body="Hello")
+client1.send(to=["teammate@work.com"], subject="Hi from work", body="Hello")
+
+# --- Calendar ---------------------------------------------------------------
+cal_id = client.list_calendars()[0]["ID"]
+begins = dt.datetime.now(dt.timezone.utc) + dt.timedelta(days=1)
+event = client.create_event(cal_id, summary="Demo",
+                            start=begins, end=begins + dt.timedelta(hours=1))
+for ev in client.list_events(cal_id, start=int(begins.timestamp()) - 3600,
+                             end=int(begins.timestamp()) + 86400):
+    print(dt.datetime.fromtimestamp(ev.start, dt.timezone.utc), ev.title)
+client.delete_event(cal_id, event["id"])
+
+# --- Contacts ---------------------------------------------------------------
+cid = client.create_contact(name="Ada Lovelace", emails=["ada@example.com"])
+for row in client.list_contact_emails():
+    print(row["name"], row["email"])
+client.delete_contacts([cid])
+
+# --- Drive ------------------------------------------------------------------
+drive = client.drive()
+with open("report.pdf", "rb") as fh:
+    drive.upload("", "report.pdf", fh.read(), "application/pdf")
+for entry in drive.list_folder(""):
+    print(entry["name"], entry["type"])
+link = drive.share_link("report.pdf")
+print(link["url"])                                # https://drive.proton.me/urls/...#password
+```
+
+### Command line
+
+A small CLI covers the mail basics:
+
+```bash
+protonlite login --user you@proton.me
+protonlite unread
+protonlite read <message-id>
+protonlite send --to friend@example.com --subject "Hi" --body "Hello"
+```
+
+## Signing in
+
+Proton logins from a server almost always trigger a human-verification page (hCaptcha). The
+login flow surfaces that URL so a person can complete it in a browser; `protonlite` never
+solves it and never asks for a password over any channel but your own code. The account
+password is used only to derive keys locally -- it is never stored; the saved session holds
+OAuth-style tokens and the derived key passphrase, nothing more. Two-factor (TOTP) is
+supported.
+
+## MCP server
+
+`protonlite` ships an optional [MCP](https://modelcontextprotocol.io) server so any MCP client
+(Cursor, Claude Code, Claude Desktop) can use Proton through it. Sign in once with the CLI,
+then run the server pointed at that session:
+
+```bash
+pip install "protonlite[mcp]"
+protonlite login --user you@proton.me          # one-time; saves a session file
+PROTONLITE_SESSION=~/you@proton.me.json protonlite-mcp
+```
+
+Wire it into an MCP client (e.g. Claude Desktop / Cursor `mcpServers` config):
+
+```json
+{
+  "mcpServers": {
+    "proton": {
+      "command": "protonlite-mcp",
+      "env": { "PROTONLITE_SESSION": "/home/you/you@proton.me.json" }
+    }
+  }
+}
+```
+
+The server never takes a password -- it reuses the saved session. It exposes `list_messages`,
+`read_message`, `search_messages`, `send_message`, `calendar`, `contacts`, `drive_list` and
+`drive_download`, and returns other people's content wrapped as untrusted data.
+
+## Status and limits
+
+The write paths (Drive upload, calendar event creation, share links) were reverse-engineered
+from Proton's Go and web clients and verified against live accounts, but the API is
+undocumented and may change. Calendar key generation shells out to `gpg` (Proton requires an
+Ed25519 key that `PGPy` cannot generate). Bug reports and PRs welcome.
+
+## Related
+
+`protonlite` is also the engine behind [hermes-proton](https://github.com/Maytrella007/hermes-proton), a Proton plugin for the
+[Hermes Agent](https://github.com/NousResearch/hermes-agent) that adds a recipient allowlist
+and a human-approval gate on every send.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

protonlite-0.1.0/protonlite/__init__.py

@@ -0,0 +1,34 @@
+"""A small, unofficial Python client for Proton Mail, Calendar, Contacts and Drive.
+
+The protocol work is a port of Proton's own MIT Go libraries; see
+THIRD-PARTY-NOTICES.md. Nothing here is derived from GPL sources.
+
+This project is not affiliated with Proton AG. It talks to a private, undocumented
+API and is provided as-is, for use on accounts you own.
+"""
+
+from .client import Contact, Message, MessageSummary, ProtonMail
+from .errors import (
+    APIError,
+    AuthError,
+    HumanVerificationRequired,
+    ProtonError,
+    SessionExpired,
+    TwoFactorRequired,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ProtonMail",
+    "Message",
+    "MessageSummary",
+    "Contact",
+    "APIError",
+    "AuthError",
+    "HumanVerificationRequired",
+    "ProtonError",
+    "SessionExpired",
+    "TwoFactorRequired",
+    "__version__",
+]

protonlite-0.1.0/protonlite/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

protonlite-0.1.0/protonlite/_modulus_key.py

@@ -0,0 +1,18 @@
+"""Proton's SRP modulus signing key.
+
+Verbatim from ProtonMail/go-srp (MIT, Copyright (c) 2019 Proton Technologies AG).
+See THIRD-PARTY-NOTICES.md.
+"""
+
+MODULUS_SIGNING_KEY = '''-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+xjMEXAHLgxYJKwYBBAHaRw8BAQdAFurWXXwjTemqjD7CXjXVyKf0of7n9Ctm
+L8v9enkzggHNEnByb3RvbkBzcnAubW9kdWx1c8J3BBAWCgApBQJcAcuDBgsJ
+BwgDAgkQNQWFxOlRjyYEFQgKAgMWAgECGQECGwMCHgEAAPGRAP9sauJsW12U
+MnTQUZpsbJb53d0Wv55mZIIiJL2XulpWPQD/V6NglBd96lZKBmInSXX/kXat
+Sv+y0io+LR8i2+jV+AbOOARcAcuDEgorBgEEAZdVAQUBAQdAeJHUz1c9+KfE
+kSIgcBRE3WuXC4oj5a2/U3oASExGDW4DAQgHwmEEGBYIABMFAlwBy4MJEDUF
+hcTpUY8mAhsMAAD/XQD8DxNI6E78meodQI+wLsrKLeHn32iLvUqJbVDhfWSU
+WO4BAMcm1u02t4VKw++ttECPt+HUgPUq5pqQWe5Q2cW4TMsE
+=Y4Mw
+-----END PGP PUBLIC KEY BLOCK-----'''

protonlite-0.1.0/protonlite/accounts.py

@@ -0,0 +1,133 @@
+"""Several Proton accounts side by side.
+
+One session file per account, in a directory, with the address recorded inside
+each one. Which account a request means is resolved by that address, never
+guessed: with more than one signed in and nothing said, the tools ask instead
+of picking. Mailing the wrong person from the wrong account is not a mistake
+worth being convenient about.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import ProtonError, SessionExpired
+
+#: Where the sessions live, overridable for tests and odd layouts.
+ROOT_ENV = "PROTONLITE_HOME"
+
+_SAFE = re.compile(r"[^A-Za-z0-9._-]+")
+
+
+def default_root() -> Path:
+    return Path(os.environ.get(ROOT_ENV) or Path.home() / ".config" / "protonlite")
+
+
+def _slug(address: str) -> str:
+    """A filename for an address. Cosmetic: the address itself lives in the file."""
+    return _SAFE.sub("-", address.strip().lower()).strip("-") or "account"
+
+
+@dataclass(frozen=True)
+class Account:
+    address: str
+    path: Path
+
+    @property
+    def label(self) -> str:
+        return self.address or self.path.stem
+
+
+class AccountStore:
+    """The set of accounts signed in on this machine."""
+
+    def __init__(self, root: str | os.PathLike[str] | None = None) -> None:
+        self.root = Path(root) if root else default_root()
+
+    # -- layout -----------------------------------------------------------
+
+    @property
+    def sessions_dir(self) -> Path:
+        return self.root / "sessions"
+
+    @property
+    def legacy_session(self) -> Path:
+        return self.root / "session.json"
+
+    def path_for(self, address: str) -> Path:
+        return self.sessions_dir / f"{_slug(address)}.json"
+
+    def migrate_legacy(self) -> Account | None:
+        """Move a single-account session into the per-account layout, once.
+
+        Early versions kept one ``session.json``. Rather than carry two code
+        paths forever, the file is moved the first time the store is read.
+        """
+        if not self.legacy_session.exists():
+            return None
+        try:
+            address = json.loads(self.legacy_session.read_text()).get("username", "")
+        except (OSError, ValueError):
+            address = ""
+        target = self.path_for(address or "default")
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if target.exists():  # a newer session wins; leave the old file alone
+            return None
+        os.replace(self.legacy_session, target)
+        return Account(address=address, path=target)
+
+    # -- reading ----------------------------------------------------------
+
+    def list(self) -> list[Account]:
+        self.migrate_legacy()
+        if not self.sessions_dir.is_dir():
+            return []
+        accounts: list[Account] = []
+        for path in sorted(self.sessions_dir.glob("*.json")):
+            try:
+                address = json.loads(path.read_text()).get("username", "")
+            except (OSError, ValueError):
+                continue  # a half-written file is not an account
+            accounts.append(Account(address=address, path=path))
+        return accounts
+
+    def resolve(self, selector: str = "") -> Account:
+        """Find the account a request means, or explain why it cannot.
+
+        An empty selector is fine with exactly one account signed in and an
+        error with several -- that ambiguity is the caller's to settle.
+        """
+        accounts = self.list()
+        if not accounts:
+            raise SessionExpired(
+                "no Proton account is signed in yet; sign in before reading mail"
+            )
+
+        selector = selector.strip().lower()
+        if not selector:
+            if len(accounts) == 1:
+                return accounts[0]
+            names = ", ".join(a.label for a in accounts)
+            raise ProtonError(
+                f"there are {len(accounts)} accounts signed in ({names}); say which one"
+            )
+
+        exact = [a for a in accounts if a.address.lower() == selector]
+        if exact:
+            return exact[0]
+
+        # A local part or any distinctive fragment is enough when it picks out
+        # exactly one account; anything vaguer is reported rather than guessed.
+        partial = [a for a in accounts if selector in a.address.lower()]
+        if len(partial) == 1:
+            return partial[0]
+        if partial:
+            names = ", ".join(a.label for a in partial)
+            raise ProtonError(f"{selector!r} matches several accounts ({names}); be exact")
+
+        names = ", ".join(a.label for a in accounts)
+        raise ProtonError(f"no account matches {selector!r}; signed in: {names}")