odcp-client 1.0.0__py3-none-any.whl

odcp_client/__init__.py

@@ -0,0 +1,23 @@
+"""odcp-client — official Python SDK for the Owndivision Control Plane.
+
+Public API is frozen at v1.0. Only the symbols re-exported below are
+considered stable. Anything else (modules with leading underscore, internal
+classes) may change without a major version bump.
+"""
+
+from odcp_client.client import AsyncOdcpClient, OdcpClient
+from odcp_client.exceptions import (
+    LicenseInvalid,
+    OdcpError,
+    WhoamiNotFound,
+)
+
+__all__ = [
+    "OdcpClient",
+    "AsyncOdcpClient",
+    "OdcpError",
+    "LicenseInvalid",
+    "WhoamiNotFound",
+]
+
+__version__ = "1.0.0"

odcp_client/_http.py

@@ -0,0 +1,147 @@
+"""Internal HTTP helpers — sync + async with bounded retries.
+
+Retry policy:
+  - On ``httpx.ConnectError``, ``httpx.ReadTimeout``, or 5xx response
+  - Up to ``retry_max`` additional attempts (so total = retry_max + 1)
+  - Backoff: ``min(0.1 * 2**attempt, 2.0)`` seconds
+  - Never retry on 4xx
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Mapping
+
+import httpx
+
+_RETRYABLE_STATUS = (500, 502, 503, 504)
+_BACKOFF_BASE_SECONDS = 0.1
+_BACKOFF_MAX_SECONDS = 2.0
+
+
+def _backoff_seconds(attempt: int) -> float:
+    return min(_BACKOFF_BASE_SECONDS * (2**attempt), _BACKOFF_MAX_SECONDS)
+
+
+def _auth_headers(api_token: str | None) -> dict[str, str]:
+    if not api_token:
+        return {}
+    return {"Authorization": f"Bearer {api_token}"}
+
+
+class SyncHttpClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_token: str | None,
+        timeout: float,
+        retry_max: int,
+    ) -> None:
+        self._client = httpx.Client(base_url=base_url, timeout=timeout)
+        self._api_token = api_token
+        self._retry_max = retry_max
+
+    def close(self) -> None:
+        self._client.close()
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        params: Mapping[str, Any] | None = None,
+        json: Any | None = None,
+        authenticated: bool = True,
+    ) -> httpx.Response:
+        merged_headers: dict[str, str] = {}
+        if authenticated:
+            merged_headers.update(_auth_headers(self._api_token))
+        if headers:
+            merged_headers.update(headers)
+
+        last_exc: Exception | None = None
+        for attempt in range(self._retry_max + 1):
+            try:
+                response = self._client.request(
+                    method,
+                    url,
+                    headers=merged_headers,
+                    params=params,
+                    json=json,
+                )
+            except (httpx.ConnectError, httpx.ReadTimeout) as exc:
+                last_exc = exc
+                if attempt >= self._retry_max:
+                    raise
+                time.sleep(_backoff_seconds(attempt))
+                continue
+
+            if response.status_code in _RETRYABLE_STATUS and attempt < self._retry_max:
+                time.sleep(_backoff_seconds(attempt))
+                continue
+            return response
+
+        # Unreachable but keeps mypy happy.
+        assert last_exc is not None
+        raise last_exc
+
+
+class AsyncHttpClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_token: str | None,
+        timeout: float,
+        retry_max: int,
+    ) -> None:
+        self._client = httpx.AsyncClient(base_url=base_url, timeout=timeout)
+        self._api_token = api_token
+        self._retry_max = retry_max
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        params: Mapping[str, Any] | None = None,
+        json: Any | None = None,
+        authenticated: bool = True,
+    ) -> httpx.Response:
+        merged_headers: dict[str, str] = {}
+        if authenticated:
+            merged_headers.update(_auth_headers(self._api_token))
+        if headers:
+            merged_headers.update(headers)
+
+        last_exc: Exception | None = None
+        for attempt in range(self._retry_max + 1):
+            try:
+                response = await self._client.request(
+                    method,
+                    url,
+                    headers=merged_headers,
+                    params=params,
+                    json=json,
+                )
+            except (httpx.ConnectError, httpx.ReadTimeout) as exc:
+                last_exc = exc
+                if attempt >= self._retry_max:
+                    raise
+                await asyncio.sleep(_backoff_seconds(attempt))
+                continue
+
+            if response.status_code in _RETRYABLE_STATUS and attempt < self._retry_max:
+                await asyncio.sleep(_backoff_seconds(attempt))
+                continue
+            return response
+
+        assert last_exc is not None
+        raise last_exc

odcp_client/branding.py

@@ -0,0 +1,150 @@
+"""Branding fetch + cache."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from odcp_client._http import AsyncHttpClient, SyncHttpClient
+from odcp_client.rbac import CacheBackend, InMemoryTTLCache
+from odcp_contracts.branding import BrandingSnapshot
+
+BRANDING_PATH_TEMPLATE = "/api/v1/branding/{slug}"
+
+
+def _cache_key(workspace_slug: str) -> str:
+    return f"branding:v1:{workspace_slug}"
+
+
+def _etag_key(workspace_slug: str) -> str:
+    return f"branding:v1:{workspace_slug}:etag"
+
+
+class BrandingCache:
+    """Sync branding cache for DP login rendering."""
+
+    def __init__(
+        self,
+        *,
+        http: SyncHttpClient,
+        backend: CacheBackend,
+        ttl_seconds: int = 300,
+    ) -> None:
+        self._http = http
+        self._backend = backend
+        self._ttl = ttl_seconds
+
+    def get(self, workspace_slug: str) -> BrandingSnapshot:
+        slug = _validate_slug(workspace_slug)
+        cached = self._backend.get(_cache_key(slug))
+        if cached is not None:
+            return cached
+        snapshot = self._fetch_branding(slug)
+        self._backend.set(_cache_key(slug), snapshot, self._ttl)
+        return snapshot
+
+    def _fetch_branding(self, workspace_slug: str) -> BrandingSnapshot:
+        etag = self._backend.get(_etag_key(workspace_slug))
+        response = self._http.request(
+            "GET",
+            BRANDING_PATH_TEMPLATE.format(slug=workspace_slug),
+            headers=_etag_headers(etag),
+            authenticated=False,
+        )
+        if response.status_code == 304:
+            cached = self._backend.get(_cache_key(workspace_slug))
+            if cached is not None:
+                return cached
+            response = self._http.request(
+                "GET",
+                BRANDING_PATH_TEMPLATE.format(slug=workspace_slug),
+                authenticated=False,
+            )
+        response.raise_for_status()
+        snapshot = BrandingSnapshot.model_validate(response.json())
+        normalised_etag = _normalise_etag(response.headers.get("etag"))
+        if normalised_etag is not None:
+            self._backend.set(_etag_key(workspace_slug), normalised_etag, self._ttl)
+        return snapshot
+
+
+class AsyncBrandingCache:
+    def __init__(
+        self,
+        *,
+        http: AsyncHttpClient,
+        backend: CacheBackend,
+        ttl_seconds: int = 300,
+    ) -> None:
+        self._http = http
+        self._backend = backend
+        self._ttl = ttl_seconds
+        self._backend_is_blocking = not isinstance(backend, InMemoryTTLCache)
+
+    async def get(self, workspace_slug: str) -> BrandingSnapshot:
+        slug = _validate_slug(workspace_slug)
+        cached = await self._cache_get(_cache_key(slug))
+        if cached is not None:
+            return cached
+        snapshot = await self._fetch_branding(slug)
+        await self._cache_set(_cache_key(slug), snapshot)
+        return snapshot
+
+    async def _fetch_branding(self, workspace_slug: str) -> BrandingSnapshot:
+        etag = await self._cache_get(_etag_key(workspace_slug))
+        response = await self._http.request(
+            "GET",
+            BRANDING_PATH_TEMPLATE.format(slug=workspace_slug),
+            headers=_etag_headers(etag),
+            authenticated=False,
+        )
+        if response.status_code == 304:
+            cached = await self._cache_get(_cache_key(workspace_slug))
+            if cached is not None:
+                return cached
+            response = await self._http.request(
+                "GET",
+                BRANDING_PATH_TEMPLATE.format(slug=workspace_slug),
+                authenticated=False,
+            )
+        response.raise_for_status()
+        snapshot = BrandingSnapshot.model_validate(response.json())
+        normalised_etag = _normalise_etag(response.headers.get("etag"))
+        if normalised_etag is not None:
+            await self._cache_set(_etag_key(workspace_slug), normalised_etag)
+        return snapshot
+
+    # ---- backend wrappers --------------------------------------------
+
+    async def _cache_get(self, key: str) -> Any | None:
+        if self._backend_is_blocking:
+            return await asyncio.to_thread(self._backend.get, key)
+        return self._backend.get(key)
+
+    async def _cache_set(self, key: str, value: Any) -> None:
+        if self._backend_is_blocking:
+            await asyncio.to_thread(self._backend.set, key, value, self._ttl)
+        else:
+            self._backend.set(key, value, self._ttl)
+
+
+def _validate_slug(workspace_slug: str) -> str:
+    slug = workspace_slug.strip()
+    if not slug:
+        raise ValueError("workspace_slug is required")
+    return slug
+
+
+def _normalise_etag(value: str | None) -> str | None:
+    if value is None:
+        return None
+    etag = value.strip()
+    if etag.startswith("W/"):
+        etag = etag[2:].strip()
+    return etag.strip('"') or None
+
+
+def _etag_headers(etag: Any | None) -> dict[str, str] | None:
+    if not isinstance(etag, str):
+        return None
+    return {"If-None-Match": f'"{etag}"'}

