ovok-sdk 0.1.0.dev13__py3-none-any.whl

ovok_sdk/__init__.py

@@ -0,0 +1,73 @@
+from ovok_sdk.auth.session import OvokReference, Session
+from ovok_sdk.config import UnauthenticatedReason
+from ovok_sdk.errors import (
+    FieldError,
+    OvokAuthenticationError,
+    OvokConfigError,
+    OvokConflictError,
+    OvokConnectionError,
+    OvokError,
+    OvokErrorDetails,
+    OvokNotFoundError,
+    OvokPermissionError,
+    OvokRateLimitError,
+    OvokServiceError,
+    OvokValidationError,
+)
+from ovok_sdk.http.transport import (
+    OvokRequest,
+    OvokResponse,
+    Transport,
+    UrllibTransport,
+)
+from ovok_sdk.ovok import Ovok
+from ovok_sdk.paging import Page
+from ovok_sdk.resources.auth import (
+    LoginResult,
+    MfaChallenge,
+    MfaRequired,
+    RegisterResult,
+    SignedIn,
+)
+from ovok_sdk.resources.measurement_builder import MeasurementTypeKey
+from ovok_sdk.resources.registration import (
+    ClinicianInvite,
+    PatientRegistration,
+    Registration,
+)
+from ovok_sdk.storage import MemoryStorage, OvokStorage
+
+__all__ = [
+    "ClinicianInvite",
+    "FieldError",
+    "LoginResult",
+    "MeasurementTypeKey",
+    "MemoryStorage",
+    "MfaChallenge",
+    "MfaRequired",
+    "Ovok",
+    "OvokAuthenticationError",
+    "OvokConfigError",
+    "OvokConflictError",
+    "OvokConnectionError",
+    "OvokError",
+    "OvokErrorDetails",
+    "OvokNotFoundError",
+    "OvokPermissionError",
+    "OvokRateLimitError",
+    "OvokReference",
+    "OvokRequest",
+    "OvokResponse",
+    "OvokServiceError",
+    "OvokStorage",
+    "OvokValidationError",
+    "Page",
+    "PatientRegistration",
+    "RegisterResult",
+    "Registration",
+    "Session",
+    "SignedIn",
+    "Transport",
+    "UnauthenticatedReason",
+    "UrllibTransport",
+]

ovok_sdk/auth/access_token.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ovok_sdk.clock import MS_PER_SECOND
+
+REFRESH_MARGIN_MS = 60_000
+
+
+def expires_at_for(expires_in_seconds: float, now_ms: int) -> int:
+    return now_ms + round(expires_in_seconds * MS_PER_SECOND)
+
+
+@dataclass(frozen=True)
+class AccessToken:
+    value: str = field(repr=False)
+    expires_at_ms: int
+
+    def is_stale_at(self, now_ms: int) -> bool:
+        """Stale a minute early, so a token never expires between the check and the request."""
+        return now_ms >= self.expires_at_ms - REFRESH_MARGIN_MS

ovok_sdk/auth/client_credentials.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from ovok_sdk.auth.access_token import AccessToken, expires_at_for
+from ovok_sdk.auth.single_flight import SingleFlight
+from ovok_sdk.auth.token_endpoint import TokenEndpoint
+from ovok_sdk.clock import Clock, epoch_ms
+from ovok_sdk.config import MachineClient
+
+CLIENT_CREDENTIALS_GRANT = "client_credentials"
+
+
+class ClientCredentials:
+    """A machine client's own token, fetched from the OAuth endpoint and renewed before it expires."""
+
+    def __init__(self, endpoint: TokenEndpoint, client: MachineClient, clock: Clock = epoch_ms) -> None:
+        self._endpoint = endpoint
+        self._client = client
+        self._clock = clock
+        self._token: AccessToken | None = None
+        self._flight: SingleFlight[AccessToken] = SingleFlight()
+
+    def access_token(self) -> str:
+        token = self._token
+        if token is None or token.is_stale_at(self._clock()):
+            token = self._flight.run(self._request_token)
+        return token.value
+
+    def refresh(self) -> bool:
+        self._flight.run(self._request_token)
+        return True
+
+    def _request_token(self) -> AccessToken:
+        response = self._endpoint.request(
+            {
+                "grant_type": CLIENT_CREDENTIALS_GRANT,
+                "client_id": self._client.client_id,
+                "client_secret": self._client.client_secret,
+            }
+        )
+        self._token = AccessToken(response.access_token, expires_at_for(response.expires_in, self._clock()))
+        return self._token

