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

openbox_core/config.py

@@ -0,0 +1,260 @@
+"""OpenBoxConfig and nested config groups with layered env resolution.
+
+Resolution order (highest wins):
+
+1. explicit arguments
+2. SDK-specific environment variables via ``env_prefix`` (e.g.
+   ``OPENBOX_FRAMEWORK_API_KEY`` for ``env_prefix="OPENBOX_FRAMEWORK"``)
+3. global ``OPENBOX_*`` environment variables
+4. defaults
+5. validation and normalization
+
+Common framework configuration fields map onto the nested groups here:
+
+    skip_workflow_types / skip_activity_types / skip_signals /
+    enforce_task_queues / send_start_event / send_activity_start_event  -> gate
+    hitl_enabled / skip_hitl_activity_types / hitl_poll_interval_ms     -> hitl
+    max_body_size                                                       -> privacy
+    on_api_error / api_timeout                                          -> top level
+
+No heavy imports; safe outside sandbox paths (env access happens only inside
+``resolve()``, never at import time).
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import OpenBoxAuthError, OpenBoxConfigError, OpenBoxInsecureURLError
+from .sdk_version import DEFAULT_SDK_ENGINE, DEFAULT_SDK_LANGUAGE
+
+__all__ = [
+    "GLOBAL_ENV_PREFIX",
+    "HitlConfig",
+    "TelemetryConfig",
+    "InstrumentationConfig",
+    "GateConfig",
+    "PrivacyConfig",
+    "OpenBoxConfig",
+]
+
+# API key format pattern (obx_live_... or obx_test_...)
+API_KEY_PATTERN = re.compile(r"^obx_(live|test)_\w+$")
+
+GLOBAL_ENV_PREFIX = "OPENBOX"
+
+# Config fields resolvable from the environment (suffix -> coercion).
+_ENV_FIELDS: dict[str, str] = {
+    "api_url": "API_URL",
+    "api_key": "API_KEY",
+    "timeout_seconds": "TIMEOUT_SECONDS",
+    "on_api_error": "ON_API_ERROR",
+    "agent_name": "AGENT_NAME",
+    "agent_did": "AGENT_DID",
+    "agent_private_key": "AGENT_PRIVATE_KEY",
+}
+
+
+@dataclass
+class HitlConfig:
+    """Human-in-the-loop approval polling configuration."""
+
+    enabled: bool = True
+    poll_interval_ms: int = 5000
+    max_wait_ms: int | None = None  # None = poll indefinitely (framework decides)
+    # Activity types to skip approval checks for (avoids infinite loops).
+    skip_activity_types: set[str] = field(default_factory=lambda: {"send_governance_event"})
+
+
+@dataclass
+class TelemetryConfig:
+    """Telemetry emission toggles."""
+
+    enabled: bool = True
+
+
+@dataclass
+class InstrumentationConfig:
+    """Generic instrumentation install toggles."""
+
+    enabled: bool = True
+    http_enabled: bool = True
+    db_enabled: bool = True
+    # Safe to default-on: interpreter-owned paths bypass governance and a
+    # re-entrancy guard passes through evaluation-time opens.
+    file_enabled: bool = True
+    function_enabled: bool = True
+    llm_enabled: bool = False  # Reserved; disabled until provider hooks are implemented.
+    install_opentelemetry: bool = True
+    preflight_enabled: bool = True
+    completed_telemetry_enabled: bool = True
+
+
+@dataclass
+class GateConfig:
+    """Event-level gate toggles (which lifecycle events are evaluated).
+
+    Gate mode is not configurable: event/runtime contracts are always strict.
+    These fields control only which events are emitted.
+    """
+
+    skip_workflow_types: set[str] = field(default_factory=set)
+    skip_signals: set[str] = field(default_factory=set)
+    # By default skip the governance event activity itself to avoid loops.
+    skip_activity_types: set[str] = field(default_factory=lambda: {"send_governance_event"})
+    enforce_task_queues: set[str] | None = None  # None = all
+    send_start_event: bool = True
+    send_activity_start_event: bool = True
+
+
+@dataclass
+class PrivacyConfig:
+    """Redaction/truncation applied BEFORE signing."""
+
+    redact_keys: set[str] = field(default_factory=set)
+    max_body_size: int = 65536  # chars
+
+
+@dataclass
+class OpenBoxConfig:
+    """Resolved base-SDK configuration.
+
+    Build via :meth:`resolve` for layered env resolution + validation, or
+    construct directly in tests (no validation on direct construction).
+    """
+
+    api_url: str = ""
+    api_key: str = ""
+    timeout_seconds: float = 30.0
+    on_api_error: str = "fail_open"  # "fail_open" | "fail_closed"
+    on_fallback: Any = None  # reserved passthrough for fallback callbacks
+    agent_name: str | None = None
+    agent_did: str | None = None
+    agent_private_key: str | None = field(default=None, repr=False)  # never in repr
+    sdk_version: str | None = None
+    sdk_engine: str = DEFAULT_SDK_ENGINE
+    sdk_language: str = DEFAULT_SDK_LANGUAGE
+    env_prefix: str | None = None
+    hitl: HitlConfig = field(default_factory=HitlConfig)
+    telemetry: TelemetryConfig = field(default_factory=TelemetryConfig)
+    instrumentation: InstrumentationConfig = field(default_factory=InstrumentationConfig)
+    gate: GateConfig = field(default_factory=GateConfig)
+    privacy: PrivacyConfig = field(default_factory=PrivacyConfig)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    # ── Resolution ───────────────────────────────────────────────────────
+
+    @classmethod
+    def resolve(
+        cls,
+        *,
+        env_prefix: str | None = None,
+        environ: Mapping[str, str] | None = None,
+        validate: bool = True,
+        **explicit: Any,
+    ) -> OpenBoxConfig:
+        """Layered resolution: explicit > env_prefix > OPENBOX_* > defaults.
+
+        Args:
+            env_prefix: SDK-specific env namespace (e.g. ``OPENBOX_FRAMEWORK``).
+            environ: Environment mapping (defaults to ``os.environ``; injectable
+                for tests).
+            validate: Run validation/normalization (step 5). Disable only in
+                tests that need partial configs.
+            **explicit: Explicit values for any OpenBoxConfig field. ``None``
+                means "not provided" and falls through to the next layer.
+        """
+        if environ is None:
+            import os
+
+            environ = os.environ
+
+        unknown = set(explicit) - {f.name for f in cls.__dataclass_fields__.values()}  # type: ignore[attr-defined]
+        if unknown:
+            raise OpenBoxConfigError(f"Unknown config fields: {sorted(unknown)}")
+
+        resolved: dict[str, Any] = {}
+        for field_name, suffix in _ENV_FIELDS.items():
+            value: Any = explicit.get(field_name)
+            if value is None and env_prefix:
+                value = environ.get(f"{env_prefix}_{suffix}")
+            if value is None:
+                value = environ.get(f"{GLOBAL_ENV_PREFIX}_{suffix}")
+            if value is not None:
+                resolved[field_name] = value
+
+        # Non-env fields pass through explicitly only.
+        for field_name, value in explicit.items():
+            if field_name not in _ENV_FIELDS and value is not None:
+                resolved[field_name] = value
+
+        config = cls(env_prefix=env_prefix, **resolved)
+        return config.normalized() if validate else config
+
+    def normalized(self) -> OpenBoxConfig:
+        """Validate + normalize in place (step 5). Returns self for chaining."""
+        if not self.api_url:
+            raise OpenBoxConfigError("api_url is required")
+        if not self.api_key:
+            raise OpenBoxConfigError("api_key is required")
+
+        self.api_url = str(self.api_url).rstrip("/")
+        _validate_url_security(self.api_url)
+
+        if not API_KEY_PATTERN.match(self.api_key):
+            raise OpenBoxAuthError(
+                f"Invalid API key format. Expected 'obx_live_*' or 'obx_test_*', "
+                f"got: '{self.api_key[:15]}...' (showing first 15 chars)"
+            )
+
+        try:
+            self.timeout_seconds = float(self.timeout_seconds)
+        except (TypeError, ValueError):
+            raise OpenBoxConfigError(
+                f"timeout_seconds must be numeric, got {self.timeout_seconds!r}"
+            ) from None
+
+        if self.on_api_error not in ("fail_open", "fail_closed"):
+            raise OpenBoxConfigError(
+                f"on_api_error must be 'fail_open' or 'fail_closed', got {self.on_api_error!r}"
+            )
+
+        # DID + private key: both-or-neither; format-validate the DID eagerly.
+        if bool(self.agent_did) != bool(self.agent_private_key):
+            raise OpenBoxConfigError(
+                "agent_did and agent_private_key must be provided together "
+                "(got only one). Provide both to enable signed requests, or neither."
+            )
+        if self.agent_did:
+            from .identity import validate_agent_did
+
+            validate_agent_did(self.agent_did)
+        return self
+
+    def load_identity(self) -> Any:
+        """Load an :class:`~openbox_core.identity.AgentIdentity` (or None).
+
+        Decodes + loads the Ed25519 seed exactly once; callers keep the
+        returned identity and never re-touch the raw key string.
+        """
+        if not (self.agent_did and self.agent_private_key):
+            return None
+        from .identity import AgentIdentity
+
+        return AgentIdentity.from_private_key(self.agent_did, self.agent_private_key)
+
+
+def _validate_url_security(api_url: str) -> None:
+    """HTTPS required for non-localhost URLs (protects API keys in transit)."""
+    from urllib.parse import urlparse
+
+    parsed = urlparse(api_url)
+    is_localhost = parsed.hostname in ("localhost", "127.0.0.1", "::1")
+    if parsed.scheme == "http" and not is_localhost:
+        raise OpenBoxInsecureURLError(
+            f"Insecure HTTP URL detected: {api_url}. "
+            "Use HTTPS for non-localhost URLs to protect API keys in transit."
+        )

openbox_core/conformance/__init__.py

@@ -0,0 +1,3 @@
+"""Reusable conformance fixtures importable by framework SDKs."""
+
+__all__: list[str] = []

openbox_core/conformance/fake_core.py

@@ -0,0 +1,169 @@
+"""Programmable fake OpenBox Core — verdict/approval queues + payload capture.
+
+No live network: requests terminate in an ``httpx.MockTransport``. Serves both
+sync and async clients. Importable from any framework SDK repo.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from ..client import EvaluationClient
+
+__all__ = ["FakeCore", "fake_client", "assert_hook_wire_shape"]
+
+_SPAN_ID_RE = re.compile(r"^[0-9a-f]{16}$")
+_TRACE_ID_RE = re.compile(r"^[0-9a-f]{32}$")
+
+# Common root fields every flat hook span must carry (present even when null).
+_COMMON_ROOT_FIELDS = (
+    "span_id",
+    "trace_id",
+    "parent_span_id",
+    "name",
+    "kind",
+    "stage",
+    "start_time",
+    "end_time",
+    "duration_ns",
+    "attributes",
+    "status",
+    "events",
+    "hook_type",
+    "error",
+)
+
+# Family-specific root fields that must exist (present even when null) per type.
+_FAMILY_ROOT_FIELDS = {
+    "http_request": (
+        "http_method",
+        "http_url",
+        "http_status_code",
+        "request_headers",
+        "response_headers",
+        "request_body",
+        "response_body",
+    ),
+    "db_query": (
+        "db_system",
+        "db_name",
+        "db_operation",
+        "db_statement",
+        "server_address",
+        "server_port",
+        "rowcount",
+    ),
+    "file_operation": (
+        "file_path",
+        "file_mode",
+        "file_operation",
+        "bytes_read",
+        "bytes_written",
+    ),
+    "function_call": ("function", "module", "args", "result"),
+}
+
+
+class FakeCore:
+    """Queue verdict/approval responses; capture every outgoing payload.
+
+    Responses pop FIFO from ``queue``; an empty queue answers ALLOW. Approval
+    polls share the same queue (enqueue in call order).
+    """
+
+    def __init__(self, *responses: dict[str, Any]):
+        self.queue: list[dict[str, Any]] = list(responses)
+        self.payloads: list[dict[str, Any]] = []
+        self.approval_requests: list[dict[str, Any]] = []
+
+    # ── transport ─────────────────────────────────────────────────────────
+
+    def handler(self, request: Any) -> Any:
+        import httpx
+
+        if request.url.path.endswith("/governance/evaluate"):
+            self.payloads.append(json.loads(request.content))
+            return httpx.Response(200, json=self._next({"verdict": "allow"}))
+        if request.url.path.endswith("/governance/approval"):
+            self.approval_requests.append(json.loads(request.content))
+            return httpx.Response(200, json=self._next({"action": "allow"}))
+        return httpx.Response(200, json={})
+
+    def _next(self, default: dict[str, Any]) -> dict[str, Any]:
+        return self.queue.pop(0) if self.queue else default
+
+    # ── capture views ─────────────────────────────────────────────────────
+
+    @property
+    def started_payloads(self) -> list[dict[str, Any]]:
+        return [
+            p for p in self.payloads
+            if p.get("spans") and p["spans"][0].get("stage") == "started"
+        ]
+
+    @property
+    def completed_payloads(self) -> list[dict[str, Any]]:
+        return [
+            p for p in self.payloads
+            if p.get("spans") and p["spans"][0].get("stage") == "completed"
+        ]
+
+    @property
+    def lifecycle_payloads(self) -> list[dict[str, Any]]:
+        return [p for p in self.payloads if not p.get("hook_trigger")]
+
+
+def fake_client(fake_core: FakeCore, **kwargs: Any) -> EvaluationClient:
+    """EvaluationClient wired to the fake Core (sync + async transports)."""
+    import httpx
+
+    transport = httpx.MockTransport(fake_core.handler)
+    return EvaluationClient(
+        kwargs.pop("api_url", "https://core.test"),
+        kwargs.pop("api_key", "obx_test_conformance"),
+        transport=transport,
+        async_transport=transport,
+        **kwargs,
+    )
+
+
+def assert_hook_wire_shape(payload: dict[str, Any]) -> None:
+    """Assert one captured hook payload matches the flat Core wire contract:
+
+    - ``event_type=ActivityStarted`` + ``hook_trigger=true`` + non-empty spans
+    - hex-string ids (regex, not truthiness)
+    - flat ``SpanData`` dicts — the nested ``otel``/``openbox`` envelope and any
+      opt-in ``data`` blob must never reach the wire
+    - every common root field present (``stage``/``hook_type``/``error``/…)
+    - every family-specific root field present for the span's ``hook_type``
+    - ``semantic_type`` never set by the SDK (Core computes it)
+    """
+    assert payload.get("event_type") == "ActivityStarted", payload.get("event_type")
+    assert payload.get("hook_trigger") is True
+    spans = payload.get("spans")
+    assert spans, "hook payload must carry non-empty spans"
+    assert payload.get("span_count") == len(spans)
+    for span in spans:
+        assert "otel" not in span and "openbox" not in span, (
+            "nested span envelope leaked to the wire"
+        )
+        assert "data" not in span, "flat hook spans must not carry a data blob"
+        assert "semantic_type" not in span, "semantic_type is computed by Core, not the SDK"
+        for field_name in _COMMON_ROOT_FIELDS:
+            assert field_name in span, f"missing common root field: {field_name}"
+        assert _SPAN_ID_RE.fullmatch(span.get("span_id", "")), span.get("span_id")
+        assert _TRACE_ID_RE.fullmatch(span.get("trace_id", "")), span.get("trace_id")
+        parent = span.get("parent_span_id")
+        if parent is not None:
+            assert _SPAN_ID_RE.fullmatch(parent), parent
+        assert span.get("stage") in ("started", "completed")
+        assert span.get("hook_type"), "hook spans must carry hook_type at the root"
+        for field_name in _FAMILY_ROOT_FIELDS.get(span.get("hook_type", ""), ()):
+            assert field_name in span, (
+                f"missing {span.get('hook_type')} root field: {field_name}"
+            )
+        if span.get("stage") == "started":
+            assert span["end_time"] is None
+            assert span["duration_ns"] is None

