pyoncat 2.5__tar.gz → 2.6__tar.gz

{pyoncat-2.5 → pyoncat-2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyoncat
-Version: 2.5
+Version: 2.6
 Summary: A Python Client for ONCat (the ORNL Neutron Catalog).
 Keywords: ornl,neutron,metadata,catalog
 Author: ONCat Support

{pyoncat-2.5 → pyoncat-2.6}/pyoncat/__init__.py

@@ -18,7 +18,8 @@ import sys
 import time
 import warnings
 import weakref
-from typing import TYPE_CHECKING, Any, Callable, ClassVar, Literal
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Callable, ClassVar, Literal, Union
 from urllib.parse import quote
 
 import oauthlib.oauth2
@@ -30,7 +31,10 @@ from urllib3.exceptions import InsecureRequestWarning
 
 from pyoncat.reduction import ReductionFileBuilder
 
-__version__ = "2.5"
+if TYPE_CHECKING:
+    import threading
+
+__version__ = "2.6"
 
 # Constant for autoreduction user
 AUTOREDUCTION_USER = "auto"
@@ -39,8 +43,19 @@ __all__ = [
     "AUTOREDUCTION_USER",
     "CLIENT_CREDENTIALS_FLOW",
     "DEVICE_AUTHORIZATION_FLOW",
+    "REAUTH_INTERACTION_REQUIRED",
+    "REAUTH_NEVER",
+    "REAUTH_PROMPT",
     "RESOURCE_OWNER_CREDENTIALS_FLOW",
+    "DeviceAuthorizationCancelled",
+    "DeviceAuthorizationChallenge",
+    "DeviceAuthorizationDenied",
+    "DeviceAuthorizationError",
+    "DeviceAuthorizationExpired",
+    "DeviceAuthorizationNetworkError",
+    "DeviceAuthorizationTimeout",
     "FileSystemTokenStore",
+    "InteractionRequiredError",
     "ONCat",
     "ONCatObject",
     "PyONCatError",
@@ -66,6 +81,50 @@ DEVICE_AUTHORIZATION_FLOW: FlowType = "device_authorization"
 
 assert isinstance(CLIENT_CREDENTIALS_FLOW, str)
 
+# Named `reauth_on_expired` modes selecting how the Device Authorization
+# Grant recovers when the refresh token has expired. These string
+# constants are the canonical, documented way to select a mode; the
+# legacy `True`/`False` booleans remain accepted and are normalized to
+# `REAUTH_NEVER` at the constructor boundary.
+#
+# - `REAUTH_PROMPT`: re-run the Device Authorization Grant (re-prompt)
+#   on expiry, then retry the original request once. Equivalent to
+#   the legacy `True`.
+# - `REAUTH_NEVER`: raise on expiry without re-authenticating, for
+#   unattended / non-interactive callers. Equivalent to the legacy `False`.
+# - `REAUTH_INTERACTION_REQUIRED`: attempt a silent refresh and, if the
+#   refresh token itself is dead, raise `InteractionRequiredError` rather
+#   than re-running `login()` from inside an ordinary API call. Its value
+#   stays the literal `"raise"` for backward compatibility.
+ReauthMode = Literal["prompt", "never", "raise"]
+ReauthOnExpired = Union[bool, ReauthMode]
+REAUTH_PROMPT: ReauthMode = "prompt"
+REAUTH_NEVER: ReauthMode = "never"
+REAUTH_INTERACTION_REQUIRED: ReauthMode = "raise"
+
+
+def _normalize_reauth_on_expired(value: ReauthOnExpired) -> ReauthMode:
+    """Map a `reauth_on_expired` argument onto a canonical `ReauthMode`.
+
+    Accepts the legacy booleans (`True` -> `REAUTH_PROMPT`, `False` ->
+    `REAUTH_NEVER`) for backward compatibility alongside the named string
+    constants, so the dispatch logic only ever compares against the
+    `REAUTH_*` constants.
+    """
+    if value is True:
+        return REAUTH_PROMPT
+    if value is False:
+        return REAUTH_NEVER
+    if value in {REAUTH_PROMPT, REAUTH_NEVER, REAUTH_INTERACTION_REQUIRED}:
+        return value
+    msg = (
+        "reauth_on_expired must be one of REAUTH_PROMPT, REAUTH_NEVER, "
+        "REAUTH_INTERACTION_REQUIRED (or the legacy True/False), "
+        f"not {value!r}."
+    )
+    raise ValueError(msg)
+
+
 # RFC 8628 §3.5 default polling interval (seconds), used when the device
 # authorization response does not specify one.
 _DEFAULT_DEVICE_FLOW_INTERVAL = 5
@@ -83,6 +142,68 @@ _DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code"
 # `oncat_cli_user` client.
 _DEFAULT_IDP_URL = "https://extidp.ornl.gov"
 
+# Finite default connect/read timeout (seconds) for the two
+# device-authorization HTTP POSTs (the authorization request and the token
+# poll). The general `self._timeout` defaults to `None` (wait
+# indefinitely), which is the right semantics for ordinary API calls but a
+# footgun for the device-authorization poll loop: a hung IdP connection
+# would block the loop forever. This bounds each individual POST so a
+# stalled connection backs off and the loop keeps polling within the
+# overall deadline instead of hanging. It is distinct from both
+# `self._timeout` (per-API-request) and `device_authorization_timeout`
+# (the overall caller deadline). Override per call via the `http_timeout`
+# argument to `login()`.
+_DEFAULT_DEVICE_AUTHORIZATION_HTTP_TIMEOUT = 30.0
+
+
+@dataclass(frozen=True)
+class DeviceAuthorizationChallenge:
+    """The user-facing details of a Device Authorization Grant challenge.
+
+    The Device Authorization Grant (often called the device flow) is the
+    OAuth 2.0 sign-in defined by RFC 8628. PyONCat passes one of these to
+    a configured `verification_handler`
+    whenever the user needs to approve a sign-in (RFC 8628 §3.2). The app
+    shows the user the link (and, if needed, the code) so they can approve
+    in a browser.
+
+    Attributes
+    ----------
+        verification_uri: str
+            The URL the user opens to approve the sign-in. Show this (with
+            `user_code`) when `verification_uri_complete` is `None`.
+
+        user_code: str
+            The one-time code the user enters at `verification_uri`.
+
+        verification_uri_complete: str | None
+            A ready-to-use link that already embeds `user_code` (RFC 8628
+            §3.3.1; OPTIONAL). Prefer showing this when present.
+
+        expires_in: int | None
+            Seconds, from when the challenge was issued, after which the
+            device code expires (RFC 8628 §3.2). `None` if the IdP omitted
+            it.
+
+        interval: float
+            The minimum number of seconds to wait between token polls
+            (RFC 8628 §3.2).
+
+        expires_at: float | None
+            The monotonic-clock deadline (`time.monotonic()` basis) after
+            which the challenge expires, derived from `expires_in` at the
+            moment the challenge was created. `None` when `expires_in` is
+            absent.
+
+    """
+
+    verification_uri: str
+    user_code: str
+    verification_uri_complete: str | None
+    expires_in: int | None
+    interval: float
+    expires_at: float | None
+
 
 _DEVICE_FLOW_REFRESH_EXPIRED_MESSAGE = (
     "Your ONCat session has expired and could not be automatically "
@@ -98,11 +219,11 @@ _DEVICE_FLOW_REFRESH_EXPIRED_MESSAGE = (
     "\n\n"
     "If you want PyONCat to prompt you to re-authenticate automatically "
     "when this\n"
-    "happens, construct the client with `reauth_on_expired=True` (the "
-    "default).\n"
+    "happens, construct the client with "
+    "`reauth_on_expired=REAUTH_PROMPT` (the default).\n"
     "\n"
-    "Set `reauth_on_expired=False` for unattended / non-interactive use, "
-    "in which\n"
+    "Set `reauth_on_expired=REAUTH_NEVER` for unattended / "
+    "non-interactive use, in which\n"
     "case this exception is raised immediately on session expiry."
 )
 
@@ -218,14 +339,46 @@ class ONCat:
             hit the IdP directly.  When `None`, defaults to
             `https://extidp.ornl.gov` (ORNL's external PingFed).
 
-        reauth_on_expired: bool
+        reauth_on_expired: ReauthOnExpired
             When using `DEVICE_AUTHORIZATION_FLOW` and the refresh
-            token has expired, controls how the client recovers.
-            `True` (the default) prompts on stderr for the user to
-            press Enter to re-authenticate via the browser, then
-            retries the original request once.  `False` raises
+            token has expired, controls how the client recovers.  Select
+            a mode with one of the named constants (the canonical form);
+            the legacy `True`/`False` booleans are still accepted and map
+            to `REAUTH_PROMPT` / `REAUTH_NEVER` respectively.
+            `REAUTH_PROMPT` (the default) prompts on stderr for the user
+            to press Enter to re-authenticate via the browser, then
+            retries the original request once.  `REAUTH_NEVER` raises
             `InvalidRefreshTokenError` immediately, which is
             appropriate for unattended or non-interactive use.
+            `REAUTH_INTERACTION_REQUIRED` first attempts a silent
+            refresh and, only if the refresh token itself is dead,
+            raises `InteractionRequiredError` rather than re-running
+            `login()` (and firing the verification callback) from
+            inside an ordinary API call.  This lets a GUI decide *when*
+            to prompt the user instead of having a data call pop a
+            sign-in dialog from a worker thread.
+
+        verification_handler:
+            Callable[[DeviceAuthorizationChallenge], None] | None
+            A function PyONCat calls whenever the user needs to sign in -
+            on the first login and again later if the session expires.
+            It receives a single `DeviceAuthorizationChallenge` carrying the
+            verification URI, user code, complete URI, expiry, and
+            polling interval, so the app has everything it needs (e.g.
+            to show a code-expiry countdown).  Your function is
+            responsible for displaying the sign-in link to the user, who
+            opens it in a browser to approve the sign-in:
+
+            - By default, show `verification_uri_complete`: a ready-to-use
+              link that already includes the code.
+            - If it is `None`, show `verification_uri` instead and have the
+              user enter `user_code` on that page.
+
+            Supplying this callback is what lets sign-in work in a GUI app
+            that has no console.  When it is set, the same callback is
+            reused if the session later needs the user to sign in again, so
+            the app is never left waiting on console input (see
+            `reauth_on_expired`).
 
     """
 
@@ -267,7 +420,9 @@ class ONCat:
         verify: bool = True,
         timeout: int | None = None,
         idp_url: str | None = None,
-        reauth_on_expired: bool = True,
+        reauth_on_expired: ReauthOnExpired = REAUTH_PROMPT,
+        verification_handler: Callable[[DeviceAuthorizationChallenge], None]
+        | None = None,
     ):
         if not url:
             msg = "A URL must be provided."
@@ -306,6 +461,7 @@ class ONCat:
         self._token_getter = token_getter
         self._token_setter = token_setter
         self._login_prompt = login_prompt
+        self._verification_handler = verification_handler
         self._api_token = api_token
         self._client_id = client_id
         self._client_secret = client_secret
@@ -315,7 +471,9 @@ class ONCat:
         self._verify = verify
         self._timeout = timeout
         self._idp_url = idp_url if idp_url is not None else _DEFAULT_IDP_URL
-        self._reauth_on_expired = reauth_on_expired
+        self._reauth_on_expired = _normalize_reauth_on_expired(
+            reauth_on_expired
+        )
 
         self._token = None
         self._oauth_client = None
@@ -325,7 +483,7 @@ class ONCat:
                 "OAuth 2.0 Resource Owner Password Credentials grant is "
                 'deprecated. RFC 9700 §2.4: "The resource owner password '
                 'credentials grant [RFC6749] MUST NOT be used." Prefer '
-                "the device authorization flow "
+                "the Device Authorization Grant "
                 "(flow=DEVICE_AUTHORIZATION_FLOW) for human-user "
                 "authentication. ROPC remains available indefinitely as "
                 "a compatibility path.",
@@ -399,6 +557,20 @@ class ONCat:
 
         try:
             return send_request()
+        except UnauthorizedError as error:
+            # Device Authorization Grant only: a 401 on the data call
+            # means the access token is dead server-side but oauthlib did
+            # not proactively refresh -- e.g. a token persisted without
+            # `expires_at` by an older PyONCat, so the proactive gate
+            # never fired. Attempt exactly ONE silent refresh + ONE retry;
+            # if that still fails, fall through to the expiry handler. The
+            # other flows keep the 2.5 behavior: re-raise the 401
+            # untouched.
+            if self._flow != DEVICE_AUTHORIZATION_FLOW:
+                raise
+            return self._handle_device_authorization_unauthorized(
+                send_request, error
+            )
         except rfc6749.errors.InvalidGrantError as error:
             if (
                 self._flow == RESOURCE_OWNER_CREDENTIALS_FLOW
@@ -441,40 +613,231 @@ class ONCat:
             msg = f'Error: "{error!s}"'
             raise PyONCatError(msg) from error
 
-    def _handle_device_flow_token_expiry(self, send_request, error):
-        """Recover from an expired Device Flow refresh token.
+    def _handle_device_authorization_unauthorized(self, send_request, error):
+        """Bounded reactive recovery from a Device Authorization Grant
+        data-call 401.
+
+        Attempts exactly ONE silent refresh (the `refresh_token` grant via
+        the wired `OAuth2Session`) and ONE retry of the original request.
+        This terminates by construction:
+
+        - The retried `send_request()` is called directly here, NOT through
+          `_call_method`, so a second consecutive 401 raises straight back
+          to the caller without re-entering this handler -- there is no
+          loop.
+        - If the silent refresh itself fails (the refresh token is dead),
+          control falls through to `_handle_device_flow_token_expiry`,
+          which raises `InteractionRequiredError` under
+          `reauth_on_expired=REAUTH_INTERACTION_REQUIRED` (or behaves
+          per the `REAUTH_PROMPT` / `REAUTH_NEVER` modes).
+
+        This is the backstop for a token that lacks `expires_at` (so
+        oauthlib never refreshed proactively) and for a server-side
+        revocation between proactive checks.
+        """
+        token = self._load_token()
+        refresh_token = token.get("refresh_token") if token else None
+        oauth_client = self._oauth_client
+
+        if refresh_token and oauth_client is not None:
+            token_url = self._idp_url.rstrip("/") + "/as/token.oauth2"
+            refresh_kwargs = {
+                "client_id": self._client_id,
+                "verify": self._should_verify(),
+            }
+            try:
+                with warnings.catch_warnings():
+                    warnings.filterwarnings(
+                        "ignore", category=DeprecationWarning
+                    )
+                    refreshed = oauth_client.refresh_token(
+                        token_url,
+                        refresh_token=refresh_token,
+                        **refresh_kwargs,
+                    )
+            except requests.exceptions.RequestException as exc:
+                # A transport-layer failure is not evidence that the
+                # refresh token is dead, so the stored token is left
+                # intact and the failure surfaces as a typed network
+                # error the caller can branch on without being signed
+                # out by a blip.
+                msg = f"Silent token refresh failed: {exc}"
+                raise DeviceAuthorizationNetworkError(msg) from exc
+            except rfc6749.errors.OAuth2Error:
+                # A genuine OAuth rejection (e.g. `invalid_grant`) means
+                # the refresh token itself is dead; hand off to the
+                # expiry handler for the re-auth decision.
+                return self._handle_device_flow_token_expiry(
+                    send_request, error
+                )
+
+            self._save_token(refreshed)
+            # The single retry runs `send_request()` directly: another 401
+            # here propagates without re-triggering a refresh (no loop).
+            return send_request()
+
+        # No usable refresh token: defer to the expiry handler.
+        return self._handle_device_flow_token_expiry(send_request, error)
 
-        Clears the persisted token and, when `reauth_on_expired` is
-        `True`, prompts on stderr for the user to re-authenticate via
-        the browser before retrying the original request once. When
-        `reauth_on_expired` is `False`, raises immediately so callers
-        running unattended can react without blocking on `input()`.
+    def _handle_device_flow_token_expiry(self, send_request, error):
+        """Recover from an expired Device Authorization Grant refresh
+        token.
+
+        Reached only after `requests_oauthlib`'s silent refresh has
+        already failed (the refresh token itself is dead). Clears the
+        persisted token and recovers according to `reauth_on_expired`:
+
+        - `REAUTH_PROMPT` (the default): prompts on stderr for the user
+          to re-authenticate via the browser before retrying the original
+          request once. When a `verification_handler` is configured, the
+          stdin "press Enter" gate is skipped entirely -- the callback
+          itself is the
+          console-less app's presence/notification surface, so the flow
+          re-runs (invoking the callback) and the original request is
+          retried once.
+        - `REAUTH_NEVER`: raises `InvalidRefreshTokenError` immediately so
+          callers running unattended can react without blocking on
+          `input()`.
+        - `REAUTH_INTERACTION_REQUIRED`: raises
+          `InteractionRequiredError` so a GUI can decide when and how to
+          prompt the user, rather than having an ordinary data call fire
+          the verification callback from a worker thread.
         """
         self._save_token(None)
 
-        if not self._reauth_on_expired:
-            raise InvalidRefreshTokenError(
+        if self._reauth_on_expired == REAUTH_INTERACTION_REQUIRED:
+            raise InteractionRequiredError(
                 _DEVICE_FLOW_REFRESH_EXPIRED_MESSAGE
             ) from error
 
-        print(_DEVICE_FLOW_REAUTH_PROMPT, file=sys.stderr)
-        try:
-            input()
-        except EOFError as eof_error:
-            # Non-interactive stdin (piped, closed, no human present);
-            # do not auto-recover -- the prompt's purpose was to confirm
-            # human presence.
+        if self._reauth_on_expired == REAUTH_NEVER:
             raise InvalidRefreshTokenError(
                 _DEVICE_FLOW_REFRESH_EXPIRED_MESSAGE
-            ) from eof_error
-        # KeyboardInterrupt propagates naturally; no special handling.
+            ) from error
 
-        # Drop any cached OAuth session so `login()` re-runs the device
-        # flow rather than reusing an exhausted refresh token.
+        if self._verification_handler is None:
+            print(_DEVICE_FLOW_REAUTH_PROMPT, file=sys.stderr)
+            try:
+                input()
+            except EOFError as eof_error:
+                # Non-interactive stdin (piped, closed, no human present);
+                # do not auto-recover -- the prompt's purpose was to confirm
+                # human presence.
+                raise InvalidRefreshTokenError(
+                    _DEVICE_FLOW_REFRESH_EXPIRED_MESSAGE
+                ) from eof_error
+            # KeyboardInterrupt propagates naturally; no special handling.
+
+        # Drop any cached OAuth session so `login()` re-runs the Device
+        # Authorization Grant rather than reusing an exhausted refresh
+        # token.
         self._oauth_client = None
         self.login()
         return send_request()
 
+    def logout(self, http_timeout: float | None = None):
+        """Sign out: revoke the refresh token and clear the local token.
+
+        The public counterpart to `login()`. When a token with a
+        `refresh_token` is present, this POSTs to the IdP's RFC 7009 token
+        revocation endpoint (`<idp_url>/as/revoke_token.oauth2`, derived the
+        same way as the device-authorization and token endpoints) to revoke
+        the refresh token server-side, then always clears the locally stored
+        token so a sign-out succeeds locally even when the server call does
+        not. The cached OAuth session is torn down so a subsequent `login()`
+        starts a fresh Device Authorization Grant rather than reusing an
+        exhausted session.
+
+        Revocation uses the configured public `client_id` and no secret
+        (the device-authorization client is a public client, RFC 8628
+        / ADR-0058).
+
+        Per RFC 7009 §2.2 the revocation endpoint returns HTTP 200 even for
+        a token that is already invalid, so a 200 confirms the request was
+        accepted -- not that a specific token was live at the time.
+
+        Arguments:
+        ---------
+            http_timeout: float | None
+                The connect/read HTTP timeout (seconds) for the revocation
+                POST. `None` (the default) uses
+                `_DEFAULT_DEVICE_AUTHORIZATION_HTTP_TIMEOUT`, the same
+                finite bound the Device Authorization Grant applies, so a
+                hung IdP connection backs off
+                instead of blocking the sign-out indefinitely.
+
+        Raises:
+        ------
+            PyONCatError
+                If the revocation request fails (non-2xx response or a
+                transport error). The local token is cleared first, so the
+                caller is signed out locally regardless; the exception
+                surfaces that server-side revocation did not succeed.
+
+        """
+        token = self._load_token()
+        refresh_token = token.get("refresh_token") if token else None
+
+        revocation_error: Exception | None = None
+        if refresh_token:
+            revocation_url = (
+                self._idp_url.rstrip("/") + "/as/revoke_token.oauth2"
+            )
+            post_timeout = (
+                http_timeout
+                if http_timeout is not None
+                else _DEFAULT_DEVICE_AUTHORIZATION_HTTP_TIMEOUT
+            )
+            try:
+                revocation_response = requests.post(
+                    revocation_url,
+                    data={
+                        "token": refresh_token,
+                        "token_type_hint": "refresh_token",
+                        "client_id": self._client_id,
+                    },
+                    verify=self._should_verify(),
+                    timeout=post_timeout,
+                    headers={
+                        "Content-Type": "application/x-www-form-urlencoded",
+                        "Accept": "application/json",
+                    },
+                )
+            except requests.exceptions.RequestException as exc:
+                revocation_error = exc
+            else:
+                if not revocation_response.ok:
+                    revocation_error = PyONCatError(
+                        "Token revocation request failed with status "
+                        f"{revocation_response.status_code}: "
+                        f"{revocation_response.text}"
+                    )
+
+        # Drop the cached session first so the in-memory teardown holds even
+        # if the token-store write raises: a caller-supplied store can fail,
+        # and a failed store write must not leave a live session behind. The
+        # store-write exception still propagates to the caller below.
+        self._oauth_client = None
+        self._save_token(None)
+
+        if revocation_error is not None:
+            msg = (
+                "Signed out locally, but server-side token revocation "
+                f"failed: {revocation_error}"
+            )
+            raise PyONCatError(msg) from revocation_error
+
+    def has_stored_token(self) -> bool:
+        """Return True if a (non-null) token is already persisted.
+
+        Reads through the configured token store / token_getter; does
+        NOT contact the IdP and does NOT validate the token (it may be
+        expired). Lets a GUI decide its initial signed-in vs signed-out
+        state without a network round trip. A session cleared by
+        logout() (persisted as JSON null) reads as absent.
+        """
+        return self._load_token() is not None
+
     def _load_oauth_client(self):
         if not self._oauth_client:
             self.login()
@@ -513,7 +876,14 @@ class ONCat:
             and "proxy" not in self._url
         )
 
-    def login(self, username=None, password=None):
+    def login(
+        self,
+        username=None,
+        password=None,
+        cancel_event: threading.Event | None = None,
+        device_authorization_timeout: float | None = None,
+        http_timeout: float | None = None,
+    ):
         """Login to the ONCat API as part of an appropriate OAuth flow.
 
         This method is no longer strictly necessary to call manually,
@@ -534,6 +904,37 @@ class ONCat:
             password: str | None
                 The password to use when logging in.
 
+            cancel_event: threading.Event | None
+                Device Authorization Grant only.  When supplied, the
+                poll loop checks it around each sleep and before each
+                token POST; if it is set, the loop raises
+                `DeviceAuthorizationCancelled`.  This is how a GUI
+                "Cancel" button truly aborts a sign-in in progress: Qt
+                (or any toolkit) cannot interrupt blocking Python, so
+                cancellation must be cooperative and live in PyONCat.
+                `None` (the default) means today's behavior -- no
+                cancellation.
+
+            device_authorization_timeout: float | None
+                Device Authorization Grant only.  An overall caller
+                deadline in seconds for the sign-in, distinct from the
+                RFC 8628 server-side `expires_in`.  When set, polling
+                stops at the deadline with `DeviceAuthorizationTimeout`.
+                Polling also stops no later than the server's own
+                `expires_in` (the effective deadline is the earlier of
+                the two).  `None` (the default) means no overall deadline
+                -- today's behavior.
+
+            http_timeout: float | None
+                Device Authorization Grant only.  The connect/read HTTP
+                timeout (seconds) applied to the two device-authorization POSTs
+                (device-authorization and token poll).  `None` (the
+                default) uses `_DEFAULT_DEVICE_AUTHORIZATION_HTTP_TIMEOUT`, a
+                finite value so a hung IdP connection backs off and the
+                loop keeps polling within the overall deadline instead of
+                hanging forever.  This is distinct from the constructor's
+                `timeout` (which applies to ordinary API requests).
+
         """
         if self._flow == CLIENT_CREDENTIALS_FLOW:
             self._login_client_credentials()
@@ -554,7 +955,11 @@ class ONCat:
             else:
                 self._login_resource_owner_credentials(username, password)
         elif self._flow == DEVICE_AUTHORIZATION_FLOW:
-            self._login_device_authorization()
+            self._login_device_authorization(
+                cancel_event=cancel_event,
+                device_authorization_timeout=device_authorization_timeout,
+                http_timeout=http_timeout,
+            )
         else:
             raise AssertionError
 
@@ -658,8 +1063,12 @@ class ONCat:
 
     def _login_device_authorization(
         self,
-        prompt: Callable[[str, str], None] | None = None,
+        prompt: Callable[[str, str, str | None], None] | None = None,
         sleep: Callable[[float], None] | None = None,
+        cancel_event: threading.Event | None = None,
+        device_authorization_timeout: float | None = None,
+        http_timeout: float | None = None,
+        monotonic: Callable[[], float] | None = None,
     ):
         """Drive the OAuth 2.0 Device Authorization Grant (RFC 8628).
 
@@ -669,17 +1078,36 @@ class ONCat:
         `OAuth2Session` is wired with `auto_refresh_url` so subsequent
         API calls roll the refresh token transparently.
 
-        `prompt` and `sleep` exist to make the polling loop deterministic
-        in unit tests; production callers pass neither.
+        `cancel_event` lets a caller cooperatively abort the poll loop;
+        `device_authorization_timeout` is the overall caller deadline (distinct
+        from the server's `expires_in`); `http_timeout` bounds each
+        individual device-authorization POST.  See `login()` for the public
+        contract.
+
+        `prompt`, `sleep`, and `monotonic` exist to make the polling loop
+        deterministic in unit tests; production callers pass none of them.
         """
         if self._load_token() is not None:
+            # No need to validate or refresh the token here: once the
+            # device-authorization token carries an absolute `expires_at`
+            # (`_stamp_token_expires_at`), the wired `OAuth2Session` owns
+            # expiry -- it refreshes proactively before the first call and
+            # reactively on a 401. Do not add a redundant validate/refresh.
             self._setup_device_oauth_session(self._load_token())
             return
 
         if prompt is None:
             prompt = _default_device_flow_prompt
         if sleep is None:
-            sleep = time.sleep
+            sleep = self._device_authorization_sleep(cancel_event)
+        if monotonic is None:
+            monotonic = time.monotonic
+
+        post_timeout = (
+            http_timeout
+            if http_timeout is not None
+            else _DEFAULT_DEVICE_AUTHORIZATION_HTTP_TIMEOUT
+        )
 
         assert self._client_id
 
@@ -692,16 +1120,37 @@ class ONCat:
         if scope_str:
             device_auth_body["scope"] = scope_str
 
-        device_auth_response = requests.post(
-            device_auth_url,
-            data=device_auth_body,
-            verify=self._should_verify(),
-            timeout=self._timeout,
-            headers={
-                "Content-Type": "application/x-www-form-urlencoded",
-                "Accept": "application/json",
-            },
+        # The caller's `device_authorization_timeout` bounds the WHOLE sign-in
+        # (ADR-0097), so the deadline clock starts BEFORE the initial
+        # device-authorization POST. A slow initial POST therefore counts
+        # against the overall budget. `http_timeout` still caps each
+        # individual POST; the caller deadline is the cumulative bound.
+        started_at = monotonic()
+        caller_deadline = (
+            started_at + device_authorization_timeout
+            if device_authorization_timeout is not None
+            else None
         )
+
+        self._raise_if_cancelled(cancel_event)
+        self._raise_if_past_deadline(caller_deadline, monotonic)
+
+        try:
+            device_auth_response = requests.post(
+                device_auth_url,
+                data=device_auth_body,
+                verify=self._should_verify(),
+                timeout=post_timeout,
+                headers={
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    "Accept": "application/json",
+                },
+            )
+        except requests.exceptions.RequestException as exc:
+            msg = f"Device authorization request failed: {exc}"
+            raise DeviceAuthorizationNetworkError(msg) from exc
+        # A slow initial POST may have already exhausted the caller budget.
+        self._raise_if_past_deadline(caller_deadline, monotonic)
         if not device_auth_response.ok:
             msg = (
                 "Device authorization request failed with status "
@@ -710,15 +1159,56 @@ class ONCat:
             )
             raise DeviceAuthorizationError(msg)
 
-        device_auth = device_auth_response.json()
-        device_code = device_auth["device_code"]
-        user_code = device_auth["user_code"]
-        verification_uri = device_auth["verification_uri"]
-        interval = float(
-            device_auth.get("interval", _DEFAULT_DEVICE_FLOW_INTERVAL)
+        try:
+            device_auth = device_auth_response.json()
+            device_code = device_auth["device_code"]
+            user_code = device_auth["user_code"]
+            verification_uri = device_auth["verification_uri"]
+            # RFC 8628 §3.3.1: `verification_uri_complete` is OPTIONAL; it
+            # may be absent, in which case the prompt falls back to the
+            # bare URI.
+            verification_uri_complete = device_auth.get(
+                "verification_uri_complete"
+            )
+            # RFC 8628 §3.2: `expires_in` is the device-code lifetime;
+            # OPTIONAL in practice, so tolerate its absence.
+            expires_in_raw = device_auth.get("expires_in")
+            expires_in = (
+                int(expires_in_raw) if expires_in_raw is not None else None
+            )
+            interval = float(
+                device_auth.get("interval", _DEFAULT_DEVICE_FLOW_INTERVAL)
+            )
+        except (ValueError, KeyError, TypeError) as err:
+            msg = (
+                "Device authorization response was not a valid JSON object "
+                "with the required fields."
+            )
+            raise DeviceAuthorizationError(msg) from err
+
+        # The effective deadline is the earlier of the caller's overall
+        # `device_authorization_timeout` (clocked from before the
+        # initial POST) and the server's own `expires_in` (clocked from
+        # now, once known).
+        server_expiry = (
+            monotonic() + expires_in if expires_in is not None else None
+        )
+        deadlines = [
+            d for d in (caller_deadline, server_expiry) if d is not None
+        ]
+        deadline = min(deadlines) if deadlines else None
+
+        self._dispatch_device_authorization_challenge(
+            prompt,
+            DeviceAuthorizationChallenge(
+                verification_uri=verification_uri,
+                user_code=user_code,
+                verification_uri_complete=verification_uri_complete,
+                expires_in=expires_in,
+                interval=interval,
+                expires_at=server_expiry,
+            ),
         )
-
-        prompt(verification_uri, user_code)
 
         token_body = {
             "grant_type": _DEVICE_CODE_GRANT_TYPE,
@@ -727,21 +1217,39 @@ class ONCat:
         }
 
         while True:
-            sleep(interval)
+            self._raise_if_cancelled(cancel_event)
+            self._raise_if_past_deadline(deadline, monotonic)
+            sleep(self._poll_wait_seconds(interval, deadline, monotonic))
+            self._raise_if_cancelled(cancel_event)
+            self._raise_if_past_deadline(deadline, monotonic)
 
-            token_response = requests.post(
-                token_url,
-                data=token_body,
-                verify=self._should_verify(),
-                timeout=self._timeout,
-                headers={
-                    "Content-Type": "application/x-www-form-urlencoded",
-                    "Accept": "application/json",
-                },
-            )
+            try:
+                token_response = requests.post(
+                    token_url,
+                    data=token_body,
+                    verify=self._should_verify(),
+                    timeout=post_timeout,
+                    headers={
+                        "Content-Type": "application/x-www-form-urlencoded",
+                        "Accept": "application/json",
+                    },
+                )
+            except requests.exceptions.Timeout:
+                # A connection/read timeout on a single poll is recoverable:
+                # back off and keep polling within the overall deadline
+                # rather than aborting the whole sign-in. The next loop
+                # iteration re-checks the deadline and cancel event.
+                continue
+            except requests.exceptions.RequestException as exc:
+                msg = f"Device token poll failed: {exc}"
+                raise DeviceAuthorizationNetworkError(msg) from exc
 
             if token_response.ok:
-                token = token_response.json()
+                try:
+                    token = token_response.json()
+                except (ValueError, KeyError, TypeError) as err:
+                    msg = "Device token response was not a valid JSON object."
+                    raise DeviceAuthorizationError(msg) from err
                 break
 
             try:
@@ -755,18 +1263,125 @@ class ONCat:
             if error_code == "slow_down":
                 interval += _DEVICE_FLOW_SLOW_DOWN_BUMP
                 continue
-            if error_code in {"expired_token", "access_denied"}:
-                msg = f"Device authorization terminated: {error_code}"
-                raise DeviceAuthorizationError(msg)
+            if error_code == "expired_token":
+                msg = "Device authorization terminated: expired_token"
+                raise DeviceAuthorizationExpired(msg)
+            if error_code == "access_denied":
+                msg = "Device authorization terminated: access_denied"
+                raise DeviceAuthorizationDenied(msg)
             msg = (
                 "Device token poll failed with status "
                 f"{token_response.status_code}: {token_response.text}"
             )
             raise DeviceAuthorizationError(msg)
 
+        self._stamp_token_expires_at(token)
         self._save_token(token)
         self._setup_device_oauth_session(token)
 
+    @staticmethod
+    def _stamp_token_expires_at(token: dict) -> None:
+        """Stamp an absolute `expires_at` on a device-authorization
+        token in place.
+
+        PingFed's device-token response carries only the relative
+        `expires_in`. oauthlib's proactive-refresh gate keys on the
+        absolute `expires_at`, recomputing it as `now + expires_in` on
+        every reload -- so a persisted token without `expires_at` looks
+        perpetually fresh and silent refresh never fires. PyONCat's other
+        flows go through `OAuth2Session.fetch_token()`, which stamps
+        `expires_at` via oauthlib's parser; the manual device poll does
+        not, so it is stamped here to the same wall-clock shape
+        (`round(time.time()) + expires_in`, matching oauthlib) anchored at
+        the moment the token was received.
+
+        RFC 6749 §5.1 makes `expires_in` only RECOMMENDED. When it is
+        absent or non-numeric, no `expires_at` is synthesized -- the
+        bounded reactive 401 net (`_call_method`) is the backstop for
+        that case.
+        """
+        if "expires_at" in token:
+            return
+        try:
+            expires_in = int(token["expires_in"])
+        except (KeyError, ValueError, TypeError):
+            return
+        token["expires_at"] = round(time.time()) + expires_in
+
+    @staticmethod
+    def _device_authorization_sleep(
+        cancel_event: threading.Event | None,
+    ) -> Callable[[float], None]:
+        """Resolve the inter-poll wait primitive for the Device
+        Authorization Grant.
+
+        When a `cancel_event` is supplied the wait blocks on the event,
+        so setting it returns immediately rather than after the full
+        interval; `threading.Event.wait(timeout)` returns as soon as the
+        event is set. Without a `cancel_event` the wait is a plain
+        `time.sleep`.
+        """
+        if cancel_event is None:
+            return time.sleep
+
+        def wait(seconds: float) -> None:
+            cancel_event.wait(seconds)
+
+        return wait
+
+    @staticmethod
+    def _poll_wait_seconds(
+        interval: float,
+        deadline: float | None,
+        monotonic: Callable[[], float],
+    ) -> float:
+        """Seconds to wait before the next poll, bounded by the deadline.
+
+        The wait is capped at the time remaining until `deadline` (the
+        earlier of the caller and server expiries) so a pending sign-in
+        observes the deadline without waiting a full `interval` past it.
+        """
+        if deadline is None:
+            return interval
+        return max(0.0, min(interval, deadline - monotonic()))
+
+    @staticmethod
+    def _raise_if_cancelled(cancel_event: threading.Event | None) -> None:
+        if cancel_event is not None and cancel_event.is_set():
+            msg = "Device authorization was cancelled by the caller."
+            raise DeviceAuthorizationCancelled(msg)
+
+    @staticmethod
+    def _raise_if_past_deadline(
+        deadline: float | None, monotonic: Callable[[], float]
+    ) -> None:
+        if deadline is not None and monotonic() >= deadline:
+            msg = (
+                "Device authorization timed out before the user completed "
+                "the sign-in."
+            )
+            raise DeviceAuthorizationTimeout(msg)
+
+    def _dispatch_device_authorization_challenge(
+        self,
+        prompt: Callable[[str, str, str | None], None],
+        challenge: DeviceAuthorizationChallenge,
+    ) -> None:
+        """Notify the caller of a pending challenge.
+
+        A configured `verification_handler` receives the structured
+        `DeviceAuthorizationChallenge`; otherwise the resolved 3-arg `prompt`
+        callback is used (the console default, or a unit-test hook).
+        """
+        if self._verification_handler is not None:
+            self._verification_handler(challenge)
+            return
+        prompt(
+            challenge.verification_uri,
+            challenge.user_code,
+            challenge.verification_uri_complete,
+        )
+
     def _setup_device_oauth_session(self, token):
         token_url = self._idp_url.rstrip("/") + "/as/token.oauth2"
         with warnings.catch_warnings():
@@ -1343,8 +1958,21 @@ def prompt_user_for_login() -> tuple[str, str]:
     return username, password
 
 
-def _default_device_flow_prompt(verification_uri: str, user_code: str) -> None:
-    """Print the RFC 8628 §3.3 user-confirmation prompt to stdout."""
+def _default_device_flow_prompt(
+    verification_uri: str,
+    user_code: str,
+    verification_uri_complete: str | None = None,
+) -> None:
+    """Print the RFC 8628 §3.3 user-confirmation prompt to stdout.
+
+    When the IdP supplies `verification_uri_complete` (RFC 8628 §3.3.1,
+    the pre-filled one-click URL), render it directly; otherwise fall
+    back to the bare verification URL plus the user code.
+    """
+    if verification_uri_complete:
+        print("Open this URL in a browser to authenticate:")
+        print(f"    {verification_uri_complete}")
+        return
     print("Open this URL in a browser to authenticate:")
     print(f"    {verification_uri}")
     print("Enter this code:")
@@ -1456,4 +2084,57 @@ class DeviceAuthorizationError(PyONCatError):
     finish the verification step before the device code expired, the user
     explicitly denied the request, or the IdP returned an unrecognized
     error response).
+
+    The specific failure modes are surfaced as subclasses
+    (`DeviceAuthorizationDenied`, `DeviceAuthorizationExpired`,
+    `DeviceAuthorizationCancelled`, `DeviceAuthorizationTimeout`,
+    `DeviceAuthorizationNetworkError`); catching this base type still
+    catches all of them.
+    """
+
+
+# The four outcome subclasses below intentionally omit the `Error` suffix
+# (triggering N818): the names are the public 2.6 device-authorization
+# API contract
+# (ADR-0097), spelled to read as outcomes the caller catches by reason --
+# Denied / Expired / Cancelled / Timeout. They subclass
+# `DeviceAuthorizationError`, so the suffixed base type still catches them.
+class DeviceAuthorizationDenied(DeviceAuthorizationError):  # noqa: N818 - public API name (ADR-0097)
+    """Raised when the user explicitly denied the sign-in request
+    (the IdP returned `access_denied`, RFC 8628 §3.5)."""
+
+
+class DeviceAuthorizationExpired(DeviceAuthorizationError):  # noqa: N818 - public API name (ADR-0097)
+    """Raised when the device code expired before the user approved the
+    sign-in (the IdP returned `expired_token`, RFC 8628 §3.5)."""
+
+
+class DeviceAuthorizationCancelled(DeviceAuthorizationError):  # noqa: N818 - public API name (ADR-0097)
+    """Raised when the caller cancelled the sign-in in progress via the
+    `cancel_event` passed to `login()`."""
+
+
+class DeviceAuthorizationTimeout(DeviceAuthorizationError):  # noqa: N818 - public API name (ADR-0097)
+    """Raised when the sign-in did not complete before the overall
+    caller deadline (`device_authorization_timeout`) or the server's own
+    `expires_in`, whichever came first."""
+
+
+class DeviceAuthorizationNetworkError(DeviceAuthorizationError):
+    """Raised when an underlying HTTP request in the Device Authorization
+    Grant failed at the transport layer (the original
+    `requests.RequestException` is preserved as `__cause__`)."""
+
+
+class InteractionRequiredError(PyONCatError):
+    """Raised when a Device Authorization Grant session has expired and a
+    silent refresh is not possible, so the user must interactively sign
+    in again.
+
+    Raised only when the client is constructed with
+    `reauth_on_expired=REAUTH_INTERACTION_REQUIRED`: instead of
+    transparently re-running `login()` (and firing the verification
+    callback) from inside an ordinary API call, PyONCat raises this so
+    the application can decide when and how to prompt the user to sign
+    in again.
     """

{pyoncat-2.5 → pyoncat-2.6}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "poetry.masonry.api"
 # https://github.com/python-poetry/roadmap/issues/3
 [tool.poetry]
 name = "pyoncat"
-version = "2.5"
+version = "2.6"
 description = "A Python Client for ONCat (the ORNL Neutron Catalog)."
 authors = ["ONCat Support <oncat-support@ornl.gov>"]
 readme = ["pyoncat/README.md", "pyoncat/LICENSE"]