494 lines
18 KiB
Python
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 []
|