overturo-sdk 2.0.0__py3-none-any.whl

overturo/__init__.py

@@ -0,0 +1,185 @@
+"""Overturo SDK — the trust conductor.
+
+Backend SDK unifying the OAP authorize protocol (relying-party side)
+and the Oversight Mode SDK (issuer / attester side).
+
+
+NOTE: Phase H expands this surface to the full flat re-export set
+(adds the oversight + decisions namespaces). This Phase E version
+exposes the authorize-side public symbols plus the cross-cutting
+errors / models / verify so the relocated tests pass.
+"""
+
+__version__ = "2.0.0"
+
+from . import consent_records, decisions, meetings, receipts
+from .authorize import (
+    DpopKeyPair,
+    OverturoAuthorize,
+    OverturoDecisionAdapter,
+    OverturoRecordStream,
+    access_token_hash,
+    jwk_thumbprint,
+    peek_receipt,
+    sign_dpop_proof,
+)
+from .errors import (
+    OapApprovalRequired,
+    OapAuthorizationDenied,
+    OapDispatchError,
+    OapError,
+    OapEscalationDenied,
+    OapIntentDenied,
+    OapSequenceDenied,
+    OapTrajectoryDenied,
+    OapWrongRegion,
+    OverturoApiError,
+    OverturoConfigError,
+    OverturoError,
+    OverturoNetworkError,
+    OverturoRateLimited,
+    OverturoServerError,
+    OverturoTimeoutError,
+    OverturoUnauthorized,
+    OverturoValidationError,
+    ReceiptInvalid,
+    RecordInvalid,
+    is_oap_error,
+)
+from .models import (
+    AttestResult,
+    DecisionKind,
+    DecisionMode,
+    DecisionStatus,
+    DecisionStatusLiteral,
+    DecisionToken,
+    EscalateResult,
+    Escalation,
+    FlowDisclosures,
+    JwksKey,
+    OfflineVerifyResult,
+    OverturoBlockInvocation,
+    OverturoDecision,
+    OverturoDecisionMalformed,
+    OverturoEscalation,
+    OverturoReceipt,
+    PeekedReceipt,
+    RevokeResult,
+    TokenInfo,
+    VerifiedReceipt,
+    parse_decision,
+)
+from .oversight import (
+    ISS_ROLE_TO_TRUST_WEIGHT,
+    ISS_ROLES,
+    Decision,
+    Discovery,
+    IssRole,
+    LegalBasis,
+    LogLevel,
+    OversightConfig,
+    OverturoOversight,
+    ResolvedEndpoints,
+    RevocationReason,
+    RevocationScope,
+    TrustWeight,
+    evidence_digest,
+)
+from .records import (
+    VerifiedRecord,
+    canonical_bytes,
+    manifest_content_hash,
+    verify_manifest_pin,
+    verify_record,
+)
+from .verify import (
+    JwksCache,
+    raw_ed25519_to_jwk,
+    verify_receipt,
+    verify_receipt_offline,
+)
+
+# Explicit public surface. Listing every re-export here makes the
+# import block clearly intentional to ruff (F401) and to readers,
+# and pins the SDK's API contract — anything not listed is internal
+# regardless of how it's imported.
+__all__ = [
+    "ISS_ROLES",
+    "ISS_ROLE_TO_TRUST_WEIGHT",
+    "AttestResult",
+    "Decision",
+    "DecisionKind",
+    "DecisionMode",
+    "DecisionStatus",
+    "DecisionStatusLiteral",
+    "DecisionToken",
+    "Discovery",
+    "DpopKeyPair",
+    "EscalateResult",
+    "Escalation",
+    "FlowDisclosures",
+    "IssRole",
+    "JwksCache",
+    "JwksKey",
+    "LegalBasis",
+    "LogLevel",
+    "OapApprovalRequired",
+    "OapAuthorizationDenied",
+    "OapDispatchError",
+    "OapError",
+    "OapEscalationDenied",
+    "OapIntentDenied",
+    "OapSequenceDenied",
+    "OapTrajectoryDenied",
+    "OapWrongRegion",
+    "OfflineVerifyResult",
+    "OversightConfig",
+    "OverturoApiError",
+    "OverturoAuthorize",
+    "OverturoBlockInvocation",
+    "OverturoRecordStream",
+    "OverturoConfigError",
+    "OverturoDecision",
+    "OverturoDecisionAdapter",
+    "OverturoDecisionMalformed",
+    "OverturoError",
+    "OverturoEscalation",
+    "OverturoNetworkError",
+    "OverturoOversight",
+    "OverturoRateLimited",
+    "OverturoReceipt",
+    "OverturoServerError",
+    "OverturoTimeoutError",
+    "OverturoUnauthorized",
+    "OverturoValidationError",
+    "PeekedReceipt",
+    "ReceiptInvalid",
+    "RecordInvalid",
+    "ResolvedEndpoints",
+    "RevocationReason",
+    "RevocationScope",
+    "RevokeResult",
+    "TokenInfo",
+    "TrustWeight",
+    "VerifiedReceipt",
+    "VerifiedRecord",
+    "__version__",
+    "access_token_hash",
+    "canonical_bytes",
+    "consent_records",
+    "decisions",
+    "evidence_digest",
+    "manifest_content_hash",
+    "meetings",
+    "is_oap_error",
+    "jwk_thumbprint",
+    "parse_decision",
+    "peek_receipt",
+    "raw_ed25519_to_jwk",
+    "receipts",
+    "sign_dpop_proof",
+    "verify_manifest_pin",
+    "verify_receipt",
+    "verify_receipt_offline",
+    "verify_record",
+]

