pyactivesync 0.2.0__py3-none-any.whl

pyactivesync/__init__.py

@@ -0,0 +1,36 @@
+"""pyactivesync: a Python client for Exchange ActiveSync (EAS / MS-ASCMD / MS-ASWBXML)."""
+from __future__ import annotations
+
+from .client import Client
+from .exceptions import EASError, ProtocolError, ProvisionError, StatusError
+from .models import (
+    AttachmentInfo,
+    BodyType,
+    Folder,
+    FolderType,
+    GalEntry,
+    PingResult,
+    Recipient,
+    SyncItem,
+    SyncResult,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Client",
+    "EASError",
+    "ProtocolError",
+    "ProvisionError",
+    "StatusError",
+    "AttachmentInfo",
+    "BodyType",
+    "Folder",
+    "FolderType",
+    "GalEntry",
+    "PingResult",
+    "Recipient",
+    "SyncItem",
+    "SyncResult",
+    "__version__",
+]

pyactivesync/_codepages.py

@@ -0,0 +1,135 @@
+"""MS-ASWBXML codepage token tables.
+
+Token values are the real MS-ASWBXML codepage numbers, verified against
+both the official spec
+(https://learn.microsoft.com/en-us/openspecs/exchange_server_protocols/ms-aswbxml/)
+and a live Exchange server -- not an arbitrary local enum order.
+"""
+from __future__ import annotations
+
+CODEPAGES: dict[str, dict[str, int]] = {
+    "AirSync": {
+        "Sync": 0x05, "Responses": 0x06, "Add": 0x07, "Change": 0x08,
+        "Delete": 0x09, "Fetch": 0x0A, "SyncKey": 0x0B, "ClientId": 0x0C,
+        "ServerId": 0x0D, "Status": 0x0E, "Collection": 0x0F, "Class": 0x10,
+        "Version": 0x11, "CollectionId": 0x12, "GetChanges": 0x13,
+        "MoreAvailable": 0x14, "WindowSize": 0x15, "Commands": 0x16,
+        "Options": 0x17, "FilterType": 0x18, "Truncation": 0x19,
+        "Conflict": 0x1B, "Collections": 0x1C, "ApplicationData": 0x1D,
+        "DeletesAsMoves": 0x1E, "Supported": 0x20, "SoftDelete": 0x21,
+        "MIMESupport": 0x22, "MIMETruncation": 0x23, "Wait": 0x24,
+        "Limit": 0x25, "Partial": 0x26, "MaxItems": 0x28,
+        "HeartbeatInterval": 0x29,
+    },
+    "Email": {
+        "DateReceived": 0x0F, "DisplayTo": 0x11, "Importance": 0x12,
+        "MessageClass": 0x13, "Subject": 0x14, "Read": 0x15, "To": 0x16,
+        "Cc": 0x17, "From": 0x18, "ReplyTo": 0x19, "Categories": 0x1B,
+        "Category": 0x1C, "InternetCPID": 0x39, "Flag": 0x3A,
+        "ContentClass": 0x3C,
+    },
+    "Move": {
+        "MoveItems": 0x05, "Move": 0x06, "SrcMsgId": 0x07, "SrcFldId": 0x08,
+        "DstFldId": 0x09, "Response": 0x0A, "Status": 0x0B, "DstMsgId": 0x0C,
+    },
+    "ItemEstimate": {
+        "GetItemEstimate": 0x05, "Collections": 0x07, "Collection": 0x08,
+        "CollectionId": 0x0A, "Estimate": 0x0C, "Response": 0x0D, "Status": 0x0E,
+    },
+    "FolderHierarchy": {
+        "DisplayName": 0x07, "ServerId": 0x08, "ParentId": 0x09,
+        "Type": 0x0A, "Response": 0x0B, "Status": 0x0C, "Changes": 0x0E,
+        "Add": 0x0F, "Delete": 0x10, "Update": 0x11, "SyncKey": 0x12,
+        "FolderCreate": 0x13, "FolderDelete": 0x14, "FolderUpdate": 0x15,
+        "FolderSync": 0x16, "Count": 0x17,
+    },
+    "Provision": {
+        "Provision": 0x05, "Policies": 0x06, "Policy": 0x07,
+        "PolicyType": 0x08, "PolicyKey": 0x09, "Data": 0x0A,
+        "Status": 0x0B, "RemoteWipe": 0x0C, "EASProvisionDoc": 0x0D,
+    },
+    "Ping": {
+        "Ping": 0x05, "AutdState": 0x06, "Status": 0x07, "HeartbeatInterval": 0x08,
+        "Folders": 0x09, "Folder": 0x0A, "Id": 0x0B, "Class": 0x0C, "MaxFolders": 0x0D,
+    },
+    "AirSyncBase": {
+        "BodyPreference": 0x05, "Type": 0x06, "TruncationSize": 0x07, "AllOrNone": 0x08,
+        "Body": 0x0A, "Data": 0x0B, "EstimatedDataSize": 0x0C, "Truncated": 0x0D,
+        "Attachments": 0x0E, "Attachment": 0x0F, "DisplayName": 0x10, "FileReference": 0x11,
+        "Method": 0x12, "ContentId": 0x13, "ContentLocation": 0x14, "IsInline": 0x15,
+        "NativeBodyType": 0x16, "ContentType": 0x17, "Preview": 0x18,
+    },
+    "Settings": {
+        "Settings": 0x05, "Status": 0x06, "Get": 0x07, "Set": 0x08,
+        "Oof": 0x09, "OofState": 0x0A, "BodyType": 0x13,
+        "DeviceInformation": 0x16, "Model": 0x17, "IMEI": 0x18,
+        "FriendlyName": 0x19, "OS": 0x1A, "OSLanguage": 0x1B,
+        "PhoneNumber": 0x1C, "UserAgent": 0x20,
+    },
+    "ItemOperations": {
+        "ItemOperations": 0x05, "Fetch": 0x06, "Store": 0x07, "Options": 0x08,
+        "Range": 0x09, "Total": 0x0A, "Properties": 0x0B, "Data": 0x0C,
+        "Status": 0x0D, "Response": 0x0E,
+    },
+    "ComposeMail": {
+        "SendMail": 0x05, "SmartForward": 0x06, "SmartReply": 0x07,
+        "SaveInSentItems": 0x08, "ReplaceMime": 0x09, "Source": 0x0B,
+        "FolderId": 0x0C, "ItemId": 0x0D, "LongId": 0x0E,
+        "InstanceId": 0x0F, "MIME": 0x10, "ClientId": 0x11,
+        "Status": 0x12, "AccountId": 0x13,
+    },
+    # ResolveRecipients/Search/GAL token values are taken verbatim from the
+    # official MS-ASWBXML spec, not reverse-engineered.
+    "ResolveRecipients": {
+        "ResolveRecipients": 0x05, "Response": 0x06, "Status": 0x07, "Type": 0x08,
+        "Recipient": 0x09, "DisplayName": 0x0A, "EmailAddress": 0x0B,
+        "Certificates": 0x0C, "Certificate": 0x0D, "MiniCertificate": 0x0E,
+        "Options": 0x0F, "To": 0x10, "CertificateRetrieval": 0x11,
+        "RecipientCount": 0x12, "MaxCertificates": 0x13, "MaxAmbiguousRecipients": 0x14,
+        "CertificateCount": 0x15,
+    },
+    "Search": {
+        "Search": 0x05, "Store": 0x07, "Name": 0x08, "Query": 0x09,
+        "Options": 0x0A, "Range": 0x0B, "Status": 0x0C, "Response": 0x0D,
+        "Result": 0x0E, "Properties": 0x0F, "Total": 0x10,
+        "EqualTo": 0x11, "Value": 0x12, "And": 0x13, "Or": 0x14, "FreeText": 0x15,
+        "DeepTraversal": 0x17, "LongId": 0x18, "RebuildResults": 0x19,
+        # GreaterThan verified byte-for-byte against a captured, working
+        # request/response pair (Store.Status=1, Total=96). Note
+        # Class/CollectionId scoping inside a Search query uses the
+        # *AirSync* codepage's tokens (xmlns="AirSync" in the spec XML),
+        # not tokens on this page -- do not add Search.Class/CollectionId.
+        "GreaterThan": 0x1B,
+    },
+    "GAL": {
+        "DisplayName": 0x05, "Phone": 0x06, "Office": 0x07, "Title": 0x08,
+        "Company": 0x09, "Alias": 0x0A, "FirstName": 0x0B, "LastName": 0x0C,
+        "HomePhone": 0x0D, "MobilePhone": 0x0E, "EmailAddress": 0x0F,
+    },
+}
+
+# Real MS-ASWBXML codepage numbers (must match the protocol, not an
+# arbitrary local order -- these are the values sent in SWITCH_PAGE).
+PAGE_INDEX: dict[str, int] = {
+    "AirSync": 0,
+    "Email": 2,
+    "Move": 5,
+    "ItemEstimate": 6,
+    "FolderHierarchy": 7,
+    "Ping": 13,
+    "Provision": 14,
+    "ResolveRecipients": 10,
+    "Search": 15,
+    "GAL": 16,
+    "AirSyncBase": 17,
+    "Settings": 18,
+    "ItemOperations": 20,
+    "ComposeMail": 21,
+}
+
+PAGE_ORDER: dict[int, str] = {num: name for name, num in PAGE_INDEX.items()}
+
+REVERSE: dict[int, dict[int, str]] = {
+    PAGE_INDEX[page]: {tok & 0x3F: tag for tag, tok in tags.items()}
+    for page, tags in CODEPAGES.items()
+}

