graphmail 1.0.0__py3-none-any.whl

graphmail/__init__.py

@@ -0,0 +1,3 @@
+"""graphmail: extract Microsoft Graph / .eml emails into a local archive."""
+
+__version__ = "1.0.0"

graphmail/auth.py

@@ -0,0 +1,411 @@
+"""Microsoft Graph OAuth: authorization-code flow with refresh-token renewal.
+
+Interactive login defaults to system-browser loopback + PKCE (RFC 8252);
+``--manual`` is the paste-code fallback. A cached refresh token means cron
+never needs a browser again.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import logging
+import os
+import secrets
+import sys
+import threading
+import time
+import webbrowser
+from collections.abc import Callable
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any
+from urllib.parse import parse_qs, urlencode, urlparse
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_SCOPE = ("Mail.Read", "User.Read", "offline_access")
+# Overridable for tests against a mock token endpoint.
+AUTHORITY = os.environ.get(
+    "GRAPHMAIL_AUTHORITY", "https://login.microsoftonline.com"
+).rstrip("/")
+# Manual-paste redirect (register in Entra for --manual).
+NATIVE_CLIENT_REDIRECT = f"{AUTHORITY}/common/oauth2/nativeclient"
+# Entra ignores the port when the registered URI is bare `http://localhost`.
+DEFAULT_AUTH_PORT = 8400
+LOOPBACK_TIMEOUT = 120.0
+# (connect, read) seconds: a stalled token endpoint must not hang a cron job.
+REQUEST_TIMEOUT = (10.0, 60.0)
+
+
+def loopback_redirect(port: int) -> str:
+    """Redirect URI for the loopback listener."""
+    return f"http://localhost:{port}/"
+
+
+def generate_pkce() -> tuple[str, str]:
+    """Return ``(code_verifier, code_challenge)`` for S256 PKCE (RFC 7636)."""
+    verifier = secrets.token_urlsafe(64)
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+    return verifier, challenge
+
+
+@dataclass(frozen=True)
+class OAuthConfig:
+    """Azure AD application credentials and token cache location."""
+
+    client_id: str
+    client_secret: str
+    tenant_id: str
+    scope: tuple[str, ...] = DEFAULT_SCOPE
+    token_path: Path = Path("token.json")
+    redirect_uri: str = NATIVE_CLIENT_REDIRECT
+
+    @property
+    def token_endpoint(self) -> str:
+        return f"{AUTHORITY}/{self.tenant_id}/oauth2/v2.0/token"
+
+    def authorization_url(
+        self,
+        *,
+        redirect_uri: str | None = None,
+        code_challenge: str | None = None,
+        state: str | None = None,
+    ) -> str:
+        params: dict[str, str] = {
+            "client_id": self.client_id,
+            "response_type": "code",
+            "redirect_uri": redirect_uri or self.redirect_uri,
+            "response_mode": "query",
+            "scope": " ".join(self.scope),
+        }
+        if code_challenge is not None:
+            params["code_challenge"] = code_challenge
+            params["code_challenge_method"] = "S256"
+        if state is not None:
+            params["state"] = state
+        return f"{AUTHORITY}/{self.tenant_id}/oauth2/v2.0/authorize?{urlencode(params)}"
+
+
+@dataclass(frozen=True)
+class AuthSession:
+    """An access token with its expiry and the refresh token that renewed it."""
+
+    access_token: str
+    expires_at: float
+    refresh_token: str
+
+
+def load_token(config: OAuthConfig) -> dict[str, Any] | None:
+    """Read the cached token payload, or ``None`` if there is no cache yet."""
+    try:
+        payload: dict[str, Any] = json.loads(
+            config.token_path.read_text(encoding="utf-8")
+        )
+        return payload
+    except FileNotFoundError:
+        return None
+
+
+def save_token(config: OAuthConfig, token_data: dict[str, Any]) -> None:
+    """Persist the token payload to disk."""
+    config.token_path.write_text(json.dumps(token_data), encoding="utf-8")
+
+
+def _session_from_payload(
+    payload: dict[str, Any], fallback_refresh: str | None = None
+) -> AuthSession:
+    return AuthSession(
+        access_token=payload["access_token"],
+        expires_at=time.time() + int(payload["expires_in"]),
+        refresh_token=payload.get("refresh_token") or fallback_refresh or "",
+    )
+
+
+def refresh_access_token(
+    config: OAuthConfig, refresh_token: str | None
+) -> AuthSession | None:
+    """Exchange a refresh token for a new access token; persist with expires_at."""
+    data: dict[str, str] = {
+        "client_id": config.client_id,
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token or "",
+        "scope": " ".join(config.scope),
+    }
+    if config.client_secret:
+        data["client_secret"] = config.client_secret
+    try:
+        response = requests.post(
+            config.token_endpoint, data=data, timeout=REQUEST_TIMEOUT
+        )
+    except requests.RequestException as exc:
+        logger.error("Token refresh failed (network): %s", exc)
+        return None
+    if response.status_code != 200:
+        logger.error("Token refresh failed. You may need to log in again.")
+        return None
+
+    session = _session_from_payload(response.json(), fallback_refresh=refresh_token)
+    save_token(
+        config,
+        {
+            "access_token": session.access_token,
+            "refresh_token": session.refresh_token,
+            "expires_at": session.expires_at,
+        },
+    )
+    return session
+
+
+def _exchange_code(
+    config: OAuthConfig,
+    *,
+    auth_code: str,
+    redirect_uri: str,
+    code_verifier: str,
+) -> AuthSession | None:
+    data: dict[str, str] = {
+        "client_id": config.client_id,
+        "grant_type": "authorization_code",
+        "code": auth_code,
+        "redirect_uri": redirect_uri,
+        "scope": " ".join(config.scope),
+        "code_verifier": code_verifier,
+    }
+    if config.client_secret:
+        data["client_secret"] = config.client_secret
+    try:
+        response = requests.post(
+            config.token_endpoint, data=data, timeout=REQUEST_TIMEOUT
+        )
+    except requests.RequestException as exc:
+        logger.error("Authentication failed (network): %s", exc)
+        return None
+    if response.status_code != 200:
+        logger.error("Authentication failed. Check credentials.")
+        return None
+
+    session = _session_from_payload(response.json())
+    save_token(
+        config,
+        {
+            "access_token": session.access_token,
+            "refresh_token": session.refresh_token,
+            "expires_at": session.expires_at,
+        },
+    )
+    return session
+
+
+def _default_open_url(url: str) -> None:
+    """Open a URL in the browser (looked up at call time, so tests can patch)."""
+    webbrowser.open(url)
+
+
+_LOOPBACK_PAGE = b"""<!doctype html>
+<html><head><title>graphmail</title></head>
+<body style="font-family: sans-serif; margin: 3rem;">
+<h1>Sign-in complete</h1>
+<p>You can close this tab and return to the terminal.</p>
+</body></html>
+"""
+
+
+class _LoopbackResult:
+    """Shared state between the HTTP handler and the waiting authenticate()."""
+
+    def __init__(self, expected_state: str) -> None:
+        self.expected_state = expected_state
+        self.code: str | None = None
+        self.error: str | None = None
+        self.error_description: str | None = None
+        self.event = threading.Event()
+
+
+def _make_handler(result: _LoopbackResult) -> type[BaseHTTPRequestHandler]:
+    class Handler(BaseHTTPRequestHandler):
+        def log_message(self, *_args: object) -> None:
+            # Keep the default stderr access log out of the CLI.
+            return
+
+        def do_GET(self) -> None:  # noqa: N802 (http.server API)
+            query = parse_qs(urlparse(self.path).query)
+            error = query.get("error", [None])[0]
+            if error is not None:
+                result.error = error
+                result.error_description = query.get("error_description", [None])[0]
+            else:
+                result.code = query.get("code", [None])[0]
+                state = query.get("state", [None])[0]
+                if state != result.expected_state:
+                    result.error = "state_mismatch"
+                    result.code = None
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.send_header("Content-Length", str(len(_LOOPBACK_PAGE)))
+            self.end_headers()
+            self.wfile.write(_LOOPBACK_PAGE)
+            result.event.set()
+
+    return Handler
+
+
+def _interactive_code(
+    config: OAuthConfig,
+    *,
+    flow: str,
+    auth_port: int,
+    timeout: float,
+    open_url: Callable[[str], None],
+    prompt: Callable[[str], str],
+) -> tuple[str | None, str, str, str]:
+    """Run the interactive leg; return ``(code, redirect_uri, verifier, error)``."""
+    verifier, challenge = generate_pkce()
+    state = secrets.token_urlsafe(16)
+
+    if flow == "loopback":
+        redirect = loopback_redirect(auth_port)
+        auth_url = config.authorization_url(
+            redirect_uri=redirect, code_challenge=challenge, state=state
+        )
+        result = _LoopbackResult(state)
+        try:
+            server = ThreadingHTTPServer(
+                ("127.0.0.1", auth_port), _make_handler(result)
+            )
+        except OSError as exc:
+            logger.warning(
+                "Loopback port %d unavailable (%s); falling back to manual "
+                "code paste.",
+                auth_port,
+                exc,
+            )
+            flow = "manual"
+        else:
+            thread = threading.Thread(target=server.serve_forever, daemon=True)
+            thread.start()
+            browser_failed = False
+            try:
+                logger.info("Login required: %s", auth_url)
+                open_url(auth_url)
+                if not result.event.wait(timeout):
+                    logger.error(
+                        "Login failed (no redirect received within %.0fs).",
+                        timeout,
+                    )
+                    return None, redirect, verifier, "timeout"
+            except OSError as exc:
+                logger.warning(
+                    "Could not open a browser (%s); falling back to manual "
+                    "code paste.",
+                    exc,
+                )
+                browser_failed = True
+                flow = "manual"
+            finally:
+                server.shutdown()
+                server.server_close()
+                thread.join(timeout=5)
+            if not browser_failed:
+                if result.error is not None:
+                    detail = (
+                        result.error
+                        if result.error_description is None
+                        else f"{result.error}: {result.error_description}"
+                    )
+                    logger.error("Login failed (%s).", detail)
+                    return None, redirect, verifier, result.error
+                if result.code is None:
+                    logger.error("Login failed (no authorization code).")
+                    return None, redirect, verifier, "no_code"
+                return result.code, redirect, verifier, ""
+
+    # Manual / embedded-browser paste flow (also the bind-failure fallback).
+    redirect = NATIVE_CLIENT_REDIRECT
+    auth_url = config.authorization_url(
+        redirect_uri=redirect, code_challenge=challenge, state=state
+    )
+    logger.info("Login required: %s", auth_url)
+    try:
+        open_url(auth_url)
+    except OSError as exc:
+        logger.warning(
+            "Could not open a browser (%s); open the URL above manually "
+            "if needed.",
+            exc,
+        )
+    code = prompt("Enter the authorization code from the browser: ").strip()
+    if not code:
+        return None, redirect, verifier, "empty_code"
+    return code, redirect, verifier, ""
+
+
+def authenticate(
+    config: OAuthConfig,
+    *,
+    flow: str = "loopback",
+    auth_port: int = DEFAULT_AUTH_PORT,
+    timeout: float = LOOPBACK_TIMEOUT,
+    open_url: Callable[[str], None] | None = None,
+    prompt: Callable[[str], str] | None = None,
+) -> AuthSession | None:
+    """Return a valid session: cached, refreshed, or via interactive login.
+
+    ``flow="loopback"`` (default) catches the browser redirect on localhost;
+    ``flow="manual"`` asks the user to paste the code. Loopback falls back
+    to manual if the port is busy or the browser fails to open.
+    """
+    open_fn: Callable[[str], None] = open_url if open_url is not None else _default_open_url
+    prompt_fn: Callable[[str], str] = prompt if prompt is not None else input
+
+    stored = load_token(config)
+    if stored is not None:
+        expires_at = stored.get("expires_at", 0)
+        if time.time() < expires_at:
+            return AuthSession(
+                access_token=stored.get("access_token", ""),
+                expires_at=expires_at,
+                refresh_token=stored.get("refresh_token", ""),
+            )
+        logger.info("Access token expired. Refreshing...")
+        return refresh_access_token(config, stored.get("refresh_token"))
+
+    # First-time authentication.
+    if flow not in ("loopback", "manual"):
+        raise ValueError(f"unknown auth flow: {flow!r}")
+
+    # Cron without a token cache: fail fast instead of hanging for a browser.
+    # Tests inject open_url/prompt and bypass this TTY check.
+    if (
+        flow == "loopback"
+        and open_url is None
+        and prompt is None
+        and not sys.stdin.isatty()
+    ):
+        logger.error(
+            "No cached token and no interactive terminal. "
+            "Run `graphmail login` once to seed token.json."
+        )
+        return None
+
+    code, redirect, verifier, error = _interactive_code(
+        config,
+        flow=flow,
+        auth_port=auth_port,
+        timeout=timeout,
+        open_url=open_fn,
+        prompt=prompt_fn,
+    )
+    if code is None or error:
+        return None
+    return _exchange_code(
+        config,
+        auth_code=code,
+        redirect_uri=redirect,
+        code_verifier=verifier,
+    )