overturo/_experimental.py

@@ -0,0 +1,37 @@
+"""@experimental decorator — marks pre-1.0 stable surfaces.
+
+Emits PendingDeprecationWarning on first access per process per surface,
+then never again. Use sparingly — only for surfaces whose API may change
+in 1.x.
+
+"""
+
+from __future__ import annotations
+
+import functools
+import warnings
+from collections.abc import Callable
+from typing import TypeVar
+
+_F = TypeVar("_F", bound=Callable[..., object])
+_SEEN: set[str] = set()
+
+
+def experimental(reason: str) -> Callable[[_F], _F]:
+    def decorator(fn: _F) -> _F:
+        key = f"{fn.__module__}.{fn.__qualname__}"
+
+        @functools.wraps(fn)
+        def wrapper(*args: object, **kwargs: object) -> object:
+            if key not in _SEEN:
+                _SEEN.add(key)
+                warnings.warn(
+                    f"{key} is experimental: {reason}. API may change in overturo 1.x.",
+                    PendingDeprecationWarning,
+                    stacklevel=2,
+                )
+            return fn(*args, **kwargs)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator

overturo/_http.py

@@ -0,0 +1,279 @@
+"""
+HTTP client with retry + `Retry-After`.
+
+Wraps an `httpx.AsyncClient` with:
+  - Bearer auth (sourced from `TokenManager`)
+  - Exponential backoff on 429 / 5xx (honors `Retry-After` header)
+  - One-shot token-rotation retry on 401
+  - Per-request timeout
+  - SDK error class mapping by HTTP status
+"""
+
+from __future__ import annotations
+
+import asyncio
+import random
+import re
+from email.utils import parsedate_to_datetime
+from typing import Any
+
+import httpx
+
+from ._logger import Logger
+from .errors import (
+    OverturoApiError,
+    OverturoNetworkError,
+    OverturoRateLimited,
+    OverturoServerError,
+    OverturoTimeoutError,
+    OverturoUnauthorized,
+    OverturoValidationError,
+)
+from .oversight.token import TokenManager
+
+
+class HttpClient:
+    def __init__(
+        self,
+        tokens: TokenManager,
+        logger: Logger,
+        *,
+        client: httpx.AsyncClient | None = None,
+        max_retries: int = 3,
+        timeout_seconds: float = 30.0,
+        owns_client: bool | None = None,
+    ) -> None:
+        """When `owns_client` is None, the SDK takes ownership iff it
+        constructed the underlying httpx client (i.e., `client` was
+        not supplied). Callers passing a shared `client` should pass
+        `owns_client=False` so `close()` doesn't shut down a client
+        the host app is still using.
+        """
+        self._tokens = tokens
+        self._logger = logger
+        self._max_retries = max_retries
+        self._timeout = timeout_seconds
+        self._owns_client = (client is None) if owns_client is None else owns_client
+        self._client = client or httpx.AsyncClient(timeout=timeout_seconds)
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def post_json(self, url: str, body: Any, extra_headers: dict | None = None) -> dict:
+        response = await self._request("POST", url, body=body, extra_headers=extra_headers)
+        if response.status_code == 204:
+            return {}
+        return response.json()
+
+    async def get_json(
+        self,
+        url: str,
+        *,
+        params: dict | None = None,
+        extra_headers: dict | None = None,
+    ) -> dict:
+        """GET helper that returns parsed JSON.
+
+        Goes through the standard retry / token-rotation loop so 401 →
+        refresh + retry, 429 / 5xx → exponential back-off all work.
+        """
+        response = await self._request(
+            "GET", url, body=None, extra_headers=extra_headers, params=params
+        )
+        if response.status_code == 204:
+            return {}
+        return response.json()
+
+    async def long_poll_get(
+        self,
+        url: str,
+        *,
+        params: dict | None = None,
+        extra_headers: dict | None = None,
+        timeout: float = 35.0,
+    ) -> dict:
+        """long-poll GET with an extended per-request timeout.
+
+        The server holds for up to 30 s; the client must
+        allow a few extra seconds for in-flight network + JSON
+        serialisation. Bypasses the standard exponential back-off loop
+        for 200 responses (a 200 with `wait_again: true` is the
+        success case and the caller's outer loop handles re-issue).
+        4xx / 5xx still raise the mapped SDK error.
+        """
+        headers = {
+            "Authorization": f"Bearer {self._tokens.current()}",
+            "Accept": "application/json",
+        }
+        if extra_headers:
+            headers.update(extra_headers)
+
+        try:
+            response = await self._client.request(
+                "GET",
+                url,
+                params=params,
+                headers=headers,
+                timeout=timeout,
+            )
+        except httpx.TimeoutException as e:
+            raise OverturoTimeoutError(f"Long-poll to {url} timed out: {e}") from e
+        except httpx.HTTPError as e:
+            raise OverturoNetworkError(f"Long-poll network error on {url}: {e}") from e
+
+        if 200 <= response.status_code < 300:
+            if response.status_code == 204:
+                return {}
+            return response.json()
+
+        raise self._raise_error(response, url)
+
+    async def heartbeat(self, url: str) -> None:
+        await self._request("POST", url, body={})
+
+    async def _request(
+        self,
+        method: str,
+        url: str,
+        body: Any = None,
+        extra_headers: dict | None = None,
+        params: dict | None = None,
+    ) -> httpx.Response:
+        attempt = 0
+        token_retried = False
+
+        while True:
+            attempt += 1
+            try:
+                response = await self._send(method, url, body, extra_headers, params)
+            except OverturoTimeoutError:
+                if attempt > self._max_retries:
+                    raise
+                await asyncio.sleep(_backoff_seconds(attempt))
+                continue
+            except OverturoNetworkError:
+                if attempt > self._max_retries:
+                    raise
+                await asyncio.sleep(_backoff_seconds(attempt))
+                continue
+
+            if 200 <= response.status_code < 300:
+                return response
+
+            if response.status_code == 401 and not token_retried:
+                rotated = await self._tokens.refresh()
+                if rotated:
+                    self._logger.info("Token rotated after 401; retrying request once")
+                    token_retried = True
+                    attempt = 0
+                    continue
+
+            if response.status_code == 429 or response.status_code >= 500:
+                if attempt > self._max_retries:
+                    raise self._raise_error(response, url)
+                retry_after = _parse_retry_after(response.headers.get("retry-after"))
+                wait = retry_after if retry_after is not None else _backoff_seconds(attempt)
+                self._logger.warn(
+                    f"HTTP {response.status_code} on {url}; backing off {wait:.2f}s "
+                    f"(attempt {attempt}/{self._max_retries})"
+                )
+                await asyncio.sleep(wait)
+                continue
+
+            raise self._raise_error(response, url)
+
+    async def _send(
+        self,
+        method: str,
+        url: str,
+        body: Any,
+        extra_headers: dict | None,
+        params: dict | None = None,
+    ) -> httpx.Response:
+        headers = {
+            "Authorization": f"Bearer {self._tokens.current()}",
+            "Accept": "application/json",
+        }
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        if extra_headers:
+            headers.update(extra_headers)
+
+        try:
+            return await self._client.request(
+                method,
+                url,
+                json=body,
+                headers=headers,
+                params=params,
+            )
+        except httpx.TimeoutException as e:
+            raise OverturoTimeoutError(f"Request to {url} timed out: {e}") from e
+        except httpx.HTTPError as e:
+            raise OverturoNetworkError(f"Network error on {url}: {e}") from e
+
+    def _raise_error(self, response: httpx.Response, url: str) -> OverturoApiError:
+        request_id = response.headers.get("x-request-id")
+        body: dict = {}
+        try:
+            body = response.json()
+        except ValueError:
+            pass
+
+        error = body.get("error") if isinstance(body, dict) else None
+        reason_code = error.get("reason_code") if isinstance(error, dict) else None
+        message = (
+            error.get("message")
+            if isinstance(error, dict)
+            else f"HTTP {response.status_code} on {url}"
+        )
+        detail = error.get("detail") if isinstance(error, dict) else None
+
+        kwargs = {
+            "reason_code": reason_code,
+            "detail": detail,
+            "request_id": request_id,
+        }
+
+        if response.status_code == 401:
+            raise OverturoUnauthorized(message, http_status=401, **kwargs)
+        if response.status_code in (400, 403, 404, 409, 422):
+            raise OverturoValidationError(message, http_status=response.status_code, **kwargs)
+        if response.status_code == 429:
+            retry_after = _parse_retry_after(response.headers.get("retry-after"))
+            raise OverturoRateLimited(
+                message,
+                retry_after_seconds=int(retry_after) if retry_after is not None else None,
+                **kwargs,
+            )
+        if response.status_code >= 500:
+            raise OverturoServerError(message, http_status=response.status_code, **kwargs)
+        raise OverturoApiError(message, http_status=response.status_code, **kwargs)
+
+
+# ── helpers ────────────────────────────────────────────────────────
+
+
+def _backoff_seconds(attempt: int) -> float:
+    base = min(1.0 * 2 ** (attempt - 1), 30.0)
+    return base + random.uniform(0, 0.25)
+
+
+def _parse_retry_after(header: str | None) -> float | None:
+    if not header:
+        return None
+    header = header.strip()
+    if re.fullmatch(r"\d+", header):
+        return float(header)
+    try:
+        dt = parsedate_to_datetime(header)
+    except (TypeError, ValueError):
+        return None
+    if dt is None:
+        return None
+    import datetime as _dt
+
+    now = _dt.datetime.now(tz=dt.tzinfo) if dt.tzinfo else _dt.datetime.now()
+    delta = (dt - now).total_seconds()
+    return max(0.0, delta)

