ohauthcat 0.0.2__py3-none-any.whl

ohauthcat/__init__.py

@@ -0,0 +1,95 @@
+"""Official OhAuthCat SDK for Python."""
+
+from ohauthcat import webhooks
+from ohauthcat._version import __version__
+from ohauthcat.access_token import AccessTokenClaims, AccessTokenVerificationError
+from ohauthcat.audit import audit_event_hints
+from ohauthcat.client import AsyncOhAuthCat, OhAuthCat
+from ohauthcat.end_user import (
+    EndUserTokenVerifier,
+    MachineTokenError,
+    MachineTokenSource,
+    has_permission,
+    has_role,
+    hosted_login_url,
+    machine_token_verifier,
+)
+from ohauthcat.errors import (
+    UNKNOWN_ERROR_CODE,
+    OhAuthCatError,
+    OhAuthCatValidationError,
+    PlanLimitReachedError,
+    parse_error_body,
+)
+from ohauthcat.flags import FlagResult, LocalFlags, evaluate_flag, flag_bucket
+from ohauthcat.jwt_verifier import JwtVerifier, TokenVerificationError
+from ohauthcat.logo import MAX_LOGO_BYTES, AsyncLogos, Logos, LogoType, check_logo
+from ohauthcat.migration import LegacySessionContext
+from ohauthcat.passkeys import AsyncNativePasskeys, NativePasskeys
+from ohauthcat.resource_server import (
+    BearerResult,
+    BearerValidator,
+    OAuthTokenVerifier,
+    bearer_challenge,
+    oauth_issuer,
+    protected_resource_metadata,
+    protected_resource_metadata_url,
+    token_scopes,
+)
+from ohauthcat.ssf import SecurityEvent, SecurityEventToken, SetVerifier, SsfError, SsfStreams
+from ohauthcat.sso import Authorization, RestartSignIn, pkce_challenge
+from ohauthcat.webhooks import VerifyOptions, WebhookVerificationError
+
+__all__ = [
+    "MAX_LOGO_BYTES",
+    "UNKNOWN_ERROR_CODE",
+    "AccessTokenClaims",
+    "AccessTokenVerificationError",
+    "AsyncLogos",
+    "AsyncNativePasskeys",
+    "AsyncOhAuthCat",
+    "Authorization",
+    "BearerResult",
+    "BearerValidator",
+    "EndUserTokenVerifier",
+    "FlagResult",
+    "JwtVerifier",
+    "LegacySessionContext",
+    "LocalFlags",
+    "LogoType",
+    "Logos",
+    "MachineTokenError",
+    "MachineTokenSource",
+    "NativePasskeys",
+    "OAuthTokenVerifier",
+    "OhAuthCat",
+    "OhAuthCatError",
+    "OhAuthCatValidationError",
+    "PlanLimitReachedError",
+    "RestartSignIn",
+    "SecurityEvent",
+    "SecurityEventToken",
+    "SetVerifier",
+    "SsfError",
+    "SsfStreams",
+    "TokenVerificationError",
+    "VerifyOptions",
+    "WebhookVerificationError",
+    "__version__",
+    "audit_event_hints",
+    "bearer_challenge",
+    "check_logo",
+    "evaluate_flag",
+    "flag_bucket",
+    "has_permission",
+    "has_role",
+    "hosted_login_url",
+    "machine_token_verifier",
+    "oauth_issuer",
+    "parse_error_body",
+    "pkce_challenge",
+    "protected_resource_metadata",
+    "protected_resource_metadata_url",
+    "token_scopes",
+    "webhooks",
+]

ohauthcat/_version.py

@@ -0,0 +1,6 @@
+"""The SDK version, kept in step with the Node SDK."""
+
+__version__ = "0.0.2"
+
+# Sent on every request to OhAuthCat, so the edge can tell SDK traffic apart.
+USER_AGENT = f"ohauthcat-sdk-python/{__version__}"

ohauthcat/access_token.py