openbox_core/conformance/hook_preflight.py

@@ -0,0 +1,87 @@
+"""Adapter/context-binding conformance pieces: recording adapter + env builder."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..config import InstrumentationConfig, OpenBoxConfig
+from ..context import ContextStore
+from ..contracts.context import ActivityContext
+from ..contracts.results import EvaluationResult, Verdict
+from ..errors import ApprovalRejectedError, GovernanceBlockedError, GovernanceHaltError
+from ..runtime import OpenBoxRuntime
+from .fake_core import FakeCore, fake_client
+
+__all__ = ["CONFORMANCE_CONTEXT", "RecordingHookAdapter", "build_conformance_runtime"]
+
+# The reference activity context every conformance case binds.
+CONFORMANCE_CONTEXT = ActivityContext(
+    workflow_id="wf-conformance",
+    run_id="run-conformance",
+    workflow_type="ConformanceWorkflow",
+    task_queue="conformance-queue",
+    activity_id="act-conformance",
+    activity_type="conformance_activity",
+)
+
+
+class RecordingHookAdapter:
+    """Reference FrameworkAdapter: records every delegation, raises core errors.
+
+    ``approve_next`` drives the async approval outcome (True ⇒ approved).
+    """
+
+    name = "conformance"
+
+    def __init__(self) -> None:
+        self.hook_blocked: list[EvaluationResult] = []
+        self.lifecycle_blocked: list[EvaluationResult] = []
+        self.completed_results: list[EvaluationResult] = []
+        self.completed_contexts: list[ActivityContext | None] = []
+        self.approvals: list[EvaluationResult] = []
+        self.approve_next = True
+
+    async def handle_approval(self, result: EvaluationResult) -> None:
+        self.approvals.append(result)
+        if not self.approve_next:
+            raise ApprovalRejectedError("rejected by conformance adapter")
+
+    def raise_lifecycle_blocked(self, result: EvaluationResult) -> None:
+        self.lifecycle_blocked.append(result)
+        self._raise(result)
+
+    def raise_hook_blocked(self, result: EvaluationResult) -> None:
+        self.hook_blocked.append(result)
+        self._raise(result)
+
+    def on_completed_hook_result(
+        self, result: EvaluationResult, context: ActivityContext | None = None
+    ) -> None:
+        self.completed_results.append(result)
+        self.completed_contexts.append(context)
+
+    @staticmethod
+    def _raise(result: EvaluationResult) -> None:
+        if result.verdict is Verdict.HALT:
+            raise GovernanceHaltError(result.reason or "halted")
+        raise GovernanceBlockedError(result.verdict, result.reason or "blocked")
+
+
+def build_conformance_runtime(
+    fake_core: FakeCore,
+    adapter: Any | None = None,
+    store: ContextStore | None = None,
+    **instrumentation_overrides: Any,
+) -> OpenBoxRuntime:
+    """OpenBoxRuntime wired to the fake Core with an isolated ContextStore."""
+    config = OpenBoxConfig(
+        api_url="https://core.test",
+        api_key="obx_test_conformance",
+        instrumentation=InstrumentationConfig(**instrumentation_overrides),
+    )
+    return OpenBoxRuntime(
+        config,
+        adapter if adapter is not None else RecordingHookAdapter(),
+        client=fake_client(fake_core),
+        context_store=store if store is not None else ContextStore(),
+    )

openbox_core/conformance/instrumentation.py

@@ -0,0 +1,91 @@
+"""Instrumentation conformance environment — real wrappers, fake Core.
+
+Framework SDKs import this to prove their integration keeps every behavioral
+guarantee: the checks assert the REAL operation ran / did not run, not merely
+payload shape. No live network (governance terminates in the fake Core; HTTP
+cases hit a local counting server).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import http.server
+import threading
+from collections.abc import Iterator
+from typing import Any
+
+from ..context import ContextStore, activity_scope
+from ..instrumentation.manager import InstrumentationManager
+from ..runtime import OpenBoxRuntime
+from .fake_core import FakeCore
+from .hook_preflight import (
+    CONFORMANCE_CONTEXT,
+    RecordingHookAdapter,
+    build_conformance_runtime,
+)
+
+__all__ = [
+    "LocalCountingServer",
+    "installed_conformance_runtime",
+    "bound_conformance_activity",
+]
+
+
+class LocalCountingServer:
+    """Loopback HTTP server counting hits — proves a request was/wasn't sent."""
+
+    def __init__(self) -> None:
+        self.hits = 0
+        outer = self
+
+        class Handler(http.server.BaseHTTPRequestHandler):
+            def _respond(self) -> None:
+                outer.hits += 1
+                body = b'{"ok": true}'
+                self.send_response(200)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(body)))
+                self.end_headers()
+                self.wfile.write(body)
+
+            do_GET = _respond
+            do_POST = _respond
+
+            def log_message(self, *args: Any) -> None:  # keep test output clean
+                pass
+
+        self._server = http.server.ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        self._thread = threading.Thread(target=self._server.serve_forever, daemon=True)
+        self._thread.start()
+        self.url = f"http://127.0.0.1:{self._server.server_port}/echo"
+
+    def stop(self) -> None:
+        self._server.shutdown()
+        self._server.server_close()
+
+
+@contextlib.contextmanager
+def installed_conformance_runtime(
+    fake_core: FakeCore,
+    adapter: Any | None = None,
+    store: ContextStore | None = None,
+    **instrumentation_overrides: Any,
+) -> Iterator[OpenBoxRuntime]:
+    """Runtime with REAL instrumentation installed; guaranteed uninstall."""
+    adapter = adapter if adapter is not None else RecordingHookAdapter()
+    store = store if store is not None else ContextStore()
+    runtime = build_conformance_runtime(fake_core, adapter, store, **instrumentation_overrides)
+    manager = InstrumentationManager(runtime)
+    runtime._instrumentation_manager = manager
+    manager.install()
+    try:
+        yield runtime
+    finally:
+        manager.uninstall()
+
+
+@contextlib.contextmanager
+def bound_conformance_activity(store: ContextStore) -> Iterator[None]:
+    """Bind the reference ActivityContext with guaranteed reset."""
+    with activity_scope(CONFORMANCE_CONTEXT, store=store):
+        yield