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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 9.0.16
+Version: 9.1.0
 Summary: Python SDK for the Dominus gateway-first platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License-Expression: LicenseRef-Proprietary

{dominus_sdk_python-9.0.16 → 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.16"
+__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.16 → 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).

{dominus_sdk_python-9.0.16 → dominus_sdk_python-9.1.0}/dominus/start.py

@@ -93,12 +93,18 @@ class Dominus:
         gateway_org_id: Optional[str] = None,
         gateway_app_slug: Optional[str] = None,
         gateway_env: Optional[str] = None,
+        exact_target: Optional[Any] = None,
     ):
         """Initialize Dominus with flat API and minimal namespaces."""
         self._gateway_user_token = gateway_user_token
         self._gateway_org_id = gateway_org_id
         self._gateway_app_slug = gateway_app_slug
         self._gateway_env = gateway_env
+        # Default exact target for every project-scoped call; a per-call
+        # ``exact_target`` overrides it. None keeps the targetless legacy call.
+        self._default_exact_target: Optional[Any] = None
+        if exact_target is not None:
+            self.set_default_exact_target(exact_target)
 
         # Create internal execute function that handles validation
         async def _execute_command(command: str, **kwargs) -> Any:
@@ -238,6 +244,96 @@ class Dominus:
             verify_token_format(_TOKEN)
             _VALIDATED = True
 
+    # ========================================
+    # EXACT-TARGET TRANSPORT
+    # ========================================
+
+    def set_default_exact_target(self, exact_target: Optional[Any]) -> None:
+        """Set (or clear) the default exact target. ``None`` = targetless legacy."""
+        if exact_target is None:
+            self._default_exact_target = None
+            return
+        from .target import validate_target
+
+        self._default_exact_target = validate_target(exact_target)
+
+    async def mint_exact_target_ticket(
+        self,
+        target: Any,
+        *,
+        ttl_seconds: Optional[int] = None,
+        run_id: Optional[str] = None,
+        scopes: Optional[List[str]] = None,
+        force_refresh: bool = False,
+    ):
+        """Exchange one exact target for an atomic ticket record (cached)."""
+        await self._ensure_ready()
+        from .helpers.core import mint_exact_target_ticket as _mint
+
+        return await _mint(
+            _TOKEN,
+            target,
+            ttl_seconds=ttl_seconds,
+            run_id=run_id,
+            scopes=scopes,
+            force_refresh=force_refresh,
+        )
+
+    async def _resolve_exact_transport(
+        self,
+        exact_target: Optional[Any],
+        user_token: Optional[str] = None,
+    ) -> Optional[Any]:
+        """Resolve the atomic ``(ticket, target_header)`` pair, or None.
+
+        A caller-supplied ``user_token`` is already the ticket, so nothing is
+        exchanged — but the target must be named on this call (a client default
+        belongs to the service identity being exchanged, never to a caller's
+        bearer) and the bearer must prove it.
+        """
+        from .target import (
+            assert_ticket_proves_target,
+            target_fingerprint,
+            target_header_value,
+            validate_target,
+        )
+
+        if user_token:
+            if exact_target is None:
+                return None
+            canonical = validate_target(exact_target)
+            assert_ticket_proves_target(
+                user_token, target_fingerprint(canonical)
+            )
+            return user_token, target_header_value(canonical)
+
+        target = (
+            exact_target if exact_target is not None else self._default_exact_target
+        )
+        if target is None:
+            return None
+
+        # The exchange authenticates with the project PSK, so the exact path
+        # enforces the same token presence/format check as the targetless path.
+        await self._ensure_ready()
+        from .helpers.core import mint_exact_target_ticket
+
+        record = await mint_exact_target_ticket(_TOKEN, target)
+        return record.ticket, record.target_header
+
+    @staticmethod
+    def _apply_exact_pair(
+        headers: Dict[str, str], exact: Optional[Any]
+    ) -> None:
+        """Write the atomic pair last so no caller header can split it."""
+        if not exact:
+            return
+        from .target import TARGET_HEADER
+
+        ticket, target_header = exact
+        headers["Authorization"] = f"Bearer {ticket}"
+        headers[TARGET_HEADER] = target_header
+
     @staticmethod
     def _normalize_flat_schema(schema: Optional[str]) -> str:
         """Map legacy flat schema names onto the live gateway contract."""
@@ -351,6 +447,7 @@ class Dominus:
         timeout: float = 30.0,
         actor: Optional[Dict[str, str]] = None,
         extra_headers: Optional[Dict[str, str]] = None,