overturo/_logger.py

@@ -0,0 +1,67 @@
+"""
+SDK logger with token redaction.
+
+NEVER emits the bearer token at any log level. Token shape:
+`tat_<region>_<base32>`; regex covers all regions.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+_LEVELS = {"silent": 0, "warn": 1, "info": 2, "debug": 3}
+
+# Token shape: `tat_<region>_<urlsafe_base64>`.
+# `SecureRandom.urlsafe_base64` emits `-` and `_` in the high-entropy
+# suffix, so the character class MUST include them — `[A-Za-z0-9]+`
+# truncates real tokens at the first `_`/`-`, leaking the suffix.
+_TOKEN_PATTERN = re.compile(r"tat_[a-z]+_[A-Za-z0-9_\-]+")
+
+
+class Logger:
+    def __init__(self, level: str = "warn") -> None:
+        if level not in _LEVELS:
+            raise ValueError(f"unknown log level: {level!r}")
+        self._level = level
+        self._stdlib = logging.getLogger("overturo")
+
+    def warn(self, message: str, **kwargs: Any) -> None:
+        if _LEVELS[self._level] >= _LEVELS["warn"]:
+            self._stdlib.warning(_redact(message), **_redact_kwargs(kwargs))
+
+    def info(self, message: str, **kwargs: Any) -> None:
+        if _LEVELS[self._level] >= _LEVELS["info"]:
+            self._stdlib.info(_redact(message), **_redact_kwargs(kwargs))
+
+    def debug(self, message: str, **kwargs: Any) -> None:
+        if _LEVELS[self._level] >= _LEVELS["debug"]:
+            self._stdlib.debug(_redact(message), **_redact_kwargs(kwargs))
+
+    @property
+    def level(self) -> str:
+        return self._level
+
+
+def _redact(value: str | None) -> str:
+    if value is None:
+        return ""
+    return _TOKEN_PATTERN.sub("tat_<redacted>", value)
+
+
+def _redact_kwargs(kwargs: dict) -> dict:
+    out: dict = {}
+    for k, v in kwargs.items():
+        out[k] = _scrub(v)
+    return out
+
+
+def _scrub(value: Any) -> Any:
+    if isinstance(value, str):
+        return _redact(value)
+    if isinstance(value, dict):
+        return {k: _scrub(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_scrub(v) for v in value]
+    return value

overturo/authorize/__init__.py

@@ -0,0 +1,30 @@
+"""Relying-party SDK for the Overturo Authorize protocol (OAP v1.0).
+
+Public surface of the OAP authorize SDK — the client class,
+the DPoP key plumbing, the chronicle stream iterator, and the
+receipt peeker. Cross-cutting types (OverturoDecision,
+JwksKey, etc.) live in `overturo.models`; errors in
+`overturo.errors`; verification in `overturo.verify`.
+"""
+
+from .adapter import OverturoDecisionAdapter
+from .client import OverturoAuthorize
+from .dpop import (
+    DpopKeyPair,
+    access_token_hash,
+    jwk_thumbprint,
+    sign_dpop_proof,
+)
+from .receipt import peek_receipt
+from .record_stream import OverturoRecordStream
+
+__all__ = [
+    "OverturoAuthorize",
+    "OverturoDecisionAdapter",
+    "OverturoRecordStream",
+    "DpopKeyPair",
+    "access_token_hash",
+    "jwk_thumbprint",
+    "sign_dpop_proof",
+    "peek_receipt",
+]

overturo/authorize/_jurisdiction.py

@@ -0,0 +1,14 @@
+# audit-public-language: allow
+#
+# maps the SDK's public ``jurisdiction`` parameter (an ISO country)
+# onto the internal authorize-context routing key the platform reads. Confined to
+# this opt-out-marked module so the rest of the SDK stays under the language
+# firewall and only ever speaks of ``jurisdiction`` / country.
+from typing import Any
+
+
+def jurisdiction_context(
+    jurisdiction: str, context: dict[str, Any] | None = None
+) -> dict[str, Any]:
+    """Merge the declared jurisdiction into the authorize context."""
+    return {**(context or {}), "destination_region": jurisdiction}

overturo/authorize/adapter.py

@@ -0,0 +1,33 @@
+"""Customer decision-engine adapter contract.
+
+Customers hosting an HTTP endpoint that `conductor.policy_gate` calls
+via its `external_endpoint_url` config implement this ABC to bridge
+their decision engine (Cedar, OPA, in-house) to OverturoDecision.
+
+The SDK provides the type contract; the customer hosts the HTTP server.
+Concrete deployment guidance lives in the per-engine example adapters
+under ``examples/`` (cedar_adapter, etc).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from ..models import OverturoDecision
+
+__all__ = ["OverturoDecisionAdapter"]
+
+
+class OverturoDecisionAdapter(ABC):
+    """Customer adapter shape. Implementations receive a parsed OAP
+    authorize request (as a dict matching the wire body shape) and
+    return an OverturoDecision.
+
+    Partial decisions are allowed — the SDK fills defaults for any
+    unspecified fields when round-tripping back to the wire layer.
+    """
+
+    @abstractmethod
+    def evaluate(self, request: dict[str, Any]) -> OverturoDecision:
+        """Evaluate one OAP authorize request and return a decision."""