mailcycle 0.1.0__tar.gz

mailcycle-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

mailcycle-0.1.0/LICENSE

@@ -0,0 +1,35 @@
+Copyright (c) 2026 Northlab Studios Ltd. All rights reserved.
+
+mailcycle for Python is proprietary software owned by Northlab Studios Ltd, a company
+registered in England and Wales ("Northlab Studios"). It is not open source.
+
+1. Licence. Northlab Studios grants you a limited, non-exclusive,
+   non-transferable, revocable licence to install and run this software, in
+   unmodified form, solely to call the Mailcycle API for a Mailcycle account you
+   are authorised to use, while you hold such an account, and in accordance with
+   the Mailcycle Terms of Service at https://mailcycle.email/legal/terms/.
+
+2. Restrictions. Except as expressly permitted above or by applicable law that
+   cannot be excluded, you may not copy, modify, adapt, translate, merge,
+   publish, distribute, sublicense, sell, rent or lease the software or any
+   part of it, create derivative works from it, or decompile, disassemble or
+   reverse engineer it.
+
+3. Ownership. The software is licensed, not sold. Northlab Studios and its
+   licensors keep all right, title and interest in it, including all
+   intellectual property rights. No rights are granted except as set out in
+   section 1.
+
+4. Termination. This licence ends automatically if you breach it or when you
+   stop holding a Mailcycle account. On termination you must stop using the
+   software and delete every copy of it.
+
+5. No warranty. To the extent permitted by law, the software is provided "as
+   is", without warranty of any kind, and Northlab Studios is not liable for
+   any claim, damages or other liability arising from it or its use, except as
+   set out in the Mailcycle Terms of Service.
+
+6. Governing law. This licence is governed by the laws of England and Wales,
+   and the courts of England and Wales have exclusive jurisdiction.
+
+Contact: hello@mailcycle.email