pyactivesync/_http.py

@@ -0,0 +1,80 @@
+"""Thin HTTP transport for EAS: one ``requests.Session``, auth + headers + retries."""
+from __future__ import annotations
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+_RETRYABLE_STATUS = (500, 502, 503, 504)
+
+
+class Transport:
+    """POSTs WBXML bodies to ``/Microsoft-Server-ActiveSync`` and returns raw response bytes."""
+
+    def __init__(
+        self,
+        server: str,
+        username: str,
+        password: str,
+        *,
+        device_id: str,
+        device_type: str = "pyactivesync",
+        protocol_version: str = "14.1",
+        verify_ssl: bool = True,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = f"https://{server}/Microsoft-Server-ActiveSync"
+        self.device_id = device_id
+        self.device_type = device_type
+        self.protocol_version = protocol_version
+        self.timeout = timeout
+        self.policy_key: str | None = None
+
+        self.session = requests.Session()
+        self.session.auth = (username, password)
+        self.session.verify = verify_ssl
+        retry = Retry(
+            total=3,
+            backoff_factor=0.5,
+            status_forcelist=_RETRYABLE_STATUS,
+            allowed_methods=frozenset({"POST"}),
+        )
+        adapter = HTTPAdapter(max_retries=retry)
+        self.session.mount("https://", adapter)
+        self.session.mount("http://", adapter)
+
+    def post(
+        self,
+        cmd: str,
+        user: str,
+        wbxml: bytes,
+        *,
+        extra_params: dict[str, str] | None = None,
+        timeout: float | None = None,
+    ) -> bytes:
+        params = {
+            "Cmd": cmd,
+            "User": user,
+            "DeviceId": self.device_id,
+            "DeviceType": self.device_type,
+        }
+        if extra_params:
+            params.update(extra_params)
+        headers = {
+            "Content-Type": "application/vnd.ms-sync.wbxml",
+            "MS-ASProtocolVersion": self.protocol_version,
+        }
+        if self.policy_key:
+            headers["X-MS-PolicyKey"] = self.policy_key
+        resp = self.session.post(
+            self.base_url,
+            params=params,
+            data=wbxml,
+            headers=headers,
+            timeout=timeout if timeout is not None else self.timeout,
+        )
+        resp.raise_for_status()
+        return resp.content
+
+    def close(self) -> None:
+        self.session.close()

pyactivesync/_mime.py

@@ -0,0 +1,22 @@
+"""MIME helpers: turn a stdlib ``email.message`` object into the CRLF bytes
+EAS's ``ComposeMail.MIME`` opaque field requires, and parse MIME bytes back.
+"""
+from __future__ import annotations
+
+from email import message_from_bytes
+from email.message import Message
+
+
+def to_crlf_bytes(message: Message) -> bytes:
+    """Render an ``email.message`` object to CRLF-terminated bytes.
+
+    EAS requires CRLF line endings in the MIME payload; LF-only bytes (the
+    default from ``Message.as_bytes()`` on POSIX) are rejected by the
+    server with ``Status=101`` (``InvalidContent``).
+    """
+    raw = message.as_bytes()
+    return raw.replace(b"\r\n", b"\n").replace(b"\n", b"\r\n")
+
+
+def parse_mime(data: bytes) -> Message:
+    return message_from_bytes(data)

pyactivesync/_wbxml.py

@@ -0,0 +1,200 @@
+"""MS-ASWBXML binary XML codec: writer, reader, and small tree helpers."""
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from ._codepages import CODEPAGES, PAGE_INDEX, PAGE_ORDER, REVERSE
+
+SWITCH_PAGE = 0x00
+END = 0x01
+ENTITY = 0x02
+STR_I = 0x03
+LITERAL = 0x04
+OPAQUE = 0xC3
+
+# A parsed WBXML node: (tag_path, text-or-None, children). Leaf text/opaque
+# nodes use the synthetic tag paths "#text" / "#opaque".
+Node = tuple[str, "str | bytes | None", list[Any]]
+NodeBuilder = Callable[["WBXMLWriter"], None]
+
+
+def _mb_uint_bytes(n: int) -> bytes:
+    out = [n & 0x7F]
+    n >>= 7
+    while n:
+        out.append((n & 0x7F) | 0x80)
+        n >>= 7
+    return bytes(reversed(out))
+
+
+class WBXMLWriter:
+    """Builds a WBXML document from a nested tree of ``tag()``/``wtag()`` calls."""
+
+    def __init__(self) -> None:
+        self.body = bytearray()
+        self.current_page = 0
+
+    def _switch(self, page_name: str) -> None:
+        page = PAGE_INDEX[page_name]
+        if page != self.current_page:
+            self.body.append(SWITCH_PAGE)
+            self.body.append(page)
+            self.current_page = page
+
+    def tag(
+        self,
+        page_name: str,
+        name: str,
+        children: Iterable[NodeBuilder] | None = None,
+        text: str | None = None,
+        opaque: bytes | None = None,
+    ) -> WBXMLWriter:
+        self._switch(page_name)
+        token = CODEPAGES[page_name][name]
+        has_content = bool(children) or text is not None or opaque is not None
+        self.body.append(token | (0x40 if has_content else 0x00))
+        if text is not None:
+            self.body.append(STR_I)
+            self.body.extend(text.encode("utf-8"))
+            self.body.append(0x00)
+        if opaque is not None:
+            self.body.append(OPAQUE)
+            self.body.extend(_mb_uint_bytes(len(opaque)))
+            self.body.extend(opaque)
+        if children:
+            for child in children:
+                child(self)
+        if has_content:
+            self.body.append(END)
+        return self
+
+    def render(self) -> bytes:
+        header = bytes([0x03, 0x01, 0x6A, 0x00])  # version 1.3, unknown PID, UTF-8, no str table
+        return header + bytes(self.body)
+
+
+def wtag(
+    page: str,
+    name: str,
+    children: Iterable[NodeBuilder] | None = None,
+    text: str | None = None,
+    opaque: bytes | None = None,
+) -> NodeBuilder:
+    """Return a closure that appends one tag (+ children) into a WBXMLWriter."""
+
+    def build(writer: WBXMLWriter) -> None:
+        writer.tag(page, name, children, text, opaque)
+
+    return build
+
+
+class WBXMLReader:
+    """Parses a WBXML document into a tree of ``Node`` tuples."""
+
+    def __init__(self, data: bytes) -> None:
+        self.data = data
+        self.pos = 3  # skip version, publicid, charset
+        strtbl_len, self.pos = self._mb_uint()
+        self.pos += strtbl_len  # skip string table
+        self.page = 0
+
+    def _mb_uint(self, pos: int | None = None) -> tuple[int, int]:
+        result = 0
+        pos = self.pos if pos is None else pos
+        while True:
+            b = self.data[pos]
+            result = (result << 7) | (b & 0x7F)
+            pos += 1
+            if not (b & 0x80):
+                break
+        return result, pos
+
+    def parse(self) -> list[Node]:
+        nodes, self.pos = self._parse_body(self.pos)
+        return nodes
+
+    def _parse_body(self, pos: int) -> tuple[list[Node], int]:
+        nodes: list[Node] = []
+        while pos < len(self.data):
+            b = self.data[pos]
+            if b == END:
+                return nodes, pos + 1
+            if b == SWITCH_PAGE:
+                self.page = self.data[pos + 1]
+                pos += 2
+                continue
+            if b == STR_I:
+                end = self.data.index(0x00, pos + 1)
+                nodes.append(("#text", self.data[pos + 1 : end].decode("utf-8"), []))
+                pos = end + 1
+                continue
+            if b == OPAQUE:
+                length, pos = self._mb_uint(pos + 1)
+                nodes.append(("#opaque", self.data[pos : pos + length], []))
+                pos += length
+                continue
+            has_content = bool(b & 0x40)
+            token = b & 0x3F
+            page_name = PAGE_ORDER.get(self.page, f"page{self.page}")
+            tag_name = REVERSE.get(self.page, {}).get(token, f"0x{token:02X}")
+            pos += 1
+            children: list[Node] = []
+            if has_content:
+                children, pos = self._parse_body(pos)
+            nodes.append((f"{page_name}.{tag_name}", None, children))
+        return nodes, pos
+
+
+def find(nodes: list[Node], path: str) -> Node | None:
+    """Find the first descendant node by dotted tag path, e.g. ``"FolderHierarchy.FolderSync"``."""
+    for name, text, children in nodes:
+        if name == path:
+            return name, text, children
+        found = find(children, path)
+        if found:
+            return found
+    return None
+
+
+def find_all(nodes: list[Node], path: str) -> list[Node]:
+    out: list[Node] = []
+    for name, text, children in nodes:
+        if name == path:
+            out.append((name, text, children))
+        out.extend(find_all(children, path))
+    return out
+
+
+def text_of(node: Node | None) -> str | None:
+    if not node:
+        return None
+    _, _, children = node
+    for name, text, _ in children:
+        if name == "#text":
+            assert text is None or isinstance(text, str)
+            return text
+    return None
+
+
+def opaque_of(node: Node | None) -> bytes | None:
+    if not node:
+        return None
+    _, _, children = node
+    for name, data, _ in children:
+        if name == "#opaque":
+            assert isinstance(data, (bytes, bytearray))
+            return bytes(data)
+    return None
+
+
+def leaves(nodes: list[Node]) -> dict[str, str]:
+    """Flatten a subtree into ``{tag_name: text}`` for every leaf with text content."""
+    out: dict[str, str] = {}
+    for name, _, children in nodes:
+        text = next((t for n, t, _ in children if n == "#text"), None)
+        if text is not None:
+            out[name] = text
+        else:
+            out.update(leaves(children))
+    return out

pyactivesync/cli.py

@@ -0,0 +1,154 @@
+"""``pyactivesync`` console script: list-folders, sync, send, fetch, ping."""
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import json
+import os
+import sys
+from email.message import EmailMessage
+
+from .client import Client
+from .exceptions import EASError
+from .models import BodyType
+
+
+def _client_from_args(args: argparse.Namespace) -> Client:
+    password = args.password or os.environ.get("PYACTIVESYNC_PASSWORD")
+    if not password:
+        raise SystemExit("no password: pass --password or set PYACTIVESYNC_PASSWORD")
+    return Client(
+        args.server,
+        args.username,
+        password,
+        device_id=args.device_id,
+        user=args.user,
+    )
+
+
+def _to_jsonable(obj: object) -> object:
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        return dataclasses.asdict(obj)
+    if isinstance(obj, list):
+        return [_to_jsonable(o) for o in obj]
+    return obj
+
+
+def _print(obj: object, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(_to_jsonable(obj), default=str, indent=2))
+    else:
+        print(obj)
+
+
+def _add_common_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--server", required=True, help="EAS server hostname")
+    p.add_argument("--username", required=True, help="auth username (domain\\user or email)")
+    p.add_argument("--user", help="mailbox SMTP address for the User param (defaults to --username)")
+    p.add_argument("--password", help="password (falls back to PYACTIVESYNC_PASSWORD env var)")
+    p.add_argument("--device-id", default="pyactivesync-cli", help="device id (default: pyactivesync-cli)")
+    p.add_argument("--json", action="store_true", help="output JSON instead of a table")
+
+
+def cmd_list_folders(args: argparse.Namespace) -> None:
+    with _client_from_args(args) as client:
+        folders = client.list_folders()
+        if args.json:
+            _print(folders, True)
+            return
+        for f in folders:
+            print(f"{f.id}\t{f.type.name}\t{f.parent_id}\t{f.name}")
+
+
+def cmd_sync(args: argparse.Namespace) -> None:
+    with _client_from_args(args) as client:
+        result = client.sync_folder(args.folder_id, sync_key=args.sync_key, window_size=args.window_size)
+        if args.json:
+            _print(result, True)
+            return
+        print(f"SyncKey={result.sync_key} more_available={result.more_available}")
+        for item in result.added:
+            print(f"  + {item.server_id}\t{item.fields}")
+        for item in result.changed:
+            print(f"  ~ {item.server_id}\t{item.fields}")
+        for server_id in result.deleted:
+            print(f"  - {server_id}")
+
+
+def cmd_fetch(args: argparse.Namespace) -> None:
+    with _client_from_args(args) as client:
+        body_type = BodyType[args.body_type.upper()]
+        props = client.fetch_item(args.folder_id, args.item_id, body_type=body_type)
+        _print(props, args.json)
+
+
+def cmd_send(args: argparse.Namespace) -> None:
+    msg = EmailMessage()
+    msg["To"] = args.to
+    msg["From"] = args.user or args.username
+    msg["Subject"] = args.subject
+    msg.set_content(args.body)
+    with _client_from_args(args) as client:
+        client.send_mail(msg)
+    if not args.json:
+        print("sent")
+
+
+def cmd_ping(args: argparse.Namespace) -> None:
+    with _client_from_args(args) as client:
+        result = client.ping(args.folder_id, heartbeat=args.heartbeat, timeout=args.timeout)
+        _print(result, args.json)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="pyactivesync", description="Exchange ActiveSync client CLI")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("list-folders", help="list the folder hierarchy")
+    _add_common_args(p)
+    p.set_defaults(func=cmd_list_folders)
+
+    p = sub.add_parser("sync", help="sync one folder")
+    _add_common_args(p)
+    p.add_argument("folder_id")
+    p.add_argument("--sync-key", default="0")
+    p.add_argument("--window-size", type=int, default=25)
+    p.set_defaults(func=cmd_sync)
+
+    p = sub.add_parser("fetch", help="fetch one item's properties")
+    _add_common_args(p)
+    p.add_argument("folder_id")
+    p.add_argument("item_id")
+    p.add_argument("--body-type", default="html", choices=["plain_text", "html", "rtf", "mime"])
+    p.set_defaults(func=cmd_fetch)
+
+    p = sub.add_parser("send", help="send a plain-text message")
+    _add_common_args(p)
+    p.add_argument("--to", required=True)
+    p.add_argument("--subject", required=True)
+    p.add_argument("--body", required=True)
+    p.set_defaults(func=cmd_send)
+
+    p = sub.add_parser("ping", help="long-poll one folder for changes")
+    _add_common_args(p)
+    p.add_argument("folder_id")
+    p.add_argument("--heartbeat", type=int, default=60)
+    p.add_argument("--timeout", type=float, default=30.0)
+    p.set_defaults(func=cmd_ping)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        args.func(args)
+    except EASError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())