ovok_sdk/auth/credentials.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class Credentials(Protocol):
+    def access_token(self) -> str | None: ...
+
+    def refresh(self) -> bool: ...
+
+
+class _NoCredentials:
+    def access_token(self) -> None:
+        return None
+
+    def refresh(self) -> bool:
+        return False
+
+
+NO_CREDENTIALS: Credentials = _NoCredentials()

ovok_sdk/auth/pkce.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import secrets
+import string
+from dataclasses import dataclass, field
+
+VERIFIER_LENGTH = 128
+UNRESERVED_CHARACTERS = string.ascii_letters + string.digits + "-._~"
+ASCII = "ascii"
+BASE64_PADDING = "="
+
+
+@dataclass(frozen=True)
+class PkcePair:
+    code_verifier: str = field(repr=False)
+    code_challenge: str
+
+
+def generate_pkce_pair() -> PkcePair:
+    verifier = "".join(secrets.choice(UNRESERVED_CHARACTERS) for _ in range(VERIFIER_LENGTH))
+    return PkcePair(verifier, code_challenge_for(verifier))
+
+
+def code_challenge_for(verifier: str) -> str:
+    digest = hashlib.sha256(verifier.encode(ASCII)).digest()
+    return base64.urlsafe_b64encode(digest).decode(ASCII).rstrip(BASE64_PADDING)

ovok_sdk/auth/session.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field, replace
+from typing import Any
+
+from ovok_sdk.auth.access_token import AccessToken, expires_at_for
+from ovok_sdk.auth.token_endpoint import TokenResponse
+
+
+@dataclass(frozen=True)
+class OvokReference:
+    reference: str
+    display: str | None = None
+
+
+@dataclass(frozen=True)
+class Session:
+    access_token: str = field(repr=False)
+    refresh_token: str | None = field(repr=False)
+    expires_at_ms: int
+    project: OvokReference
+    profile: OvokReference
+
+    def is_stale_at(self, now_ms: int) -> bool:
+        return AccessToken(self.access_token, self.expires_at_ms).is_stale_at(now_ms)
+
+
+def session_from_login(tokens: Mapping[str, Any], now_ms: int) -> Session:
+    """`tokens` is the camelCase body every Ovok sign-in route answers with."""
+    return Session(
+        access_token=tokens["accessToken"],
+        refresh_token=tokens.get("refreshToken"),
+        expires_at_ms=expires_at_for(tokens["expiresIn"], now_ms),
+        project=reference_from_json(tokens["project"]),
+        profile=reference_from_json(tokens["profile"]),
+    )
+
+
+def session_after_refresh(session: Session, response: TokenResponse, now_ms: int) -> Session:
+    return replace(
+        session,
+        access_token=response.access_token,
+        refresh_token=response.refresh_token or session.refresh_token,
+        expires_at_ms=expires_at_for(response.expires_in, now_ms),
+    )
+
+
+def reference_from_json(value: Mapping[str, Any]) -> OvokReference:
+    return OvokReference(value["reference"], value.get("display"))
+
+
+def reference_to_json(reference: OvokReference) -> dict[str, Any]:
+    return {"reference": reference.reference, "display": reference.display}

