mailcycle 0.1.0__py3-none-any.whl

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/_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")