openbox-langgraph-sdk-python 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

openbox_langgraph/__init__.py

@@ -32,11 +32,19 @@ from openbox_langgraph.errors import (
     GovernanceHaltError,
     GuardrailsValidationError,
     OpenBoxAuthError,
+    OpenBoxConfigError,
     OpenBoxError,
     OpenBoxInsecureURLError,
     OpenBoxNetworkError,
 )
 from openbox_langgraph.hitl import poll_until_decision
+from openbox_langgraph.identity import (
+    AgentIdentityConfig,
+    build_agent_identity_canonical_request,
+    create_agent_identity_headers,
+    parse_optional_agent_identity_config,
+    validate_agent_identity_config,
+)
 from openbox_langgraph.langgraph_handler import (
     OpenBoxLangGraphHandler,
     OpenBoxLangGraphHandlerOptions,
@@ -79,6 +87,7 @@ from openbox_langgraph.verdict_handler import (
 
 __all__ = [
     "DEFAULT_HITL_CONFIG",
+    "AgentIdentityConfig",
     "ApprovalExpiredError",
     "ApprovalRejectedError",
     "ApprovalResponse",
@@ -95,6 +104,7 @@ __all__ = [
     "LangChainGovernanceEvent",
     "LangGraphStreamEvent",
     "OpenBoxAuthError",
+    "OpenBoxConfigError",
     "OpenBoxError",
     "OpenBoxInsecureURLError",
     "OpenBoxLangGraphHandler",
@@ -105,7 +115,9 @@ __all__ = [
     "WorkflowEventType",
     "WorkflowSpanBuffer",
     "WorkflowSpanProcessor",
+    "build_agent_identity_canonical_request",
     "build_auth_headers",
+    "create_agent_identity_headers",
     "create_openbox_graph_handler",
     "create_span",
     "enforce_verdict",
@@ -117,12 +129,14 @@ __all__ = [
     "merge_config",
     "parse_approval_response",
     "parse_governance_response",
+    "parse_optional_agent_identity_config",
     "poll_until_decision",
     "rfc3339_now",
     "safe_serialize",
     "setup_opentelemetry_for_governance",
     "to_server_event_type",
     "traced",
+    "validate_agent_identity_config",
     "verdict_from_string",
     "verdict_priority",
     "verdict_requires_approval",

openbox_langgraph/client.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 import os
 from dataclasses import dataclass
 from datetime import UTC
@@ -9,7 +10,12 @@ from typing import Any
 
 import httpx
 
-from openbox_langgraph.errors import OpenBoxNetworkError
+from openbox_langgraph.errors import OpenBoxConfigError, OpenBoxNetworkError
+from openbox_langgraph.identity import (
+    AgentIdentityConfig,
+    create_agent_identity_headers,
+    parse_optional_agent_identity_config,
+)
 from openbox_langgraph.types import (
     ApprovalResponse,
     GovernanceVerdictResponse,
@@ -19,20 +25,41 @@ from openbox_langgraph.types import (
     to_server_event_type,
 )
 
-_SDK_VERSION = "0.1.0"
+_SDK_VERSION = "0.2.0"
 
 
-def build_auth_headers(api_key: str) -> dict[str, str]:
+def build_auth_headers(
+    api_key: str,
+    *,
+    method: str | None = None,
+    pathname: str | None = None,
+    body: bytes | str | None = None,
+    agent_identity: AgentIdentityConfig | None = None,
+) -> dict[str, str]:
     """Build standard auth headers for governance API calls.
 
     Single source of truth — used by GovernanceClient and hook_governance.
     """
-    return {
+    headers = {
         "Authorization": f"Bearer {api_key}",
         "Content-Type": "application/json",
         "User-Agent": f"OpenBox-LangGraph-SDK/{_SDK_VERSION}",
         "X-OpenBox-SDK-Version": _SDK_VERSION,
     }
+    if agent_identity:
+        if method is None or pathname is None:
+            msg = "method and pathname are required when signing OpenBox requests."
+            raise OpenBoxConfigError(msg)
+        headers.update(
+            create_agent_identity_headers(
+                did=agent_identity.did,
+                private_key=agent_identity.private_key,
+                method=method,
+                pathname=pathname,
+                body=body,
+            )
+        )
+    return headers
 
 
 @dataclass
@@ -58,6 +85,8 @@ class GovernanceClient:
         api_key: str,
         timeout: float = 30.0,  # seconds
         on_api_error: str = "fail_open",
+        agent_did: str | None = None,
+        agent_private_key: str | None = None,
     ) -> None:
         self._api_url = api_url.rstrip("/")
         self._api_key = api_key
@@ -65,7 +94,10 @@ class GovernanceClient:
         self._on_api_error = on_api_error
         self._client: httpx.AsyncClient | None = None
         self._sync_client: httpx.Client | None = None
-        self._cached_headers = build_auth_headers(api_key)
+        self._agent_identity = parse_optional_agent_identity_config(
+            did=agent_did,
+            private_key=agent_private_key,
+        )
         # Deduplication: prevent sending the same (activity_id, event_type) twice
         # within the same workflow run. Keyed by (workflow_id, run_id) so it resets
         # automatically on each new ainvoke() call.
@@ -110,7 +142,11 @@ class GovernanceClient:
             client = self._get_client()
             response = await client.get(
                 f"{self._api_url}/api/v1/auth/validate",
-                headers=self._headers(),
+                headers=self._headers(
+                    method="GET",
+                    pathname="/api/v1/auth/validate",
+                    body=b"",
+                ),
             )
             if response.status_code in (401, 403):
                 msg = "Invalid API key. Check your API key at dashboard.openbox.ai"
@@ -176,16 +212,22 @@ class GovernanceClient:
 
         if os.environ.get("OPENBOX_DEBUG") == "1":
             import json
+
             print(
                 f"[OpenBox Debug] governance request: {json.dumps(payload, indent=2, default=str)}"
             )
 
         try:
             client = self._get_client()
+            body = _json_body(payload)
             response = await client.post(
                 f"{self._api_url}/api/v1/governance/evaluate",
-                headers=self._headers(),
-                json=payload,
+                headers=self._headers(
+                    method="POST",
+                    pathname="/api/v1/governance/evaluate",
+                    body=body,
+                ),
+                content=body,
             )
 
             if not response.is_success:
@@ -226,6 +268,7 @@ class GovernanceClient:
 
         if os.environ.get("OPENBOX_DEBUG") == "1":
             import json
+
             print(
                 "[OpenBox Debug] sync governance request:"
                 f" {json.dumps(payload, indent=2, default=str)}"
@@ -233,10 +276,15 @@ class GovernanceClient:
 
         try:
             client = self._get_sync_client()
+            body = _json_body(payload)
             response = client.post(
                 f"{self._api_url}/api/v1/governance/evaluate",
-                headers=self._headers(),
-                json=payload,
+                headers=self._headers(
+                    method="POST",
+                    pathname="/api/v1/governance/evaluate",
+                    body=body,
+                ),
+                content=body,
             )
 
             if not response.is_success:
@@ -256,9 +304,7 @@ class GovernanceClient:
                 raise OpenBoxNetworkError(msg) from e
             return None
 
-    async def poll_approval(
-        self, params: ApprovalPollParams
-    ) -> ApprovalResponse | None:
+    async def poll_approval(self, params: ApprovalPollParams) -> ApprovalResponse | None:
         """Poll for HITL approval status.
 
         Returns `None` on network failure so the caller can retry.
@@ -268,14 +314,21 @@ class GovernanceClient:
         """
         try:
             client = self._get_client()
-            response = await client.post(
-                f"{self._api_url}/api/v1/governance/approval",
-                headers=self._headers(),
-                json={
+            body = _json_body(
+                {
                     "workflow_id": params.workflow_id,
                     "run_id": params.run_id,
                     "activity_id": params.activity_id,
-                },
+                }
+            )
+            response = await client.post(
+                f"{self._api_url}/api/v1/governance/approval",
+                headers=self._headers(
+                    method="POST",
+                    pathname="/api/v1/governance/approval",
+                    body=body,
+                ),
+                content=body,
             )
 
             if not response.is_success:
@@ -287,6 +340,7 @@ class GovernanceClient:
             # SDK-side expiration check
             if parsed.approval_expiration_time and not parsed.expired:
                 from datetime import datetime
+
                 expiry = datetime.fromisoformat(
                     parsed.approval_expiration_time.replace("Z", "+00:00")
                 )
@@ -298,9 +352,7 @@ class GovernanceClient:
         except Exception:
             return None
 
-    async def evaluate_raw(
-        self, payload: dict[str, Any]
-    ) -> dict[str, Any] | None:
+    async def evaluate_raw(self, payload: dict[str, Any]) -> dict[str, Any] | None:
         """Send a pre-built payload to the governance evaluate endpoint.
 
         Used by hook-level governance where the payload is fully assembled
@@ -311,16 +363,22 @@ class GovernanceClient:
         """
         if os.environ.get("OPENBOX_DEBUG") == "1":
             import json
+
             print(
                 f"[OpenBox Debug] span hook request: {json.dumps(payload, indent=2, default=str)}"
             )
 
         try:
             client = self._get_client()
+            body = _json_body(payload)
             response = await client.post(
                 f"{self._api_url}/api/v1/governance/evaluate",
-                headers=self._headers(),
-                json=payload,
+                headers=self._headers(
+                    method="POST",
+                    pathname="/api/v1/governance/evaluate",
+                    body=body,
+                ),
+                content=body,
             )
 
             if not response.is_success:
@@ -354,5 +412,15 @@ class GovernanceClient:
     # Private helpers
     # ─────────────────────────────────────────────────────────────
 
-    def _headers(self) -> dict[str, str]:
-        return self._cached_headers
+    def _headers(self, *, method: str, pathname: str, body: bytes | str | None) -> dict[str, str]:
+        return build_auth_headers(
+            self._api_key,
+            method=method,
+            pathname=pathname,
+            body=body,
+            agent_identity=self._agent_identity,
+        )
+
+
+def _json_body(payload: dict[str, Any]) -> bytes:
+    return json.dumps(payload, separators=(",", ":"), default=str).encode("utf-8")

openbox_langgraph/config.py

@@ -7,22 +7,31 @@ from __future__ import annotations
 
 import re
 from dataclasses import dataclass, field
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from openbox_langgraph.errors import (
     OpenBoxAuthError,
+    OpenBoxConfigError,
     OpenBoxInsecureURLError,
     OpenBoxNetworkError,
 )
+from openbox_langgraph.identity import (
+    AgentIdentityConfig,
+    parse_optional_agent_identity_config,
+)
 from openbox_langgraph.types import DEFAULT_HITL_CONFIG, HITLConfig
 
+if TYPE_CHECKING:
+    from logging import Logger
+
 # API key format pattern (obx_live_... or obx_test_...)
 _API_KEY_PATTERN = re.compile(r"^obx_(live|test)_[a-zA-Z0-9_]+$")
 
 
-def _get_logger():
+def _get_logger() -> Logger:
     """Lazy logger import."""
     import logging
+
     return logging.getLogger(__name__)
 
 
@@ -30,6 +39,7 @@ def _get_logger():
 # API key / URL validation
 # ═══════════════════════════════════════════════════════════════════
 
+
 def validate_api_key_format(api_key: str) -> bool:
     """Return True if the API key matches the expected `obx_live_*` / `obx_test_*` format."""
     return bool(_API_KEY_PATTERN.match(api_key))
@@ -53,6 +63,7 @@ def validate_url_security(api_url: str) -> None:
 # GovernanceConfig
 # ═══════════════════════════════════════════════════════════════════
 
+
 @dataclass
 class GovernanceConfig:
     """Full resolved governance configuration for the handler."""
@@ -143,16 +154,27 @@ def merge_config(partial: dict[str, Any] | None = None) -> GovernanceConfig:
 # Global Config Singleton
 # ═══════════════════════════════════════════════════════════════════
 
+
 @dataclass
 class _GlobalConfigState:
     api_url: str = ""
     api_key: str = ""
     governance_timeout: float = 30.0  # seconds
-
-    def configure(self, api_url: str, api_key: str, governance_timeout: float = 30.0) -> None:
+    agent_did: str | None = None
+    agent_private_key: str | None = None
+
+    def configure(
+        self,
+        api_url: str,
+        api_key: str,
+        governance_timeout: float = 30.0,
+        agent_identity: AgentIdentityConfig | None = None,
+    ) -> None:
         self.api_url = api_url.rstrip("/")
         self.api_key = api_key
         self.governance_timeout = governance_timeout
+        self.agent_did = agent_identity.did if agent_identity else None
+        self.agent_private_key = agent_identity.private_key if agent_identity else None
 
     def __repr__(self) -> str:
         if self.api_key and len(self.api_key) > 8:
@@ -164,7 +186,8 @@ class _GlobalConfigState:
         return (
             f"_GlobalConfigState(api_url={self.api_url!r}, "
             f"api_key={masked!r}, "
-            f"governance_timeout={self.governance_timeout})"
+            f"governance_timeout={self.governance_timeout}, "
+            f"agent_did={self.agent_did!r})"
         )
 
     def is_configured(self) -> bool:
@@ -183,8 +206,12 @@ def get_global_config() -> _GlobalConfigState:
 # Server-side API key validation (sync, using urllib — no httpx at module level)
 # ═══════════════════════════════════════════════════════════════════
 
+
 def _validate_api_key_with_server(
-    api_url: str, api_key: str, timeout: float
+    api_url: str,
+    api_key: str,
+    timeout: float,
+    agent_identity: AgentIdentityConfig | None = None,
 ) -> None:
     """Validate API key by calling /api/v1/auth/validate endpoint (synchronous).
 
@@ -194,14 +221,18 @@ def _validate_api_key_with_server(
     from urllib.error import HTTPError, URLError  # lazy
     from urllib.request import Request, urlopen  # lazy
 
+    from openbox_langgraph.client import build_auth_headers  # lazy
+
     try:
         req = Request(
             f"{api_url}/api/v1/auth/validate",
-            headers={
-                "Authorization": f"Bearer {api_key}",
-                "Content-Type": "application/json",
-                "User-Agent": "OpenBox-LangGraph-SDK/0.1.0",
-            },
+            headers=build_auth_headers(
+                api_key,
+                method="GET",
+                pathname="/api/v1/auth/validate",
+                body=b"",
+                agent_identity=agent_identity,
+            ),
             method="GET",
         )
         with urlopen(req, timeout=timeout) as response:
@@ -230,11 +261,14 @@ def _validate_api_key_with_server(
 # initialize() — synchronous, matching openbox-temporal-sdk-python
 # ═══════════════════════════════════════════════════════════════════
 
+
 def initialize(
     api_url: str,
     api_key: str,
     governance_timeout: float = 30.0,
     validate: bool = True,
+    agent_did: str | None = None,
+    agent_private_key: str | None = None,
 ) -> None:
     """Initialize the OpenBox LangGraph SDK with credentials.
 
@@ -246,7 +280,12 @@ def initialize(
         api_key: API key in `obx_live_*` or `obx_test_*` format.
         governance_timeout: HTTP timeout in **seconds** for governance calls (default 30.0).
         validate: If True, validates the API key against the server on startup.
+        agent_did: Optional OpenBox agent DID. Falls back to `OPENBOX_AGENT_DID`.
+        agent_private_key: Optional raw Ed25519 private key seed. Falls back to
+            `OPENBOX_AGENT_PRIVATE_KEY`.
     """
+    import os
+
     validate_url_security(api_url)
 
     if not validate_api_key_format(api_key):
@@ -259,9 +298,27 @@ def initialize(
         )
         raise OpenBoxAuthError(msg)
 
-    _global_config.configure(api_url.rstrip("/"), api_key, governance_timeout)
+    try:
+        agent_identity = parse_optional_agent_identity_config(
+            did=agent_did or os.environ.get("OPENBOX_AGENT_DID"),
+            private_key=agent_private_key or os.environ.get("OPENBOX_AGENT_PRIVATE_KEY"),
+        )
+    except OpenBoxConfigError:
+        raise
 
     if validate:
-        _validate_api_key_with_server(api_url.rstrip("/"), api_key, governance_timeout)
+        _validate_api_key_with_server(
+            api_url.rstrip("/"),
+            api_key,
+            governance_timeout,
+            agent_identity,
+        )
+
+    _global_config.configure(
+        api_url.rstrip("/"),
+        api_key,
+        governance_timeout,
+        agent_identity,
+    )
 
     _get_logger().info(f"OpenBox LangGraph SDK initialized with API URL: {api_url}")

openbox_langgraph/errors.py

@@ -11,6 +11,10 @@ class OpenBoxAuthError(OpenBoxError):
     """Raised when the API key is invalid or unauthorized."""
 
 
+class OpenBoxConfigError(OpenBoxError):
+    """Raised when SDK configuration is invalid."""
+
+
 class OpenBoxNetworkError(OpenBoxError):
     """Raised when the OpenBox Core API is unreachable or returns an error."""
 

openbox_langgraph/hook_governance.py

@@ -21,6 +21,7 @@ from typing import TYPE_CHECKING, Any
 import httpx
 
 from .client import build_auth_headers
+from .identity import AgentIdentityConfig, parse_optional_agent_identity_config
 
 if TYPE_CHECKING:
     from .span_processor import WorkflowSpanProcessor
@@ -37,7 +38,7 @@ _api_key: str = ""
 _api_timeout: float = 30.0
 _on_api_error: str = FAIL_OPEN
 _span_processor: WorkflowSpanProcessor | None = None
-_cached_auth_headers: dict | None = None
+_agent_identity: AgentIdentityConfig | None = None
 
 # Persistent HTTP clients (lazy-init, thread-safe for requests)
 _sync_client: httpx.Client | None = None
@@ -51,6 +52,8 @@ def configure(
     *,
     api_timeout: float = 30.0,
     on_api_error: str = "fail_open",
+    agent_did: str | None = None,
+    agent_private_key: str | None = None,
 ) -> None:
     """Set governance config. Called once by setup_opentelemetry_for_governance().
 
@@ -60,16 +63,20 @@ def configure(
         span_processor: WorkflowSpanProcessor for activity context lookup
         api_timeout: Timeout for governance API calls (seconds)
         on_api_error: Error policy — "fail_open" or "fail_closed"
+        agent_did: Optional OpenBox agent DID for AIP request signing
+        agent_private_key: Optional OpenBox agent private key for AIP request signing
     """
     global _api_url, _api_key, _api_timeout, _on_api_error
-    global _span_processor, _sync_client, _async_client, _cached_auth_headers
+    global _span_processor, _sync_client, _async_client, _agent_identity
     _api_url = api_url.rstrip("/")
     _api_key = api_key
     _api_timeout = api_timeout
     _on_api_error = on_api_error
     _span_processor = span_processor
-    # Cache auth headers (immutable after configure)
-    _cached_auth_headers = build_auth_headers(api_key)
+    _agent_identity = parse_optional_agent_identity_config(
+        did=agent_did,
+        private_key=agent_private_key,
+    )
     # Reset persistent clients so they pick up new timeout/config
     _sync_client = None
     _async_client = None
@@ -138,9 +145,15 @@ def extract_span_context(span) -> tuple:
     return span_id, trace_id, parent_span_id
 
 
-def _auth_headers() -> dict:
-    """Return cached auth headers (built once in configure())."""
-    return _cached_auth_headers or build_auth_headers(_api_key)
+def _auth_headers(*, method: str, pathname: str, body: bytes | str | None) -> dict[str, str]:
+    """Build auth headers for the exact outbound governance request."""
+    return build_auth_headers(
+        _api_key,
+        method=method,
+        pathname=pathname,
+        body=body,
+        agent_identity=_agent_identity,
+    )
 
 
 def _build_payload(
@@ -332,10 +345,15 @@ def evaluate_sync(
 
     try:
         client = _get_sync_client()
+        body = _json_body(payload)
         response = client.post(
             f"{_api_url}/api/v1/governance/evaluate",
-            json=payload,
-            headers=_auth_headers(),
+            content=body,
+            headers=_auth_headers(
+                method="POST",
+                pathname="/api/v1/governance/evaluate",
+                body=body,
+            ),
         )
         _send_and_handle(response, identifier, span=span)
 
@@ -380,10 +398,15 @@ async def evaluate_async(
 
     try:
         client = _get_async_client()
+        body = _json_body(payload)
         response = await client.post(
             f"{_api_url}/api/v1/governance/evaluate",
-            json=payload,
-            headers=_auth_headers(),
+            content=body,
+            headers=_auth_headers(
+                method="POST",
+                pathname="/api/v1/governance/evaluate",
+                body=body,
+            ),
         )
         _send_and_handle(response, identifier, span=span)
 
@@ -395,3 +418,7 @@ async def evaluate_async(
             raise GovernanceBlockedError(
                 "halt", f"Governance evaluation error: {e}", identifier
             ) from e
+
+
+def _json_body(payload: dict[str, Any]) -> bytes:
+    return json.dumps(payload, separators=(",", ":"), default=str).encode("utf-8")

openbox_langgraph/identity.py

@@ -0,0 +1,160 @@
+"""OpenBox AIP agent identity signing helpers."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import re
+import uuid
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from openbox_langgraph.errors import OpenBoxConfigError
+
+OPENBOX_AGENT_DID_HEADER = "X-OpenBox-Agent-DID"
+OPENBOX_AGENT_TIMESTAMP_HEADER = "X-OpenBox-Agent-Timestamp"
+OPENBOX_AGENT_NONCE_HEADER = "X-OpenBox-Agent-Nonce"
+OPENBOX_BODY_SHA256_HEADER = "X-OpenBox-Body-SHA256"
+OPENBOX_AGENT_SIGNATURE_HEADER = "X-OpenBox-Agent-Signature"
+
+_DID_PATTERN = re.compile(
+    r"^did:aip:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+    re.IGNORECASE,
+)
+_ED25519_SEED_BYTE_LENGTH = 32
+
+
+@dataclass(frozen=True)
+class AgentIdentityConfig:
+    """Validated AIP identity configuration for one OpenBox agent."""
+
+    did: str
+    private_key: str
+
+
+AgentIdentityHeaders = dict[str, str]
+
+
+def build_agent_identity_canonical_request(
+    *,
+    body_sha256: str,
+    method: str,
+    nonce: str,
+    pathname: str,
+    timestamp: str,
+) -> str:
+    """Return Core's newline-joined canonical request string."""
+    return "\n".join([method.upper(), pathname, timestamp, nonce, body_sha256])
+
+
+def validate_agent_identity_config(*, did: str, private_key: str) -> AgentIdentityConfig:
+    """Validate and normalize AIP DID/private-key configuration."""
+    normalized_did = did.strip()
+    normalized_private_key = private_key.strip()
+
+    if not _DID_PATTERN.match(normalized_did):
+        msg = "Invalid OpenBox agent DID. Expected format 'did:aip:<uuid>'."
+        raise OpenBoxConfigError(msg)
+
+    private_key_seed = _decode_private_key_seed(normalized_private_key)
+    return AgentIdentityConfig(
+        did=normalized_did,
+        private_key=base64.b64encode(private_key_seed).decode("ascii"),
+    )
+
+
+def parse_optional_agent_identity_config(
+    *,
+    did: str | None,
+    private_key: str | None,
+) -> AgentIdentityConfig | None:
+    """Parse optional DID config and fail fast when only one value is present."""
+    normalized_did = _normalize_optional_string(did)
+    normalized_private_key = _normalize_optional_string(private_key)
+
+    if normalized_did is None and normalized_private_key is None:
+        return None
+
+    if normalized_did is None or normalized_private_key is None:
+        msg = (
+            "Both OPENBOX_AGENT_DID and OPENBOX_AGENT_PRIVATE_KEY are required "
+            "when enabling OpenBox agent identity signing."
+        )
+        raise OpenBoxConfigError(msg)
+
+    return validate_agent_identity_config(did=normalized_did, private_key=normalized_private_key)
+
+
+def create_agent_identity_headers(
+    *,
+    did: str,
+    private_key: str,
+    method: str,
+    pathname: str,
+    body: bytes | str | None = None,
+    timestamp: str | None = None,
+    nonce: str | None = None,
+) -> AgentIdentityHeaders:
+    """Create signed AIP headers for an exact outbound request body."""
+    identity = validate_agent_identity_config(did=did, private_key=private_key)
+    body_bytes = _body_to_bytes(body)
+    body_sha256 = hashlib.sha256(body_bytes).hexdigest()
+    timestamp_value = timestamp or _rfc3339_now()
+    nonce_value = nonce or str(uuid.uuid4())
+    canonical = build_agent_identity_canonical_request(
+        method=method,
+        pathname=pathname,
+        timestamp=timestamp_value,
+        nonce=nonce_value,
+        body_sha256=body_sha256,
+    )
+    signing_key = Ed25519PrivateKey.from_private_bytes(
+        _decode_private_key_seed(identity.private_key)
+    )
+    signature = signing_key.sign(canonical.encode("utf-8"))
+
+    return {
+        OPENBOX_AGENT_DID_HEADER: identity.did,
+        OPENBOX_AGENT_TIMESTAMP_HEADER: timestamp_value,
+        OPENBOX_AGENT_NONCE_HEADER: nonce_value,
+        OPENBOX_BODY_SHA256_HEADER: body_sha256,
+        OPENBOX_AGENT_SIGNATURE_HEADER: base64.b64encode(signature).decode("ascii"),
+    }
+
+
+def _decode_private_key_seed(private_key: str) -> bytes:
+    try:
+        decoded = base64.b64decode(private_key, validate=True)
+    except ValueError as exc:
+        msg = "Invalid OpenBox agent private key. Expected a base64 raw 32-byte Ed25519 seed."
+        raise OpenBoxConfigError(msg) from exc
+
+    if (
+        len(decoded) != _ED25519_SEED_BYTE_LENGTH
+        or base64.b64encode(decoded).decode("ascii") != private_key
+    ):
+        msg = "Invalid OpenBox agent private key. Expected a base64 raw 32-byte Ed25519 seed."
+        raise OpenBoxConfigError(msg)
+
+    return decoded
+
+
+def _body_to_bytes(body: bytes | str | None) -> bytes:
+    if body is None:
+        return b""
+    if isinstance(body, bytes):
+        return body
+    return body.encode("utf-8")
+
+
+def _normalize_optional_string(value: str | None) -> str | None:
+    if value is None:
+        return None
+    stripped = value.strip()
+    return stripped or None
+
+
+def _rfc3339_now() -> str:
+    return datetime.now(tz=UTC).isoformat(timespec="microseconds").replace("+00:00", "Z")

openbox_langgraph/langgraph_handler.py

@@ -413,6 +413,8 @@ class OpenBoxLangGraphHandler:
                 api_key=gc.api_key,
                 timeout=gc.governance_timeout,  # seconds
                 on_api_error=self._config.on_api_error,
+                agent_did=gc.agent_did,
+                agent_private_key=gc.agent_private_key,
             )
 
         # Setup OTel HTTP governance hooks (required)
@@ -429,6 +431,8 @@ class OpenBoxLangGraphHandler:
                 api_timeout=gc.governance_timeout,
                 on_api_error=self._config.on_api_error,
                 sqlalchemy_engine=opts.sqlalchemy_engine,
+                agent_did=gc.agent_did,
+                agent_private_key=gc.agent_private_key,
             )
             _logger.debug("[OpenBox] OTel HTTP governance hooks enabled")
         else:
@@ -1451,6 +1455,8 @@ def create_openbox_graph_handler(
     validate: bool = True,
     enable_telemetry: bool = True,
     sqlalchemy_engine: Any = None,
+    agent_did: str | None = None,
+    agent_private_key: str | None = None,
     **handler_kwargs: Any,
 ) -> OpenBoxLangGraphHandler:
     """Create a fully configured `OpenBoxLangGraphHandler` wrapping a compiled LangGraph graph.
@@ -1467,6 +1473,9 @@ def create_openbox_graph_handler(
         enable_telemetry: Reserved for future HTTP-span telemetry patching.
         sqlalchemy_engine: Optional SQLAlchemy Engine instance to instrument for DB
             governance. Required when the engine is created before the handler.
+        agent_did: Optional OpenBox agent DID. Falls back to `OPENBOX_AGENT_DID`.
+        agent_private_key: Optional raw Ed25519 private key seed. Falls back to
+            `OPENBOX_AGENT_PRIVATE_KEY`.
         **handler_kwargs: Additional keyword arguments forwarded to
             `OpenBoxLangGraphHandlerOptions`.
 
@@ -1488,6 +1497,8 @@ def create_openbox_graph_handler(
         api_key=api_key,
         governance_timeout=governance_timeout,
         validate=validate,
+        agent_did=agent_did,
+        agent_private_key=agent_private_key,
     )
 
     options = OpenBoxLangGraphHandlerOptions(

openbox_langgraph/otel_setup.py

@@ -67,6 +67,8 @@ def setup_opentelemetry_for_governance(
     sqlalchemy_engine: Any | None = None,
     api_timeout: float = 30.0,
     on_api_error: str = "fail_open",
+    agent_did: str | None = None,
+    agent_private_key: str | None = None,
 ) -> None:
     """
     Setup OpenTelemetry instrumentors with body capture hooks.
@@ -88,6 +90,8 @@ def setup_opentelemetry_for_governance(
                           when the engine is created before instrumentation runs (e.g.,
                           at module import time). If not provided, only future engines
                           created via create_engine() will be instrumented.
+        agent_did: Optional OpenBox agent DID for AIP request signing.
+        agent_private_key: Optional OpenBox agent private key for AIP request signing.
     """
     global _span_processor, _ignored_url_prefixes
     _span_processor = span_processor
@@ -99,8 +103,13 @@ def setup_opentelemetry_for_governance(
 
     # Configure governance modules
     _hook_gov.configure(
-        api_url, api_key, span_processor,
-        api_timeout=api_timeout, on_api_error=on_api_error,
+        api_url,
+        api_key,
+        span_processor,
+        api_timeout=api_timeout,
+        on_api_error=on_api_error,
+        agent_did=agent_did,
+        agent_private_key=agent_private_key,
     )
     _db_gov.configure(span_processor)
 

{openbox_langgraph_sdk_python-0.1.2.dist-info → openbox_langgraph_sdk_python-0.2.0.dist-info}/METADATA

@@ -1,11 +1,13 @@
 Metadata-Version: 2.4
 Name: openbox-langgraph-sdk-python
-Version: 0.1.2
+Version: 0.2.0
 Summary: OpenBox governance and observability SDK for LangGraph
 License: MIT
+License-File: LICENSE
 Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0.0
 Requires-Dist: httpx>=0.27.0
-Requires-Dist: langchain-core>=1.2.22
+Requires-Dist: langchain-core>=1.3.3
 Requires-Dist: langgraph>=0.2.0
 Requires-Dist: opentelemetry-api>=1.20.0
 Requires-Dist: opentelemetry-instrumentation-asyncpg>=0.41b0
@@ -24,6 +26,7 @@ Requires-Dist: opentelemetry-sdk>=1.20.0
 Provides-Extra: dev
 Requires-Dist: mypy>=1.10.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.6.0; extra == 'dev'
 Provides-Extra: otel
@@ -128,15 +131,19 @@ uv add openbox-langgraph-sdk-python
 
 ## Quickstart
 
-### 1. Get your API key
+### 1. Get your agent credentials
 
-Sign in to [dashboard.openbox.ai](https://dashboard.openbox.ai), create an agent called `"MyAgent"`, and copy your API key (`obx_live_...` or `obx_test_...`).
+Sign in to [dashboard.openbox.ai](https://dashboard.openbox.ai), create an agent called `"MyAgent"`, and copy the agent API key plus its DID credentials.
+
+New OpenBox agents have DID signing enabled by default. Keep the private key secret and load it from your environment.
 
 ### 2. Set environment variables
 
 ```bash
 export OPENBOX_URL="https://core.openbox.ai"
 export OPENBOX_API_KEY="obx_live_..."
+export OPENBOX_AGENT_DID="did:aip:..."
+export OPENBOX_AGENT_PRIVATE_KEY="..."
 ```
 
 ### 3. Wrap your graph
@@ -195,6 +202,8 @@ See `test-agent/README.md` for setup and run instructions.
 | `graph` | `CompiledGraph` | **required** | Your compiled LangGraph graph |
 | `api_url` | `str` | **required** | Base URL of your OpenBox Core instance |
 | `api_key` | `str` | **required** | API key (`obx_live_*` or `obx_test_*`) |
+| `agent_did` | `str` | `OPENBOX_AGENT_DID` | Agent DID used to sign governance requests |
+| `agent_private_key` | `str` | `OPENBOX_AGENT_PRIVATE_KEY` | Base64 raw Ed25519 private key seed for the agent DID |
 | `agent_name` | `str` | `None` | Agent name as configured in the dashboard |
 | `validate` | `bool` | `True` | Validate API key against server on startup |
 | `on_api_error` | `str` | `"fail_open"` | `"fail_open"` (allow on error) or `"fail_closed"` (block on error) |

openbox_langgraph_sdk_python-0.2.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+openbox_langgraph/__init__.py,sha256=PCVxIw5vkxH8e8QoTO7xSZtzzT5cLm2hiccVv9dESqA,4048
+openbox_langgraph/client.py,sha256=18LfPcAZqpEjes0Vca-yymQqTL4ZWcviliE2pmHLmjk,15602
+openbox_langgraph/config.py,sha256=e6aeRJYbgwMZMYW0miOftl-OcSHhDfEZI7SqXAziE-0,13106
+openbox_langgraph/db_governance_hooks.py,sha256=9Cj3Afsr3WUl1HYqOC8Q1P8OWMOR0lSOZhO5OxrpOl8,40120
+openbox_langgraph/errors.py,sha256=2FLK2_h-ObNZ-r3jPZJQR0fU5WMBoEE_0FPOxL5BLlA,3806
+openbox_langgraph/file_governance_hooks.py,sha256=ddPZEF8yu8iq48rfU3OhI867P6G_I9Kt_ajfPo_6izc,16100
+openbox_langgraph/hitl.py,sha256=p8Xyxp9vvIBciumghM2RGJ53deIIwbufLRmw-PPLteU,2751
+openbox_langgraph/hook_governance.py,sha256=BsXrOGMPIFtkoYukbI7qL0hMohgTMJwk7unnztmOIug,14913
+openbox_langgraph/http_governance_hooks.py,sha256=DbY1p_ZipUxJqR6jrc9FjLVA4RkYRVx6p-Nrlf0hzt8,28170
+openbox_langgraph/identity.py,sha256=PI0BngywO5sCDSw9rw0N12QBWEKcRoB7QBkmig4-nqA,5028
+openbox_langgraph/langgraph_handler.py,sha256=UP9aXufLx_CtswEaOpmyva6NRtECeYn3KO5g2H4SvKQ,72722
+openbox_langgraph/otel_setup.py,sha256=EVEGcfkobo2_qkec9lyyyNDIzJjIv1k8QuX6cL6aXN8,17637
+openbox_langgraph/span_processor.py,sha256=tY3OXXIq9b47vjmA1oZy2Uu7N1Y5gSaxBOI1RgZK09Q,13289
+openbox_langgraph/tracing.py,sha256=818uke3pRRRFLuO5Ca-Tj3p-LA2QCVjRiI41gQcs5yU,12590
+openbox_langgraph/types.py,sha256=EUozIU3pCimjXItwKLaZ-NLLpHGAD06SgBRxgK1rHHg,18591
+openbox_langgraph/verdict_handler.py,sha256=YmZjBxzOa2RBbkF13xDCPUAGzz7m1hwdMErwOVDl2WM,8323
+openbox_langgraph_sdk_python-0.2.0.dist-info/METADATA,sha256=4QbHIlf-h2TEb3xF_DOauHdmnkKTLwYUsvShRMdcrJE,21481
+openbox_langgraph_sdk_python-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+openbox_langgraph_sdk_python-0.2.0.dist-info/licenses/LICENSE,sha256=bPyy7QFDMnA5r6asaR3iD9rQvpjz5cUFk1ouHCuBYIY,1071
+openbox_langgraph_sdk_python-0.2.0.dist-info/RECORD,,

openbox_langgraph_sdk_python-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OPENBOX AI LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openbox_langgraph_sdk_python-0.1.2.dist-info/RECORD

@@ -1,18 +0,0 @@
-openbox_langgraph/__init__.py,sha256=_hLVtJi-ERJ_GQJImJOMsSzu8RKse52kA-Lsk-hskgs,3581
-openbox_langgraph/client.py,sha256=YpTvZEruBuhYPHbOlt9Hq1YsB_b3Ak9cwuTXYdVr2_M,13356
-openbox_langgraph/config.py,sha256=xWMqcntzY6yveP2roqsC2gdkc66n9F8c903ATt415f4,11643
-openbox_langgraph/db_governance_hooks.py,sha256=9Cj3Afsr3WUl1HYqOC8Q1P8OWMOR0lSOZhO5OxrpOl8,40120
-openbox_langgraph/errors.py,sha256=ZEE6gUBf6KSEUqwOU887ocMoJuqX9Jt3U12u93BevQk,3712
-openbox_langgraph/file_governance_hooks.py,sha256=ddPZEF8yu8iq48rfU3OhI867P6G_I9Kt_ajfPo_6izc,16100
-openbox_langgraph/hitl.py,sha256=p8Xyxp9vvIBciumghM2RGJ53deIIwbufLRmw-PPLteU,2751
-openbox_langgraph/hook_governance.py,sha256=ZDAcyjTBQnFkwG6fv6XOAwiMtwXRQAQCTgTWiD6np40,13946
-openbox_langgraph/http_governance_hooks.py,sha256=DbY1p_ZipUxJqR6jrc9FjLVA4RkYRVx6p-Nrlf0hzt8,28170
-openbox_langgraph/langgraph_handler.py,sha256=BD61U9F2ESLzSTDJ-wXLS5tNFjvoaeSLHqoj2ABYfQQ,72177
-openbox_langgraph/otel_setup.py,sha256=ti9hQ8pWVj8gQk8E4WMw9gDPqGUlGSzoJLoav38EJno,17305
-openbox_langgraph/span_processor.py,sha256=tY3OXXIq9b47vjmA1oZy2Uu7N1Y5gSaxBOI1RgZK09Q,13289
-openbox_langgraph/tracing.py,sha256=818uke3pRRRFLuO5Ca-Tj3p-LA2QCVjRiI41gQcs5yU,12590
-openbox_langgraph/types.py,sha256=EUozIU3pCimjXItwKLaZ-NLLpHGAD06SgBRxgK1rHHg,18591
-openbox_langgraph/verdict_handler.py,sha256=YmZjBxzOa2RBbkF13xDCPUAGzz7m1hwdMErwOVDl2WM,8323
-openbox_langgraph_sdk_python-0.1.2.dist-info/METADATA,sha256=V3opgqntXab1KFXSYKwjc-0uEUpq4uDNcVYXzMkzeD4,20963
-openbox_langgraph_sdk_python-0.1.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-openbox_langgraph_sdk_python-0.1.2.dist-info/RECORD,,