ovok_sdk/auth/session_store.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ovok_sdk.auth.session import Session, reference_from_json, reference_to_json
+from ovok_sdk.storage import OvokStorage
+from ovok_sdk.values import finite_number
+
+SESSION_KEY = "ovok:{tenant_code}:session"
+
+
+class SessionStore:
+    """Keeps the session as JSON in the TypeScript SDK's shape, so stores are interchangeable."""
+
+    def __init__(self, storage: OvokStorage, key: str) -> None:
+        self._storage = storage
+        self._key = key
+
+    @classmethod
+    def for_tenant(cls, storage: OvokStorage, tenant_code: str) -> SessionStore:
+        """One key per tenant, so clearing a session never touches anything else in shared storage."""
+        return cls(storage, SESSION_KEY.format(tenant_code=tenant_code))
+
+    def load(self) -> Session | None:
+        raw = self._storage.get_item(self._key)
+        return None if raw is None else _session_from_json(raw)
+
+    def save(self, session: Session) -> None:
+        self._storage.set_item(self._key, _session_to_json(session))
+
+    def clear(self) -> None:
+        self._storage.remove_item(self._key)
+
+
+def _session_to_json(session: Session) -> str:
+    return json.dumps(
+        {
+            "accessToken": session.access_token,
+            "refreshToken": session.refresh_token,
+            "expiresAt": session.expires_at_ms,
+            "project": reference_to_json(session.project),
+            "profile": reference_to_json(session.profile),
+        }
+    )
+
+
+def _session_from_json(raw: str) -> Session | None:
+    try:
+        value = json.loads(raw)
+    except ValueError:
+        return None
+    return _session_from(value) if _is_complete(value) else None
+
+
+def _session_from(value: dict[str, Any]) -> Session:
+    return Session(
+        access_token=value["accessToken"],
+        refresh_token=value.get("refreshToken"),
+        expires_at_ms=value["expiresAt"],
+        project=reference_from_json(value["project"]),
+        profile=reference_from_json(value["profile"]),
+    )
+
+
+def _is_complete(value: Any) -> bool:
+    return (
+        isinstance(value, dict)
+        and isinstance(value.get("accessToken"), str)
+        and finite_number(value.get("expiresAt")) is not None
+        and _is_reference(value.get("project"))
+        and _is_reference(value.get("profile"))
+    )
+
+
+def _is_reference(value: Any) -> bool:
+    return isinstance(value, dict) and isinstance(value.get("reference"), str)

ovok_sdk/auth/single_flight.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from functools import partial
+from typing import Generic, NoReturn, TypeVar
+
+T = TypeVar("T")
+
+Settled = Callable[[], T]
+
+
+class SingleFlight(Generic[T]):
+    """Runs one call at a time; callers who arrive while it runs share its outcome instead of repeating it."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._finished_calls = 0
+        self._latest: Settled[T] = _nothing_ran
+
+    def run(self, call: Callable[[], T]) -> T:
+        calls_seen = self._finished_calls
+        with self._lock:
+            if self._finished_calls == calls_seen:
+                self._latest = _settle(call)
+                self._finished_calls += 1
+            latest = self._latest
+        return latest()
+
+
+def _settle(call: Callable[[], T]) -> Settled[T]:
+    try:
+        value = call()
+    except Exception as error:
+        return partial(_reraise, error)
+    return lambda: value
+
+
+def _reraise(error: Exception) -> NoReturn:
+    raise error
+
+
+def _nothing_ran() -> NoReturn:
+    raise RuntimeError("SingleFlight has run nothing yet.")

ovok_sdk/auth/token_endpoint.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import urlencode
+
+from ovok_sdk.config import OvokSettings
+from ovok_sdk.http.error_response import error_from_response
+from ovok_sdk.http.transport import OvokRequest
+
+TOKEN_PATH = "oauth2/token"
+FORM_HEADERS = {"Content-Type": "application/x-www-form-urlencoded", "Accept": "application/json"}
+
+
+@dataclass(frozen=True)
+class TokenResponse:
+    access_token: str = field(repr=False)
+    expires_in: float
+    refresh_token: str | None = field(default=None, repr=False)
+
+    @classmethod
+    def from_json(cls, body: Mapping[str, Any]) -> TokenResponse:
+        return cls(body["access_token"], body["expires_in"], body.get("refresh_token"))
+
+
+class TokenEndpoint:
+    """Ovok's OAuth token endpoint: one plain form POST, without retries or credentials."""
+
+    def __init__(self, settings: OvokSettings) -> None:
+        self._settings = settings
+
+    def request(self, form: Mapping[str, str]) -> TokenResponse:
+        response = self._settings.transport(
+            OvokRequest(
+                method="POST",
+                url=f"{self._settings.base_url}{TOKEN_PATH}",
+                headers=FORM_HEADERS,
+                body=urlencode(form),
+                timeout=self._settings.timeout,
+            )
+        )
+        if response.is_success:
+            return TokenResponse.from_json(response.json())
+        raise error_from_response(response)

