openbox-sdk-python 1.2.0__tar.gz → 1.3.0__tar.gz

openbox_sdk_python-1.3.0/CHANGELOG.md

@@ -0,0 +1,116 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- **Okta identity bootstrap** — an `okta_ai_agent` runtime now needs only
+  `OPENBOX_API_URL`, `OPENBOX_API_KEY`, and `OPENBOX_OKTA_AGENT_PRIVATE_KEY`. The SDK
+  fetches the remaining identity metadata (agent id, organization id, deployment id,
+  assertion audience, external Okta agent id, credential `kid`, algorithm) from
+  `GET /api/v2/auth/bootstrap` on first use and caches it in memory for the lifetime of
+  the client. The signed assertion and its verification are unchanged — only how the SDK
+  obtains its non-secret configuration.
+- Before the first governed request the SDK derives its private key's RFC 7638 public-key
+  thumbprint and compares it (constant-time) with the one Core reports for the agent's
+  selected credential. A mismatch raises `OpenBoxConfigError` with actionable guidance;
+  no governed request is sent.
+- `EvaluationClient.refresh_identity_metadata()` / `arefresh_identity_metadata()` for
+  long-running agents whose selected credential rotated. The thumbprint is re-verified
+  *before* cached metadata is replaced, so a credential rotated to a key this process
+  does not hold fails loudly and leaves the client on its previous identity. The client
+  never refreshes automatically after an auth failure — a blind retry cannot repair a key
+  mismatch and would hide it.
+- `EvaluationClient.identity_metadata()` exposes the validated bootstrap document
+  (non-secret).
+- New modules `openbox_core.bootstrap` and `openbox_core.jwk_thumbprint`.
+
+### Changed
+- Okta configuration now resolves into exactly one of three modes, never a blend:
+  **bootstrap** (private key only), **legacy explicit** (every metadata field set, works
+  unchanged), or **invalid mixed** (only some metadata fields set) — which raises
+  `OpenBoxConfigError` naming the offending fields rather than merging stale local values
+  over what Core would have supplied.
+- `OPENBOX_DEPLOYMENT_ID` is no longer required in bootstrap mode. Core returns its own
+  deployment id, which prevents a runtime from signing for one deployment while calling
+  another.
+- No failure path downgrades to v1, to an unsigned request, or to a different identity
+  method. A Core that predates the endpoint (`404`) produces actionable upgrade guidance.
+
+## [1.3.0] - 2026-07-30
+
+### Added
+- v2 (Okta AI Agent) identity verification support, alongside existing v1 (OpenBox DID)
+  and inferred `legacy_unsigned` support: tagged identity configuration
+  (`OpenBoxDidIdentityConfig` / `OktaAiAgentIdentityConfig` in
+  `openbox_core.identity_types`), RS256 assertion signing
+  (`openbox_core.identity_okta`), and version-aware endpoint selection —
+  `okta_ai_agent` identities route to `/api/v2/governance/evaluate`,
+  `/api/v2/governance/approval`, `GET /api/v2/auth/validate`, and
+  `/api/v2/handoffs`; there is no cross-version retry.
+- New env vars: `OPENBOX_AGENT_IDENTITY_METHOD`, `OPENBOX_OKTA_AGENT_ID`,
+  `OPENBOX_OKTA_AGENT_KEY_ID`, `OPENBOX_OKTA_AGENT_PRIVATE_KEY`,
+  `OPENBOX_OKTA_AGENT_ALGORITHM`, `OPENBOX_AGENT_ID`, `OPENBOX_ORGANIZATION_ID`,
+  `OPENBOX_DEPLOYMENT_ID`, `OPENBOX_AGENT_PROOF_AUDIENCE`. DID and Okta identity
+  fields are mutually exclusive; the canonical Okta private-key encoding is PKCS8 PEM.
+- `EvaluationClient.emit_handoff` / `aemit_handoff` — source-authenticated handoff
+  (`POST /api/v1/handoffs` for openbox_did, `/api/v2/handoffs` for okta_ai_agent).
+  Inferred unsigned mode raises `OpenBoxConfigError` (no source identity to prove)
+  instead of silently falling back to the legacy receiver-authenticated event.
+- `EvaluationClient.validate_okta_identity_transition` /
+  `avalidate_okta_identity_transition` and `.validate_openbox_did_identity_transition` /
+  `avalidate_openbox_did_identity_transition` — transition-preflight helpers that sign
+  with an **explicit candidate identity** and never fall back to the client's active
+  signer, even if the client happens to already use the same identity method.
+
+### Fixed
+- **BREAKING (security fix):** `EvaluationClient.evaluate` / `aevaluate` and
+  `.poll_approval` / `.apoll_approval` now raise an actionable
+  `OpenBoxAuthError`/`OpenBoxSigningError` on HTTP 401/403, regardless of
+  `on_api_error`. Previously, evaluate routed every `>= 400` response — including
+  401/403 — through the network-failure path, which under the default `fail_open`
+  produced a fallback `ALLOW`; an agent whose key was revoked kept operating,
+  ungoverned. Approval polling treated 401/403 the same as a transient poll failure
+  (returned `None`, read by callers as "still pending"), so a revoked agent's
+  approval wait never terminated. Both are now hard authentication failures: they
+  fail closed unconditionally and are never retried against the other API version.
+  A genuine network error or 5xx is unaffected and still respects `on_api_error`.
+
+## [1.2.0] - 2026-07-23
+
+### Changed
+- **BREAKING:** Renamed the public BLOCK remediation contract from `retry_plan` to `patch`.
+  `RetryPlan` is now `Patch`, `RetryDirective` is now `PatchDirective`, and
+  `handle_retryable_block()` is now `handle_patch()`. `EvaluationResult.retry_plan` and
+  `ApprovalResult.retry_plan` are now `.patch`. The parser now reads only the canonical outer
+  wire key `patch`; the old `retry_plan` key is no longer recognized.
+- The verdict gate is unchanged: a directive is still surfaced only for an exact `BLOCK` verdict
+  carrying a valid patch — never for HALT/`should_stop()`, and never for an expired approval
+  result.
+
+### Notes
+- This is a breaking release: the old public names (`RetryPlan`, `RetryDirective`,
+  `handle_retryable_block`, `.retry_plan`) are removed, not aliased. Consumers still pinned to
+  `1.1.0` remain fail-safe — they ignore the unknown `patch` field but still enforce the `BLOCK`
+  verdict.
+
+## [1.1.0] - 2026-07-21
+
+### Added
+- `RetryPlan` and `RetryDirective` dataclasses in `openbox_core.contracts.results`.
+- Optional `retry_plan` directive parsing on both `EvaluationResult` and `ApprovalResult`.
+  A `_MISSING` sentinel keeps a present `new_input: null` distinct from an absent field; falsy
+  values (`null`, `""`, `0`, `[]`, `{}`) are preserved; a boolean `new_input` is rejected; and every
+  number (recursively) must be finite and, if integral, a JS-safe integer (`|n| <= 2^53 - 1`).
+- `handle_retryable_block(result)` — an opt-in, pure inspector that returns a `RetryDirective` only
+  for a `BLOCK` verdict carrying a valid plan. Returns `None` for a plain BLOCK, every non-BLOCK
+  verdict (including HALT), a pending verdict, and an expired `ApprovalResult`.
+
+### Notes
+- Default enforcement is unchanged: a `BLOCK` verdict still raises `GovernanceBlockedError`. The new
+  helper is opt-in and never triggers an automatic retry; malformed or ineligible plans are treated
+  as absent (never fail open).