mailcycle-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.5
+Name: mailcycle
+Version: 0.1.0
+Summary: Python client for the Mailcycle API. Create addresses that receive mail, read and decrypt it on your machine, send, and listen for events.
+Project-URL: Homepage, https://mailcycle.email/
+Project-URL: Documentation, https://docs.mailcycle.email/
+Author-email: Northlab Studios Ltd <hello@mailcycle.email>
+License: Copyright (c) 2026 Northlab Studios Ltd. All rights reserved.
+        
+        mailcycle for Python is proprietary software owned by Northlab Studios Ltd, a company
+        registered in England and Wales ("Northlab Studios"). It is not open source.
+        
+        1. Licence. Northlab Studios grants you a limited, non-exclusive,
+           non-transferable, revocable licence to install and run this software, in
+           unmodified form, solely to call the Mailcycle API for a Mailcycle account you
+           are authorised to use, while you hold such an account, and in accordance with
+           the Mailcycle Terms of Service at https://mailcycle.email/legal/terms/.
+        
+        2. Restrictions. Except as expressly permitted above or by applicable law that
+           cannot be excluded, you may not copy, modify, adapt, translate, merge,
+           publish, distribute, sublicense, sell, rent or lease the software or any
+           part of it, create derivative works from it, or decompile, disassemble or
+           reverse engineer it.
+        
+        3. Ownership. The software is licensed, not sold. Northlab Studios and its
+           licensors keep all right, title and interest in it, including all
+           intellectual property rights. No rights are granted except as set out in
+           section 1.
+        
+        4. Termination. This licence ends automatically if you breach it or when you
+           stop holding a Mailcycle account. On termination you must stop using the
+           software and delete every copy of it.
+        
+        5. No warranty. To the extent permitted by law, the software is provided "as
+           is", without warranty of any kind, and Northlab Studios is not liable for
+           any claim, damages or other liability arising from it or its use, except as
+           set out in the Mailcycle Terms of Service.
+        
+        6. Governing law. This licence is governed by the laws of England and Wales,
+           and the courts of England and Wales have exclusive jurisdiction.
+        
+        Contact: hello@mailcycle.email
+License-File: LICENSE
+Keywords: email,encryption,end-to-end,mailcycle,privacy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx>=0.27
+Provides-Extra: events
+Requires-Dist: websockets>=13; extra == 'events'
+Description-Content-Type: text/markdown
+
+# mailcycle
+
+A Python client for the Mailcycle API that does the encryption on your machine. Create addresses that receive mail, read what arrives, send, and listen for events. Mailcycle stores mail sealed to keys derived from your recovery phrase, and this package derives them locally; the phrase never leaves your machine.
+
+Needs Python 3.10 or later.
+
+```sh
+pip install mailcycle          # add [events] for the live event stream
+```
+
+## Sign in
+
+```python
+import os
+from mailcycle import Mailcycle
+
+# With the recovery phrase: everything the app can do, on any plan.
+mc = Mailcycle.sign_in(os.environ["MAILCYCLE_PHRASE"])
+
+# With an API key (Operator and up). Add the phrase to open mail and create
+# addresses that receive it.
+scripted = Mailcycle.with_api_key(
+    os.environ["MAILCYCLE_API_KEY"],
+    phrase=os.environ.get("MAILCYCLE_PHRASE"),
+)
+```
+
+Signing in uses the same handshake as the app: the server sends a challenge and the client proves it holds the key, so nothing secret crosses the wire. With an API key and a phrase, the phrase is checked against the key's account before anything is opened.
+
+Deriving the keys runs the phrase through 120,000 PBKDF2 iterations, which takes a few tens of milliseconds here because Python's `hashlib` does it natively. The app pays far more for the same bytes, on its own JavaScript. Each `sign_in` opens a new 30-day session: a script that runs often can keep `mc.session_token` somewhere private and pick it up with `Mailcycle.resume(token, phrase)`, and `mc.sign_out()` ends a session it no longer needs.
+
+`Mailcycle.create_account()` makes a new account and returns the client and its phrase. Keep the phrase. Nothing can recover the account without it, and nobody at Mailcycle can help.
+
+## Addresses that receive mail
+
+```python
+address = mc.addresses.create(prefix="signup", label="Test run 42")
+print(address.email_address)  # signup-x7k2@…
+```
+
+The address's public key is derived from the phrase and sent with it, so the mail server can seal what arrives. The label is sealed on your machine, and the server stores it as ciphertext. `addresses.list()`, `update()` and `delete()` do the rest.
+
+## Reading mail
+
+```python
+for message in mc.messages.list(address.id):
+    print(message.from_address, message.subject, message.text)
+
+data = mc.messages.attachment(message, 0)   # bytes, opened locally
+mc.messages.mark_read(message.id)
+```
+
+`messages.iterate(address.id)` walks every page for you.
+
+A message that will not open, because there is no phrase or it is the wrong one, comes back with `opened=False` and empty content rather than raising, so one unreadable message does not hide the rest of a page.
+
+`message.html` is the HTML as the sender wrote it, remote images and all. `message.safe_html` has everything remote removed, the same way the app does it, and is the one to render; `message.blocked` says what was taken out and who it would have reported to.
+
+## Waiting for mail
+
+```python
+code = mc.messages.wait_for(address_id=address.id, subject="verification", timeout=60)
+```
+
+This listens on the event stream and returns the next matching message, opened. Where the stream is not available (an API key below Scale, or no `websockets` installed) it checks the address every five seconds instead, so `address_id` is needed then. If nothing arrives in time it raises an `APIError` with `code="timeout"`. Mail received from `since` on counts, even if it landed before the stream was up; it defaults to now, so to wait for a reply to something you are about to send, take the time before sending.
+
+## Sending
+
+```python
+mc.messages.send(
+    from_address=address.email_address,
+    to="someone@example.com",
+    subject="Hello",
+    text="Hi",
+)
+
+mc.messages.send(
+    from_address=address.email_address,
+    to=message.reply_to,
+    subject=f"Re: {message.subject}",
+    text="Thanks",
+    reply_to=message,     # fills in the threading headers
+)
+```
+
+Attachments take raw bytes and the client encodes them. A message can carry up to ten files, 3.5 MB between them. Give a file a `content_id` to show it inline, where the HTML says `cid:` and that id. Program and script files, like `.exe` and `.js`, are refused.
+
+```python
+from pathlib import Path
+from mailcycle import OutgoingAttachment
+
+mc.messages.send(
+    from_address=address.email_address,
+    to="someone@example.com",
+    subject="Your invoice",
+    text="Attached.",
+    html='<img src="cid:logo"><p>Attached.</p>',
+    attachments=[
+        OutgoingAttachment("invoice.pdf", Path("invoice.pdf").read_bytes(), mime_type="application/pdf"),
+        OutgoingAttachment("logo.png", Path("logo.png").read_bytes(), mime_type="image/png", content_id="logo"),
+    ],
+)
+```
+
+A session can send on every plan; an API key on Scale and up. Limits are in the [rate limits](https://docs.mailcycle.email/reference/rate-limits/).
+
+## Usage and activity
+
+```python
+usage = mc.usage()
+print(usage["addresses"]["used"], "of", usage["addresses"]["limit"], "addresses")
+
+for entry in mc.activity(50):
+    print(entry.created_at, entry.kind)
+```
+
+`usage()` reads back the counters the API enforces its limits on, so it says what a request would be refused on before it is refused. `activity()` is the account's own event log: ids and times, never content.
+
+## Events
+
+```python
+with mc.events.stream() as events:
+    for event in events:
+        print(event.type, event.payload)
+```
+
+The same events as webhooks, the moment they happen, and they carry ids rather than content. The stream reconnects after a drop, and events that happen while it is down are not replayed, so `on_reconnect=` is where to refetch whatever you are showing. Needs `pip install 'mailcycle[events]'`.
+
+To check a webhook came from Mailcycle:
+
+```python
+from mailcycle import verify_webhook_signature
+
+verify_webhook_signature(secret, raw_body, request.headers.get("Mailcycle-Signature"))
+```
+
+Pass the body exactly as it arrived, before any parsing.
+
+## Errors
+
+Everything raises a subclass of `MailcycleError`. An API failure is an `APIError` carrying the HTTP `status` and the API's own `code`, such as `plan_required` or `session_required`, which is what to match on rather than the message. See [errors](https://docs.mailcycle.email/reference/errors/).
+
+## How it is checked
+
+The encryption here is a second implementation of Mailcycle's scheme, and a second implementation is a liability unless it is proven rather than trusted. `tests/test_vectors.py` runs it against `packages/crypto-vectors/vectors.json`, the frozen vectors the app and the mail server are checked against: the same keys from the same phrase, the same boxes opened, the same proof and the same signature. The negative cases are checked too, because each is something a hostile server can try: the wrong additional data, another address's key, a box relabelled as the other version, an attachment served under the wrong object key.
+
+Two further suites cover what the vectors cannot. `test_cross_implementation.py` has this package and the app seal for each other, since the additional data a record is bound to is the client's choice rather than the format's. `test_trackers.py` runs both tracker strippers over the same markup and requires identical output, because a tracker one reader blocks and another fetches is a privacy promise broken rather than a test going red.
+
+## Licence
+
+Proprietary. Copyright (c) 2026 Northlab Studios Ltd. All rights reserved. You may run this package, unmodified, to call the Mailcycle API for an account you're authorised to use. You may not copy, modify, redistribute or reverse engineer it. See [LICENSE](LICENSE) and the [Terms of Service](https://mailcycle.email/legal/terms/).

mailcycle-0.1.0/README.md

@@ -0,0 +1,151 @@
+# mailcycle
+
+A Python client for the Mailcycle API that does the encryption on your machine. Create addresses that receive mail, read what arrives, send, and listen for events. Mailcycle stores mail sealed to keys derived from your recovery phrase, and this package derives them locally; the phrase never leaves your machine.
+
+Needs Python 3.10 or later.
+
+```sh
+pip install mailcycle          # add [events] for the live event stream
+```
+
+## Sign in
+
+```python
+import os
+from mailcycle import Mailcycle
+
+# With the recovery phrase: everything the app can do, on any plan.
+mc = Mailcycle.sign_in(os.environ["MAILCYCLE_PHRASE"])
+
+# With an API key (Operator and up). Add the phrase to open mail and create
+# addresses that receive it.
+scripted = Mailcycle.with_api_key(
+    os.environ["MAILCYCLE_API_KEY"],
+    phrase=os.environ.get("MAILCYCLE_PHRASE"),
+)
+```
+
+Signing in uses the same handshake as the app: the server sends a challenge and the client proves it holds the key, so nothing secret crosses the wire. With an API key and a phrase, the phrase is checked against the key's account before anything is opened.
+
+Deriving the keys runs the phrase through 120,000 PBKDF2 iterations, which takes a few tens of milliseconds here because Python's `hashlib` does it natively. The app pays far more for the same bytes, on its own JavaScript. Each `sign_in` opens a new 30-day session: a script that runs often can keep `mc.session_token` somewhere private and pick it up with `Mailcycle.resume(token, phrase)`, and `mc.sign_out()` ends a session it no longer needs.
+
+`Mailcycle.create_account()` makes a new account and returns the client and its phrase. Keep the phrase. Nothing can recover the account without it, and nobody at Mailcycle can help.
+
+## Addresses that receive mail
+
+```python
+address = mc.addresses.create(prefix="signup", label="Test run 42")
+print(address.email_address)  # signup-x7k2@…
+```
+
+The address's public key is derived from the phrase and sent with it, so the mail server can seal what arrives. The label is sealed on your machine, and the server stores it as ciphertext. `addresses.list()`, `update()` and `delete()` do the rest.
+
+## Reading mail
+
+```python
+for message in mc.messages.list(address.id):
+    print(message.from_address, message.subject, message.text)
+
+data = mc.messages.attachment(message, 0)   # bytes, opened locally
+mc.messages.mark_read(message.id)
+```
+
+`messages.iterate(address.id)` walks every page for you.
+
+A message that will not open, because there is no phrase or it is the wrong one, comes back with `opened=False` and empty content rather than raising, so one unreadable message does not hide the rest of a page.
+
+`message.html` is the HTML as the sender wrote it, remote images and all. `message.safe_html` has everything remote removed, the same way the app does it, and is the one to render; `message.blocked` says what was taken out and who it would have reported to.
+
+## Waiting for mail
+
+```python
+code = mc.messages.wait_for(address_id=address.id, subject="verification", timeout=60)
+```
+
+This listens on the event stream and returns the next matching message, opened. Where the stream is not available (an API key below Scale, or no `websockets` installed) it checks the address every five seconds instead, so `address_id` is needed then. If nothing arrives in time it raises an `APIError` with `code="timeout"`. Mail received from `since` on counts, even if it landed before the stream was up; it defaults to now, so to wait for a reply to something you are about to send, take the time before sending.
+
+## Sending
+
+```python
+mc.messages.send(
+    from_address=address.email_address,
+    to="someone@example.com",
+    subject="Hello",
+    text="Hi",
+)
+
+mc.messages.send(
+    from_address=address.email_address,
+    to=message.reply_to,
+    subject=f"Re: {message.subject}",
+    text="Thanks",
+    reply_to=message,     # fills in the threading headers
+)
+```
+
+Attachments take raw bytes and the client encodes them. A message can carry up to ten files, 3.5 MB between them. Give a file a `content_id` to show it inline, where the HTML says `cid:` and that id. Program and script files, like `.exe` and `.js`, are refused.
+
+```python
+from pathlib import Path
+from mailcycle import OutgoingAttachment
+
+mc.messages.send(
+    from_address=address.email_address,
+    to="someone@example.com",
+    subject="Your invoice",
+    text="Attached.",
+    html='<img src="cid:logo"><p>Attached.</p>',
+    attachments=[
+        OutgoingAttachment("invoice.pdf", Path("invoice.pdf").read_bytes(), mime_type="application/pdf"),
+        OutgoingAttachment("logo.png", Path("logo.png").read_bytes(), mime_type="image/png", content_id="logo"),
+    ],
+)
+```
+
+A session can send on every plan; an API key on Scale and up. Limits are in the [rate limits](https://docs.mailcycle.email/reference/rate-limits/).
+
+## Usage and activity
+
+```python
+usage = mc.usage()
+print(usage["addresses"]["used"], "of", usage["addresses"]["limit"], "addresses")
+
+for entry in mc.activity(50):
+    print(entry.created_at, entry.kind)
+```
+
+`usage()` reads back the counters the API enforces its limits on, so it says what a request would be refused on before it is refused. `activity()` is the account's own event log: ids and times, never content.
+
+## Events
+
+```python
+with mc.events.stream() as events:
+    for event in events:
+        print(event.type, event.payload)
+```
+
+The same events as webhooks, the moment they happen, and they carry ids rather than content. The stream reconnects after a drop, and events that happen while it is down are not replayed, so `on_reconnect=` is where to refetch whatever you are showing. Needs `pip install 'mailcycle[events]'`.
+
+To check a webhook came from Mailcycle:
+
+```python
+from mailcycle import verify_webhook_signature
+
+verify_webhook_signature(secret, raw_body, request.headers.get("Mailcycle-Signature"))
+```
+
+Pass the body exactly as it arrived, before any parsing.
+
+## Errors
+
+Everything raises a subclass of `MailcycleError`. An API failure is an `APIError` carrying the HTTP `status` and the API's own `code`, such as `plan_required` or `session_required`, which is what to match on rather than the message. See [errors](https://docs.mailcycle.email/reference/errors/).
+
+## How it is checked
+
+The encryption here is a second implementation of Mailcycle's scheme, and a second implementation is a liability unless it is proven rather than trusted. `tests/test_vectors.py` runs it against `packages/crypto-vectors/vectors.json`, the frozen vectors the app and the mail server are checked against: the same keys from the same phrase, the same boxes opened, the same proof and the same signature. The negative cases are checked too, because each is something a hostile server can try: the wrong additional data, another address's key, a box relabelled as the other version, an attachment served under the wrong object key.
+
+Two further suites cover what the vectors cannot. `test_cross_implementation.py` has this package and the app seal for each other, since the additional data a record is bound to is the client's choice rather than the format's. `test_trackers.py` runs both tracker strippers over the same markup and requires identical output, because a tracker one reader blocks and another fetches is a privacy promise broken rather than a test going red.
+
+## Licence
+
+Proprietary. Copyright (c) 2026 Northlab Studios Ltd. All rights reserved. You may run this package, unmodified, to call the Mailcycle API for an account you're authorised to use. You may not copy, modify, redistribute or reverse engineer it. See [LICENSE](LICENSE) and the [Terms of Service](https://mailcycle.email/legal/terms/).

mailcycle-0.1.0/live/README.md

@@ -0,0 +1,37 @@
+# Live check
+
+`live_check.py` runs this SDK against the real API, the way the TypeScript SDK was checked before it shipped (REMAINING.md, section 11). Run it before every release to PyPI, and again whenever the format or the API moves.
+
+It is not part of the package: the wheel ships `src/mailcycle` only, and the sdist lists what it includes, which leaves `live/` out.
+
+## Running it
+
+```sh
+cd packages/sdk-python && .venv/bin/pip install -e '.[events]' && .venv/bin/python live/live_check.py
+```
+
+It creates a throwaway account and prints its id. Put that account on the Scale plan in the admin console; the script checks every 10 seconds for up to 15 minutes and carries on once it sees the change. Set `MAILCYCLE_SKIP_WAIT=1` if the account is already on Scale.
+
+`MAILCYCLE_API_URL` points it somewhere else. It defaults to `https://api.mailcycle.email`.
+
+Each check prints one `PASS` or `FAIL` line, and the script exits non-zero if any fail. The account is deleted at the end, and also when a check fails or the run is interrupted. If that cleanup fails too, the last line says so with the account id, to delete by hand. It prints ids only, never the phrase, a token or message content.
+
+## What it checks
+
+1. The API it is pointed at.
+2. Creating an account, then waiting for Scale.
+3. Two addresses on a shared domain (`letterhold.com` when offered), both receiving mail, labels opening.
+4. The session's event stream.
+5. Mail from A to B through Email Sending and Email Routing, with a text attachment: `wait_for`, subject, text, sender, and the attachment opening to the same bytes.
+6. The sealed Sent copy on A, attachment included.
+7. Mark read and unread, star and unstar, move to junk and trash and restore, and a Sent copy refused a move to the inbox.
+8. A second client signing in with the phrase alone reading the same message.
+9. An API key made with the session: it lists addresses, reads labels and the message with the phrase, is refused key listing, webhook creation, pairing and account deletion with `session_required`, and holds the event stream.
+10. Deleting both addresses, and the stream having carried `inbox.created`, `message.sent`, `message.received` and `inbox.deleted`, with ids only.
+11. Deleting the account, after which signing in, the old session and the key are all refused.
+
+## What it does not check
+
+An API key below Scale being closed with 4003 on the event stream. That needs the plan changed down mid-run, which the script does not do. Check it by hand: with a key open on the stream, move the account to Operator in the console and watch the stream end.
+
+Some calls here have no SDK method yet (making an API key, the refusals in step 9, deleting the account), so the script makes them through the client's own HTTP layer.

mailcycle-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mailcycle"
+version = "0.1.0"
+description = "Python client for the Mailcycle API. Create addresses that receive mail, read and decrypt it on your machine, send, and listen for events."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Northlab Studios Ltd", email = "hello@mailcycle.email" }]
+keywords = ["email", "privacy", "encryption", "mailcycle", "end-to-end"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: Other/Proprietary License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Communications :: Email",
+  "Topic :: Security :: Cryptography",
+  "Typing :: Typed",
+]
+dependencies = [
+  "cryptography>=42",
+  "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+events = ["websockets>=13"]
+
+[project.urls]
+Homepage = "https://mailcycle.email/"
+Documentation = "https://docs.mailcycle.email/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mailcycle"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/mailcycle", "tests", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 130
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["F", "E", "W", "I", "UP", "B"]

mailcycle-0.1.0/src/mailcycle/__init__.py

@@ -0,0 +1,81 @@
+"""Mailcycle for Python.
+
+Privacy-first email you can automate. Create addresses that receive mail, read
+and decrypt it on your own machine, send, and listen for events.
+
+    from mailcycle import Mailcycle
+
+    client = Mailcycle.sign_in("your twelve word recovery phrase ...")
+    address = client.addresses.create(label="Sign-in codes")
+    message = client.messages.wait_for(address_id=address.id)
+    print(message.subject, message.text)
+
+The recovery phrase never leaves this machine. Mail is sealed to a key derived
+from it, so the API serves ciphertext it cannot read, and this package opens it
+locally. Lose the phrase and the mail is gone; nobody at Mailcycle can help.
+
+Documentation: https://docs.mailcycle.email/
+"""
+
+from __future__ import annotations
+
+from .client import Mailcycle
+from .crypto.mnemonic import generate_phrase, validate_phrase
+from .errors import (
+    APIError,
+    AuthProofError,
+    Base64URLError,
+    DecryptionError,
+    MailcycleError,
+    PhraseError,
+)
+from .events import EventStream
+from .keys import Keys
+from .models import (
+    Account,
+    AccountEvent,
+    ActivityEntry,
+    Address,
+    Attachment,
+    Device,
+    Domain,
+    Message,
+    MessagePage,
+    OutgoingAttachment,
+    Plan,
+)
+from .trackers import BlockedTracker, strip_remote_content, summarize_blocked
+from .webhooks import verify_webhook_signature, webhook_signature_header
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Mailcycle",
+    "Keys",
+    "EventStream",
+    "Account",
+    "AccountEvent",
+    "ActivityEntry",
+    "Address",
+    "Attachment",
+    "BlockedTracker",
+    "Device",
+    "Domain",
+    "Message",
+    "MessagePage",
+    "OutgoingAttachment",
+    "Plan",
+    "MailcycleError",
+    "APIError",
+    "AuthProofError",
+    "Base64URLError",
+    "DecryptionError",
+    "PhraseError",
+    "generate_phrase",
+    "validate_phrase",
+    "strip_remote_content",
+    "summarize_blocked",
+    "verify_webhook_signature",
+    "webhook_signature_header",
+    "__version__",
+]

mailcycle-0.1.0/src/mailcycle/_encoding.py

@@ -0,0 +1,57 @@
+"""base64url without padding, decoded strictly.
+
+The permissive decoders accept several spellings of the same bytes, which
+matters here: these strings are compared, stored and fed to a MAC, and a
+server picks how they are spelled. So unknown characters are an error, padding
+is an error, a length that cannot come from whole bytes is an error, and the
+unused low bits of the final character must be zero. This is
+`fromBase64Url` in the app's `src/crypto/bytes.ts`, rule for rule.
+"""
+
+from __future__ import annotations
+
+import base64
+
+from .errors import Base64URLError
+
+_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
+_INDEX = {char: value for value, char in enumerate(_ALPHABET)}
+
+
+def to_b64u(data: bytes) -> str:
+    """Bytes to base64url, unpadded."""
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def from_b64u(value: str) -> bytes:
+    """base64url to bytes, refusing anything non-canonical."""
+    if not isinstance(value, str):
+        raise Base64URLError("Expected base64url text.")
+    # One leftover character cannot encode any whole byte.
+    if len(value) % 4 == 1:
+        raise Base64URLError("Truncated base64url.")
+
+    out = bytearray()
+    buffer = 0
+    bits = 0
+    for position, char in enumerate(value):
+        index = _INDEX.get(char)
+        if index is None:
+            raise Base64URLError(f"Unexpected character at {position}.")
+        buffer = (buffer << 6) | index
+        bits += 6
+        if bits >= 8:
+            bits -= 8
+            out.append((buffer >> bits) & 0xFF)
+            buffer &= (1 << bits) - 1
+
+    # Whatever is left is padding bits, and in a canonical encoding they are
+    # zero. Non-zero means two strings would decode to the same bytes.
+    if bits and buffer:
+        raise Base64URLError("Non-canonical trailing bits.")
+    return bytes(out)
+
+
+def be64(value: int) -> bytes:
+    """Eight bytes, big-endian. The additional data's length, in a MAC input."""
+    return value.to_bytes(8, "big")