ovok_sdk/auth/user_session.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from ovok_sdk.auth.session import Session, session_after_refresh, session_from_login
+from ovok_sdk.auth.session_store import SessionStore
+from ovok_sdk.auth.single_flight import SingleFlight
+from ovok_sdk.auth.token_endpoint import TokenEndpoint
+from ovok_sdk.clock import Clock, epoch_ms
+from ovok_sdk.config import OvokSettings, UnauthenticatedReason
+from ovok_sdk.errors import OvokError
+
+REFRESH_TOKEN_GRANT = "refresh_token"
+REJECTED_REFRESH_STATUSES = frozenset({400, 401, 403})
+
+
+class UserSession:
+    """The signed-in user's tokens, kept in storage and refreshed a minute before they expire."""
+
+    def __init__(
+        self,
+        store: SessionStore,
+        endpoint: TokenEndpoint,
+        settings: OvokSettings,
+        clock: Clock = epoch_ms,
+    ) -> None:
+        self._store = store
+        self._endpoint = endpoint
+        self._settings = settings
+        self._clock = clock
+        self._flight: SingleFlight[bool] = SingleFlight()
+        self._listeners: list[Callable[[], None]] = []
+
+    def current(self) -> Session | None:
+        return self._store.load()
+
+    def begin(self, tokens: Mapping[str, Any]) -> Session:
+        session = session_from_login(tokens, self._clock())
+        self._store.save(session)
+        self._notify_change()
+        return session
+
+    def end(self) -> None:
+        self._store.clear()
+        self._notify_change()
+
+    def on_change(self, listener: Callable[[], None]) -> None:
+        self._listeners.append(listener)
+
+    def access_token(self) -> str | None:
+        if self._needs_refresh(self.current()):
+            self.refresh()
+        session = self.current()
+        return None if session is None else session.access_token
+
+    def refresh(self) -> bool:
+        return self._flight.run(self._exchange_refresh_token)
+
+    def _needs_refresh(self, session: Session | None) -> bool:
+        return session is not None and session.refresh_token is not None and session.is_stale_at(self._clock())
+
+    def _exchange_refresh_token(self) -> bool:
+        session = self.current()
+        if session is None or session.refresh_token is None:
+            return False
+        try:
+            response = self._endpoint.request(self._refresh_form(session.refresh_token))
+        except OvokError as error:
+            return self._sign_out_if_rejected(error)
+        self._store.save(session_after_refresh(session, response, self._clock()))
+        self._notify_change()
+        return True
+
+    def _notify_change(self) -> None:
+        for listener in tuple(self._listeners):
+            listener()
+
+    def _sign_out_if_rejected(self, error: OvokError) -> bool:
+        """Only a refused refresh token signs the user out; an outage keeps the session for a later retry."""
+        if error.status in REJECTED_REFRESH_STATUSES:
+            self.end()
+            self._settings.on_unauthenticated(UnauthenticatedReason(status=error.status))
+            return False
+        raise error
+
+    def _refresh_form(self, refresh_token: str) -> dict[str, str]:
+        client = {} if self._settings.client_id is None else {"client_id": self._settings.client_id}
+        return {"grant_type": REFRESH_TOKEN_GRANT, "refresh_token": refresh_token, **client}

ovok_sdk/clock.py

@@ -0,0 +1,11 @@
+import time
+from collections.abc import Callable
+
+MS_PER_SECOND = 1000
+NS_PER_MS = 1_000_000
+
+Clock = Callable[[], int]
+
+
+def epoch_ms() -> int:
+    return time.time_ns() // NS_PER_MS

