sharefetch 1.0.0__py3-none-any.whl

sharefetch/__init__.py

@@ -0,0 +1,11 @@
+"""Resumable, rate-limited downloads from Microsoft Graph drives.
+
+The package mirrors a SharePoint or OneDrive drive to local storage over the
+Microsoft Graph API. Transfers resume from a state file after an interruption,
+requests are throttled to stay inside the service limits, and no download path
+removes user data: a failed or partial transfer leaves its file on disk.
+"""
+
+__version__ = "1.0.0"
+
+__all__ = ["__version__"]

sharefetch/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for ``python -m sharefetch``."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

sharefetch/auth.py

@@ -0,0 +1,343 @@
+"""Device-code sign-in and access-token supply for one run.
+
+:class:`TokenProvider` owns the msal public client application and is the only
+place in the package that holds an access token. ``GraphClient`` calls
+:meth:`TokenProvider.get_token` before every request, so the token this module
+returns is the single credential the run uses.
+
+Three properties hold here and are the reason the module exists:
+
+* One refresh at a time. ``get_token`` takes a re-entrant lock and re-checks the
+  cached token after taking it, so two workers reaching expiry together produce
+  one refresh and one sign-in.
+* No token in a log. No logging call in this module receives a flow dict, a
+  result dict, an access token, a refresh token or a device code. Account
+  identifiers and exception class names are logged, and nothing else.
+* Responsive cancellation. :meth:`TokenProvider.cancel` sets the event that
+  msal's polling loop tests once per second, so a cancelled sign-in stops
+  without waiting for the device code to expire.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from collections.abc import Callable
+from typing import Any, Protocol
+
+import msal
+import requests
+
+from .config import AUTHORITY_TEMPLATE, MSAL_SCOPES
+from .errors import AuthError
+from .events import DeviceCodeCompleted, DeviceCodeRequested, EventSink
+from .tokencache import build_cache
+
+logger = logging.getLogger(__name__)
+
+# msal treats an access token with less than five minutes of life left as
+# expired and refreshes it (application.py:1762). The copy cached here goes
+# stale at the same point, so this layer never hands out a token msal itself
+# would decline to reuse. The value mirrors a library fact rather than tuning a
+# bound, so it stays beside the one calculation that reads it.
+_EXPIRY_MARGIN_SECONDS = 5 * 60
+
+# Exceptions msal lets through from the network layer, the token cache and a
+# malformed identity-provider response. A silent refresh that raises one of
+# these falls back to the device flow; an interactive acquisition that raises
+# one is terminal for the run.
+_MSAL_FAILURES = (ValueError, KeyError, OSError, requests.RequestException)
+
+_UNKNOWN_ACCOUNT = "an unidentified account"
+_CANCELLED = "the sign-in was cancelled"
+_EXPIRED = "the device code expired before it was entered"
+_REFUSED = "the identity provider refused the sign-in"
+_REQUEST_REFUSED = "the device authorization request was refused"
+
+
+class MsalApplication(Protocol):
+    """The part of ``msal.PublicClientApplication`` this module uses.
+
+    Naming it keeps the dependency on msal to four calls and lets a test supply
+    an application that completes a flow without a network or a real sign-in.
+    """
+
+    def get_accounts(self) -> list[dict[str, Any]]: ...
+
+    def acquire_token_silent(
+        self, scopes: list[str], account: dict[str, Any] | None = None
+    ) -> dict[str, Any] | None: ...
+
+    def initiate_device_flow(self, scopes: list[str] | None = None) -> dict[str, Any]: ...
+
+    def acquire_token_by_device_flow(
+        self, flow: dict[str, Any], **kwargs: Any
+    ) -> dict[str, Any]: ...
+
+
+def _as_float(value: object, default: float) -> float:
+    """Return ``value`` as a float, or ``default`` where it is not numeric."""
+    if isinstance(value, bool) or not isinstance(value, (int, float, str)):
+        return default
+    try:
+        return float(value)
+    except ValueError:
+        return default
+
+
+def _description(payload: object) -> str:
+    """Return the identity provider's own account of a refusal, verbatim.
+
+    Returns the empty string where the payload carries neither key, so a caller
+    can state its own reason without appending an invented one.
+    """
+    if not isinstance(payload, dict):
+        return ""
+    for key in ("error_description", "error"):
+        value = payload.get(key)
+        if isinstance(value, str) and value.strip():
+            return value
+    return ""
+
+
+def _refusal(reason: str, payload: object) -> str:
+    """Compose an error message carrying the server's description unaltered."""
+    description = _description(payload)
+    return f"{reason}: {description}" if description else reason
+
+
+def _account_label(payload: object) -> str:
+    """Return a human-readable identifier for the signed-in account.
+
+    Accepts either an account entry from the cache or a token result. Carries no
+    credential: the keys read are an identifier, never token material.
+    """
+    if isinstance(payload, dict):
+        for key in ("username", "home_account_id"):
+            value = payload.get(key)
+            if isinstance(value, str) and value.strip():
+                return value
+        claims = payload.get("id_token_claims")
+        if isinstance(claims, dict):
+            for key in ("preferred_username", "upn", "sub"):
+                value = claims.get(key)
+                if isinstance(value, str) and value.strip():
+                    return value
+    return _UNKNOWN_ACCOUNT
+
+
+def _access_token(result: object) -> str | None:
+    """Return the access token in ``result``, or ``None`` where there is none."""
+    if not isinstance(result, dict):
+        return None
+    token = result.get("access_token")
+    if isinstance(token, str) and token:
+        return token
+    return None
+
+
+class TokenProvider:
+    """Supplies the access token for every Graph request made by one run.
+
+    The provider is shared by every worker thread and is safe to call from all
+    of them. ``client_id`` and ``tenant`` are validated by ``config`` before
+    they arrive here.
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        tenant: str,
+        sink: EventSink,
+        reauth: bool = False,
+        *,
+        app: MsalApplication | None = None,
+        clock: Callable[[], float] = time.time,
+    ) -> None:
+        """Build the provider and its msal application.
+
+        ``reauth`` skips the cached account once, so the first acquisition of the
+        run is interactive. ``app`` and ``clock`` exist so a test can drive the
+        flow without a network, a real sign-in or a real wait.
+        """
+        self._sink = sink
+        self._reauth = reauth
+        self._clock = clock
+        self._lock = threading.RLock()
+        self._cancelled = threading.Event()
+        # One tuple, so a reader outside the lock never observes a token paired
+        # with the expiry of a different token.
+        self._cached: tuple[str, float] | None = None
+        self._generation = 0
+        self._app: MsalApplication = (
+            app
+            if app is not None
+            else msal.PublicClientApplication(
+                client_id,
+                authority=AUTHORITY_TEMPLATE.format(tenant=tenant),
+                token_cache=build_cache(),
+            )
+        )
+
+    def get_token(self, force_refresh: bool = False) -> str:
+        """Return an access token, refreshing or signing in where required.
+
+        ``force_refresh`` discards the cached token, which is how a ``401``
+        mid-transfer is answered. A forced refresh that arrives while another
+        worker is already refreshing returns that worker's new token instead of
+        starting a second refresh.
+
+        Raises :class:`~sharefetch.errors.AuthError` where the sign-in is
+        refused, expires or is cancelled.
+        """
+        generation = self._generation
+        if not force_refresh:
+            cached = self._cached_token()
+            if cached is not None:
+                return cached
+        with self._lock:
+            refreshed_meanwhile = self._generation != generation
+            if refreshed_meanwhile or not force_refresh:
+                cached = self._cached_token()
+                if cached is not None:
+                    return cached
+            return self._acquire()
+
+    def cancel(self) -> None:
+        """Stop a device-code poll in progress.
+
+        msal tests the exit condition once per second, so a poll stops within
+        about a second of this call. A provider that has been cancelled refuses
+        every later interactive acquisition.
+        """
+        self._cancelled.set()
+        logger.info("sign-in cancellation requested")
+
+    def _cached_token(self) -> str | None:
+        """Return the cached access token while it remains usable."""
+        cached = self._cached
+        if cached is None:
+            return None
+        token, expires_at = cached
+        if self._clock() < expires_at:
+            return token
+        return None
+
+    def _acquire(self) -> str:
+        """Acquire a token silently where possible and interactively otherwise.
+
+        Called with the lock held. Drops the cached token first, so a failure
+        never leaves a stale token behind for the next caller to hand out.
+        """
+        self._cached = None
+        result = None if self._reauth else self._acquire_silent()
+        if result is None:
+            result = self._acquire_by_device_code()
+        token = _access_token(result)
+        if token is None:
+            raise AuthError(_refusal(_REFUSED, result))
+        lifetime = _as_float(result.get("expires_in"), 0.0)
+        self._cached = (token, self._clock() + max(0.0, lifetime - _EXPIRY_MARGIN_SECONDS))
+        self._generation += 1
+        return token
+
+    def _acquire_silent(self) -> dict[str, Any] | None:
+        """Refresh from the token cache, or return ``None`` to sign in again.
+
+        Every failure here is recoverable: the device flow follows and costs the
+        user one code entry.
+        """
+        try:
+            accounts = self._app.get_accounts()
+        except _MSAL_FAILURES as exc:
+            logger.warning(
+                "the token cache could not be read (%s); a device code sign-in follows",
+                type(exc).__name__,
+            )
+            return None
+        if not accounts:
+            logger.debug("no account in the token cache; a device code sign-in follows")
+            return None
+        account = accounts[0]
+        label = _account_label(account)
+        try:
+            result = self._app.acquire_token_silent(list(MSAL_SCOPES), account=account)
+        except _MSAL_FAILURES as exc:
+            logger.warning(
+                "the silent refresh for %s failed (%s); a device code sign-in follows",
+                label,
+                type(exc).__name__,
+            )
+            return None
+        if _access_token(result) is None:
+            logger.info(
+                "the cached grant for %s no longer yields a token; a device code sign-in follows",
+                label,
+            )
+            return None
+        logger.debug("refreshed the access token for %s without interaction", label)
+        return result
+
+    def _acquire_by_device_code(self) -> dict[str, Any]:
+        """Run the device authorization grant to completion.
+
+        Emits :class:`~sharefetch.events.DeviceCodeRequested` once the code is
+        available and :class:`~sharefetch.events.DeviceCodeCompleted` once the
+        user has entered it. Raises :class:`~sharefetch.errors.AuthError` on a
+        refusal, an expiry or a cancellation.
+        """
+        if self._cancelled.is_set():
+            raise AuthError(_CANCELLED)
+        flow = self._initiate()
+        self._sink.emit(
+            DeviceCodeRequested(
+                user_code=str(flow["user_code"]),
+                verification_uri=str(flow.get("verification_uri", "")),
+                message=str(flow.get("message", "")),
+                expires_at=_as_float(flow.get("expires_at"), 0.0),
+            )
+        )
+        logger.info("a device code sign-in is required; the front end is displaying the code")
+        try:
+            result = self._app.acquire_token_by_device_flow(
+                flow, exit_condition=self._exit_condition
+            )
+        except _MSAL_FAILURES as exc:
+            raise AuthError(f"{_REFUSED}: {type(exc).__name__}") from exc
+        if _access_token(result) is None:
+            raise AuthError(self._failure_message(flow, result))
+        label = _account_label(result)
+        logger.info("the device code sign-in completed for %s", label)
+        self._sink.emit(DeviceCodeCompleted(account=label))
+        # --reauth applies to the first acquisition only, so a refresh later in
+        # the run does not demand a second code.
+        self._reauth = False
+        return result
+
+    def _initiate(self) -> dict[str, Any]:
+        """Request a device code, or raise where the request is refused."""
+        try:
+            flow = self._app.initiate_device_flow(scopes=list(MSAL_SCOPES))
+        except _MSAL_FAILURES as exc:
+            raise AuthError(f"{_REQUEST_REFUSED}: {type(exc).__name__}") from exc
+        if not isinstance(flow, dict) or not flow.get("user_code"):
+            raise AuthError(_refusal(_REQUEST_REFUSED, flow))
+        return flow
+
+    def _failure_message(self, flow: dict[str, Any], result: object) -> str:
+        """Name why the device flow ended without a token.
+
+        A cancelled or expired poll returns msal's last pending response, whose
+        description describes the poll and not the outcome, so the reason is
+        stated here and the server's description is appended unaltered.
+        """
+        if self._cancelled.is_set():
+            return _CANCELLED
+        if _as_float(flow.get("expires_at"), 0.0) < self._clock():
+            return _refusal(_EXPIRED, result)
+        return _refusal(_REFUSED, result)
+
+    def _exit_condition(self, flow: dict[str, Any]) -> bool:
+        """Tell msal's polling loop to stop. Tested once per second."""
+        return self._cancelled.is_set() or _as_float(flow.get("expires_at"), 0.0) < self._clock()