openbox_sdk_python-1.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenBox AI
+
+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_sdk_python-1.2.0 → openbox_sdk_python-1.3.0}/PKG-INFO

@@ -1,13 +1,13 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: openbox-sdk-python
-Version: 1.2.0
+Version: 1.3.0
 Summary: OpenBox base SDK - governance contracts, strict gate, identity/signing, evaluate client, context runtime, OTel span wire serialization, and generic instrumentation shared by every OpenBox framework SDK
 Author-email: OpenBox Team <tino@openbox.ai>
 License-Expression: MIT
+License-File: LICENSE
 Keywords: governance,observability,openbox,opentelemetry,sdk
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -46,10 +46,14 @@ framework SDK builds on. It owns:
   `EvaluationResult`, `ApprovalResult`, `Verdict`).
 - **Always-strict governance gate** — malformed event/runtime contracts raise
   `ContractError` before send; there are no configurable gate modes.
-- **Identity & signing** — AIP DID validation + Ed25519 request signing,
-  byte-compatible with the Temporal SDK signing contract.
-- **Evaluate client** — sync + async calls to OpenBox Core
-  (`/api/v1/governance/evaluate`, `/approval`, `/auth/validate`).
+- **Identity & signing** — v1 OpenBox DID: AIP DID validation + Ed25519 request
+  signing, byte-compatible with the Temporal SDK signing contract. v2 Okta AI
+  Agent: tagged identity configuration + RS256 JWT assertion signing
+  (`openbox_core.identity_okta`, `openbox_core.identity_types`).
+- **Evaluate client** — sync + async calls to OpenBox Core, routed by
+  configured identity: `/api/v1/governance/evaluate` (`/approval`,
+  `/auth/validate`, `/handoffs`) for OpenBox DID / inferred unsigned mode, or
+  the `/api/v2/*` equivalents for Okta AI Agent — no cross-version retry.
 - **Context & runtime** — `ActivityContext`, `ContextStore`, trace
   correlation, `FrameworkAdapter` protocol, `OpenBoxRuntime`.
 - **OTel span wire serialization** — OTel spans are the internal source of
