cloakapi 0.5.1__py3-none-any.whl

cloakapi/_relay.py

@@ -0,0 +1,213 @@
+"""One relay request, from the tokenised body to the bytes that leave.
+
+The sync and async clients share every step that does not touch the network:
+what the request declares about itself, which notices it carries, and what the
+reviewer is shown. Two copies of these rules drifted before, so they live here
+once. The clients pass in their own ``engine_available`` and
+``require_pinned_engine_identity`` so each keeps a single place to substitute
+them.
+
+What a prepared request always has:
+
+* the exact body bytes, serialised once, that the MAC is minted over and that
+  are then sent;
+* ``X-Cloak-Coverage`` and ``X-CloakAPI-Tokenized: true;coverage=<coverage>``,
+  which state which local layers ran;
+* engine identity headers only when a pinned engine with this SDK's rule set
+  ran. A request the structured rules prepared claims no engine.
+
+What never happens here: a request is not refused for its content. Reduced
+coverage, a value in a place that must stay as written (an identifier, a tool
+schema literal, a number, a key inside tool arguments) and media this device
+did not read become notices on the request, shown to the reviewer and returned
+with the reply. A detected value used as an object key in free-form data is
+replaced here, where it stands.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from ._http import absolutt_url, serialise_body
+from ._request_strings import assert_no_thai_khmer, bind_tokeniser, settle_structure
+from .coverage import Coverage
+from .degraded import KIND_NO_NER, engine_reason, guard_reduced_coverage
+from .errors import EngineIdentityError, PlaintextRelayNotSupportedError
+from .notices import (
+    REDUCED_COVERAGE,
+    ReviewInfo,
+    SendWarning,
+    place_warnings,
+    print_unchecked_content,
+    reduced_coverage_warning,
+    unchecked_content_warning,
+)
+from .review import RelayReview
+
+_NO_ENGINE_SENTENCE = "No on-device engine is installed for this platform."
+_ENGINE_REFUSED_SENTENCE = "The on-device engine could not process part of this request."
+_MODEL_MESSAGE = (
+    "The name model is not available on this device, so names are checked against "
+    "the built-in list only."
+)
+
+
+@dataclass
+class BuiltRelay:
+    """A relay request that is ready for review. Nothing has been sent."""
+
+    method: str
+    path: str
+    url: str
+    content: bytes
+    headers: dict[str, str]
+    coverage: Coverage
+    warnings: tuple[SendWarning, ...] = ()
+    token_map: dict[str, str] = field(default_factory=dict)
+    #: The signed receipt the gateway returned with the reply to THIS request, if any.
+    receipt: dict[str, Any] | None = None
+
+    @property
+    def text(self) -> str:
+        """The exact outgoing body, as text."""
+        return self.content.decode("utf-8")
+
+    @property
+    def state(self) -> str:
+        return "ok" if self.coverage is Coverage.FULL and not self.warnings else "degraded"
+
+    def info(self) -> ReviewInfo:
+        return ReviewInfo(
+            state="ok" if self.state == "ok" else "degraded",
+            coverage=self.coverage.value,
+            warnings=self.warnings,
+        )
+
+    def review(self) -> RelayReview:
+        return RelayReview.create(self.method, self.url, self.content, self.headers)
+
+
+def build_relay(
+    client: Any,
+    body: dict[str, Any],
+    extra_headers: dict[str, str],
+    should_tokenize: bool,
+    *,
+    method: str,
+    path: str,
+    engine_available: Callable[[], bool],
+    require_pinned_engine_identity: Callable[[], Any],
+    state: dict[str, Any] | None = None,
+) -> BuiltRelay:
+    """Finalise the body and headers of one relay request. No network, no review.
+
+    ``state`` is the per-request state ``_prepare_messages`` returned. When it
+    is given, coverage and notices are read from it and not from the client's
+    "latest request" attributes, so two overlapping requests on one client
+    cannot take each other's coverage or lose each other's notices.
+    """
+    if not should_tokenize:
+        raise PlaintextRelayNotSupportedError(
+            "tokenize=False is not supported for relay requests; enable on-device tokenization."
+        )
+    notices: list[SendWarning] = []
+    own = state if isinstance(state, dict) and "coverage" in state else None
+    # Keys, identifiers, schema literals and media: the last pass over the body.
+    # It replaces what can be replaced and records the rest on this request.
+    settle_tok = bind_tokeniser(client, state if isinstance(state, dict) else None)
+    body = settle_structure(body, settle_tok)
+    places = list(settle_tok.state.get("unreplaced_places", ()))  # type: ignore[attr-defined]
+    coverage = (own["coverage"] if own is not None else client._last_coverage) or Coverage.FULL
+    if assert_no_thai_khmer(body):
+        coverage = Coverage.RULES_ONLY
+        client._last_coverage = coverage
+        guard_reduced_coverage("tokenise text", kind=KIND_NO_NER)
+        notices.append(unchecked_content_warning("unverified_script"))
+    value_not_replaced = (
+        own.get("value_not_replaced", False)
+        if own is not None
+        else getattr(client, "_last_value_not_replaced", False)
+    )
+    if places:
+        notices.extend(place_warnings(places))
+    elif value_not_replaced:
+        notices.append(unchecked_content_warning("value_not_replaced"))
+    headers = dict(extra_headers)
+    trusted_engine = engine_available()
+    ident: dict[str, str] = {}
+    if trusted_engine:
+        try:
+            candidate = require_pinned_engine_identity()
+            if isinstance(candidate, dict) and candidate.get("version") and candidate.get("hash"):
+                ident = candidate
+            else:
+                trusted_engine = False
+        except EngineIdentityError:
+            trusted_engine = False
+    # The engine is in use but would not take at least one string of this
+    # request, and the structured rules prepared it instead. Such a request was
+    # not prepared by the engine: it states no engine identity, and its notice
+    # says what ran (not "the name model is missing").
+    engine_refused = bool(trusted_engine and own is not None and own.get("rules_prepared"))
+    if engine_refused:
+        trusted_engine = False
+        ident = {}
+    if not trusted_engine:
+        if coverage is not Coverage.RULES_ONLY:
+            guard_reduced_coverage("tokenise text", kind=KIND_NO_NER)
+        coverage = Coverage.RULES_ONLY
+        client._last_coverage = coverage
+        # _prepare_messages may have populated identity headers before the
+        # final pin check. Never carry those claims into review or egress when
+        # this request cannot prove the loaded engine.
+        headers.pop("X-Cloak-Engine-Version", None)
+        headers.pop("X-Cloak-Engine-Hash", None)
+        if engine_refused:
+            notices.insert(0, reduced_coverage_warning("engine_refused", _ENGINE_REFUSED_SENTENCE))
+        else:
+            reason = engine_reason() or ("engine_missing", _NO_ENGINE_SENTENCE)
+            notices.insert(
+                0, reduced_coverage_warning(reason[0], reason[1] or _NO_ENGINE_SENTENCE)
+            )
+    elif coverage is not Coverage.FULL and (
+        own is None or own.get("detector_coverage", coverage) is not Coverage.FULL
+    ):
+        # The engine ran; only its name model is missing. Not "rules ran instead".
+        # (Not said when the detector reported full coverage and the label was
+        # lowered only because a value or a script was left as written: those
+        # have their own notice.)
+        notices.insert(0, SendWarning(REDUCED_COVERAGE, "model_missing", _MODEL_MESSAGE))
+    headers["X-Cloak-Coverage"] = coverage.value
+    headers["X-CloakAPI-Tokenized"] = f"true;coverage={coverage.value}"
+    content = serialise_body(body)
+    last_mode = (own.get("surrogate_mode") if own is not None else None) or client._last_surrogate_mode
+    actual_mode = getattr(last_mode, "mode", last_mode)
+    headers["X-CloakAPI-Mode"] = (
+        "max" if coverage is Coverage.RULES_ONLY and actual_mode == "max" else client.tier
+    )
+    if ident.get("version") and (coverage is not Coverage.RULES_ONLY or ident.get("hash")):
+        headers["X-Cloak-Engine-Version"] = ident["version"]
+    if ident.get("hash"):
+        headers["X-Cloak-Engine-Hash"] = ident["hash"]
+    warnings = tuple(notices)
+    client._last_warnings = warnings
+    print_unchecked_content(warnings)
+    return BuiltRelay(
+        method=method,
+        path=path,
+        url=absolutt_url(client._base_url, path),
+        content=content,
+        headers=headers,
+        coverage=coverage,
+        warnings=warnings,
+    )
+
+
+def refuse_plaintext_tier(client: Any) -> None:
+    if str(client.tier) == "off":  # defense-in-depth for runtime mutation
+        raise PlaintextRelayNotSupportedError(
+            "tier='off' is a plaintext relay; under Level-1-only the gateway "
+            "relays only client-tokenised requests. Use tier 'balanced' or 'max'."
+        )

cloakapi/_release.py

@@ -0,0 +1,30 @@
+"""The release set this package was cut for.
+
+One place for the numbers that tie this package to the other CloakAPI packages
+of the same release: the rule set it expects and the native engine files it
+trusts when one is shipped inside a wheel. ``repo/release-set.json`` is the
+source; ``repo/shared/testing/release-set-check.mjs python`` and
+``tests/test_release_set.py`` fail when this file disagrees with it, and
+``hatch_build.py`` refuses to build a wheel around any other engine file.
+
+Plain string constants on purpose: the build hook and the lockstep check read
+them without importing the package.
+"""
+
+from __future__ import annotations
+
+RELEASE_SET = "R-1.6.1"
+
+#: Rule set this SDK's own rules and its native engine must both carry.
+RULESET_VERSION = "1.6.1"
+RULESET_SHA256 = "8660b7abe553154802c9d27888a144863bcceaa3703517b8401cc56c590df2f9"
+
+#: SHA-256 of the native engine file per platform (``cloak-engine-ffi`` 0.3.0).
+NATIVE_SHA256_LINUX_X86_64 = "b2aec8d6d90ead4328258270c41a79dda4e1f71efa79025f308ce8e09f080744"
+NATIVE_SHA256_LINUX_AARCH64 = "a8bfb99346cdaf6e47b13214e7f1f872f95e0c2fe040cf6bb3e6a82f1d26ed30"
+
+#: Wheel platform arch -> the one engine file a wheel for it may carry.
+NATIVE_ENGINE_SHA256 = {
+    "x86_64": NATIVE_SHA256_LINUX_X86_64,
+    "aarch64": NATIVE_SHA256_LINUX_AARCH64,
+}