dominus-sdk-python 9.0.15__tar.gz → 9.1.0__tar.gz

{dominus_sdk_python-9.0.15 → dominus_sdk_python-9.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 9.0.15
+Version: 9.1.0
 Summary: Python SDK for the Dominus gateway-first platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License-Expression: LicenseRef-Proprietary
@@ -38,8 +38,9 @@ Async Python SDK for the Dominus gateway-first service plane.
 ## Agent Guide
 
 Start with `docs/agent-guide/INDEX.md`. The current snapshot is
-`docs/agent-guide/2026-09-19-1300-sdk-python/00-reading-order.md`; the latest
-cleanup audit is `docs/janitor/2026-09-19-1300-sdk-python-cleanup-audit.md`.
+`docs/agent-guide/2026-10-16-1300-sdk-python/00-reading-order.md`; the latest
+cleanup audit is `docs/janitor/2026-10-16-1300-sdk-python-cleanup-audit.md`.
+Knowledge graph: graphify-out/GRAPH_REPORT.md — query with `graphify-run query "<question>"` before grepping.
 
 ## What This Repo Ships
 
@@ -48,7 +49,7 @@ cleanup audit is `docs/janitor/2026-09-19-1300-sdk-python-cleanup-audit.md`.
 - Gateway-scoped client mode for MCP and other user-JWT sessions
 - Transport compatibility for wrapped `{success,data}` responses and unwrapped Warden/control-plane success objects
 - Local helpers for JWT verification, trace propagation, retries, and console capture
-- Current package version: `9.0.15`
+- Current package version: `9.0.16`
 
 ## Install
 

{dominus_sdk_python-9.0.15 → dominus_sdk_python-9.1.0}/README.md

@@ -5,8 +5,9 @@ Async Python SDK for the Dominus gateway-first service plane.
 ## Agent Guide
 
 Start with `docs/agent-guide/INDEX.md`. The current snapshot is
-`docs/agent-guide/2026-09-19-1300-sdk-python/00-reading-order.md`; the latest
-cleanup audit is `docs/janitor/2026-09-19-1300-sdk-python-cleanup-audit.md`.
+`docs/agent-guide/2026-10-16-1300-sdk-python/00-reading-order.md`; the latest
+cleanup audit is `docs/janitor/2026-10-16-1300-sdk-python-cleanup-audit.md`.
+Knowledge graph: graphify-out/GRAPH_REPORT.md — query with `graphify-run query "<question>"` before grepping.
 
 ## What This Repo Ships
 
@@ -15,7 +16,7 @@ cleanup audit is `docs/janitor/2026-09-19-1300-sdk-python-cleanup-audit.md`.
 - Gateway-scoped client mode for MCP and other user-JWT sessions
 - Transport compatibility for wrapped `{success,data}` responses and unwrapped Warden/control-plane success objects
 - Local helpers for JWT verification, trace propagation, retries, and console capture
-- Current package version: `9.0.15`
+- Current package version: `9.0.16`
 
 ## Install
 

{dominus_sdk_python-9.0.15 → dominus_sdk_python-9.1.0}/dominus/__init__.py

@@ -148,6 +148,29 @@ from .helpers.core import (
     mint_selected_scope_jwt,
 )
 
+# Export the exact-target surface. The shared kernel codec stays a lazy,
+# out-of-band dependency (documented git-tag lane); importing this module never
+# requires it, so the base install stays targetless.
+from .target import (
+    EXACT_EXCHANGE_VERSION,
+    EXACT_TARGET_DEPENDENCY_LANE,
+    EXACT_TARGET_VERSION,
+    SERVICE_CORE_TAG,
+    TARGET_HEADER,
+    TOPOLOGY_TARGET_VERSION,
+    ExactTargetDependencyError,
+    ExactTargetError,
+    ExactTicketRecord,
+    assert_ticket_proves_target,
+    canonical_target_bytes,
+    selected_scope_target,
+    target_fingerprint,
+    target_header_value,
+    topology_target_hash,
+    validate_target,
+    validate_target_exchange_response,
+)
+
 # Export trace utilities for distributed tracing
 from .helpers.trace import (
     generate_trace_id,
@@ -191,7 +214,7 @@ from .errors import (
     TimeoutError as DominusTimeoutError,
 )
 
-__version__ = "9.0.15"
+__version__ = "9.1.0"
 __all__ = [
     # Main SDK instance
     "dominus",
@@ -267,6 +290,24 @@ __all__ = [
     "verify_jwt_locally",
     "is_jwt_valid",
     "mint_selected_scope_jwt",
+    # Exact-target surface (lazy shared kernel codec)
+    "EXACT_TARGET_VERSION",
+    "TOPOLOGY_TARGET_VERSION",
+    "EXACT_EXCHANGE_VERSION",
+    "TARGET_HEADER",
+    "SERVICE_CORE_TAG",
+    "EXACT_TARGET_DEPENDENCY_LANE",
+    "ExactTargetError",
+    "ExactTargetDependencyError",
+    "ExactTicketRecord",
+    "validate_target",
+    "selected_scope_target",
+    "validate_target_exchange_response",
+    "assert_ticket_proves_target",
+    "canonical_target_bytes",
+    "target_header_value",
+    "target_fingerprint",
+    "topology_target_hash",
     # Trace utilities
     "generate_trace_id",
     "get_current_trace_id",

{dominus_sdk_python-9.0.15 → dominus_sdk_python-9.1.0}/dominus/helpers/cache.py

@@ -108,7 +108,7 @@ def exponential_backoff_with_jitter(
     """
     delay = min(base_delay * (2 ** attempt), max_delay)
     jitter_range = delay * jitter
-    return delay + random.uniform(-jitter_range, jitter_range)
+    return min(max_delay, delay + random.uniform(-jitter_range, jitter_range))
 
 
 class DominusCache:
@@ -124,7 +124,7 @@ class DominusCache:
     """
 
     def __init__(self, default_ttl: int = 300):
-        self._store: Dict[str, Tuple[bytes, float]] = {}
+        self._store: Dict[str, Tuple[bytes, float, int]] = {}
         self._default_ttl = default_ttl
         self._cipher: Optional[Fernet] = None
 
@@ -141,7 +141,7 @@ class DominusCache:
         if not entry:
             return None
 
-        encrypted_value, expires_at = entry
+        encrypted_value, expires_at, duration = entry
 
         # Check expiry
         if time.time() >= expires_at:
@@ -159,8 +159,8 @@ class DominusCache:
         else:
             value = json.loads(encrypted_value.decode())
 
-        # Touch TTL
-        self._store[key] = (encrypted_value, time.time() + self._default_ttl)
+        # Touch TTL using the entry's own duration
+        self._store[key] = (encrypted_value, time.time() + duration, duration)
         return value
 
     def set(self, key: str, value: Any, ttl: Optional[int] = None) -> None:
@@ -173,7 +173,7 @@ class DominusCache:
         else:
             encrypted_value = json.dumps(value).encode()
 
-        self._store[key] = (encrypted_value, time.time() + duration)
+        self._store[key] = (encrypted_value, time.time() + duration, duration)
 
     def delete(self, key: str) -> bool:
         """Delete key."""

{dominus_sdk_python-9.0.15 → dominus_sdk_python-9.1.0}/dominus/helpers/core.py

@@ -5,6 +5,8 @@ Includes circuit breaker pattern to prevent runaway retries from exhausting
 Cloud Run CPU quota during service outages or circular dependency issues.
 """
 import asyncio
+import dataclasses
+import hashlib
 import httpx
 import base64
 import json
@@ -21,6 +23,21 @@ MAX_RETRIES = 3
 # When multiple concurrent coroutines need a new JWT, only one will mint
 _jwt_refresh_lock = asyncio.Lock()
 
+# Exact-target ticket cache. One entry is one immutable record — a ticket is
+# never paired with target bytes derived from a different request. The key is
+# the credential context plus the FULL target fingerprint, so any refinement
+# (branch, tenant, provisioning target, group, environment, project) or a
+# different credential gets its own entry.
+EXACT_TICKET_CACHE_PREFIX = "jwt:exact:"
+EXACT_TICKET_REFRESH_BUFFER_SECONDS = 60
+# Upper bound on the shared encrypted cache entry; the ticket's own `exp`
+# (minus the refresh buffer) wins when it is sooner.
+EXACT_TICKET_CACHE_TTL = 3300  # 55 minutes
+# One mutex per cache entry: concurrent callers for the same credential+target
+# share a single exchange, while unrelated credentials/targets never queue
+# behind each other's network round-trip.
+_exact_ticket_locks: dict[str, asyncio.Lock] = {}
+
 # Type alias
 DominusResponse = dict[str, Any]
 
@@ -642,6 +659,249 @@ async def mint_selected_scope_jwt(
         raise RuntimeError(f"Selected-scope JWT mint failed: {e}") from e
 
 
+def _exact_credential_key(psk_token: str) -> str:
+    """Credential discriminator for the exact-target cache. The PSK never enters a key."""
+    digest = hashlib.sha256(psk_token.encode("utf-8")).digest()
+    return base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+
+
+def _exact_refinement_key(
+    ttl_seconds: Optional[int],
+    run_id: Optional[str],
+    scopes: Optional[list],
+) -> str:
+    """Digest of the mint refinements — they land in the ticket's own claims."""
+    if ttl_seconds is None and run_id is None and scopes is None:
+        return ""
+    payload = {
+        "ttl_seconds": ttl_seconds,
+        "run_id": run_id,
+        "scopes": list(scopes) if scopes is not None else None,
+    }
+    digest = hashlib.sha256(
+        json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).digest()
+    return ":" + base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+
+
+def _exact_ticket_cache_key(
+    psk_token: str,
+    fingerprint: str,
+    refinements: str = "",
+) -> str:
+    return (
+        f"{EXACT_TICKET_CACHE_PREFIX}{_exact_credential_key(psk_token)}"
+        f":{fingerprint}{refinements}"
+    )
+
+
+def _exact_ticket_lock_for(cache_key: str) -> asyncio.Lock:
+    lock = _exact_ticket_locks.get(cache_key)
+    if lock is None:
+        lock = asyncio.Lock()
+        _exact_ticket_locks[cache_key] = lock
+    return lock
+
+
+def _exact_ticket_expiry(ticket: str) -> float:
+    """Local expiry from the ticket's own ``exp``, refreshed before it lapses."""
+    try:
+        payload = _decode_jwt_payload(ticket)
+        exp = payload.get("exp")
+        if isinstance(exp, (int, float)) and not isinstance(exp, bool):
+            return float(exp) - EXACT_TICKET_REFRESH_BUFFER_SECONDS
+    except Exception:
+        pass
+    return time.time() + EXACT_TICKET_CACHE_TTL
+
+
+def _cached_exact_ticket(cache_key: str):
+    """Read one cached record, re-validating its bytes; drop anything stale/tampered."""
+    from ..target import ExactTicketRecord
+
+    entry = dominus_cache.get(cache_key)
+    if not isinstance(entry, dict):
+        return None
+    try:
+        expires_at = float(entry.get("expires_at") or 0)
+    except (TypeError, ValueError):
+        expires_at = 0.0
+    if expires_at <= time.time():
+        dominus_cache.delete(cache_key)
+        return None
+    try:
+        return ExactTicketRecord.from_mapping(entry)
+    except Exception:
+        dominus_cache.delete(cache_key)
+        return None
+
+
+def _target_payload(target: Any) -> dict:
+    if dataclasses.is_dataclass(target) and not isinstance(target, type):
+        return dataclasses.asdict(target)
+    return dict(target)
+
+
+async def _exchange_exact_target(
+    psk_token: str,
+    target: Any,
+    *,
+    ttl_seconds: Optional[int] = None,
+    run_id: Optional[str] = None,
+    scopes: Optional[list] = None,
+    timeout: float = 30.0,
+):
+    """Perform one ``target-exchange.v1`` mint and validate the whole response."""
+    from ..config.endpoints import get_gateway_url, get_proxy_config
+    from ..errors import (
+        DominusError,
+        ConnectionError as DominusConnectionError,
+        TimeoutError as DominusTimeoutError,
+        raise_for_status,
+    )
+    from ..target import EXACT_EXCHANGE_VERSION, validate_target_exchange_response
+    from .trace import get_current_trace_id, get_current_span_id
+
+    headers = {
+        "Authorization": f"Bearer {psk_token}",
+        "Content-Type": "text/plain",
+        "X-Trace-Id": get_current_trace_id(),
+        "X-Parent-Span-Id": get_current_span_id(),
+    }
+
+    body: dict = {"version": EXACT_EXCHANGE_VERSION, "target": _target_payload(target)}
+    if ttl_seconds is not None:
+        body["ttl_seconds"] = ttl_seconds
+    if run_id is not None:
+        body["run_id"] = run_id
+    if scopes is not None:
+        body["scopes"] = list(scopes)
+
+    try:
+        async with httpx.AsyncClient(
+            base_url=get_gateway_url(),
+            headers=headers,
+            timeout=timeout,
+            proxy=get_proxy_config(),
+        ) as client:
+            response = await client.post("/jwt/mint", content=_b64_encode(body))
+    except httpx.TimeoutException as exc:
+        raise DominusTimeoutError(
+            "Exact-target exchange timed out", endpoint="/jwt/mint"
+        ) from exc
+    except httpx.NetworkError as exc:
+        raise DominusConnectionError(
+            f"Exact-target exchange failed: {exc}", endpoint="/jwt/mint"
+        ) from exc
+
+    if response.is_error:
+        message = f"Exact-target exchange failed: HTTP {response.status_code}"
+        details: dict = {}
+        try:
+            error_payload = _decode_json_or_b64_json(response.text)
+        except Exception:
+            error_payload = {}
+        if isinstance(error_payload, dict):
+            message = (
+                error_payload.get("message")
+                or error_payload.get("error")
+                or error_payload.get("detail")
+                or message
+            )
+            nested = error_payload.get("error")
+            error_details = error_payload.get("details")
+            details = error_details if isinstance(error_details, dict) else {}
+            for src in (error_payload, nested if isinstance(nested, dict) else {}):
+                for key in ("kind", "code", "category", "retryable", "trace_id", "request_id"):
+                    if key in src and key not in details:
+                        details[key] = src[key]
+        raise_for_status(response.status_code, str(message), details, "/jwt/mint")
+
+    result = _decode_json_or_b64_json(response.text)
+    if not isinstance(result, dict):
+        raise DominusError(
+            "Exact-target exchange returned a non-object response",
+            endpoint="/jwt/mint",
+        )
+    if result.get("success") is False:
+        error_details = result.get("details")
+        raise DominusError(
+            str(result.get("error") or result.get("message") or "Unknown exact-target exchange error"),
+            details=error_details if isinstance(error_details, dict) else {},
+            endpoint="/jwt/mint",
+        )
+
+    data = result.get("data", result)
+    return validate_target_exchange_response(data, target)
+
+
+async def mint_exact_target_ticket(
+    psk_token: str,
+    target: Any,
+    *,
+    ttl_seconds: Optional[int] = None,
+    run_id: Optional[str] = None,
+    scopes: Optional[list] = None,
+    force_refresh: bool = False,
+    timeout: float = 30.0,
+):
+    """Exchange an exact target for one atomic ticket record, cached.
+
+    The ticket, canonical target, fingerprint, and header are one immutable
+    unit keyed by credential context + full target fingerprint: identical
+    targets under the same credential reuse the entry, and any target-field or
+    credential change separates it.
+    """
+    from ..target import target_fingerprint, validate_target
+
+    canonical = validate_target(target)
+    fingerprint = target_fingerprint(canonical)
+    refinements = _exact_refinement_key(ttl_seconds, run_id, scopes)
+    cache_key = _exact_ticket_cache_key(psk_token, fingerprint, refinements)
+
+    if refinements:
+        # Refinement identities are caller-controlled (run ids, TTLs) and carry
+        # per-run claims, so they are exchanged fresh instead of cached — the
+        # cache (and its lock map) stays bounded by credential × target. A
+        # ticket minted for one run can therefore never be served to another.
+        return await _exchange_exact_target(
+            psk_token,
+            canonical,
+            ttl_seconds=ttl_seconds,
+            run_id=run_id,
+            scopes=scopes,
+            timeout=timeout,
+        )
+
+    if force_refresh:
+        dominus_cache.delete(cache_key)
+    else:
+        cached = _cached_exact_ticket(cache_key)
+        if cached is not None:
+            return cached
+
+    async with _exact_ticket_lock_for(cache_key):
+        if not force_refresh:
+            cached = _cached_exact_ticket(cache_key)
+            if cached is not None:
+                return cached
+
+        record = await _exchange_exact_target(
+            psk_token,
+            canonical,
+            ttl_seconds=ttl_seconds,
+            run_id=run_id,
+            scopes=scopes,
+            timeout=timeout,
+        )
+        expires_at = _exact_ticket_expiry(record.ticket)
+        ttl = int(max(1, min(EXACT_TICKET_CACHE_TTL, expires_at - time.time())))
+        dominus_cache.set(
+            cache_key, {**record.to_mapping(), "expires_at": expires_at}, ttl=ttl
+        )
+        return record
+
+
 def verify_token_format(token: str) -> bool:
     """
     Verify token format is valid (basic check, not server verification).