@@ -78,6 +82,64 @@ uv sync --extra http    # + HTTP instrumentation targets
 uv sync --extra db      # + DB instrumentation targets
 ```
 
+## Okta AI Agent identity (`okta_ai_agent`)
+
+An agent whose OpenBox identity is verified against an Okta AI Agent credential
+signs every request with an RS256 assertion. That assertion binds seven values
+OpenBox Core already owns, so the runtime does **not** configure them — it fetches
+them from Core after authenticating with its API key:
+
+```dotenv
+OPENBOX_API_URL=https://core.example.com
+OPENBOX_API_KEY=obx_live_...
+OPENBOX_OKTA_AGENT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
+...
+-----END PRIVATE KEY-----"
+```
+
+That is the complete configuration. The private key is the only value Core can
+never supply — **OpenBox never receives, stores, or returns it.** Everything else
+(agent id, organization id, deployment id, assertion audience, external Okta agent
+id, credential `kid`, algorithm) comes from `GET /api/v2/auth/bootstrap` on first
+use and is cached in memory for the lifetime of the client.
+
+Before the first governed request the SDK derives its private key's RFC 7638
+public-key thumbprint and compares it with the one Core reports for the agent's
+selected credential. A mismatch raises `OpenBoxConfigError` immediately, rather
+than sending an assertion that could only be rejected:
+
+> The configured private key does not match the selected Okta credential for this
+> OpenBox agent. Export the private key associated with the selected credential,
+> or rotate the agent credential.
+
+**Credential rotation.** Long-running agents can refresh explicitly:
+
+```python
+document = client.refresh_identity_metadata()   # async: await client.arefresh_identity_metadata()
+print(document.okta.credential_kid)
+print(document.authority.activation_version)
+```
+
+The document also carries required, non-secret assignment, provider-generation,
+activation, credential, and projection identifiers. The SDK fails closed when an
+IAM-v3 Core deployment omits or returns malformed authority metadata.
+The refresh re-runs the thumbprint check *before* replacing cached metadata, so a
+credential that rotated to a key this process does not hold fails loudly and leaves
+the client on its previous identity. The SDK never refreshes automatically after an
+auth failure: rotation may have selected a new public key while the process still
+holds the old private key, and a silent retry would hide that rather than fix it.
+
+**Requirements.** The key must be a PKCS8 PEM RSA key of at least 2048 bits, and
+its public half must already be registered in Okta for the selected credential.
+
+**Explicit configuration** (every metadata field set locally) remains supported for
+compatibility. The two styles cannot be mixed: a configuration carrying only *some*
+metadata fields raises `OpenBoxConfigError` naming the offending fields, rather than
+quietly merging stale local values over what Core would have supplied. If Core
+answers `404`, the SDK reports that the deployment predates bootstrap and asks you
+to upgrade Core or supply the complete explicit configuration — it never downgrades
+to an unsigned request or to a different identity method.
+
 ## Import safety
 
 `openbox_core.__init__` and all `openbox_core.contracts.*` modules import
@@ -85,6 +147,9 @@ without pulling in `httpx`, `cryptography`, `requests`, or OTel
 instrumentation — safe for constrained framework paths such as the Temporal
 workflow sandbox. `tests/test_import_safety.py` enforces this in CI.
 
+`openbox_core.bootstrap` and `openbox_core.jwk_thumbprint` follow the same rule —
+both keep `httpx`/`cryptography` behind function-local imports.
+
 ## Development
 
 ```bash