odcp_client/client.py

@@ -0,0 +1,291 @@
+"""OdcpClient + AsyncOdcpClient — official Python SDK for the Owndivision CP."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+from uuid import UUID
+
+from odcp_client._http import AsyncHttpClient, SyncHttpClient
+from odcp_client.branding import AsyncBrandingCache, BrandingCache
+from odcp_client.exceptions import LicenseInvalid
+from odcp_client.rbac import CacheBackend, InMemoryTTLCache
+from odcp_client.whoami import AsyncWhoamiCache, WhoamiCache
+
+if TYPE_CHECKING:
+    from odcp_client.jwks import AsyncJwksCache, JwksCache
+    from odcp_contracts.branding import BrandingSnapshot
+    from odcp_contracts.licensing import DeploymentLicenseClaims
+    from odcp_contracts.whoami import WhoAmIResponse
+
+
+class _BaseClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_token: str | None = None,
+        license_token: str | None = None,
+        whoami_cache_ttl: int = 60,
+        jwks_cache_ttl: int = 3600,
+        http_timeout: float = 5.0,
+        retry_max: int = 3,
+        cache_backend: Any | None = None,
+    ) -> None:
+        if not base_url:
+            raise ValueError("base_url is required")
+        # Strip trailing slash so callers can append paths consistently.
+        self._base_url = base_url.rstrip("/")
+        self._api_token = api_token
+        self._license_token = license_token
+        self._whoami_cache_ttl = whoami_cache_ttl
+        self._jwks_cache_ttl = jwks_cache_ttl
+        self._http_timeout = http_timeout
+        self._retry_max = retry_max
+        self._cache_backend: CacheBackend = cache_backend  # type: ignore[assignment]
+
+
+class OdcpClient(_BaseClient):
+    def __init__(
+        self,
+        *,
+        signing_issuer: str = "owndivision-control-plane",
+        signing_audience: str = "owndivision-dp",
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self._http = SyncHttpClient(
+            base_url=self._base_url,
+            api_token=self._api_token,
+            timeout=self._http_timeout,
+            retry_max=self._retry_max,
+        )
+        self._signing_issuer = signing_issuer
+        self._signing_audience = signing_audience
+        self._cache_backend = self._cache_backend or InMemoryTTLCache()
+        self._jwks: JwksCache | None = None
+        self._whoami_cache = WhoamiCache(
+            http=self._http,
+            backend=self._cache_backend,
+            ttl_seconds=self._whoami_cache_ttl,
+        )
+        self._branding_cache = BrandingCache(
+            http=self._http,
+            backend=self._cache_backend,
+            ttl_seconds=300,
+        )
+
+    def _jwks_cache(self) -> JwksCache:
+        if self._jwks is None:
+            from odcp_client.jwks import JwksCache
+
+            self._jwks = JwksCache(http=self._http, ttl_seconds=self._jwks_cache_ttl)
+        return self._jwks
+
+    def verify_license(self, token: str | None = None) -> DeploymentLicenseClaims:
+        """Verify the configured (or supplied) license token.
+
+        If ``token`` is omitted, uses the ``license_token`` passed to the
+        constructor. Raises ``LicenseInvalid`` if no token is available.
+        """
+        from odcp_client.license import verify_license_jwt
+
+        license_token = token or self._license_token
+        if not license_token:
+            raise LicenseInvalid("malformed", "No license token configured or supplied")
+        return verify_license_jwt(
+            license_token,
+            jwks=self._jwks_cache(),
+            issuer=self._signing_issuer,
+            audience=self._signing_audience,
+        )
+
+    def whoami(
+        self,
+        *,
+        provider: str,
+        subject: str,
+        workspace_id: UUID | str,
+    ) -> WhoAmIResponse:
+        return self._whoami_cache.get(
+            provider=provider,
+            subject=subject,
+            workspace_id=workspace_id,
+        )
+
+    def has_permission(
+        self,
+        *,
+        provider: str,
+        subject: str,
+        workspace_id: UUID | str,
+        permission: str,
+    ) -> bool:
+        """True if the user has the named permission in the given workspace.
+
+        Reads from the membership's permissions list. Returns False if
+        the user has no membership for that workspace, even if they have
+        other memberships.
+        """
+        whoami = self.whoami(
+            provider=provider, subject=subject, workspace_id=workspace_id
+        )
+        memberships = getattr(whoami, "workspaces", None) or []
+        for m in memberships:
+            if str(getattr(m, "workspace_id", "")) != str(workspace_id):
+                continue
+            # Direct permissions list on the membership (v2 schema).
+            direct_perms: list[Any] = getattr(m, "permissions", None) or []
+            # Also check role.permissions for forward-compat with future schemas.
+            role_perms: list[Any] = (
+                getattr(getattr(m, "role", None), "permissions", None) or []
+            )
+            all_perms = direct_perms + role_perms
+            permission_codes: set[str] = set()
+            for p in all_perms:
+                if isinstance(p, str):
+                    permission_codes.add(p)
+                elif isinstance(p, dict):
+                    code = p.get("code")
+                    if isinstance(code, str):
+                        permission_codes.add(code)
+                else:
+                    code = getattr(p, "code", None)
+                    if isinstance(code, str):
+                        permission_codes.add(code)
+            return permission in permission_codes
+        return False
+
+    def branding(self, workspace_slug: str) -> BrandingSnapshot:
+        """Fetch and cache the public branding snapshot for a workspace."""
+        if not workspace_slug:
+            raise ValueError("workspace_slug is required")
+        return self._branding_cache.get(workspace_slug)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> OdcpClient:
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        self.close()
+
+
+class AsyncOdcpClient(_BaseClient):
+    def __init__(
+        self,
+        *,
+        signing_issuer: str = "owndivision-control-plane",
+        signing_audience: str = "owndivision-dp",
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self._http = AsyncHttpClient(
+            base_url=self._base_url,
+            api_token=self._api_token,
+            timeout=self._http_timeout,
+            retry_max=self._retry_max,
+        )
+        self._signing_issuer = signing_issuer
+        self._signing_audience = signing_audience
+        self._cache_backend = self._cache_backend or InMemoryTTLCache()
+        self._jwks: AsyncJwksCache | None = None
+        self._whoami_cache = AsyncWhoamiCache(
+            http=self._http,
+            backend=self._cache_backend,
+            ttl_seconds=self._whoami_cache_ttl,
+        )
+        self._branding_cache = AsyncBrandingCache(
+            http=self._http,
+            backend=self._cache_backend,
+            ttl_seconds=300,
+        )
+
+    def _jwks_cache(self) -> AsyncJwksCache:
+        if self._jwks is None:
+            from odcp_client.jwks import AsyncJwksCache
+
+            self._jwks = AsyncJwksCache(
+                http=self._http, ttl_seconds=self._jwks_cache_ttl
+            )
+        return self._jwks
+
+    async def verify_license(self, token: str | None = None) -> DeploymentLicenseClaims:
+        from odcp_client.license import averify_license_jwt
+
+        license_token = token or self._license_token
+        if not license_token:
+            raise LicenseInvalid("malformed", "No license token configured or supplied")
+        return await averify_license_jwt(
+            license_token,
+            jwks=self._jwks_cache(),
+            issuer=self._signing_issuer,
+            audience=self._signing_audience,
+        )
+
+    async def whoami(
+        self,
+        *,
+        provider: str,
+        subject: str,
+        workspace_id: UUID | str,
+    ) -> WhoAmIResponse:
+        return await self._whoami_cache.get(
+            provider=provider,
+            subject=subject,
+            workspace_id=workspace_id,
+        )
+
+    async def has_permission(
+        self,
+        *,
+        provider: str,
+        subject: str,
+        workspace_id: UUID | str,
+        permission: str,
+    ) -> bool:
+        whoami = await self.whoami(
+            provider=provider, subject=subject, workspace_id=workspace_id
+        )
+        memberships = (
+            getattr(whoami, "workspaces", None)
+            or getattr(whoami, "memberships", None)
+            or []
+        )
+        for m in memberships:
+            if str(getattr(m, "workspace_id", "")) != str(workspace_id):
+                continue
+            direct_perms: list[Any] = getattr(m, "permissions", None) or []
+            role_perms: list[Any] = (
+                getattr(getattr(m, "role", None), "permissions", None) or []
+            )
+            all_perms = direct_perms + role_perms
+            permission_codes: set[str] = set()
+            for p in all_perms:
+                if isinstance(p, str):
+                    permission_codes.add(p)
+                elif isinstance(p, dict):
+                    code = p.get("code")
+                    if isinstance(code, str):
+                        permission_codes.add(code)
+                else:
+                    code = getattr(p, "code", None)
+                    if isinstance(code, str):
+                        permission_codes.add(code)
+            return permission in permission_codes
+        return False
+
+    async def branding(self, workspace_slug: str) -> BrandingSnapshot:
+        """Fetch and cache the public branding snapshot for a workspace."""
+        if not workspace_slug:
+            raise ValueError("workspace_slug is required")
+        return await self._branding_cache.get(workspace_slug)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncOdcpClient:
+        return self
+
+    async def __aexit__(self, *_exc: Any) -> None:
+        await self.aclose()

odcp_client/exceptions.py

@@ -0,0 +1,36 @@
+"""Exception hierarchy for odcp-client.
+
+All exceptions inherit from ``OdcpError`` so DP code can do a single
+``except OdcpError`` if it wants a catch-all.
+"""
+
+from __future__ import annotations
+
+
+class OdcpError(Exception):
+    """Base for all errors raised by odcp-client."""
+
+
+class LicenseInvalid(OdcpError):
+    """Raised when a license token cannot be verified.
+
+    The ``reason`` attribute is a short stable code suitable for logging /
+    metrics: ``"expired"``, ``"bad_signature"``, ``"wrong_issuer"``,
+    ``"wrong_audience"``, ``"unknown_kid"``, ``"malformed"``.
+    """
+
+    def __init__(self, reason: str, message: str | None = None) -> None:
+        self.reason = reason
+        super().__init__(message or reason)
+
+
+class WhoamiNotFound(OdcpError):
+    """Raised when CP responds 404 to a whoami lookup."""
+
+
+class RbacRevisionMismatch(OdcpError):
+    """Internal — used by the cache layer to signal a stale entry.
+
+    Not part of the public API. Callers must never see this; the cache
+    refresh path catches it and re-fetches.
+    """