Files
mcp-home/owamail/vendor/exchange_mcp/owa_client.py
T

494 lines
18 KiB
Python

"""Centralized OWA HTTP client for Exchange API.
Extracts and unifies the duplicated request/cookie/session patterns
from all standalone scripts into a single reusable client.
"""
import os
import requests
from pathlib import Path
class SessionExpiredError(Exception):
"""Raised when the OWA session has expired (HTTP 401/440 or HTML redirect)."""
pass
# Map common folder names (English + Russian) to OWA distinguished folder IDs
DISTINGUISHED_FOLDERS = {
"inbox": "inbox",
"входящие": "inbox",
"sent": "sentitems",
"отправленные": "sentitems",
"drafts": "drafts",
"черновики": "drafts",
"deleted": "deleteditems",
"удаленные": "deleteditems",
"junk": "junkemail",
"нежелательная почта": "junkemail",
"outbox": "outbox",
"исходящие": "outbox",
"calendar": "calendar",
"календарь": "calendar",
}
class OWAClient:
"""HTTP client for OWA (Outlook Web Access) JSON API.
Handles cookie loading, CSRF token extraction, request construction,
session expiry detection, and automatic cookie reload on first failure.
"""
def __init__(
self,
cookie_file: str | None = None,
owa_url: str | None = None,
):
self.cookie_file = Path(
cookie_file
or os.environ.get("EXCHANGE_COOKIE_FILE", "")
or str(Path(__file__).parent.parent / "session-cookies.txt")
)
self.owa_url = (
owa_url
or os.environ.get("EXCHANGE_OWA_URL", "")
).rstrip("/")
if not self.owa_url:
raise ValueError(
"OWA URL not configured. Set the EXCHANGE_OWA_URL environment variable."
)
self._cookies: dict[str, str] = {}
self._canary: str = ""
self._session = requests.Session()
self._loaded = False
self.user_email: str = ""
# ------------------------------------------------------------------
# Cookie / session helpers
# ------------------------------------------------------------------
def _load_cookies(self) -> None:
"""Read session-cookies.txt (name=value per line) and extract X-OWA-CANARY."""
if not self.cookie_file.exists():
raise SessionExpiredError(
f"Cookie file not found: {self.cookie_file}. Call the login tool first."
)
raw = self.cookie_file.read_text().strip()
# Detect encrypted cookie file (Fernet tokens start with gAAAAA)
if raw.startswith("gAAAAA"):
raise SessionExpiredError(
"Cookie file is encrypted. Call the login tool to decrypt and restore the session."
)
cookies: dict[str, str] = {}
for line in raw.split("\n"):
if "=" in line:
name, value = line.split("=", 1)
cookies[name] = value
if not cookies:
raise SessionExpiredError("Cookie file is empty. Call the login tool first.")
self._cookies = cookies
self._canary = cookies.get("X-OWA-CANARY", "")
self._session = requests.Session()
self._session.cookies.update(cookies)
self._loaded = True
def _ensure_loaded(self) -> None:
"""Load cookies on first use."""
if not self._loaded:
self._load_cookies()
def reload_cookies(self) -> None:
"""Force-reload cookies from disk (e.g. after re-login).
Preserves the existing in-memory session if reloading fails
(e.g. cookie file is encrypted or missing).
"""
old_cookies = self._cookies
old_canary = self._canary
old_session = self._session
old_loaded = self._loaded
try:
self._loaded = False
self._load_cookies()
except SessionExpiredError:
# Restore previous state to avoid corrupting a valid in-memory session
self._cookies = old_cookies
self._canary = old_canary
self._session = old_session
self._loaded = old_loaded
raise
def load_cookies_from_string(self, cookies_str: str) -> None:
"""Load cookies from a decrypted name=value string (one per line).
Used by the login tool to inject cookies directly into memory
without writing plaintext to disk.
"""
cookies: dict[str, str] = {}
for line in cookies_str.strip().split("\n"):
if "=" in line:
name, value = line.split("=", 1)
cookies[name] = value
if not cookies:
raise SessionExpiredError("No cookies in provided data.")
self._cookies = cookies
self._canary = cookies.get("X-OWA-CANARY", "")
self._session = requests.Session()
self._session.cookies.update(cookies)
self._loaded = True
# ------------------------------------------------------------------
# Core request method
# ------------------------------------------------------------------
def request(self, action: str, payload: dict, *, timeout: int = 30) -> dict:
"""POST to /owa/service.svc?action={action}&EP=1&ID=-1&AC=1.
On session expiry (401, 440, or text/html response), reloads cookies
once and retries. If that also fails, raises SessionExpiredError.
Returns the parsed JSON response dict.
"""
self._ensure_loaded()
for attempt in range(2):
try:
data = self._do_request(action, payload, timeout=timeout)
return data
except SessionExpiredError:
if attempt == 0:
# Try reloading cookies (user may have re-logged in)
try:
self.reload_cookies()
except SessionExpiredError:
pass # Keep in-memory state, retry anyway
else:
raise
# Should not reach here, but just in case
raise SessionExpiredError("Session expired. Run login.py to login again.")
def _do_request(self, action: str, payload: dict, *, timeout: int = 30) -> dict:
"""Execute a single OWA API request (no retry)."""
url = f"{self.owa_url}/owa/service.svc?action={action}&EP=1&ID=-1&AC=1"
# Prefer our explicitly-tracked canary (updated on every response)
# over the session cookie jar, which can hold stale domain-less entries.
canary = self._canary or self._session.cookies.get("X-OWA-CANARY")
headers = {
"Content-Type": "application/json; charset=utf-8",
"Action": action,
"X-OWA-CANARY": canary,
"X-Requested-With": "XMLHttpRequest",
}
try:
resp = self._session.post(url, json=payload, headers=headers, timeout=timeout)
except requests.exceptions.RequestException as exc:
raise SessionExpiredError(f"Request failed: {exc}") from exc
# Keep cached canary in sync if OWA rotated it
new_canary = resp.cookies.get("X-OWA-CANARY")
if new_canary:
self._canary = new_canary
self._session.cookies.set("X-OWA-CANARY", new_canary)
# Detect session expiry
if resp.status_code in (401, 440):
raise SessionExpiredError("Session expired (HTTP {}).".format(resp.status_code))
if "text/html" in resp.headers.get("Content-Type", ""):
# Extract a snippet from HTML for diagnostics (login redirects vs API errors)
body_snippet = resp.text[:300] if resp.text else ""
raise SessionExpiredError(
f"Session expired or invalid action (HTML response, HTTP {resp.status_code}). "
f"Snippet: {body_snippet}"
)
# Parse JSON
try:
return resp.json()
except (ValueError, requests.exceptions.JSONDecodeError) as exc:
raise SessionExpiredError(
f"Unexpected response (HTTP {resp.status_code}). "
"Session may have expired."
) from exc
def request_header_payload(
self, action: str, payload: dict, *, timeout: int = 30
) -> dict:
"""POST with payload in x-owa-urlpostdata header (empty body).
Some OWA actions (CreateFolder, DeleteFolder, RenameFolder, etc.)
require the JSON payload to be sent as a URL-encoded string in the
``x-owa-urlpostdata`` header instead of the POST body. This method
handles that pattern with the same retry logic as ``request()``.
"""
self._ensure_loaded()
for attempt in range(2):
try:
return self._do_request_header_payload(
action, payload, timeout=timeout
)
except SessionExpiredError:
if attempt == 0:
try:
self.reload_cookies()
except SessionExpiredError:
pass
else:
raise
raise SessionExpiredError("Session expired. Run login.py to login again.")
def _do_request_header_payload(
self, action: str, payload: dict, *, timeout: int = 30
) -> dict:
"""Execute a single OWA API request with payload in header."""
import json as _json
from urllib.parse import quote
url = f"{self.owa_url}/owa/service.svc?action={action}&EP=1&ID=-1&AC=1"
canary = self._canary or self._session.cookies.get("X-OWA-CANARY")
url_post_data = quote(_json.dumps(payload, separators=(",", ":")))
headers = {
"Content-Type": "application/json; charset=UTF-8",
"Action": action,
"X-OWA-CANARY": canary,
"X-OWA-UrlPostData": url_post_data,
"X-Requested-With": "XMLHttpRequest",
}
try:
resp = self._session.post(url, headers=headers, timeout=timeout)
except requests.exceptions.RequestException as exc:
raise SessionExpiredError(f"Request failed: {exc}") from exc
new_canary = resp.cookies.get("X-OWA-CANARY")
if new_canary:
self._canary = new_canary
self._session.cookies.set("X-OWA-CANARY", new_canary)
if resp.status_code in (401, 440):
raise SessionExpiredError(
"Session expired (HTTP {}).".format(resp.status_code)
)
if "text/html" in resp.headers.get("Content-Type", ""):
body_snippet = resp.text[:300] if resp.text else ""
raise SessionExpiredError(
f"Session expired or invalid action (HTML response, HTTP {resp.status_code}). "
f"Snippet: {body_snippet}"
)
try:
return resp.json()
except (ValueError, requests.exceptions.JSONDecodeError) as exc:
raise SessionExpiredError(
f"Unexpected response (HTTP {resp.status_code}). "
"Session may have expired."
) from exc
# ------------------------------------------------------------------
# File download (attachments)
# ------------------------------------------------------------------
def download_file(
self, attachment_id: str, *, timeout: int = 60
) -> tuple[bytes, str, str]:
"""Download a file attachment by its AttachmentId.
Uses the OWA GetFileAttachment endpoint (direct GET).
Returns:
(content_bytes, filename, content_type)
"""
self._ensure_loaded()
from urllib.parse import quote
canary = self._canary or self._session.cookies.get("X-OWA-CANARY")
url = (
f"{self.owa_url}/owa/service.svc/s/GetFileAttachment"
f"?id={quote(attachment_id)}&X-OWA-CANARY={quote(canary)}"
)
try:
resp = self._session.get(url, timeout=timeout)
except requests.exceptions.RequestException as exc:
raise SessionExpiredError(f"Download failed: {exc}") from exc
if resp.status_code in (401, 440):
raise SessionExpiredError(
f"Session expired (HTTP {resp.status_code})."
)
if "text/html" in resp.headers.get("Content-Type", ""):
raise SessionExpiredError(
"Session expired (HTML response on attachment download)."
)
# Parse filename from Content-Disposition header
filename = "attachment"
cd = resp.headers.get("Content-Disposition", "")
if cd:
import re as _re
from urllib.parse import unquote
# Try filename*= (RFC 5987) first, then filename=
match = _re.search(r"filename\*=(?:UTF-8''|utf-8'')(.+?)(?:;|$)", cd)
if match:
filename = unquote(match.group(1).strip())
else:
match = _re.search(r'filename="?([^";]+)"?', cd)
if match:
filename = unquote(match.group(1).strip())
content_type = resp.headers.get("Content-Type", "application/octet-stream")
return resp.content, filename, content_type
# ------------------------------------------------------------------
# Convenience: extract response items
# ------------------------------------------------------------------
@staticmethod
def extract_items(data: dict) -> list[dict]:
"""Extract Items from standard OWA response envelope.
Response shape: data["Body"]["ResponseMessages"]["Items"]
"""
try:
return data["Body"]["ResponseMessages"]["Items"]
except (KeyError, TypeError):
return []
# ------------------------------------------------------------------
# Folder helpers
# ------------------------------------------------------------------
def get_folder_id(self, folder_name: str) -> str | None:
"""Resolve a folder name to its Exchange folder ID.
Supports distinguished folder names (inbox, sentitems, drafts, etc.)
in both English and Russian, plus custom folder names looked up
via FindFolder on msgfolderroot.
"""
folder_lower = folder_name.lower()
# Check distinguished folders first
distinguished_id = DISTINGUISHED_FOLDERS.get(folder_lower)
if distinguished_id:
payload = {
"__type": "GetFolderJsonRequest:#Exchange",
"Header": {
"__type": "JsonRequestHeaders:#Exchange",
"RequestServerVersion": "Exchange2013",
},
"Body": {
"__type": "GetFolderRequest:#Exchange",
"FolderShape": {
"__type": "FolderResponseShape:#Exchange",
"BaseShape": "IdOnly",
},
"FolderIds": [
{
"__type": "DistinguishedFolderId:#Exchange",
"Id": distinguished_id,
}
],
},
}
data = self.request("GetFolder", payload)
for msg in self.extract_items(data):
if "Folders" in msg:
for f in msg["Folders"]:
fid = f.get("FolderId", {}).get("Id")
if fid:
return fid
# Fall back to searching custom folders by name
payload = {
"__type": "FindFolderJsonRequest:#Exchange",
"Header": {
"__type": "JsonRequestHeaders:#Exchange",
"RequestServerVersion": "Exchange2013",
},
"Body": {
"__type": "FindFolderRequest:#Exchange",
"FolderShape": {
"__type": "FolderResponseShape:#Exchange",
"BaseShape": "Default",
},
"ParentFolderIds": [
{
"__type": "DistinguishedFolderId:#Exchange",
"Id": "msgfolderroot",
}
],
"Traversal": "Shallow",
"Paging": {
"__type": "IndexedPageView:#Exchange",
"BasePoint": "Beginning",
"Offset": 0,
"MaxEntriesReturned": 200,
},
},
}
data = self.request("FindFolder", payload)
for msg in self.extract_items(data):
if "RootFolder" in msg and "Folders" in msg["RootFolder"]:
for f in msg["RootFolder"]["Folders"]:
if f.get("DisplayName", "").lower() == folder_lower:
return f.get("FolderId", {}).get("Id")
return None
# ------------------------------------------------------------------
# ResolveNames (directory search / attendee resolution)
# ------------------------------------------------------------------
def resolve_names(
self, query: str, *, full_contact: bool = True
) -> list[dict]:
"""Call ResolveNames to search the directory.
Returns the list of Resolution dicts from the API, each containing
Mailbox and optionally Contact data.
"""
payload = {
"__type": "ResolveNamesJsonRequest:#Exchange",
"Header": {
"__type": "JsonRequestHeaders:#Exchange",
"RequestServerVersion": "Exchange2013",
},
"Body": {
"__type": "ResolveNamesRequest:#Exchange",
"UnresolvedEntry": query,
"ReturnFullContactData": full_contact,
"SearchScope": "ActiveDirectoryContacts",
"ContactDataShape": "AllProperties" if full_contact else "Default",
},
}
data = self.request("ResolveNames", payload)
for msg in self.extract_items(data):
if "ResolutionSet" in msg and "Resolutions" in msg["ResolutionSet"]:
return msg["ResolutionSet"]["Resolutions"]
return []