@@ -92,3 +157,7 @@ uv sync --all-extras
 uv run pytest
 uv run ruff check .
 ```
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

openbox_sdk_python-1.3.0/README.md

@@ -0,0 +1,124 @@
+# openbox-sdk-python
+
+OpenBox base SDK (`import openbox_core`) — the standalone core every OpenBox
+framework SDK builds on. It owns:
+
+- **Contracts** — event and result dataclasses (`EventEnvelope`,
+  `EvaluationResult`, `ApprovalResult`, `Verdict`).
+- **Always-strict governance gate** — malformed event/runtime contracts raise
+  `ContractError` before send; there are no configurable gate modes.
+- **Identity & signing** — v1 OpenBox DID: AIP DID validation + Ed25519 request
+  signing, byte-compatible with the Temporal SDK signing contract. v2 Okta AI
+  Agent: tagged identity configuration + RS256 JWT assertion signing
+  (`openbox_core.identity_okta`, `openbox_core.identity_types`).
+- **Evaluate client** — sync + async calls to OpenBox Core, routed by
+  configured identity: `/api/v1/governance/evaluate` (`/approval`,
+  `/auth/validate`, `/handoffs`) for OpenBox DID / inferred unsigned mode, or
+  the `/api/v2/*` equivalents for Okta AI Agent — no cross-version retry.
+- **Context & runtime** — `ActivityContext`, `ContextStore`, trace
+  correlation, `FrameworkAdapter` protocol, `OpenBoxRuntime`.
+- **OTel span wire serialization** — OTel spans are the internal source of
+  truth, projected to the current Core `SpanData` wire shape before send.
+- **Generic instrumentation** — HTTP/DB/file/function wrappers with a
+  started/completed hook runtime enforcing preflight before real operations.
+- **Conformance kit** — reusable fixtures framework SDKs run to prove parity.
+
+Framework SDKs (Temporal, LangGraph, LangChain, DeepAgent, CrewAI) are thin
+adapters: they bind framework lifecycle into `ActivityContext`, emit lifecycle
+events, and translate `EvaluationResult` into native behavior.
+
+## Framework SDK integration
+
+New framework SDK developers and agents should start with
+[the OpenBox Python Framework SDK Integration guide](.github/instructions/openbox-sdk-python.instructions.md).
+It describes how to build a framework SDK on top of this base package without
+reimplementing config, signing, governance gates, hook wire payloads, or
+conformance fixtures.
+
+## Install
+
+```bash
+uv sync                 # core
+uv sync --extra http    # + HTTP instrumentation targets
+uv sync --extra db      # + DB instrumentation targets
+```
+
+## Okta AI Agent identity (`okta_ai_agent`)
+
+An agent whose OpenBox identity is verified against an Okta AI Agent credential
+signs every request with an RS256 assertion. That assertion binds seven values
+OpenBox Core already owns, so the runtime does **not** configure them — it fetches
+them from Core after authenticating with its API key:
+
+```dotenv
+OPENBOX_API_URL=https://core.example.com
+OPENBOX_API_KEY=obx_live_...
+OPENBOX_OKTA_AGENT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
+...
+-----END PRIVATE KEY-----"
+```
+
+That is the complete configuration. The private key is the only value Core can
+never supply — **OpenBox never receives, stores, or returns it.** Everything else
+(agent id, organization id, deployment id, assertion audience, external Okta agent
+id, credential `kid`, algorithm) comes from `GET /api/v2/auth/bootstrap` on first
+use and is cached in memory for the lifetime of the client.
+
+Before the first governed request the SDK derives its private key's RFC 7638
+public-key thumbprint and compares it with the one Core reports for the agent's
+selected credential. A mismatch raises `OpenBoxConfigError` immediately, rather
+than sending an assertion that could only be rejected:
+
+> The configured private key does not match the selected Okta credential for this
+> OpenBox agent. Export the private key associated with the selected credential,
+> or rotate the agent credential.
+
+**Credential rotation.** Long-running agents can refresh explicitly:
+
+```python
+document = client.refresh_identity_metadata()   # async: await client.arefresh_identity_metadata()
+print(document.okta.credential_kid)
+print(document.authority.activation_version)
+```
+
+The document also carries required, non-secret assignment, provider-generation,
+activation, credential, and projection identifiers. The SDK fails closed when an
+IAM-v3 Core deployment omits or returns malformed authority metadata.
+The refresh re-runs the thumbprint check *before* replacing cached metadata, so a
+credential that rotated to a key this process does not hold fails loudly and leaves
+the client on its previous identity. The SDK never refreshes automatically after an
+auth failure: rotation may have selected a new public key while the process still
+holds the old private key, and a silent retry would hide that rather than fix it.
+
+**Requirements.** The key must be a PKCS8 PEM RSA key of at least 2048 bits, and
+its public half must already be registered in Okta for the selected credential.
+
+**Explicit configuration** (every metadata field set locally) remains supported for
+compatibility. The two styles cannot be mixed: a configuration carrying only *some*
+metadata fields raises `OpenBoxConfigError` naming the offending fields, rather than
+quietly merging stale local values over what Core would have supplied. If Core
+answers `404`, the SDK reports that the deployment predates bootstrap and asks you
+to upgrade Core or supply the complete explicit configuration — it never downgrades
+to an unsigned request or to a different identity method.
+
+## Import safety
+
+`openbox_core.__init__` and all `openbox_core.contracts.*` modules import
+without pulling in `httpx`, `cryptography`, `requests`, or OTel
+instrumentation — safe for constrained framework paths such as the Temporal
+workflow sandbox. `tests/test_import_safety.py` enforces this in CI.
+
+`openbox_core.bootstrap` and `openbox_core.jwk_thumbprint` follow the same rule —
+both keep `httpx`/`cryptography` behind function-local imports.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check .
+```
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

{openbox_sdk_python-1.2.0 → openbox_sdk_python-1.3.0}/openbox_core/__init__.py

@@ -37,7 +37,7 @@ from .errors import (
 # governance; eagerly it can deadlock package init as a circular import, and
 # lazily it can recurse unboundedly when a per-request header builder resolves
 # the version. Keep in sync with pyproject.toml on release.
-__version__ = "1.2.0"
+__version__ = "1.3.0"
 
 __all__ = [
     "__version__",