@@ -0,0 +1,400 @@
+"""Configured-issuer ES256 access-token verification with bounded JWKS caching."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import binascii
+import re
+import threading
+import time
+from collections.abc import Awaitable, Callable
+from contextlib import suppress
+from dataclasses import dataclass, field
+
+import httpx
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.asymmetric.utils import encode_dss_signature
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+from ohauthcat.errors import OhAuthCatError
+from ohauthcat.transport import Settings, origin
+from ohauthcat.wire import JSON, record
+
+
+class AccessTokenVerificationError(ValueError):
+    """A safe failure that never includes a token, claim or key payload."""
+
+    def __init__(self) -> None:
+        super().__init__("Access token verification failed")
+
+
+class AccessTokenClaims(BaseModel):
+    """Authenticated, issuer/client/environment-bound access-token claims."""
+
+    model_config = ConfigDict(strict=True, frozen=True)
+    iss: str
+    aud: str
+    sub: str
+    env: str
+    org: str
+    conn: str
+    iat: int
+    nbf: int
+    exp: int
+    jti: str
+
+
+def decode_segment(segment: str) -> bytes:
+    """Require canonical unpadded base64url, never permissive alternate encodings."""
+    if not re.fullmatch(r"[A-Za-z0-9_-]+", segment):
+        raise AccessTokenVerificationError()
+    try:
+        result = base64.urlsafe_b64decode(segment + "=" * (-len(segment) % 4))
+        if base64.urlsafe_b64encode(result).decode().rstrip("=") != segment:
+            raise AccessTokenVerificationError()
+        return result
+    except (ValueError, binascii.Error):
+        raise AccessTokenVerificationError() from None
+
+
+def token_parts(token: str) -> tuple[str, bytes, bytes, bytes]:
+    """Pin JOSE semantics before obtaining a verification key."""
+    try:
+        if not isinstance(token, str) or not 0 < len(token) <= 4096:
+            raise AccessTokenVerificationError()
+        first, second, third = token.split(".")
+        header = record(JSON.validate_json(decode_segment(first)))
+        kid = header.get("kid")
+        signature = decode_segment(third)
+        if (
+            header.get("alg") != "ES256"
+            or header.get("typ") != "at+jwt"
+            or not isinstance(kid, str)
+            or not 0 < len(kid) <= 128
+            or "crit" in header
+            or "b64" in header
+            or len(signature) != 64
+        ):
+            raise AccessTokenVerificationError()
+        return kid, (first + "." + second).encode("ascii"), decode_segment(second), signature
+    except (ValueError, UnicodeError, ValidationError, RecursionError):
+        raise AccessTokenVerificationError() from None
+
+
+def public_keys(raw: bytes) -> dict[str, ec.EllipticCurvePublicKey]:
+    """Accept only unique public ES256/P-256 signature keys."""
+    try:
+        entries = record(JSON.validate_json(raw)).get("keys")
+        if not isinstance(entries, list) or not 1 <= len(entries) <= 32:
+            raise AccessTokenVerificationError()
+        result: dict[str, ec.EllipticCurvePublicKey] = {}
+        for entry in entries:
+            key = record(entry)
+            kid, x, y = key.get("kid"), key.get("x"), key.get("y")
+            if (
+                key.get("kty") != "EC"
+                or key.get("crv") != "P-256"
+                or key.get("alg") != "ES256"
+                or key.get("use") != "sig"
+                or "d" in key
+                or not isinstance(kid, str)
+                or not 0 < len(kid) <= 128
+                or kid in result
+                or not isinstance(x, str)
+                or not isinstance(y, str)
+            ):
+                raise AccessTokenVerificationError()
+            decoded_x, decoded_y = decode_segment(x), decode_segment(y)
+            if len(decoded_x) != 32 or len(decoded_y) != 32:
+                raise AccessTokenVerificationError()
+            result[kid] = ec.EllipticCurvePublicNumbers(
+                int.from_bytes(decoded_x, "big"), int.from_bytes(decoded_y, "big"), ec.SECP256R1()
+            ).public_key()
+        return result
+    except (ValueError, ValidationError, RecursionError):
+        raise AccessTokenVerificationError() from None
+
+
+def cache_ttl(header: str | None) -> float:
+    """Respect no-cache/no-store and cap explicit cache age at 300 seconds."""
+    value = header or ""
+    if re.search(r"(?:^|,)\s*(?:no-store|no-cache)(?:\s*(?:,|$))", value, re.I):
+        return 0
+    age = re.search(r"(?:^|,)\s*max-age=(\d+)(?:\s*(?:,|$))", value)
+    return min(300, int(age[1][:10])) if age else 300
+
+
+def verify_claims(
+    key: ec.EllipticCurvePublicKey, signed: bytes, raw: bytes, signature: bytes, settings: Settings
+) -> AccessTokenClaims:
+    """Verify raw r||s using cryptography and enforce configured trust bindings."""
+    try:
+        key.verify(
+            encode_dss_signature(
+                int.from_bytes(signature[:32], "big"), int.from_bytes(signature[32:], "big")
+            ),
+            signed,
+            ec.ECDSA(hashes.SHA256()),
+        )
+        claims = AccessTokenClaims.model_validate(JSON.validate_json(raw))
+        now = time.time()
+        if (
+            any(
+                not value
+                for value in [
+                    claims.iss,
+                    claims.aud,
+                    claims.sub,
+                    claims.env,
+                    claims.org,
+                    claims.conn,
+                    claims.jti,
+                ]
+            )
+            or any(not 0 <= value <= 2**53 - 1 for value in [claims.iat, claims.nbf, claims.exp])
+            or claims.iss != origin(settings.issuer, issuer=True)
+            or claims.aud != settings.client_id
+            or claims.env != settings.environment_id
+            or now >= claims.exp + 60
+            or now + 60 < claims.nbf
+            or now + 60 < claims.iat
+            or claims.exp <= claims.iat
+            or claims.nbf > claims.exp
+        ):
+            raise AccessTokenVerificationError()
+        return claims
+    except (InvalidSignature, ValueError, ValidationError, RecursionError):
+        raise AccessTokenVerificationError() from None
+
+
+@dataclass
+class Cache:
+    """Per-client cache; callers serialize refresh mutations."""
+
+    keys: dict[str, ec.EllipticCurvePublicKey] = field(default_factory=dict)
+    expires: float = 0
+    unknown_refresh: float = float("-inf")
+    failed_refresh: float = float("-inf")
+
+    def needs_refresh(self, kid: str) -> bool:
+        now = time.monotonic()
+        if (kid not in self.keys and now - self.unknown_refresh < 30) or (
+            now >= self.expires and now - self.failed_refresh < 30
+        ):
+            raise AccessTokenVerificationError()
+        if now >= self.expires:
+            return True
+        if kid not in self.keys:
+            self.unknown_refresh = now
+            return True
+        return False
+
+    def replace(self, raw: bytes, header: str | None, kid: str) -> None:
+        self.keys = public_keys(raw)
+        self.expires = time.monotonic() + cache_ttl(header)
+        self.failed_refresh = float("-inf")
+        if kid not in self.keys:
+            self.unknown_refresh = time.monotonic()
+
+    def failed(self) -> None:
+        self.failed_refresh = self.unknown_refresh = time.monotonic()
+
+
+def jwks_request(
+    settings: Settings, remaining: float | None = None, retrieval_origin: str | None = None
+) -> httpx.Request:
+    """Use only configured issuer, with no inherited client auth or cookies."""
+    return httpx.Request(
+        "GET",
+        origin(retrieval_origin or settings.issuer, issuer=True) + "/.well-known/jwks.json",
+        extensions={
+            "timeout": {
+                name: (settings.timeout_ms / 1000 if remaining is None else remaining)
+                for name in ["connect", "read", "write", "pool"]
+            }
+        },
+    )
+
+
+class Verifier:
+    """Sync single-flight refresh guarded by a bounded per-client lock."""
+
+    def __init__(
+        self,
+        settings: Settings,
+        client: httpx.Client,
+        retrieval_origin: Callable[[], str] | None = None,
+    ) -> None:
+        self.settings, self.client = settings, client
+        self.retrieval_origin = retrieval_origin
+        self.fetch_jwks: Callable[[float], tuple[bytes, str | None, int]] | None = None
+        self.keys_healthy: Callable[[int], None] | None = None
+        self.cache = Cache()
+        self.lock = threading.Lock()
+        self.closed = False
+
+    def close(self) -> None:
+        self.closed = True
+
+    def verify(self, token: str) -> AccessTokenClaims:
+        if not self.settings.client_id or not self.settings.environment_id or self.closed:
+            raise AccessTokenVerificationError()
+        deadline = time.monotonic() + self.settings.timeout_ms / 1000
+        kid, signed, raw, signature = token_parts(token)
+        if not self.lock.acquire(timeout=max(0, deadline - time.monotonic())):
+            raise AccessTokenVerificationError()
+        try:
+            if self.closed:
+                raise AccessTokenVerificationError()
+            if self.cache.needs_refresh(kid):
+                response: httpx.Response | None = None
+                try:
+                    remaining = deadline - time.monotonic()
+                    if remaining <= 0:
+                        raise AccessTokenVerificationError()
+                    if self.fetch_jwks is not None:
+                        raw_bytes, control, revision = self.fetch_jwks(deadline)
+                        self.cache.replace(raw_bytes, control, kid)
+                        if self.keys_healthy is not None:
+                            self.keys_healthy(revision)
+                    else:
+                        response = self.client.send(
+                            jwks_request(
+                                self.settings,
+                                remaining,
+                                None if self.retrieval_origin is None else self.retrieval_origin(),
+                            ),
+                            stream=True,
+                            auth=None,
+                            follow_redirects=False,
+                        )
+                        if not response.is_success:
+                            raise AccessTokenVerificationError()
+                        chunks: list[bytes] = []
+                        size = 0
+                        for chunk in response.iter_bytes():
+                            size += len(chunk)
+                            if size > 65536 or time.monotonic() >= deadline or self.closed:
+                                raise AccessTokenVerificationError()
+                            chunks.append(chunk)
+                        if self.closed:
+                            raise AccessTokenVerificationError()
+                        self.cache.replace(
+                            b"".join(chunks), response.headers.get("Cache-Control"), kid
+                        )
+                except (httpx.HTTPError, ValueError, OhAuthCatError):
+                    self.cache.failed()
+                    raise AccessTokenVerificationError() from None
+                finally:
+                    if response is not None:
+                        response.close()
+            key = self.cache.keys.get(kid)
+            if key is None:
+                raise AccessTokenVerificationError()
+            return verify_claims(key, signed, raw, signature, self.settings)
+        finally:
+            self.lock.release()
+
+
+class AsyncVerifier:
+    """Async single-flight refresh; cancelling one waiter does not cancel shared work."""
+
+    def __init__(
+        self,
+        settings: Settings,
+        client: httpx.AsyncClient,
+        retrieval_origin: Callable[[], str] | None = None,
+    ) -> None:
+        self.settings, self.client = settings, client
+        self.retrieval_origin = retrieval_origin
+        self.fetch_jwks: Callable[[float], Awaitable[tuple[bytes, str | None, int]]] | None = None
+        self.keys_healthy: Callable[[int], None] | None = None
+        self.cache = Cache()
+        self.pending: asyncio.Task[None] | None = None
+        self.closed = False
+
+    async def aclose(self) -> None:
+        self.closed = True
+        if self.pending is not None:
+            self.pending.cancel()
+            with suppress(asyncio.CancelledError, AccessTokenVerificationError):
+                await self.pending
+
+    async def _refresh(self, kid: str) -> None:
+        async def run() -> None:
+            response: httpx.Response | None = None
+            try:
+                if self.fetch_jwks is not None:
+                    raw_bytes, control, revision = await self.fetch_jwks(
+                        time.monotonic() + self.settings.timeout_ms / 1000
+                    )
+                    self.cache.replace(raw_bytes, control, kid)
+                    if self.keys_healthy is not None:
+                        self.keys_healthy(revision)
+                else:
+                    response = await self.client.send(
+                        jwks_request(
+                            self.settings,
+                            retrieval_origin=None
+                            if self.retrieval_origin is None
+                            else self.retrieval_origin(),
+                        ),
+                        stream=True,
+                        auth=None,
+                        follow_redirects=False,
+                    )
+                    if not response.is_success or self.closed:
+                        raise AccessTokenVerificationError()
+                    chunks: list[bytes] = []
+                    size = 0
+                    async for chunk in response.aiter_bytes():
+                        size += len(chunk)
+                        if size > 65536:
+                            raise AccessTokenVerificationError()
+                        chunks.append(chunk)
+                    if self.closed:
+                        raise AccessTokenVerificationError()
+                    self.cache.replace(b"".join(chunks), response.headers.get("Cache-Control"), kid)
+            finally:
+                if response is not None:
+                    await response.aclose()
+
+        try:
+            await asyncio.wait_for(run(), self.settings.timeout_ms / 1000)
+        except (httpx.HTTPError, ValueError, OhAuthCatError, asyncio.TimeoutError):
+            self.cache.failed()
+            raise AccessTokenVerificationError() from None
+
+    @staticmethod
+    def _consume_refresh(task: asyncio.Task[None]) -> None:
+        """Retrieve failures even if the last waiting caller was cancelled."""
+        if not task.cancelled():
+            task.exception()
+
+    async def verify(self, token: str) -> AccessTokenClaims:
+        if not self.settings.client_id or not self.settings.environment_id or self.closed:
+            raise AccessTokenVerificationError()
+        kid, signed, raw, signature = token_parts(token)
+        try:
+            if self.pending is not None and self.pending.done():
+                self.pending = None
+            if self.pending is None and self.cache.needs_refresh(kid):
+                self.pending = asyncio.create_task(self._refresh(kid))
+                self.pending.add_done_callback(self._consume_refresh)
+            if self.pending is not None:
+                pending = self.pending
+                done, _ = await asyncio.wait({pending}, timeout=self.settings.timeout_ms / 1000)
+                if not done:
+                    raise AccessTokenVerificationError()
+                pending.result()
+            if self.closed:
+                raise AccessTokenVerificationError()
+            key = self.cache.keys.get(kid)
+            if key is None:
+                raise AccessTokenVerificationError()
+            return verify_claims(key, signed, raw, signature, self.settings)
+        except (asyncio.TimeoutError, ValueError):
+            raise AccessTokenVerificationError() from None

ohauthcat/audit.py

@@ -0,0 +1,56 @@
+"""Pre-send hints for audit log events against the pinned schema."""
+
+from __future__ import annotations
+
+from pydantic import JsonValue
+
+from ohauthcat.wire import SCHEMAS, matches, record
+
+
+def _resolve(schema: JsonValue) -> dict[str, JsonValue]:
+    current = record(schema)
+    for _ in range(16):
+        ref = current.get("$ref")
+        if not isinstance(ref, str):
+            break
+        current = record(SCHEMAS.get(ref.rsplit("/", 1)[-1], {}))
+    return current
+
+
+def _walk(value: JsonValue, schema: JsonValue, path: str, hints: list[str]) -> None:
+    if matches(value, schema):
+        return
+    shape = _resolve(schema)
+    properties = shape.get("properties")
+    if isinstance(value, dict) and isinstance(properties, dict):
+        required = shape.get("required")
+        for name in required if isinstance(required, list) else []:
+            if isinstance(name, str) and value.get(name) is None:
+                hints.append(f"{path}.{name} is required")
+        for name, item in value.items():
+            if item is None:
+                continue
+            if name in properties:
+                _walk(item, properties[name], f"{path}.{name}", hints)
+            elif shape.get("additionalProperties") is False:
+                hints.append(f"{path}.{name} is not a known field")
+        if not hints:
+            hints.append(f"{path} does not match the schema")
+        return
+    items = shape.get("items")
+    if isinstance(value, list) and isinstance(items, dict):
+        before = len(hints)
+        for index, item in enumerate(value):
+            _walk(item, items, f"{path}[{index}]", hints)
+        if len(hints) == before:
+            hints.append(f"{path} has the wrong number of items")
+        return
+    hints.append(f"{path} does not match the schema")
+
+
+def audit_event_hints(body: JsonValue) -> list[str]:
+    """Readable problems with an audit log event body; empty when well formed.
+    The server still validates the event against the action's registered schema."""
+    hints: list[str] = []
+    _walk(body, {"$ref": "#/components/schemas/AuditLogEventCreate"}, "body", hints)
+    return hints