openbox-sdk-python 0.2.0__py3-none-any.whl

openbox_core/errors.py

@@ -0,0 +1,287 @@
+"""OpenBox base SDK — unified exception hierarchy.
+
+Pure module: no network, crypto, OTel, logging, or wall-clock imports. Safe to
+import from constrained framework paths.
+
+Hierarchy:
+    OpenBoxError (base)
+    ├── ContractError               # strict-gate event/runtime contract violation
+    ├── OpenBoxConfigError
+    │   ├── OpenBoxAuthError
+    │   │   └── OpenBoxSigningError # Core rejected a signed (AIP DID) request
+    │   ├── OpenBoxNetworkError
+    │   └── OpenBoxInsecureURLError
+    ├── GovernanceBlockedError      # hook/activity verdict BLOCK
+    ├── GovernanceHaltError         # verdict HALT (framework-level termination)
+    ├── GovernanceAPIError          # governance API failure (fail_closed)
+    ├── GuardrailsValidationError   # guardrails validation_passed=False
+    ├── ApprovalExpiredError        # HITL approval window expired
+    ├── ApprovalRejectedError       # HITL approval explicitly rejected
+    └── ApprovalTimeoutError        # HITL polling exceeded max wait
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .contracts.results import Verdict
+
+__all__ = [
+    "OpenBoxError",
+    "ContractError",
+    "OpenBoxConfigError",
+    "OpenBoxAuthError",
+    "OpenBoxNetworkError",
+    "OpenBoxInsecureURLError",
+    "OpenBoxSigningError",
+    "map_signing_error",
+    "GovernanceBlockedError",
+    "GovernanceHaltError",
+    "GovernanceAPIError",
+    "GuardrailsValidationError",
+    "ApprovalExpiredError",
+    "ApprovalRejectedError",
+    "ApprovalTimeoutError",
+    "extract_governance_error",
+]
+
+
+# ═══════════════════════════════════════════════════════════════════
+# Base
+# ═══════════════════════════════════════════════════════════════════
+
+
+class OpenBoxError(Exception):
+    """Base class for all OpenBox SDK errors."""
+
+
+# ═══════════════════════════════════════════════════════════════════
+# Strict-gate contract violations
+# ═══════════════════════════════════════════════════════════════════
+
+
+class ContractError(OpenBoxError):
+    """Raised by the always-strict gate on a malformed event/runtime contract.
+
+    Contract violations raise *before* any network send, regardless of the
+    ``on_api_error`` fail-open/fail-closed setting — fail-open applies only to
+    network errors, never to contract violations.
+
+    Attributes:
+        code: Machine-readable violation code (e.g. ``HOOK_TRIGGER_FALSE``).
+        detail: Optional structured context about the violation.
+    """
+
+    def __init__(self, message: str, code: str = "", detail: dict | None = None):
+        self.code = code
+        self.detail = detail or {}
+        super().__init__(message)
+
+
+# ═══════════════════════════════════════════════════════════════════
+# Configuration errors
+# ═══════════════════════════════════════════════════════════════════
+
+
+class OpenBoxConfigError(OpenBoxError):
+    """Raised when OpenBox configuration fails."""
+
+
+class OpenBoxAuthError(OpenBoxConfigError):
+    """Raised when API key validation fails."""
+
+
+class OpenBoxNetworkError(OpenBoxConfigError):
+    """Raised when network connectivity fails."""
+
+
+class OpenBoxInsecureURLError(OpenBoxConfigError):
+    """Raised when HTTP is used for non-localhost URLs."""
+
+
+class OpenBoxSigningError(OpenBoxAuthError):
+    """Raised when Core rejects a signed (AIP DID) request.
+
+    Attributes:
+        reason_code: Core's machine reason code (e.g. ``signature_invalid``).
+    """
+
+    def __init__(self, message: str, reason_code: str | None = None):
+        self.reason_code = reason_code
+        super().__init__(message)
+
+
+# Core signed-request rejection reason codes → actionable SDK guidance.
+# Forward-compatible: Core today often collapses identity failures into a
+# generic "invalid token" body with no machine code; these richer messages
+# activate once Core emits a machine reason code ("reason_code"/"code"/"reason").
+_SIGNING_REASON_MESSAGES: dict[str, str] = {
+    "signature_invalid": (
+        "Request signature rejected (signature_invalid). The signed bytes did not "
+        "match — usually a body-hash mismatch (send content= bytes, never json=) or "
+        "a wrong/rotated private key."
+    ),
+    "nonce_replayed": (
+        "Request nonce was already used (nonce_replayed). Each request must carry a "
+        "fresh nonce; do not retry a fully-prepared request verbatim."
+    ),
+    "did_agent_mismatch": (
+        "DID does not match the authenticated agent (did_agent_mismatch). Check that "
+        "agent_did matches the agent the API key/private key were provisioned for."
+    ),
+    "verifier_not_configured": (
+        "Core has no verifier for this agent (verifier_not_configured). The agent's "
+        "public key may not be imported to KMS yet — re-provision the agent."
+    ),
+    # Core's code is "timestamp_outside_window"; "timestamp_skew" kept as an alias.
+    "timestamp_outside_window": (
+        "Request timestamp outside the allowed window (timestamp_outside_window). Sync "
+        "the host clock (NTP); signatures are valid only within ±300s."
+    ),
+    "timestamp_skew": (
+        "Request timestamp outside the allowed window (timestamp_skew). Sync the host "
+        "clock (NTP); signatures are valid only within ±300s."
+    ),
+}
+
+
+def map_signing_error(reason_code: str | None, fallback: str = "") -> OpenBoxSigningError:
+    """Map a Core signing reason code to an actionable OpenBoxSigningError.
+
+    Unknown/empty codes fall back to a generic message (optionally augmented with
+    ``fallback`` context). Never raises — always returns an exception to raise.
+    """
+    if reason_code and reason_code in _SIGNING_REASON_MESSAGES:
+        return OpenBoxSigningError(_SIGNING_REASON_MESSAGES[reason_code], reason_code)
+    msg = fallback or (
+        "Signed request rejected by OpenBox Core"
+        + (f" ({reason_code})" if reason_code else "")
+        + "."
+    )
+    return OpenBoxSigningError(msg, reason_code)
+
+
+# ═══════════════════════════════════════════════════════════════════
+# Governance verdict errors
+# ═══════════════════════════════════════════════════════════════════
+
+
+class GovernanceBlockedError(OpenBoxError):
+    """Raised when governance blocks an operation (default adapter behavior).
+
+    Framework adapters typically translate this into a native error type; the
+    base adapter raises it directly.
+
+    Attributes:
+        verdict: The Verdict enum value (normalized from string if needed).
+        reason: Human-readable explanation from the policy engine.
+        url: The URL or resource identifier that was blocked (optional).
+    """
+
+    def __init__(self, verdict: str | Verdict, reason: str, url: str = ""):
+        # Lazy import avoids a hard module-level dependency on contracts.
+        if isinstance(verdict, str):
+            from .contracts.results import Verdict
+
+            self.verdict = Verdict.from_string(verdict)
+        else:
+            self.verdict = verdict
+        self.reason = reason
+        self.url = url
+        super().__init__(f"Governance {self.verdict.value}: {reason}")
+
+
+class GovernanceHaltError(OpenBoxError):
+    """Raised when governance halts execution (HALT verdict).
+
+    HALT is the nuclear option — the framework adapter decides how to stop
+    future work.
+    """
+
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+class GovernanceAPIError(OpenBoxError):
+    """Raised when the governance API fails and policy is fail_closed."""
+
+
+# ═══════════════════════════════════════════════════════════════════
+# Guardrails errors
+# ═══════════════════════════════════════════════════════════════════
+
+
+class GuardrailsValidationError(OpenBoxError):
+    """Raised when guardrails validation_passed is False.
+
+    Attributes:
+        reasons: List of reason strings from the guardrails evaluation.
+    """
+
+    def __init__(self, reasons: list[str] | None = None):
+        self.reasons = reasons or []
+        reason_str = (
+            "; ".join(self.reasons) if self.reasons else "Guardrails validation failed"
+        )
+        super().__init__(reason_str)
+
+
+# ═══════════════════════════════════════════════════════════════════
+# HITL approval errors
+# ═══════════════════════════════════════════════════════════════════
+
+
+class ApprovalExpiredError(OpenBoxError):
+    """Raised when the HITL approval window expires (server-side deadline)."""
+
+
+class ApprovalRejectedError(OpenBoxError):
+    """Raised when a HITL approval is explicitly rejected by a human."""
+
+
+class ApprovalTimeoutError(OpenBoxError):
+    """Raised when HITL polling exceeds the configured max wait time."""
+
+    def __init__(self, max_wait_ms: int | None = None):
+        self.max_wait_ms = max_wait_ms
+        msg = (
+            f"Approval polling timed out after {max_wait_ms}ms"
+            if max_wait_ms
+            else "Approval polling timed out"
+        )
+        super().__init__(msg)
+
+
+# ═══════════════════════════════════════════════════════════════════
+# Utility: exception chain walker
+# ═══════════════════════════════════════════════════════════════════
+
+
+def extract_governance_error(exc: BaseException) -> GovernanceBlockedError | None:
+    """Walk an exception chain to find a wrapped GovernanceBlockedError.
+
+    Frameworks and client libraries often wrap errors. This utility recovers
+    the original GovernanceBlockedError for verdict inspection.
+
+    Args:
+        exc: Any exception, potentially wrapping a GovernanceBlockedError.
+
+    Returns:
+        The GovernanceBlockedError if found in the chain, None otherwise.
+    """
+    seen: set[int] = set()
+    current: BaseException | None = exc
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        if isinstance(current, GovernanceBlockedError):
+            return current
+        # Walk both explicit (__cause__) and implicit (__context__) chains
+        next_exc = getattr(current, "__cause__", None) or getattr(
+            current, "__context__", None
+        )
+        # Also check framework .cause properties.
+        if next_exc is None:
+            next_exc = getattr(current, "cause", None)
+        current = next_exc
+    return None

openbox_core/gate.py

@@ -0,0 +1,185 @@
+"""GovernanceGate — always-strict validation orchestrating evaluate calls.
+
+The gate is ALWAYS STRICT for OpenBox event contracts and runtime invariants:
+malformed contracts raise ``ContractError`` BEFORE any network send. There is
+deliberately NO ``mode``/``OBSERVE``/``SANITIZE``/``STRICT`` toggle anywhere in
+this API — fail-open policy applies only to network errors inside the client,
+never to contract violations.
+
+Paths:
+- ``evaluate``/``aevaluate``   — lifecycle events (no spans); the gate
+  serializes the envelope dict directly.
+- ``preflight``/``apreflight`` — hook STARTED-stage evaluation. Enforced by
+  the hook runtime/adapter (BLOCK/HALT/REQUIRE_APPROVAL stop the operation).
+- ``completed``/``acompleted`` — hook COMPLETED-stage telemetry. Influences
+  *future* execution only; it never undoes the operation.
+
+Hook body assembly is delegated to the injected ``payload_builder`` —
+``wire/evaluate_payload.build_evaluate_payload`` is the single owner of the
+evaluate body shape. The gate never reimplements it.
+
+Enforcement priority (for adapters interpreting results):
+HALT > BLOCK > guardrails-fail > REQUIRE_APPROVAL > CONSTRAIN > ALLOW.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from .client import EvaluationClient
+from .config import OpenBoxConfig
+from .contracts.events import EventEnvelope
+from .contracts.results import EvaluationResult, Verdict
+from .errors import (
+    GovernanceBlockedError,
+    GovernanceHaltError,
+    GuardrailsValidationError,
+    OpenBoxConfigError,
+)
+from .serialization import apply_redaction, rfc3339_now, to_json_safe
+from .validation.diagnostics import Diagnostic
+from .validation.registry import validate_hook, validate_lifecycle
+from .validation.span_normalization import redaction_diagnostics, strip_compat_noise
+
+__all__ = ["GovernanceGate", "STAGE_STARTED", "STAGE_COMPLETED", "raise_for_verdict"]
+
+STAGE_STARTED = "started"
+STAGE_COMPLETED = "completed"
+
+# payload_builder(event) -> (payload_dict, diagnostics)
+PayloadBuilder = Callable[[EventEnvelope], tuple[dict[str, Any], list[Diagnostic]]]
+
+
+class GovernanceGate:
+    """Validate → serialize → evaluate → parse, strictly.
+
+    Args:
+        client: The EvaluationClient used for network calls.
+        config: Resolved OpenBoxConfig (privacy settings are read here).
+        payload_builder: Hook evaluate-body assembler. Wired to
+            ``wire/evaluate_payload.build_evaluate_payload`` by the runtime;
+            hook paths raise until one is provided (lifecycle paths work
+            without it).
+    """
+
+    def __init__(
+        self,
+        client: EvaluationClient,
+        config: OpenBoxConfig | None = None,
+        *,
+        payload_builder: PayloadBuilder | None = None,
+    ):
+        self._client = client
+        self._config = config or OpenBoxConfig()
+        self._payload_builder = payload_builder
+
+    # ── Lifecycle events ──────────────────────────────────────────────────
+
+    def evaluate(self, event: EventEnvelope) -> EvaluationResult:
+        """Evaluate a lifecycle/signal/handoff event (strictly validated)."""
+        payload, diagnostics = self._prepare_lifecycle(event)
+        result = self._client.evaluate(payload)
+        result.diagnostics.extend(d.to_dict() for d in diagnostics)
+        return result
+
+    async def aevaluate(self, event: EventEnvelope) -> EvaluationResult:
+        """Async :meth:`evaluate`."""
+        payload, diagnostics = self._prepare_lifecycle(event)
+        result = await self._client.aevaluate(payload)
+        result.diagnostics.extend(d.to_dict() for d in diagnostics)
+        return result
+
+    def _prepare_lifecycle(self, event: EventEnvelope) -> tuple[dict, list[Diagnostic]]:
+        diagnostics = validate_lifecycle(event)
+        payload = event.to_payload_dict()
+        payload.setdefault("timestamp", rfc3339_now())
+        # Empty span compatibility noise never reaches the wire.
+        payload, noise_diagnostics = strip_compat_noise(payload)
+        diagnostics.extend(noise_diagnostics)
+        return self._finalize_payload(payload, diagnostics)
+
+    # ── Hook events ───────────────────────────────────────────────────────
+
+    def preflight(self, event: EventEnvelope) -> EvaluationResult:
+        """Started-stage hook evaluation (validated; body via payload_builder)."""
+        payload, diagnostics = self._prepare_hook(event, STAGE_STARTED)
+        result = self._client.evaluate(payload)
+        result.diagnostics.extend(d.to_dict() for d in diagnostics)
+        return result
+
+    async def apreflight(self, event: EventEnvelope) -> EvaluationResult:
+        """Async :meth:`preflight`."""
+        payload, diagnostics = self._prepare_hook(event, STAGE_STARTED)
+        result = await self._client.aevaluate(payload)
+        result.diagnostics.extend(d.to_dict() for d in diagnostics)
+        return result
+
+    def completed(self, event: EventEnvelope) -> EvaluationResult:
+        """Completed-stage hook telemetry. Never undoes the operation — the
+        result may only influence FUTURE execution (adapter decides)."""
+        payload, diagnostics = self._prepare_hook(event, STAGE_COMPLETED)
+        result = self._client.evaluate(payload)
+        result.diagnostics.extend(d.to_dict() for d in diagnostics)
+        return result
+
+    async def acompleted(self, event: EventEnvelope) -> EvaluationResult:
+        """Async :meth:`completed`."""
+        payload, diagnostics = self._prepare_hook(event, STAGE_COMPLETED)
+        result = await self._client.aevaluate(payload)
+        result.diagnostics.extend(d.to_dict() for d in diagnostics)
+        return result
+
+    def _prepare_hook(self, event: EventEnvelope, stage: str) -> tuple[dict, list[Diagnostic]]:
+        diagnostics = validate_hook(event, stage)
+        if self._payload_builder is None:
+            raise OpenBoxConfigError(
+                "GovernanceGate has no payload_builder — hook evaluation requires "
+                "wire/evaluate_payload.build_evaluate_payload (wired by OpenBoxRuntime)"
+            )
+        payload, builder_diagnostics = self._payload_builder(event)
+        diagnostics.extend(builder_diagnostics)
+        payload.setdefault("timestamp", rfc3339_now())
+        return self._finalize_payload(payload, diagnostics)
+
+    # ── Shared payload finishing ──────────────────────────────────────────
+
+    def _finalize_payload(
+        self, payload: dict, diagnostics: list[Diagnostic]
+    ) -> tuple[dict, list[Diagnostic]]:
+        """JSON-safety + privacy redaction, applied BEFORE signing/sending.
+
+        ``exclude_none=False`` is deliberate: started-stage spans carry
+        EXPLICIT ``end_time: null`` / ``duration_ns: null`` (Core's non-pointer
+        int64 relies on them), so nulls must survive to the wire.
+        Omit-when-absent is handled where payloads are BUILT (keys left out),
+        not by dropping None here.
+        """
+        payload = to_json_safe(payload, exclude_none=False)
+        redact_keys = self._config.privacy.redact_keys
+        if redact_keys:
+            payload, changed = apply_redaction(payload, redact_keys)
+            diagnostics.extend(redaction_diagnostics(changed))
+        return payload, diagnostics
+
+
+def raise_for_verdict(result: EvaluationResult) -> EvaluationResult | None:
+    """Default enforcement helper implementing the verdict priority order.
+
+    HALT > BLOCK > guardrails-fail > REQUIRE_APPROVAL > CONSTRAIN > ALLOW.
+
+    Raises the core error types for stop-shaped results; returns the result
+    for REQUIRE_APPROVAL (caller drives approval) and for ALLOW/CONSTRAIN
+    (caller proceeds). Framework adapters typically translate these into
+    native errors instead of calling this helper.
+    """
+    verdict = result.verdict
+    if verdict == Verdict.HALT:
+        raise GovernanceHaltError(result.reason or "Halted by governance policy")
+    if verdict == Verdict.BLOCK:
+        raise GovernanceBlockedError(verdict, result.reason or "Blocked by governance policy")
+    # Guardrails failure outranks approval so it is never swallowed by a HITL flow.
+    if result.guardrails and not result.guardrails.validation_passed:
+        reasons = result.guardrails.get_reason_strings()
+        raise GuardrailsValidationError(reasons or ["Guardrails validation failed"])
+    return result