ovok_sdk/config.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from ovok_sdk.errors import OvokConfigError, OvokErrorDetails
+from ovok_sdk.http.transport import Transport, UrllibTransport
+from ovok_sdk.storage import MemoryStorage, OvokStorage
+from ovok_sdk.values import finite_number
+
+DEFAULT_FHIR_PATH = "fhir"
+DEFAULT_TIMEOUT_SECONDS = 30.0
+DEFAULT_MAX_NETWORK_RETRIES = 2
+ABSOLUTE_HTTP_URL = re.compile(r"https?://[^/\s]+", re.IGNORECASE)
+PATH_SEPARATOR = "/"
+REFRESH_REJECTED = "refresh-rejected"
+
+
+@dataclass(frozen=True)
+class MachineClient:
+    client_id: str
+    client_secret: str = field(repr=False)
+
+
+@dataclass(frozen=True)
+class UnauthenticatedReason:
+    status: int
+    type: str = REFRESH_REJECTED
+
+
+OnUnauthenticated = Callable[[UnauthenticatedReason], None]
+
+
+@dataclass(frozen=True)
+class OvokSettings:
+    base_url: str
+    tenant_code: str
+    fhir_path: str
+    storage: OvokStorage = field(repr=False)
+    transport: Transport = field(repr=False)
+    timeout: float
+    max_network_retries: int
+    client_id: str | None
+    machine_client: MachineClient | None
+    on_unauthenticated: OnUnauthenticated = field(repr=False)
+
+
+def read_settings(
+    base_url: str,
+    tenant_code: str,
+    *,
+    fhir_path: str = DEFAULT_FHIR_PATH,
+    storage: OvokStorage | None = None,
+    client_id: str | None = None,
+    client_secret: str | None = None,
+    transport: Transport | None = None,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    max_network_retries: int = DEFAULT_MAX_NETWORK_RETRIES,
+    on_unauthenticated: OnUnauthenticated | None = None,
+) -> OvokSettings:
+    """Checks every option up front, so a bad one fails at construction, not on the first request."""
+    return OvokSettings(
+        base_url=_read_base_url(base_url),
+        tenant_code=_require_text(tenant_code, "tenant_code"),
+        fhir_path=fhir_path.strip(PATH_SEPARATOR),
+        storage=storage or MemoryStorage(),
+        transport=transport or UrllibTransport(),
+        timeout=_require_positive(timeout, "timeout"),
+        max_network_retries=_require_count(max_network_retries, "max_network_retries"),
+        client_id=_optional_text(client_id, "client_id"),
+        machine_client=_read_machine_client(client_id, client_secret),
+        on_unauthenticated=on_unauthenticated or _ignore,
+    )
+
+
+def _ignore(_reason: UnauthenticatedReason) -> None:
+    return None
+
+
+def _config_error(message: str) -> OvokConfigError:
+    return OvokConfigError(OvokErrorDetails(message))
+
+
+def _read_base_url(base_url: str) -> str:
+    if isinstance(base_url, str) and ABSOLUTE_HTTP_URL.match(base_url):
+        return base_url if base_url.endswith(PATH_SEPARATOR) else f"{base_url}{PATH_SEPARATOR}"
+    raise _config_error("base_url must be an absolute http(s) URL.")
+
+
+def _read_machine_client(client_id: str | None, client_secret: str | None) -> MachineClient | None:
+    if client_secret is None:
+        return None
+    return MachineClient(_require_text(client_id, "client_id"), _require_text(client_secret, "client_secret"))
+
+
+def _optional_text(value: str | None, name: str) -> str | None:
+    return None if value is None else _require_text(value, name)
+
+
+def _require_text(value: str | None, name: str) -> str:
+    text = value.strip() if isinstance(value, str) else ""
+    if text:
+        return text
+    raise _config_error(f"{name} is required.")
+
+
+def _require_positive(value: float, name: str) -> float:
+    number = finite_number(value)
+    if number is not None and number > 0:
+        return float(number)
+    raise _config_error(f"{name} must be a positive number.")
+
+
+def _require_count(value: int, name: str) -> int:
+    if isinstance(value, int) and not isinstance(value, bool) and value >= 0:
+        return value
+    raise _config_error(f"{name} must be a whole number of at least 0.")