coelevate-cli 0.2.0__py3-none-any.whl

coelevate_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Command-line client for the Coelevate Context Repository public API."""
+
+__version__ = "0.2.0"

coelevate_cli/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from coelevate_cli.cli import main
+
+sys.exit(main())

coelevate_cli/auth.py

@@ -0,0 +1,169 @@
+"""OAuth client-credentials token source for the Context Repository public API.
+
+A customer API key (client id + secret) is exchanged at the token endpoint for a
+short-lived bearer token: ``POST <token url>`` with ``grant_type=client_credentials``,
+the requested ``scope`` as a form field, and the key as HTTP Basic (RFC 6749 section
+2.3.1). The token is cached until a minute before **its own** ``exp`` claim rather than
+``now + expires_in``: a declared lifetime is a claim about one response, while ``exp``
+is a fact about the token, and a server may legitimately hand back an already
+partly-consumed token while reporting its full lifetime.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import threading
+import time
+
+import httpx
+
+#: The path the platform serves the token exchange on; the full URL (scheme + host) is
+#: deployment-specific and always supplied by the caller.
+TOKEN_PATH = "/oauth/token"
+
+#: The two scopes a key can hold for this API. There is deliberately no publish scope.
+READ_SCOPE = "context:read"
+ASSETS_SCOPE = "context:assets"
+KITS_SCOPE = "context:kits"
+GAPS_SCOPE = "context:gaps"
+
+#: Token-endpoint error codes that mean "this key may not have that scope", as opposed to a
+#: failure of the exchange itself.
+_REFUSAL_CODES = frozenset({"invalid_scope", "access_denied", "unauthorized_client"})
+
+#: Refresh a token this long before its own ``exp``.
+_REFRESH_MARGIN_SECONDS = 60
+
+
+class OAuthTokenError(RuntimeError):
+    """The token endpoint refused the exchange. ``error`` is RFC 6749 section 5.2's code
+    (``invalid_client``, ``invalid_scope``, ...) when the server sent one."""
+
+    def __init__(self, message: str, *, error: str | None, status_code: int) -> None:
+        super().__init__(message)
+        self.error = error
+        self.status_code = status_code
+
+
+def _jwt_claim(token: str, name: str) -> object | None:
+    """One unverified claim of a JWT, or ``None`` if the token is not a parseable JWT or
+    lacks it. A client-side hint only: the server verifies every call regardless of what
+    this returns."""
+    try:
+        _, payload_b64, _ = token.split(".")
+        padded = payload_b64 + "=" * (-len(payload_b64) % 4)
+        return json.loads(base64.urlsafe_b64decode(padded)).get(name)
+    except Exception:  # noqa: BLE001 - any parse failure just means "use the fallback"
+        return None
+
+
+def _jwt_exp(token: str) -> float | None:
+    """The unverified ``exp`` claim (Unix seconds) of a JWT, or ``None``: a caching hint."""
+    exp = _jwt_claim(token, "exp")
+    try:
+        return float(exp) if exp is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _jwt_project_id(token: str) -> str | None:
+    """The unverified ``project_id`` claim: the fallback for a token response that does
+    not carry the project in its body."""
+    claim = _jwt_claim(token, "project_id")
+    return claim if isinstance(claim, str) and claim else None
+
+
+class ClientCredentialsTokenSource(httpx.Auth):
+    """Exchanges a key for bearer tokens and attaches one to every request of the
+    client it is installed on. Thread-safe: one exchange at a time."""
+
+    def __init__(
+        self,
+        *,
+        token_url: str,
+        client_id: str,
+        client_secret: str,
+        scope: str | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        if not (token_url and client_id and client_secret):
+            raise ValueError("token_url, client_id and client_secret are all required")
+        self.token_url = token_url
+        self.client_id = client_id
+        self._client_secret = client_secret
+        self._scope = scope
+        self._client = http_client or httpx.Client(timeout=httpx.Timeout(15.0))
+        self._lock = threading.Lock()
+        self._cached: tuple[str, float] | None = None
+        #: What the last exchange said about the key (set by ``token()``): the project the
+        #: key resolves to and the scope the server actually granted. ``None`` until the
+        #: first exchange, or when the server named none.
+        self.project_id: str | None = None
+        self.granted_scope: str | None = None
+
+    def token(self) -> str:
+        """A token with more than the refresh margin left, exchanging only when needed."""
+        with self._lock:
+            now = time.time()
+            if self._cached is not None and self._cached[1] - now > _REFRESH_MARGIN_SECONDS:
+                return self._cached[0]
+            access_token, expiry = self._exchange(now)
+            self._cached = (access_token, expiry)
+            return access_token
+
+    def grants_scope(self, scope: str) -> bool | None:
+        """Whether the server grants this key ``scope``, asked by requesting a token for that
+        scope alone: ``True`` when granted, ``False`` when refused, ``None`` (unknown) when the
+        exchange failed for another reason (network, 5xx), which says nothing about the key.
+        Leaves this source's own cached token and granted scope untouched."""
+        probe = ClientCredentialsTokenSource(
+            token_url=self.token_url,
+            client_id=self.client_id,
+            client_secret=self._client_secret,
+            scope=scope,
+            http_client=self._client,
+        )
+        try:
+            probe.token()
+        except OAuthTokenError as exc:
+            return False if exc.error in _REFUSAL_CODES else None
+        except httpx.HTTPError:
+            return None
+        return scope in (probe.granted_scope or "").split()
+
+    def auth_flow(self, request: httpx.Request):
+        request.headers["Authorization"] = f"Bearer {self.token()}"
+        yield request
+
+    def _exchange(self, now: float) -> tuple[str, float]:
+        form = {"grant_type": "client_credentials"}
+        if self._scope:
+            form["scope"] = self._scope
+        response = self._client.post(self.token_url, data=form, auth=(self.client_id, self._client_secret))
+        if response.status_code != 200:
+            error, description = None, None
+            try:
+                body = response.json()
+                error, description = body.get("error"), body.get("error_description")
+            except ValueError:
+                pass
+            detail = f"{error}: {description}" if description else (error or response.text[:200])
+            raise OAuthTokenError(
+                f"{self.token_url} refused client {self.client_id!r} (HTTP {response.status_code}): {detail}",
+                error=error,
+                status_code=response.status_code,
+            )
+        body = response.json()
+        access_token = body["access_token"]
+        project_id = body.get("project_id")
+        self.project_id = project_id if isinstance(project_id, str) and project_id else _jwt_project_id(access_token)
+        scope = body.get("scope")
+        self.granted_scope = scope if isinstance(scope, str) and scope else self._scope
+        real_exp = _jwt_exp(access_token)
+        if real_exp is not None:
+            return access_token, real_exp
+        # An opaque token: the declared lifetime is all there is. With neither, never
+        # cache - the next call exchanges again rather than trusting a guess.
+        expires_in = body.get("expires_in")
+        return access_token, (now + float(expires_in)) if expires_in is not None else now