openbox_core/hooks/__init__.py

@@ -0,0 +1,3 @@
+"""Started/completed hook runtime."""
+
+__all__: list[str] = []

openbox_core/hooks/events.py

@@ -0,0 +1,64 @@
+"""Hook event assembly from the bound ActivityContext + serialized OTel span."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from typing import Any
+
+from ..context import ContextStore
+from ..contracts.context import ActivityContext
+from ..contracts.events import EventEnvelope, hook
+from ..contracts.otel_spans import HookType, Stage, from_otel_span
+from ..otel.trace_context import raw_trace_id
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["resolve_context", "build_hook_event"]
+
+
+def resolve_context(store: ContextStore, span: Any) -> ActivityContext | None:
+    """Bound context via ContextVar first, trace-map fallback second.
+
+    The trace-map path serves code running where ContextVars don't propagate
+    (executor threads); both sides key by the canonical integer trace id.
+    """
+    ctx = store.current_activity_context()
+    if ctx is not None:
+        return ctx
+    trace_id = raw_trace_id(span)
+    if trace_id is not None and trace_id != 0:
+        return store.context_for_trace(trace_id)
+    return None
+
+
+def build_hook_event(
+    store: ContextStore,
+    span: Any,
+    *,
+    stage: Stage,
+    hook_type: HookType,
+    fields: Mapping[str, Any] | None = None,
+) -> EventEnvelope | None:
+    """Build a hook EventEnvelope, or None when the hook must be SKIPPED.
+
+    No bound ActivityContext (or a context without an activity binding) means
+    this operation is not inside a governed activity — skipping is the
+    CORRECT behavior, not an error.
+    """
+    ctx = resolve_context(store, span)
+    if ctx is None:
+        logger.debug("hook skipped: no bound ActivityContext for span")
+        return None
+    if not ctx.activity_id or not ctx.activity_type:
+        logger.debug("hook skipped: bound context has no activity binding")
+        return None
+    span_data = from_otel_span(
+        span, stage=stage, hook_type=hook_type, activity_context=None, fields=fields
+    )
+    return hook(
+        activity_context=ctx.to_payload_fields(),
+        activity_id=ctx.activity_id,
+        activity_type=ctx.activity_type,
+        spans=[span_data],
+    )