+        exact_target: Optional[Any] = None,
     ) -> Dict[str, Any]:
         """
         Make an HTTP request to the Dominus service plane.
@@ -380,7 +477,11 @@ class Dominus:
 
         # Determine which JWT to use (per-call user_token wins over MCP/session client defaults)
         effective_user_token = user_token or getattr(self, "_gateway_user_token", None)
-        if effective_user_token:
+        exact = await self._resolve_exact_transport(exact_target, effective_user_token)
+        if exact:
+            # The exchanged ticket IS the bearer; the header travels with it.
+            jwt = exact[0]
+        elif effective_user_token:
             # Use the provided user JWT directly; downstream services validate it.
             jwt = effective_user_token
         else:
@@ -424,6 +525,8 @@ class Dominus:
         if effective_actor and effective_actor.get("type") and effective_actor.get("id"):
             headers["X-Actor-Type"] = str(effective_actor["type"])
             headers["X-Actor-Id"] = str(effective_actor["id"])
+        # Atomic exact pair, written last: no caller header can split ticket/bytes.
+        self._apply_exact_pair(headers, exact)
 
         # Prepare body
         body_b64 = _b64_encode(body or {})
@@ -527,15 +630,20 @@ class Dominus:
         body: Optional[Dict[str, Any]] = None,
         headers: Optional[Dict[str, str]] = None,
         timeout: float = 30.0,
+        exact_target: Optional[Any] = None,
     ) -> Any:
         """Gateway `/svc/*` fetch with mixed JSON/base64 wire handling.
 
         Mirrors the Node SDK `DominusClient.gatewayFetch()` contract so Python
         callers can use the same remaining operator control-plane surfaces.
         """
-        await self._ensure_ready()
-        from .helpers.core import _ensure_valid_jwt
-        jwt = await _ensure_valid_jwt(_TOKEN, _BASE_URL)
+        exact = await self._resolve_exact_transport(exact_target)
+        if exact:
+            jwt = exact[0]
+        else:
+            await self._ensure_ready()
+            from .helpers.core import _ensure_valid_jwt
+            jwt = await _ensure_valid_jwt(_TOKEN, _BASE_URL)
 
         path = path.strip()
         if not path.startswith("/"):
@@ -568,6 +676,7 @@ class Dominus:
         }
         if headers:
             req_headers.update(headers)
+        self._apply_exact_pair(req_headers, exact)
 
         request_content = None
         request_json = None
@@ -655,7 +764,8 @@ class Dominus:
         body: Optional[Dict[str, Any]] = None,
         on_chunk: Optional[Any] = None,
         timeout: float = 300.0,
-        use_gateway: bool = True
+        use_gateway: bool = True,
+        exact_target: Optional[Any] = None,
     ):
         """
         Make an SSE streaming request to the Dominus service plane.
@@ -679,9 +789,13 @@ class Dominus:
             endpoint = "/svc/" + endpoint[5:]
 
         # Validate and get JWT
-        await self._ensure_ready()
-        from .helpers.core import _ensure_valid_jwt
-        jwt = await _ensure_valid_jwt(_TOKEN, _BASE_URL)
+        exact = await self._resolve_exact_transport(exact_target)
+        if exact:
+            jwt = exact[0]
+        else:
+            await self._ensure_ready()
+            from .helpers.core import _ensure_valid_jwt
+            jwt = await _ensure_valid_jwt(_TOKEN, _BASE_URL)
 
         from .helpers.trace import get_current_trace_id, get_current_span_id
         headers = {
@@ -691,6 +805,7 @@ class Dominus:
             "X-Trace-Id": get_current_trace_id(),
             "X-Parent-Span-Id": get_current_span_id(),
         }
+        self._apply_exact_pair(headers, exact)
 
         body_b64 = _b64_encode(body or {})
 
@@ -711,7 +826,8 @@ class Dominus:
         content_type: str = "application/octet-stream",
         additional_fields: Optional[Dict[str, str]] = None,
         timeout: float = 60.0,
-        use_gateway: bool = True
+        use_gateway: bool = True,
+        exact_target: Optional[Any] = None,
     ) -> Dict[str, Any]:
         """
         Upload binary file via multipart/form-data (no base64 encoding).
@@ -734,9 +850,13 @@ class Dominus:
         if use_gateway and endpoint.startswith("/api/"):
             endpoint = "/svc/" + endpoint[5:]
 
-        await self._ensure_ready()
-        from .helpers.core import _ensure_valid_jwt
-        jwt = await _ensure_valid_jwt(_TOKEN, _BASE_URL)
+        exact = await self._resolve_exact_transport(exact_target)
+        if exact:
+            jwt = exact[0]
+        else:
+            await self._ensure_ready()
+            from .helpers.core import _ensure_valid_jwt
+            jwt = await _ensure_valid_jwt(_TOKEN, _BASE_URL)
 
         from .helpers.trace import get_current_trace_id, get_current_span_id
         headers = {
@@ -744,6 +864,7 @@ class Dominus:
             "X-Trace-Id": get_current_trace_id(),
             "X-Parent-Span-Id": get_current_span_id(),
         }
+        self._apply_exact_pair(headers, exact)
 
         # Build multipart form data
         files = {"file": (filename, file_bytes, content_type)}
@@ -770,7 +891,8 @@ class Dominus:
         endpoint: str,
         body: Optional[Dict[str, Any]] = None,
         timeout: float = 60.0,
-        use_gateway: bool = True
+        use_gateway: bool = True,
+        exact_target: Optional[Any] = None,
     ) -> bytes:
         """
         Download binary content (no base64 encoding in response).
@@ -793,9 +915,13 @@ class Dominus:
         if use_gateway and endpoint.startswith("/api/"):
             endpoint = "/svc/" + endpoint[5:]
 
-        await self._ensure_ready()
-        from .helpers.core import _ensure_valid_jwt
-        jwt = await _ensure_valid_jwt(_TOKEN, _BASE_URL)
+        exact = await self._resolve_exact_transport(exact_target)
+        if exact:
+            jwt = exact[0]
+        else:
+            await self._ensure_ready()
+            from .helpers.core import _ensure_valid_jwt
+            jwt = await _ensure_valid_jwt(_TOKEN, _BASE_URL)
 
         from .helpers.trace import get_current_trace_id, get_current_span_id
         headers = {
@@ -805,6 +931,7 @@ class Dominus:
             "X-Trace-Id": get_current_trace_id(),
             "X-Parent-Span-Id": get_current_span_id(),
         }
+        self._apply_exact_pair(headers, exact)
 
         body_b64 = _b64_encode(body or {})