pyoncat 2.3__tar.gz → 2.5__tar.gz

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

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

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

@@ -14,6 +14,8 @@ import getpass
 import json
 import os
 import pathlib
+import sys
+import time
 import warnings
 import weakref
 from typing import TYPE_CHECKING, Any, Callable, ClassVar, Literal
@@ -28,13 +30,16 @@ from urllib3.exceptions import InsecureRequestWarning
 
 from pyoncat.reduction import ReductionFileBuilder
 
-__version__ = "2.3"
+__version__ = "2.5"
 
 # Constant for autoreduction user
 AUTOREDUCTION_USER = "auto"
 
 __all__ = [
     "AUTOREDUCTION_USER",
+    "CLIENT_CREDENTIALS_FLOW",
+    "DEVICE_AUTHORIZATION_FLOW",
+    "RESOURCE_OWNER_CREDENTIALS_FLOW",
     "FileSystemTokenStore",
     "ONCat",
     "ONCatObject",
@@ -52,13 +57,61 @@ __all__ = [
 FlowType = Literal[
     "client_credentials",
     "resource_owner",
+    "device_authorization",
 ]
 CLIENT_CREDENTIALS_FLOW: FlowType = "client_credentials"
 RESOURCE_OWNER_CREDENTIALS_FLOW: FlowType = "resource_owner"
+DEVICE_AUTHORIZATION_FLOW: FlowType = "device_authorization"
 
 
 assert isinstance(CLIENT_CREDENTIALS_FLOW, str)
 
+# RFC 8628 §3.5 default polling interval (seconds), used when the device
+# authorization response does not specify one.
+_DEFAULT_DEVICE_FLOW_INTERVAL = 5
+
+# RFC 8628 §3.5: on `slow_down`, the client MUST increase the polling
+# interval by 5 seconds for subsequent requests.
+_DEVICE_FLOW_SLOW_DOWN_BUMP = 5
+
+# `urn:ietf:params:oauth:grant-type:device_code` per RFC 8628 §3.4.
+_DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code"
+
+# Default OAuth IdP base URL. Used when `idp_url` is not provided to the
+# `ONCat` constructor; resolves to ORNL's external PingFed instance, which
+# hosts the device-authorization and token endpoints for the public
+# `oncat_cli_user` client.
+_DEFAULT_IDP_URL = "https://extidp.ornl.gov"
+
+
+_DEVICE_FLOW_REFRESH_EXPIRED_MESSAGE = (
+    "Your ONCat session has expired and could not be automatically "
+    "refreshed.\n"
+    "\n"
+    "To re-authenticate, call:\n"
+    "\n"
+    "    oncat.login()\n"
+    "\n"
+    "This will print a verification URL and a one-time code; complete the "
+    "flow in\n"
+    "your browser. PyONCat will then resume normally on the next API call."
+    "\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"
+    "\n"
+    "Set `reauth_on_expired=False` for unattended / non-interactive use, "
+    "in which\n"
+    "case this exception is raised immediately on session expiry."
+)
+
+
+_DEVICE_FLOW_REAUTH_PROMPT = (
+    "Your ONCat session has expired. Press Enter to re-authenticate via "
+    "your browser, or Ctrl-C to abort."
+)
+
 
 class ONCat:
     """The ONCat API client.
@@ -157,6 +210,23 @@ class ONCat:
             client will wait indefinitely for a response, as per the
             underlying behavior of the `requests` module.
 
+        idp_url: str | None
+            The base URL of the OAuth identity provider (e.g.
+            `https://extidp.ornl.gov`).  Used when `flow` is
+            `DEVICE_AUTHORIZATION_FLOW` so that device-authorization
+            and token requests bypass any ONCat-side OAuth proxy and
+            hit the IdP directly.  When `None`, defaults to
+            `https://extidp.ornl.gov` (ORNL's external PingFed).
+
+        reauth_on_expired: bool
+            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
+            `InvalidRefreshTokenError` immediately, which is
+            appropriate for unattended or non-interactive use.
+
     """
 
     if TYPE_CHECKING:
@@ -179,8 +249,8 @@ class ONCat:
         User: User
         Task: Task
         Info: Info
-        CacheEntry: CacheEntry
-        UsageEntry: UsageEntry
+        Cache: Cache
+        Usage: Usage
         Template: Template
 
     def __init__(
@@ -196,6 +266,8 @@ class ONCat:
         scopes: list[str] | None = None,
         verify: bool = True,
         timeout: int | None = None,
+        idp_url: str | None = None,
+        reauth_on_expired: bool = True,
     ):
         if not url:
             msg = "A URL must be provided."
@@ -242,10 +314,25 @@ class ONCat:
         self._scopes: list[Any] | None = scopes
         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._token = None
         self._oauth_client = None
 
+        if flow == RESOURCE_OWNER_CREDENTIALS_FLOW:
+            warnings.warn(
+                "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 "
+                "(flow=DEVICE_AUTHORIZATION_FLOW) for human-user "
+                "authentication. ROPC remains available indefinitely as "
+                "a compatibility path.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
         for resource_cls in _ONCatMixinMeta.REGISTERED_RESOURCES:
             setattr(self, resource_cls.__name__, resource_cls(self))
 
@@ -334,15 +421,60 @@ class ONCat:
                     "your calls to the ONCat API.\n\n"
                 )
                 raise InvalidRefreshTokenError(msg) from error
+            if (
+                self._flow == DEVICE_AUTHORIZATION_FLOW
+                and "(invalid_grant)" in str(error)
+            ):
+                return self._handle_device_flow_token_expiry(
+                    send_request, error
+                )
             msg = f'Error: "{error!s}"'
             raise PyONCatError(msg) from error
         except oauthlib.oauth2.TokenExpiredError as error:
             if self._flow == CLIENT_CREDENTIALS_FLOW:
                 self.login()
                 return send_request()
+            if self._flow == DEVICE_AUTHORIZATION_FLOW:
+                return self._handle_device_flow_token_expiry(
+                    send_request, error
+                )
             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.
+
+        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()`.
+        """
+        self._save_token(None)
+
+        if not self._reauth_on_expired:
+            raise InvalidRefreshTokenError(
+                _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.
+            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
+        # flow rather than reusing an exhausted refresh token.
+        self._oauth_client = None
+        self.login()
+        return send_request()
+
     def _load_oauth_client(self):
         if not self._oauth_client:
             self.login()
@@ -421,6 +553,8 @@ class ONCat:
                         self._save_token(None)
             else:
                 self._login_resource_owner_credentials(username, password)
+        elif self._flow == DEVICE_AUTHORIZATION_FLOW:
+            self._login_device_authorization()
         else:
             raise AssertionError
 
@@ -522,6 +656,133 @@ class ONCat:
             token_updater=self._save_token,
         )
 
+    def _login_device_authorization(
+        self,
+        prompt: Callable[[str, str], None] | None = None,
+        sleep: Callable[[float], None] | None = None,
+    ):
+        """Drive the OAuth 2.0 Device Authorization Grant (RFC 8628).
+
+        The PingFed device-authorization endpoint is hit at
+        `<idp_url>/as/device_authz.oauth2` and the token endpoint at
+        `<idp_url>/as/token.oauth2`.  After receiving a token, an
+        `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.
+        """
+        if self._load_token() is not None:
+            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
+
+        assert self._client_id
+
+        device_auth_url = self._idp_url.rstrip("/") + "/as/device_authz.oauth2"
+        token_url = self._idp_url.rstrip("/") + "/as/token.oauth2"
+
+        scope_str = " ".join(self._scopes) if self._scopes else None
+
+        device_auth_body: dict[str, str] = {"client_id": self._client_id}
+        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",
+            },
+        )
+        if not device_auth_response.ok:
+            msg = (
+                "Device authorization request failed with status "
+                f"{device_auth_response.status_code}: "
+                f"{device_auth_response.text}"
+            )
+            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)
+        )
+
+        prompt(verification_uri, user_code)
+
+        token_body = {
+            "grant_type": _DEVICE_CODE_GRANT_TYPE,
+            "device_code": device_code,
+            "client_id": self._client_id,
+        }
+
+        while True:
+            sleep(interval)
+
+            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",
+                },
+            )
+
+            if token_response.ok:
+                token = token_response.json()
+                break
+
+            try:
+                error_payload = token_response.json()
+            except ValueError:
+                error_payload = {}
+            error_code = error_payload.get("error")
+
+            if error_code == "authorization_pending":
+                continue
+            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)
+            msg = (
+                "Device token poll failed with status "
+                f"{token_response.status_code}: {token_response.text}"
+            )
+            raise DeviceAuthorizationError(msg)
+
+        self._save_token(token)
+        self._setup_device_oauth_session(token)
+
+    def _setup_device_oauth_session(self, token):
+        token_url = self._idp_url.rstrip("/") + "/as/token.oauth2"
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", category=DeprecationWarning)
+            self._oauth_client = requests_oauthlib.OAuth2Session(
+                self._client_id,
+                token=token,
+                scope=self._scopes,
+                auto_refresh_url=token_url,
+                auto_refresh_kwargs={
+                    "client_id": self._client_id,
+                    "verify": self._should_verify(),
+                },
+                token_updater=self._save_token,
+            )
+
 
 class ONCatObject:
     """A representation of a JSON object returned from the ONCat API.
@@ -868,6 +1129,14 @@ class Cycle(_ListableONCatMixin, _ControllerONCatMixin):
     _NAMESPACE = "api"
 
 
+class Directories(
+    _ControllerONCatMixin,
+    _ListableONCatMixin,
+):
+    _RESOURCE_ENDPOINT = "directories"
+    _NAMESPACE = "data"
+
+
 class Datafile(
     _ControllerONCatMixin,
     _CreatableONCatMixin,
@@ -914,12 +1183,12 @@ class Info(_ONCatResource):
 ########################################################################
 
 
-class CacheEntry(_UpdatableONCatMixin):
+class Cache(_UpdatableONCatMixin):
     _RESOURCE_ENDPOINT = "cache"
     _NAMESPACE = "admin"
 
 
-class UsageEntry(_ListableONCatMixin):
+class Usage(_ListableONCatMixin):
     _RESOURCE_ENDPOINT = "usage"
     _NAMESPACE = "admin"
 
@@ -940,42 +1209,42 @@ class Template(
 
 
 class ExperimentSummary(_ONCatResource):
-    _RESOURCE_ENDPOINT = "experiment"
+    _RESOURCE_ENDPOINT = "experiments"
     _NAMESPACE = "summary"
 
 
 class GroupingSummary(_ONCatResource):
-    _RESOURCE_ENDPOINT = "grouping"
+    _RESOURCE_ENDPOINT = "groupings"
     _NAMESPACE = "summary"
 
 
 class InstrumentSummary(_ONCatResource):
-    _RESOURCE_ENDPOINT = "instrument"
+    _RESOURCE_ENDPOINT = "instruments"
     _NAMESPACE = "summary"
 
 
 class ReductionSummary(_ONCatResource):
-    _RESOURCE_ENDPOINT = "reduction"
+    _RESOURCE_ENDPOINT = "reductions"
     _NAMESPACE = "summary"
 
 
 class RunSummary(_ONCatResource):
-    _RESOURCE_ENDPOINT = "run"
+    _RESOURCE_ENDPOINT = "runs"
     _NAMESPACE = "summary"
 
 
 class SampleSummary(_ONCatResource):
-    _RESOURCE_ENDPOINT = "sample"
+    _RESOURCE_ENDPOINT = "samples"
     _NAMESPACE = "summary"
 
 
 class ScanSummary(_ONCatResource):
-    _RESOURCE_ENDPOINT = "scan"
+    _RESOURCE_ENDPOINT = "scans"
     _NAMESPACE = "summary"
 
 
 class SessionSummary(_ONCatResource):
-    _RESOURCE_ENDPOINT = "session"
+    _RESOURCE_ENDPOINT = "sessions"
     _NAMESPACE = "summary"
 
 
@@ -1007,9 +1276,9 @@ class _InMemoryTokenStore:
 class FileSystemTokenStore:
     """A token store that persists OAuth tokens to a file on disk.
 
-    The file is created if it doesn't already exist, however the parent
-    directory must exist and you must have write permissions else an
-    exception will be raised.
+    The file is created if it doesn't already exist, including any
+    necessary parent directories. You must have write permissions to
+    the parent directory else an exception will be raised.
 
     This kind of store may be useful for long-lived applications where
     you need to persist the token across uses of the client, and it is
@@ -1044,15 +1313,25 @@ class FileSystemTokenStore:
     def write_token(self, token: dict | None):
         """Write the token to the file on disk.
 
+        On first creation, the file is set to mode 0o600. On subsequent
+        writes, the existing mode is preserved.
+
         Arguments:
         ---------
             token: str | None
                 The token to write to the file, or `None` to clear the
-                token.
+                token (which persists a JSON `null` payload).
 
         """
+        parent_dir = os.path.dirname(os.path.abspath(self.path))
+        if parent_dir:
+            os.makedirs(parent_dir, exist_ok=True)
+
+        is_new_file = not os.path.exists(self.path)
         with open(self.path, "w") as storage:
             json.dump(token, storage)
+        if is_new_file:
+            os.chmod(self.path, 0o600)
 
 
 def prompt_user_for_login() -> tuple[str, str]:
@@ -1064,6 +1343,14 @@ 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."""
+    print("Open this URL in a browser to authenticate:")
+    print(f"    {verification_uri}")
+    print("Enter this code:")
+    print(f"    {user_code}")
+
+
 class _UserConfigFile:
     """Subject to change and NOT recommended for use by end-users."""
 
@@ -1161,3 +1448,12 @@ class BadRequestError(PyONCatError):
 
     Check your input and try again.
     """
+
+
+class DeviceAuthorizationError(PyONCatError):
+    """An error that is raised when the OAuth 2.0 Device Authorization
+    Grant (RFC 8628) flow cannot complete (for example, the user did not
+    finish the verification step before the device code expired, the user
+    explicitly denied the request, or the IdP returned an unrecognized
+    error response).
+    """

{pyoncat-2.3 → pyoncat-2.5}/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.3"
+version = "2.5"
 description = "A Python Client for ONCat (the ORNL Neutron Catalog)."
 authors = ["ONCat Support <oncat-support@ornl.gov>"]
 readme = ["pyoncat/README.md", "pyoncat/LICENSE"]