cloakapi 0.5.1__py3-none-any.whl

cloakapi/_http.py

@@ -0,0 +1,443 @@
+"""
+Internal HTTP layer -- shared by both sync and async clients.
+
+Handles:
+- Authorization header injection
+- Retry with exponential backoff + jitter
+- Error mapping from HTTP responses
+- Debug logging (scrubbed of API key; never logs message content)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import random
+import time
+from typing import Any, TypeVar
+from urllib.parse import urlsplit
+
+import httpx
+
+from ._version import SDK_VERSION
+from .config import DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT
+from .errors import (
+    CloakAPIError,
+    NetworkError,
+    RequestBodyRejectedError,
+    _extract_error,
+    _map_status,
+    _request_id,
+)
+
+logger = logging.getLogger("cloakapi")
+
+_ModelT = TypeVar("_ModelT")
+
+# Keep the JSON response ceiling in step with the Go SDK's readLimitedBody.
+# httpx has already buffered response.content at this point, but refusing before
+# JSON parsing prevents a gateway response from expanding into an unbounded
+# Python object graph.
+MAX_RESPONSE_BODY_BYTES = 32 * 1024 * 1024
+
+_LOG_REQUESTS = os.environ.get("CLOAKAPI_LOG_REQUESTS", "") == "1"
+
+# Status codes that are safe to retry
+_RETRY_STATUSES = {429, 502, 503, 504}
+_RETRY_EXCEPTIONS = (httpx.ConnectError, httpx.ReadTimeout, httpx.ConnectTimeout)
+_RELAY_MAC_HEADER = "X-Cloak-Client-MAC"
+
+
+def serialise_body(body: Any) -> bytes:
+    """Canonical JSON serialisation of a relay body.
+
+    This is the SINGLE source of truth for how a request body is turned into
+    bytes. The exact bytes produced here are BOTH what egresses to the gateway
+    AND what is signed for the pre-tokenised passthrough MAC (POST
+    /api/v1/pretokenised/mac). They must be byte-identical for the gateway's
+    constant-time MAC check to pass, so both paths call this one function with
+    the same ``dict`` (Python's ``json.dumps`` preserves key insertion order and
+    uses fixed default separators, so the output is deterministic).
+    """
+    try:
+        # allow_nan is on by default and emits the tokens NaN / Infinity, which
+        # are not JSON. A non-finite leaf must not leave with the rest of the body.
+        return json.dumps(body, allow_nan=False).encode()
+    except ValueError:
+        raise RequestBodyRejectedError() from None
+
+
+def response_json_object(response: httpx.Response, *, endpoint: str) -> dict[str, Any]:
+    """Return a JSON object response, rejecting other JSON shapes explicitly."""
+    payload = response_json(response)
+    if not isinstance(payload, dict):
+        raise ValueError(f"expected a JSON object from {endpoint}")
+    return payload
+
+
+def ensure_response_size(response: httpx.Response) -> None:
+    """Reject an oversized buffered gateway response before JSON parsing."""
+    if len(response.content) > MAX_RESPONSE_BODY_BYTES:
+        raise CloakAPIError("Gateway response exceeds the SDK limit")
+
+
+def _read_limited_response(response: httpx.Response) -> httpx.Response:
+    """Buffer at most the SDK response limit, then close the transport stream."""
+    body = bytearray()
+    try:
+        for chunk in response.iter_bytes():
+            if len(body) + len(chunk) > MAX_RESPONSE_BODY_BYTES:
+                raise CloakAPIError("Gateway response exceeds the SDK limit")
+            body.extend(chunk)
+    finally:
+        response.close()
+
+    headers = response.headers.copy()
+    for key in ("content-encoding", "content-length", "transfer-encoding"):
+        headers.pop(key, None)
+    return httpx.Response(
+        response.status_code,
+        headers=headers,
+        content=bytes(body),
+        request=response.request,
+    )
+
+
+async def _aread_limited_response(response: httpx.Response) -> httpx.Response:
+    """Async variant of :func:`_read_limited_response`."""
+    body = bytearray()
+    try:
+        async for chunk in response.aiter_bytes():
+            if len(body) + len(chunk) > MAX_RESPONSE_BODY_BYTES:
+                raise CloakAPIError("Gateway response exceeds the SDK limit")
+            body.extend(chunk)
+    finally:
+        await response.aclose()
+
+    headers = response.headers.copy()
+    for key in ("content-encoding", "content-length", "transfer-encoding"):
+        headers.pop(key, None)
+    return httpx.Response(
+        response.status_code,
+        headers=headers,
+        content=bytes(body),
+        request=response.request,
+    )
+
+
+def response_json(response: httpx.Response) -> Any:
+    """Decode a gateway response without retaining malformed body data in errors."""
+    ensure_response_size(response)
+    invalid_json = False
+    try:
+        payload = response.json()
+    except (json.JSONDecodeError, UnicodeDecodeError, ValueError):
+        # Keep only a boolean beyond the except block: JSONDecodeError.doc and
+        # its traceback/context can contain the entire upstream response.
+        invalid_json = True
+        payload = None
+    if invalid_json:
+        raise CloakAPIError("Gateway returned invalid JSON")
+    return payload
+
+
+def validate_response(data: Any, model: type[_ModelT], *, endpoint: str) -> _ModelT:
+    """Validate upstream JSON without exposing response fields in validation errors."""
+    from .errors import CloakAPIError
+
+    invalid = False
+    result: _ModelT | None = None
+    try:
+        result = model.model_validate(data)  # type: ignore[attr-defined]
+    except Exception:
+        invalid = True
+    if invalid or result is None:
+        raise CloakAPIError(f"Gateway returned an invalid response from {endpoint}")
+    return result
+
+
+def _base_headers(api_key: str, extra: dict[str, str] | None = None) -> dict[str, str]:
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+        "User-Agent": f"cloakapi-python/{SDK_VERSION}",
+        "X-CloakAPI-SDK": f"python/{SDK_VERSION}",
+    }
+    if extra:
+        headers.update(extra)
+    return headers
+
+
+def _backoff(attempt: int, retry_after: float | None = None) -> float:
+    """Exponential backoff with full jitter, respecting Retry-After."""
+    if retry_after is not None:
+        return retry_after
+    base = min(0.5 * (2**attempt), 32.0)
+    return float(base * random.random())
+
+
+def _require_retry_budget(max_retries: object, timeout: object) -> None:
+    """Reject a wrong-typed retry budget before any byte is sent."""
+    if isinstance(max_retries, bool) or not isinstance(max_retries, int) or max_retries < 0:
+        raise ValueError("max_retries must be a non-negative integer")
+    if (
+        isinstance(timeout, bool)
+        or not isinstance(timeout, (int, float))
+        or timeout < 0
+        or timeout != timeout
+        or timeout == float("inf")
+    ):
+        raise ValueError("timeout must be a non-negative finite number")
+
+
+def safe_path_segment(value: object, *, what: str) -> str:
+    """One URL path segment. Rejects traversal, queries, and control bytes.
+
+    The error text is fixed: ``value`` is caller-supplied and may be a secret
+    or a document name.
+    """
+    if not isinstance(value, str) or not _is_safe_path_segment(value):
+        raise ValueError(f"{what} is invalid")
+    return value
+
+
+def _is_safe_path_segment(value: str) -> bool:
+    if not value or len(value) > 200 or ".." in value:
+        return False
+    for ch in value:
+        if ("0" <= ch <= "9") or ("A" <= ch <= "Z") or ("a" <= ch <= "z") or ch in "._:-":
+            continue
+        return False
+    return True
+
+
+def absolutt_url(base_url: str | None, path: str) -> str:
+    """Join the GATEWAY-LOCK-validated base to a request path.
+
+    ⛔ KVIFOR (2026-08-07, målt)
+
+    ``base_url`` used to be applied ONLY to the ``httpx.Client`` this SDK builds
+    for itself. A caller who passed ``http_client=`` got a client with no base,
+    so every path stayed relative — and, worse, a caller whose own client had a
+    base of ``https://api.openai.com`` egressed there while ``client.base_url``
+    still reported ``https://api.cloakapi.io``. ``validate_gateway_base``
+    documents itself as "the HARD billing invariant … there is NO
+    direct-to-provider mode", and it validated a value the request path then
+    never used.
+
+    The fix is the .NET port's shape (``Client.cs:607``), which never sets
+    ``BaseAddress`` and builds ``_baseUrl + path`` at every call site — the one
+    port of the nine that already had this right.
+
+    An already-absolute ``path`` is returned untouched, so a caller that passes
+    a full URL (the receipts resource builds some) is unaffected.
+    """
+    if not isinstance(path, str) or "\r" in path or "\n" in path:
+        raise ValueError("request path is invalid")
+    if path.startswith("//") or "@" in path.split("?", 1)[0]:
+        raise ValueError("request path must stay on the configured origin")
+    path_only = path.split("?", 1)[0].split("#", 1)[0]
+    if any(segment in {".", ".."} for segment in path_only.split("/")):
+        raise ValueError("request path must stay on the configured origin")
+    if not base_url:
+        if path.startswith(("http://", "https://")):
+            return path
+        return path
+    base = urlsplit(base_url)
+    candidate = urlsplit(path)
+    if candidate.scheme or candidate.netloc:
+        def origin(parts: Any) -> tuple[str, str | None, int | None]:
+            scheme = parts.scheme.lower()
+            port = parts.port or (443 if scheme == "https" else 80 if scheme == "http" else None)
+            return scheme, parts.hostname.lower() if parts.hostname else None, port
+
+        if origin(candidate) != origin(base):
+            raise ValueError("request URL must stay on the configured origin")
+        return path
+    return base_url.rstrip("/") + "/" + path.lstrip("/")
+
+
+def sync_request(
+    client: httpx.Client,
+    method: str,
+    path: str,
+    api_key: str,
+    *,
+    base_url: str | None = None,
+    body: dict[str, Any] | None = None,
+    content: bytes | None = None,
+    extra_headers: dict[str, str] | None = None,
+    stream: bool = False,
+    max_retries: int = DEFAULT_MAX_RETRIES,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> httpx.Response:
+    """
+    Execute a sync HTTP request with retry + error mapping.
+
+    Returns the raw httpx.Response (caller reads .json() or iterates stream).
+    Raises CloakAPIError subclasses on unrecoverable failure.
+
+    ``content`` (pre-serialised bytes) takes precedence over ``body`` so a
+    caller that has already serialised (e.g. to sign the pre-tokenised MAC over
+    the exact egressing bytes) can relay those same bytes verbatim.
+    """
+    _require_retry_budget(max_retries, timeout)
+    headers = _base_headers(api_key, extra_headers)
+    # A pre-tokenised relay POST is approved by its exact-body MAC. Retrying it
+    # after a lost response could replay an already accepted request.
+    single_attempt = method.upper() == "POST" and _RELAY_MAC_HEADER in headers
+    if content is None:
+        content = serialise_body(body) if body is not None else None
+    path = absolutt_url(base_url, path)
+    attempt = 0
+
+    while True:
+        failure: NetworkError | None = None
+        try:
+            if _LOG_REQUESTS:
+                logger.debug("REQUEST %s", method)
+
+            request = client.build_request(
+                method,
+                path,
+                content=content,
+                headers=headers,
+                timeout=timeout,
+            )
+            response = client.send(request, stream=True, follow_redirects=False)
+            response = _read_limited_response(response)
+
+        except _RETRY_EXCEPTIONS:
+            attempt += 1
+            if single_attempt or attempt > max_retries:
+                failure = NetworkError(f"Connection failed after {max_retries} retries")
+            else:
+                wait = _backoff(attempt)
+                logger.debug(
+                    "Network error (attempt %d/%d), retrying in %.2fs",
+                    attempt,
+                    max_retries,
+                    wait,
+                )
+                time.sleep(wait)
+                continue
+
+        except httpx.HTTPError:
+            failure = NetworkError("HTTP request failed")
+
+        if failure is not None:
+            raise failure
+
+        ensure_response_size(response)
+
+        if response.is_success:
+            return response
+
+        if not single_attempt and response.status_code in _RETRY_STATUSES and attempt < max_retries:
+            message, code, retry_after = _extract_error(response)
+            wait = _backoff(attempt, retry_after)
+            attempt += 1
+            logger.debug(
+                "Status %d (attempt %d/%d), retrying in %.2fs",
+                response.status_code,
+                attempt,
+                max_retries,
+                wait,
+            )
+            time.sleep(wait)
+            continue
+
+        message, code, retry_after = _extract_error(response)
+        rid = _request_id(response)
+        raise _map_status(
+            response.status_code, message, request_id=rid, code=code, retry_after=retry_after
+        )
+
+
+async def async_request(
+    client: httpx.AsyncClient,
+    method: str,
+    path: str,
+    api_key: str,
+    *,
+    base_url: str | None = None,
+    body: dict[str, Any] | None = None,
+    content: bytes | None = None,
+    extra_headers: dict[str, str] | None = None,
+    stream: bool = False,
+    max_retries: int = DEFAULT_MAX_RETRIES,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> httpx.Response:
+    """Async variant of sync_request (``content`` overrides ``body``)."""
+    _require_retry_budget(max_retries, timeout)
+    headers = _base_headers(api_key, extra_headers)
+    single_attempt = method.upper() == "POST" and _RELAY_MAC_HEADER in headers
+    if content is None:
+        content = serialise_body(body) if body is not None else None
+    path = absolutt_url(base_url, path)
+    attempt = 0
+
+    while True:
+        failure: NetworkError | None = None
+        try:
+            if _LOG_REQUESTS:
+                logger.debug("ASYNC REQUEST %s", method)
+
+            request = client.build_request(
+                method,
+                path,
+                content=content,
+                headers=headers,
+                timeout=timeout,
+            )
+            response = await client.send(request, stream=True, follow_redirects=False)
+            response = await _aread_limited_response(response)
+
+        except _RETRY_EXCEPTIONS:
+            attempt += 1
+            if single_attempt or attempt > max_retries:
+                failure = NetworkError(f"Connection failed after {max_retries} retries")
+            else:
+                wait = _backoff(attempt)
+                logger.debug(
+                    "Async network error (attempt %d/%d), retrying in %.2fs",
+                    attempt,
+                    max_retries,
+                    wait,
+                )
+                await asyncio.sleep(wait)
+                continue
+
+        except httpx.HTTPError:
+            failure = NetworkError("HTTP request failed")
+
+        if failure is not None:
+            raise failure
+
+        ensure_response_size(response)
+
+        if response.is_success:
+            return response
+
+        if not single_attempt and response.status_code in _RETRY_STATUSES and attempt < max_retries:
+            message, code, retry_after = _extract_error(response)
+            wait = _backoff(attempt, retry_after)
+            attempt += 1
+            logger.debug(
+                "Async status %d (attempt %d/%d), retrying in %.2fs",
+                response.status_code,
+                attempt,
+                max_retries,
+                wait,
+            )
+            await asyncio.sleep(wait)
+            continue
+
+        message, code, retry_after = _extract_error(response)
+        rid = _request_id(response)
+        raise _map_status(
+            response.status_code, message, request_id=rid, code=code, retry_after=retry_after
+        )

cloakapi/_pretokenised.py

@@ -0,0 +1,134 @@
+"""
+Client-side pre-tokenised passthrough (Level-1 relay half).
+
+The SDK tokenises PII on-device (``cloakapi.pii.tokenizer`` / the shared FFI
+engine) BEFORE anything egresses, then relays the already-tokenised body to the
+CloakAPI gateway. Under the Level-1-only fail-closed gateway the relay is
+accepted ONLY when it PROVES the body was tokenised client-side, via:
+
+    X-Cloak-Pretokenised: 1
+    X-Cloak-Client-MAC:  <HMAC-SHA256 of the exact tokenised body bytes>
+    X-CloakAPI-Routing:  client
+
+on top of the engine-identity headers the SDK already sends
+(``X-Cloak-Engine-Version`` / ``X-Cloak-Engine-Hash``). The per-body MAC is
+minted server-side from the tenant key by ``POST /api/v1/pretokenised/mac`` — so
+the client never holds the raw tenant key — and is computed over the EXACT bytes
+that are then relayed to ``/messages`` / ``/chat/completions`` (both derived from
+the one :func:`cloakapi._http.serialise_body` call), so the gateway's
+constant-time check (``PrivacyTokenisationMiddleware``) passes.
+
+This mirrors, in Python, the cloakup server relay
+(``cloakup/src/lib/server/cloak/pretokenised.ts``) and the CloakAPI starter-kit
+route — same endpoint, same header names, same "MAC over the exact egressing
+bytes" contract.
+
+Fail-loud: if the MAC cannot be obtained the request is NOT relayed. An HTTP
+error from ``/mac`` surfaces as the usual typed :class:`~cloakapi.errors.APIError`
+(e.g. 401 when unauthenticated); a 2xx response with no usable ``mac`` raises
+:class:`~cloakapi.errors.PretokenisedMacError`. There is deliberately NO
+silent "relay without the MAC" fallback.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ._http import async_request, sync_request
+from .config import DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT
+from .errors import PretokenisedMacError
+
+# Endpoint that mints the per-body passthrough MAC for the authenticated tenant.
+MAC_PATH = "/api/v1/pretokenised/mac"
+
+# Passthrough proof headers (EXACT names the gateway's
+# PrivacyTokenisationMiddleware reads; mirror cloakup/starter-kit/TS SDK).
+HEADER_PRETOKENISED = "X-Cloak-Pretokenised"
+HEADER_CLIENT_MAC = "X-Cloak-Client-MAC"
+HEADER_ROUTING = "X-CloakAPI-Routing"
+
+
+def proof_headers(mac: str) -> dict[str, str]:
+    """The pre-tokenised passthrough proof headers for a minted per-body MAC."""
+    return {
+        HEADER_PRETOKENISED: "1",
+        HEADER_CLIENT_MAC: mac,
+        HEADER_ROUTING: "client",
+    }
+
+
+def _extract_mac(payload: Any) -> str:
+    """Pull the ``mac`` string out of the /mac response (``{mac}`` or
+    ``{data:{mac}}``, matching the cloakup/TS clients). Raises if absent."""
+    mac: Any = None
+    if isinstance(payload, dict):
+        mac = payload.get("mac")
+        if not mac and isinstance(payload.get("data"), dict):
+            mac = payload["data"].get("mac")
+    if isinstance(mac, str) and mac:
+        return mac
+    raise PretokenisedMacError(
+        "pre-tokenised MAC endpoint returned no usable 'mac' — refusing to relay "
+        "without the client MAC proof"
+    )
+
+
+def fetch_mac_sync(
+    client: httpx.Client,
+    api_key: str,
+    body_bytes: bytes,
+    *,
+    base_url: str | None = None,
+    max_retries: int = DEFAULT_MAX_RETRIES,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> str:
+    """Mint the per-body passthrough MAC for ``body_bytes`` (the EXACT bytes that
+    will be relayed). Fail-loud: never returns without a valid MAC."""
+    resp = sync_request(
+        client,
+        "POST",
+        MAC_PATH,
+        api_key,
+        base_url=base_url,
+        content=body_bytes,
+        max_retries=max_retries,
+        timeout=timeout,
+    )
+    try:
+        payload = resp.json()
+    except Exception:
+        payload = None
+    if payload is None:
+        raise PretokenisedMacError("pre-tokenised MAC response was not valid JSON")
+    return _extract_mac(payload)
+
+
+async def fetch_mac_async(
+    client: httpx.AsyncClient,
+    api_key: str,
+    body_bytes: bytes,
+    *,
+    base_url: str | None = None,
+    max_retries: int = DEFAULT_MAX_RETRIES,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> str:
+    """Async variant of :func:`fetch_mac_sync`."""
+    resp = await async_request(
+        client,
+        "POST",
+        MAC_PATH,
+        api_key,
+        base_url=base_url,
+        content=body_bytes,
+        max_retries=max_retries,
+        timeout=timeout,
+    )
+    try:
+        payload = resp.json()
+    except Exception:
+        payload = None
+    if payload is None:
+        raise PretokenisedMacError("pre-tokenised MAC response was not valid JSON")
+    return _extract_mac(payload)