pyactivesync 0.2.0__py3-none-any.whl

pyactivesync/client.py

@@ -0,0 +1,642 @@
+"""EAS client: one method per MS-ASCMD command, WBXML in and out."""
+from __future__ import annotations
+
+import base64
+import uuid
+from email.message import Message
+from types import TracebackType
+
+from ._http import Transport
+from ._mime import to_crlf_bytes
+from ._wbxml import Node, WBXMLReader, WBXMLWriter, find, find_all, leaves, text_of, wtag
+from .exceptions import ProtocolError, ProvisionError, StatusError
+from .models import (
+    BodyType,
+    Folder,
+    FolderType,
+    GalEntry,
+    PingResult,
+    Recipient,
+    SyncItem,
+    SyncResult,
+)
+
+_PROVISION_STATUS_MEANINGS = {"165": "DeviceInformationRequired"}
+_SENDMAIL_STATUS_MEANINGS = {"101": "InvalidContent"}
+
+
+def _check_status(command: str, status: str | None, meanings: dict[str, str] | None = None) -> None:
+    if status is not None and status != "1":
+        raise StatusError(command, status, (meanings or {}).get(status))
+
+
+class Client:
+    """A stateless-HTTP EAS client wrapping one connection to a single mailbox.
+
+    ``username`` is passed to HTTP Basic auth as-is (NTLM-style
+    ``domain\\user`` or a plain email, both work against Basic-auth EAS
+    endpoints). ``user`` is the value sent as the ``User`` query parameter
+    on every command (the mailbox's SMTP address) -- it defaults to
+    ``username`` and only needs to be set separately when the login
+    identity and the mailbox's primary SMTP address differ.
+    """
+
+    def __init__(
+        self,
+        server: str,
+        username: str,
+        password: str,
+        *,
+        device_id: str,
+        user: str | None = None,
+        device_type: str = "pyactivesync",
+        protocol_version: str = "14.1",
+        verify_ssl: bool = True,
+        timeout: float = 30.0,
+    ) -> None:
+        self.user = user or username
+        self._transport = Transport(
+            server,
+            username,
+            password,
+            device_id=device_id,
+            device_type=device_type,
+            protocol_version=protocol_version,
+            verify_ssl=verify_ssl,
+            timeout=timeout,
+        )
+        self._provisioned = False
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def _post(
+        self, cmd: str, wbxml: bytes, *, extra_params: dict[str, str] | None = None, timeout: float | None = None
+    ) -> bytes:
+        return self._transport.post(cmd, self.user, wbxml, extra_params=extra_params, timeout=timeout)
+
+    def _ensure_provisioned(self) -> None:
+        if not self._provisioned:
+            self.provision()
+
+    # -- Device provisioning -------------------------------------------------
+
+    def provision(self) -> str:
+        """Acknowledge device policy (two round-trips). Returns the granted PolicyKey.
+
+        A bare ``Provision`` request is rejected with ``Status=165``
+        (``DeviceInformationRequired``) unless a ``Settings.DeviceInformation``
+        block is included on the first request.
+        """
+        w = WBXMLWriter()
+        w.tag(
+            "Provision",
+            "Provision",
+            children=[
+                wtag(
+                    "Settings",
+                    "DeviceInformation",
+                    children=[
+                        wtag(
+                            "Settings",
+                            "Set",
+                            children=[
+                                wtag("Settings", "Model", text="pyactivesync"),
+                                wtag("Settings", "FriendlyName", text="pyactivesync client"),
+                                wtag("Settings", "OS", text="Linux"),
+                                wtag("Settings", "UserAgent", text="pyactivesync/0.1"),
+                            ],
+                        ),
+                    ],
+                ),
+                wtag(
+                    "Provision",
+                    "Policies",
+                    children=[
+                        wtag(
+                            "Provision",
+                            "Policy",
+                            children=[wtag("Provision", "PolicyType", text="MS-EAS-Provisioning-WBXML")],
+                        ),
+                    ],
+                ),
+            ],
+        )
+        resp = self._post("Provision", w.render())
+        nodes = WBXMLReader(resp).parse()
+        status = text_of(find(nodes, "Provision.Status"))
+        _check_status("Provision", status, _PROVISION_STATUS_MEANINGS)
+        temp_key = text_of(find(nodes, "Provision.PolicyKey"))
+        if not temp_key:
+            raise ProvisionError("Provision: no PolicyKey in response")
+
+        w2 = WBXMLWriter()
+        w2.tag(
+            "Provision",
+            "Provision",
+            children=[
+                wtag(
+                    "Provision",
+                    "Policies",
+                    children=[
+                        wtag(
+                            "Provision",
+                            "Policy",
+                            children=[
+                                wtag("Provision", "PolicyType", text="MS-EAS-Provisioning-WBXML"),
+                                wtag("Provision", "PolicyKey", text=temp_key),
+                                wtag("Provision", "Status", text="1"),
+                            ],
+                        ),
+                    ],
+                ),
+            ],
+        )
+        resp2 = self._post("Provision", w2.render(), extra_params={"PolicyKey": temp_key})
+        nodes2 = WBXMLReader(resp2).parse()
+        final_key = text_of(find(nodes2, "Provision.PolicyKey"))
+        key = final_key or temp_key
+        self._transport.policy_key = key
+        self._provisioned = True
+        return key
+
+    # -- Folders ---------------------------------------------------------------
+
+    def list_folders(self) -> list[Folder]:
+        """Full ``FolderSync`` hierarchy listing."""
+        self._ensure_provisioned()
+        w = WBXMLWriter()
+        w.tag("FolderHierarchy", "FolderSync", children=[wtag("FolderHierarchy", "SyncKey", text="0")])
+        resp = self._post("FolderSync", w.render())
+        nodes = WBXMLReader(resp).parse()
+        status = text_of(find(nodes, "FolderHierarchy.Status"))
+        _check_status("FolderSync", status)
+        folders = []
+        for _, _, children in find_all(nodes, "FolderHierarchy.Add"):
+            server_id = text_of(find(children, "FolderHierarchy.ServerId"))
+            parent_id = text_of(find(children, "FolderHierarchy.ParentId"))
+            type_ = text_of(find(children, "FolderHierarchy.Type"))
+            name = text_of(find(children, "FolderHierarchy.DisplayName"))
+            if server_id is None or parent_id is None or type_ is None or name is None:
+                raise ProtocolError("FolderSync: incomplete Add entry in response")
+            folders.append(Folder(id=server_id, parent_id=parent_id, type=FolderType(int(type_)), name=name))
+        return folders
+
+    def _folder_sync_key(self) -> str:
+        """Bootstrap ``SyncKey`` for a mutating FolderHierarchy command."""
+        w = WBXMLWriter()
+        w.tag("FolderHierarchy", "FolderSync", children=[wtag("FolderHierarchy", "SyncKey", text="0")])
+        resp = self._post("FolderSync", w.render())
+        key = text_of(find(WBXMLReader(resp).parse(), "FolderHierarchy.SyncKey"))
+        if not key:
+            raise ProtocolError("FolderSync: no SyncKey in response")
+        return key
+
+    def create_folder(
+        self, display_name: str, parent_id: str = "0", type: FolderType = FolderType.USER_GENERIC
+    ) -> Folder:
+        self._ensure_provisioned()
+        sync_key = self._folder_sync_key()
+        w = WBXMLWriter()
+        w.tag(
+            "FolderHierarchy",
+            "FolderCreate",
+            children=[
+                wtag("FolderHierarchy", "SyncKey", text=sync_key),
+                wtag("FolderHierarchy", "ParentId", text=parent_id),
+                wtag("FolderHierarchy", "DisplayName", text=display_name),
+                wtag("FolderHierarchy", "Type", text=str(int(type))),
+            ],
+        )
+        resp = self._post("FolderCreate", w.render())
+        nodes = WBXMLReader(resp).parse()
+        status = text_of(find(nodes, "FolderHierarchy.Status"))
+        _check_status("FolderCreate", status)
+        server_id = text_of(find(nodes, "FolderHierarchy.ServerId"))
+        if not server_id:
+            raise ProtocolError("FolderCreate: no ServerId in response")
+        return Folder(id=server_id, parent_id=parent_id, type=type, name=display_name)
+
+    def update_folder(self, folder_id: str, display_name: str, parent_id: str = "0") -> None:
+        self._ensure_provisioned()
+        sync_key = self._folder_sync_key()
+        w = WBXMLWriter()
+        w.tag(
+            "FolderHierarchy",
+            "FolderUpdate",
+            children=[
+                wtag("FolderHierarchy", "SyncKey", text=sync_key),
+                wtag("FolderHierarchy", "ServerId", text=folder_id),
+                wtag("FolderHierarchy", "ParentId", text=parent_id),
+                wtag("FolderHierarchy", "DisplayName", text=display_name),
+            ],
+        )
+        resp = self._post("FolderUpdate", w.render())
+        status = text_of(find(WBXMLReader(resp).parse(), "FolderHierarchy.Status"))
+        _check_status("FolderUpdate", status)
+
+    def delete_folder(self, folder_id: str) -> None:
+        self._ensure_provisioned()
+        sync_key = self._folder_sync_key()
+        w = WBXMLWriter()
+        w.tag(
+            "FolderHierarchy",
+            "FolderDelete",
+            children=[
+                wtag("FolderHierarchy", "SyncKey", text=sync_key),
+                wtag("FolderHierarchy", "ServerId", text=folder_id),
+            ],
+        )
+        resp = self._post("FolderDelete", w.render())
+        status = text_of(find(WBXMLReader(resp).parse(), "FolderHierarchy.Status"))
+        _check_status("FolderDelete", status)
+
+    # -- Sync ------------------------------------------------------------------
+
+    def sync_folder(
+        self,
+        folder_id: str,
+        sync_key: str = "0",
+        *,
+        window_size: int = 25,
+        filter_type: str | None = None,
+    ) -> SyncResult:
+        """``Sync`` one collection. Pass ``sync_key="0"`` (the default) to bootstrap.
+
+        A bootstrap request only returns a fresh ``SyncKey``, no items --
+        call again with that key to fetch the actual ``Add``/``Change``/``Delete``
+        entries, exactly as the protocol requires.
+        """
+        self._ensure_provisioned()
+        options = [wtag("AirSync", "FilterType", text=filter_type)] if filter_type else []
+        collection_children = [
+            wtag("AirSync", "SyncKey", text=sync_key),
+            wtag("AirSync", "CollectionId", text=folder_id),
+            wtag("AirSync", "WindowSize", text=str(window_size)),
+        ]
+        if options:
+            collection_children.append(wtag("AirSync", "Options", children=options))
+        w = WBXMLWriter()
+        w.tag(
+            "AirSync",
+            "Sync",
+            children=[
+                wtag(
+                    "AirSync",
+                    "Collections",
+                    children=[wtag("AirSync", "Collection", children=collection_children)],
+                ),
+            ],
+        )
+        resp = self._post("Sync", w.render())
+        nodes = WBXMLReader(resp).parse()
+        status = text_of(find(nodes, "AirSync.Status"))
+        _check_status("Sync", status)
+        new_sync_key = text_of(find(nodes, "AirSync.SyncKey")) or sync_key
+
+        added = [self._sync_item(c) for _, _, c in find_all(nodes, "AirSync.Add")]
+        changed = [self._sync_item(c) for _, _, c in find_all(nodes, "AirSync.Change")]
+        deleted = [
+            sid
+            for _, _, c in find_all(nodes, "AirSync.Delete")
+            if (sid := text_of(find(c, "AirSync.ServerId"))) is not None
+        ]
+        more_available = find(nodes, "AirSync.MoreAvailable") is not None
+        return SyncResult(
+            sync_key=new_sync_key, added=added, changed=changed, deleted=deleted, more_available=more_available
+        )
+
+    @staticmethod
+    def _sync_item(children: list[Node]) -> SyncItem:
+        server_id = text_of(find(children, "AirSync.ServerId")) or ""
+        appdata = find(children, "AirSync.ApplicationData")
+        return SyncItem(server_id=server_id, fields=leaves(appdata[2]) if appdata else {})
+
+    def get_item_estimate(self, folder_id: str, sync_key: str) -> int:
+        """``GetItemEstimate`` needs a real (non-zero) ``SyncKey`` -- bootstrap one via ``sync_folder`` first."""
+        self._ensure_provisioned()
+        w = WBXMLWriter()
+        w.tag(
+            "ItemEstimate",
+            "GetItemEstimate",
+            children=[
+                wtag(
+                    "ItemEstimate",
+                    "Collections",
+                    children=[
+                        wtag(
+                            "ItemEstimate",
+                            "Collection",
+                            children=[
+                                wtag("AirSync", "SyncKey", text=sync_key),
+                                wtag("ItemEstimate", "CollectionId", text=folder_id),
+                            ],
+                        ),
+                    ],
+                ),
+            ],
+        )
+        resp = self._post("GetItemEstimate", w.render())
+        nodes = WBXMLReader(resp).parse()
+        status = text_of(find(nodes, "ItemEstimate.Status"))
+        _check_status("GetItemEstimate", status)
+        estimate = text_of(find(nodes, "ItemEstimate.Estimate"))
+        if estimate is None:
+            raise ProtocolError("GetItemEstimate: no Estimate in response")
+        return int(estimate)
+
+    # -- Items -------------------------------------------------------------------
+
+    def fetch_item(self, folder_id: str, item_id: str, *, body_type: BodyType = BodyType.HTML) -> dict[str, str]:
+        """``ItemOperations`` Fetch: full item properties. Does not mark the item read."""
+        self._ensure_provisioned()
+        w = WBXMLWriter()
+        w.tag(
+            "ItemOperations",
+            "ItemOperations",
+            children=[
+                wtag(
+                    "ItemOperations",
+                    "Fetch",
+                    children=[
+                        wtag("ItemOperations", "Store", text="Mailbox"),
+                        wtag("AirSync", "CollectionId", text=folder_id),
+                        wtag("AirSync", "ServerId", text=item_id),
+                        wtag(
+                            "ItemOperations",
+                            "Options",
+                            children=[
+                                wtag(
+                                    "AirSyncBase",
+                                    "BodyPreference",
+                                    children=[wtag("AirSyncBase", "Type", text=str(int(body_type)))],
+                                ),
+                            ],
+                        ),
+                    ],
+                ),
+            ],
+        )
+        resp = self._post("ItemOperations", w.render())
+        nodes = WBXMLReader(resp).parse()
+        status = text_of(find(nodes, "ItemOperations.Status"))
+        _check_status("ItemOperations", status)
+        props = find(nodes, "ItemOperations.Properties")
+        return leaves(props[2]) if props else {}
+
+    def fetch_attachment(self, file_reference: str) -> bytes:
+        """``ItemOperations`` Fetch by ``FileReference``. Returns decoded attachment bytes."""
+        self._ensure_provisioned()
+        w = WBXMLWriter()
+        w.tag(
+            "ItemOperations",
+            "ItemOperations",
+            children=[
+                wtag(
+                    "ItemOperations",
+                    "Fetch",
+                    children=[
+                        wtag("ItemOperations", "Store", text="Mailbox"),
+                        wtag("AirSyncBase", "FileReference", text=file_reference),
+                    ],
+                ),
+            ],
+        )
+        resp = self._post("ItemOperations", w.render())
+        nodes = WBXMLReader(resp).parse()
+        status = text_of(find(nodes, "ItemOperations.Status"))
+        _check_status("ItemOperations", status)
+        b64 = text_of(find(nodes, "ItemOperations.Data"))
+        return base64.b64decode(b64) if b64 else b""
+
+    def move_item(self, item_id: str, src_folder_id: str, dst_folder_id: str) -> str:
+        """``MoveItems``. Returns the new (destination) ``ServerId``."""
+        self._ensure_provisioned()
+        w = WBXMLWriter()
+        w.tag(
+            "Move",
+            "MoveItems",
+            children=[
+                wtag(
+                    "Move",
+                    "Move",
+                    children=[
+                        wtag("Move", "SrcMsgId", text=item_id),
+                        wtag("Move", "SrcFldId", text=src_folder_id),
+                        wtag("Move", "DstFldId", text=dst_folder_id),
+                    ],
+                ),
+            ],
+        )
+        resp = self._post("MoveItems", w.render())
+        nodes = WBXMLReader(resp).parse()
+        status = text_of(find(nodes, "Move.Status"))
+        _check_status("MoveItems", status)
+        new_id = text_of(find(nodes, "Move.DstMsgId"))
+        if not new_id:
+            raise ProtocolError("MoveItems: no DstMsgId in response")
+        return new_id
+
+    # -- Mail --------------------------------------------------------------------
+
+    def send_mail(self, message: Message, *, save_in_sent_items: bool = True) -> None:
+        """``SendMail``: WBXML ``ComposeMail`` wrapper, MIME embedded as opaque data.
+
+        Protocol v14.1 (what this client negotiates) requires the
+        ``ComposeMail`` WBXML wrapper -- unlike v12.0/12.1, a raw
+        ``message/rfc822`` POST body is rejected.
+        """
+        self._ensure_provisioned()
+        mime_bytes = to_crlf_bytes(message)
+        children = [wtag("ComposeMail", "ClientId", text=uuid.uuid4().hex)]
+        if save_in_sent_items:
+            children.append(wtag("ComposeMail", "SaveInSentItems"))
+        children.append(wtag("ComposeMail", "MIME", opaque=mime_bytes))
+        w = WBXMLWriter()
+        w.tag("ComposeMail", "SendMail", children=children)
+        resp = self._post("SendMail", w.render())
+        if resp:
+            status = text_of(find(WBXMLReader(resp).parse(), "ComposeMail.Status"))
+            _check_status("SendMail", status, _SENDMAIL_STATUS_MEANINGS)
+
+    # -- Device / connectivity ----------------------------------------------------
+
+    def ping(
+        self, folder_id: str, *, folder_class: str = "Email", heartbeat: int = 60, timeout: float | None = None
+    ) -> PingResult:
+        """``Ping``: long-poll for changes on one folder.
+
+        ``timeout`` bounds the client-side wait; it is independent of
+        ``heartbeat`` (the server-side long-poll duration requested).
+        """
+        self._ensure_provisioned()
+        w = WBXMLWriter()
+        w.tag(
+            "Ping",
+            "Ping",
+            children=[
+                wtag("Ping", "HeartbeatInterval", text=str(heartbeat)),
+                wtag(
+                    "Ping",
+                    "Folders",
+                    children=[
+                        wtag(
+                            "Ping",
+                            "Folder",
+                            children=[
+                                wtag("Ping", "Id", text=folder_id),
+                                wtag("Ping", "Class", text=folder_class),
+                            ],
+                        ),
+                    ],
+                ),
+            ],
+        )
+        resp = self._post("Ping", w.render(), timeout=timeout)
+        nodes = WBXMLReader(resp).parse()
+        status = text_of(find(nodes, "Ping.Status")) or ""
+        changed = [
+            sid for _, _, c in find_all(nodes, "Ping.Folder") if (sid := text_of(find(c, "Ping.Id"))) is not None
+        ]
+        return PingResult(status=status, changed_folder_ids=changed)
+
+    # -- Directory / search --------------------------------------------------------
+
+    def resolve_recipients(self, address: str) -> list[Recipient]:
+        """Resolve one address against contacts/GAL."""
+        self._ensure_provisioned()
+        w = WBXMLWriter()
+        w.tag("ResolveRecipients", "ResolveRecipients", children=[wtag("ResolveRecipients", "To", text=address)])
+        resp = self._post("ResolveRecipients", w.render())
+        nodes = WBXMLReader(resp).parse()
+        status = text_of(find(nodes, "ResolveRecipients.Status"))
+        _check_status("ResolveRecipients", status)
+        recipients = []
+        for _, _, children in find_all(nodes, "ResolveRecipients.Recipient"):
+            data = leaves(children)
+            recipients.append(
+                Recipient(
+                    type=data.get("ResolveRecipients.Type"),
+                    display_name=data.get("ResolveRecipients.DisplayName"),
+                    email_address=data.get("ResolveRecipients.EmailAddress"),
+                )
+            )
+        return recipients
+
+    def search_gal(self, query: str, *, max_results: int = 10) -> list[GalEntry]:
+        """GAL (directory) search."""
+        self._ensure_provisioned()
+        w = WBXMLWriter()
+        w.tag(
+            "Search",
+            "Search",
+            children=[
+                wtag(
+                    "Search",
+                    "Store",
+                    children=[
+                        wtag("Search", "Name", text="GAL"),
+                        wtag("Search", "Query", text=query),
+                        wtag("Search", "Options", children=[wtag("Search", "Range", text=f"0-{max_results - 1}")]),
+                    ],
+                ),
+            ],
+        )
+        resp = self._post("Search", w.render())
+        nodes = WBXMLReader(resp).parse()
+        status = text_of(find(nodes, "Search.Status"))
+        _check_status("Search", status)
+        entries = []
+        for _, _, children in find_all(nodes, "Search.Result"):
+            data = leaves(children)
+            entries.append(
+                GalEntry(
+                    display_name=data.get("GAL.DisplayName"),
+                    email_address=data.get("GAL.EmailAddress"),
+                    phone=data.get("GAL.Phone"),
+                    office=data.get("GAL.Office"),
+                    title=data.get("GAL.Title"),
+                    company=data.get("GAL.Company"),
+                    alias=data.get("GAL.Alias"),
+                    first_name=data.get("GAL.FirstName"),
+                    last_name=data.get("GAL.LastName"),
+                    home_phone=data.get("GAL.HomePhone"),
+                    mobile_phone=data.get("GAL.MobilePhone"),
+                )
+            )
+        return entries
+
+    def search_mailbox(
+        self,
+        folder_id: str,
+        *,
+        date_received_after: str,
+        item_class: str = "Email",
+        max_results: int = 10,
+    ) -> list[dict[str, str]]:
+        """Structured mailbox search: items of ``item_class`` in ``folder_id``
+        received after ``date_received_after`` (an ``AirSyncBase``-style UTC
+        timestamp, e.g. ``"2020-01-01T00:00:00.000Z"``).
+
+        There is deliberately no ``free_text=`` parameter: full-text search
+        conditions in ``Search`` are known to fail against real servers
+        with ``Store.Status=110`` (a server-side bug, not a WBXML encoding
+        issue -- confirmed by cross-checking the same mailbox's content
+        index through an unrelated protocol). Shipping that parameter would
+        just reproduce the failure for every caller; only the structured
+        condition below is exposed.
+        """
+        self._ensure_provisioned()
+        w = WBXMLWriter()
+        w.tag(
+            "Search",
+            "Search",
+            children=[
+                wtag(
+                    "Search",
+                    "Store",
+                    children=[
+                        wtag("Search", "Name", text="Mailbox"),
+                        wtag(
+                            "Search",
+                            "Query",
+                            children=[
+                                wtag(
+                                    "Search",
+                                    "And",
+                                    children=[
+                                        wtag("AirSync", "Class", text=item_class),
+                                        wtag("AirSync", "CollectionId", text=folder_id),
+                                        wtag(
+                                            "Search",
+                                            "GreaterThan",
+                                            children=[
+                                                wtag("Email", "DateReceived"),
+                                                wtag("Search", "Value", text=date_received_after),
+                                            ],
+                                        ),
+                                    ],
+                                ),
+                            ],
+                        ),
+                        wtag("Search", "Options", children=[wtag("Search", "Range", text=f"0-{max_results - 1}")]),
+                    ],
+                ),
+            ],
+        )
+        resp = self._post("Search", w.render())
+        nodes = WBXMLReader(resp).parse()
+        status = text_of(find(nodes, "Search.Status"))
+        _check_status("Search", status)
+        return [leaves(children) for _, _, children in find_all(nodes, "Search.Result")]

pyactivesync/exceptions.py

@@ -0,0 +1,29 @@
+"""Exception hierarchy for pyactivesync."""
+from __future__ import annotations
+
+
+class EASError(Exception):
+    """Base class for all pyactivesync errors."""
+
+
+class ProtocolError(EASError):
+    """The server response did not match the expected MS-ASCMD/MS-ASWBXML shape."""
+
+
+class StatusError(ProtocolError):
+    """An EAS command returned a non-success ``Status`` code.
+
+    ``code`` is the raw status string from the response (e.g. ``"110"``);
+    ``meaning`` is a short human-readable label where known, else ``None``.
+    """
+
+    def __init__(self, command: str, code: str, meaning: str | None = None) -> None:
+        self.command = command
+        self.code = code
+        self.meaning = meaning
+        suffix = f" ({meaning})" if meaning else ""
+        super().__init__(f"{command}: Status={code}{suffix}")
+
+
+class ProvisionError(EASError):
+    """Device provisioning failed (policy not acknowledged, no PolicyKey granted, ...)."""