dominus-sdk-python 2.7.1__tar.gz → 2.8.0__tar.gz

{dominus_sdk_python-2.7.1 → dominus_sdk_python-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 2.7.1
+Version: 2.8.0
 Summary: Python SDK for the Dominus Orchestrator Platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License: Proprietary

{dominus_sdk_python-2.7.1 → dominus_sdk_python-2.8.0}/dominus/__init__.py

@@ -126,6 +126,12 @@ from .helpers.cache import (
     exponential_backoff_with_jitter,
 )
 
+# Export JWT verification utilities
+from .helpers.core import (
+    verify_jwt_locally,
+    is_jwt_valid,
+)
+
 # Export error classes
 from .errors import (
     DominusError,
@@ -140,7 +146,7 @@ from .errors import (
     TimeoutError as DominusTimeoutError,
 )
 
-__version__ = "2.7.1"
+__version__ = "2.8.0"
 __all__ = [
     # Main SDK instance
     "dominus",
@@ -186,6 +192,9 @@ __all__ = [
     "DominusCache",
     "orchestrator_circuit_breaker",
     "exponential_backoff_with_jitter",
+    # JWT verification utilities
+    "verify_jwt_locally",
+    "is_jwt_valid",
     # Error classes
     "DominusError",
     "AuthenticationError",

{dominus_sdk_python-2.7.1 → dominus_sdk_python-2.8.0}/dominus/helpers/core.py

@@ -41,10 +41,10 @@ def _b64url_decode(s: str) -> bytes:
 def _decode_jwt_payload(jwt: str) -> dict:
     """
     Decode JWT payload without verification (for exp checks only).
-    
+
     Args:
         jwt: JWT token string
-        
+
     Returns:
         Decoded payload dict
     """
@@ -59,6 +59,259 @@ def _decode_jwt_payload(jwt: str) -> dict:
         raise ValueError(f"Failed to decode JWT payload: {e}")
 
 
+def _decode_jwt_header(jwt: str) -> dict:
+    """
+    Decode JWT header without verification.
+
+    Args:
+        jwt: JWT token string
+
+    Returns:
+        Decoded header dict (contains alg, kid, typ)
+    """
+    try:
+        parts = jwt.split('.')
+        if len(parts) != 3:
+            raise ValueError("Invalid JWT format")
+        header_b64url = parts[0]
+        header_bytes = _b64url_decode(header_b64url)
+        return json.loads(header_bytes.decode('utf-8'))
+    except Exception as e:
+        raise ValueError(f"Failed to decode JWT header: {e}")
+
+
+# ============================================
+# JWKS and Local JWT Verification
+# ============================================
+
+# JWKS cache
+_cached_jwks: Optional[dict] = None
+_jwks_cache_time: float = 0
+_JWKS_CACHE_TTL = 3600  # 1 hour in seconds
+
+
+async def _fetch_jwks() -> dict:
+    """
+    Fetch JWKS from gateway.
+
+    Returns:
+        JWKS dict with 'keys' array
+    """
+    global _cached_jwks, _jwks_cache_time
+
+    # Check cache first
+    if _cached_jwks and time.time() - _jwks_cache_time < _JWKS_CACHE_TTL:
+        return _cached_jwks
+
+    from ..config.endpoints import get_gateway_url
+    gateway_url = get_gateway_url()
+
+    try:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            response = await client.get(f"{gateway_url}/jwt/jwks")
+            response.raise_for_status()
+
+            # Response is base64 encoded
+            result = _b64_decode(response.text)
+
+            # Handle wrapped response or direct JWKS
+            if isinstance(result, dict):
+                if result.get("data", {}).get("keys"):
+                    jwks = result["data"]
+                elif result.get("keys"):
+                    jwks = result
+                else:
+                    raise ValueError("Invalid JWKS response format")
+            else:
+                raise ValueError("Invalid JWKS response format")
+
+            _cached_jwks = jwks
+            _jwks_cache_time = time.time()
+            return jwks
+
+    except Exception as e:
+        # If fetch fails but we have cached JWKS, use it (stale is better than nothing)
+        if _cached_jwks:
+            return _cached_jwks
+        raise RuntimeError(f"Failed to fetch JWKS: {e}")
+
+
+def _jwk_to_rsa_public_key(jwk: dict):
+    """
+    Convert JWK to RSA public key for verification.
+
+    Args:
+        jwk: JWK dict with n, e components
+
+    Returns:
+        RSA public key object
+    """
+    from cryptography.hazmat.primitives.asymmetric import rsa
+    from cryptography.hazmat.backends import default_backend
+
+    # Decode n and e from base64url
+    n_bytes = _b64url_decode(jwk["n"])
+    e_bytes = _b64url_decode(jwk["e"])
+
+    # Convert to integers
+    n = int.from_bytes(n_bytes, byteorder='big')
+    e = int.from_bytes(e_bytes, byteorder='big')
+
+    # Create RSA public numbers and derive public key
+    public_numbers = rsa.RSAPublicNumbers(e, n)
+    return public_numbers.public_key(default_backend())
+
+
+async def verify_jwt_signature(jwt_token: str) -> dict:
+    """
+    Verify JWT signature locally using JWKS.
+
+    Args:
+        jwt_token: The JWT token to verify
+
+    Returns:
+        The decoded payload if valid
+
+    Raises:
+        RuntimeError: If verification fails
+    """
+    global _cached_jwks
+
+    from cryptography.hazmat.primitives import hashes
+    from cryptography.hazmat.primitives.asymmetric import padding
+    from cryptography.exceptions import InvalidSignature
+
+    parts = jwt_token.split('.')
+    if len(parts) != 3:
+        raise RuntimeError("Invalid JWT format")
+
+    header_b64, payload_b64, signature_b64 = parts
+
+    # Decode header to get kid
+    header = _decode_jwt_header(jwt_token)
+
+    # Verify algorithm
+    if header.get("alg") != "RS256":
+        raise RuntimeError(f"Unsupported JWT algorithm: {header.get('alg')}")
+
+    # Fetch JWKS and find the key
+    jwks = await _fetch_jwks()
+    kid = header.get("kid")
+
+    key = None
+    if kid:
+        for k in jwks.get("keys", []):
+            if k.get("kid") == kid:
+                key = k
+                break
+    else:
+        # Use first key if no kid
+        keys = jwks.get("keys", [])
+        if keys:
+            key = keys[0]
+
+    if not key:
+        # Key not found - refresh JWKS and try again
+        _cached_jwks = None
+        jwks = await _fetch_jwks()
+
+        if kid:
+            for k in jwks.get("keys", []):
+                if k.get("kid") == kid:
+                    key = k
+                    break
+        else:
+            keys = jwks.get("keys", [])
+            if keys:
+                key = keys[0]
+
+        if not key:
+            raise RuntimeError(f"JWT signing key not found: {kid}")
+
+    # Import the public key
+    public_key = _jwk_to_rsa_public_key(key)
+
+    # Verify signature
+    signature_input = f"{header_b64}.{payload_b64}".encode('utf-8')
+    signature = _b64url_decode(signature_b64)
+
+    try:
+        public_key.verify(
+            signature,
+            signature_input,
+            padding.PKCS1v15(),
+            hashes.SHA256()
+        )
+    except InvalidSignature:
+        raise RuntimeError("JWT signature verification failed")
+
+    # Decode and return payload
+    return _decode_jwt_payload(jwt_token)
+
+
+async def verify_jwt_locally(jwt_token: str) -> dict:
+    """
+    Verify JWT locally: signature + claims.
+
+    Performs full local verification:
+    1. Signature verification using JWKS
+    2. Expiry check (exp claim)
+    3. Not-before check (nbf claim if present)
+    4. Issued-at sanity check (iat claim)
+
+    Args:
+        jwt_token: The JWT token to verify
+
+    Returns:
+        The decoded payload if valid
+
+    Raises:
+        RuntimeError: If verification fails
+    """
+    # Verify signature
+    payload = await verify_jwt_signature(jwt_token)
+
+    now = int(time.time())
+
+    # Check expiry
+    if payload.get("exp") and payload["exp"] < now:
+        raise RuntimeError("JWT has expired")
+
+    # Check not-before
+    if payload.get("nbf") and payload["nbf"] > now:
+        raise RuntimeError("JWT not yet valid")
+
+    # Sanity check issued-at (not more than 24 hours in the future)
+    if payload.get("iat") and payload["iat"] > now + 86400:
+        raise RuntimeError("JWT issued-at is in the future")
+
+    return payload
+
+
+def is_jwt_valid(jwt_token: str) -> bool:
+    """
+    Quick local JWT validation (expiry only, no signature verification).
+    Use this for fast checks before making API calls.
+
+    Args:
+        jwt_token: The JWT token to check
+
+    Returns:
+        True if token appears valid (not expired), False otherwise
+    """
+    try:
+        payload = _decode_jwt_payload(jwt_token)
+        now = int(time.time())
+
+        # Check if expired (with 60 second buffer)
+        if payload.get("exp") and payload["exp"] < now - 60:
+            return False
+
+        return True
+    except Exception:
+        return False
+
+
 async def _get_service_jwt(psk_token: str, base_url: str) -> str:
     """
     Get service JWT by calling gateway /jwt/mint with PSK.

{dominus_sdk_python-2.7.1 → dominus_sdk_python-2.8.0}/dominus/namespaces/ai.py

@@ -211,7 +211,11 @@ class RagSubNamespace(GatewayMixin):
         slug: str,
         identifier: str,
         content: str,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
         category: Optional[str] = None,
+        subcategory: Optional[str] = None,
+        source_reference: Optional[Dict[str, Any]] = None,
         metadata: Optional[Dict[str, Any]] = None
     ) -> Dict[str, Any]:
         """
@@ -220,13 +224,25 @@ class RagSubNamespace(GatewayMixin):
         Args:
             slug: Corpus identifier
             identifier: Entry identifier (unique within corpus)
-            content: Text content to embed
+            content: Text content to embed (stored as content_markdown)
+            name: Optional human-readable name
+            description: Optional brief description
             category: Optional category for filtering
+            subcategory: Optional subcategory
+            source_reference: Optional source attribution
             metadata: Optional metadata dict
         """
-        body: Dict[str, Any] = {"content": content}
+        body: Dict[str, Any] = {"content_markdown": content}
+        if name:
+            body["name"] = name
+        if description:
+            body["description"] = description
         if category:
             body["category"] = category
+        if subcategory:
+            body["subcategory"] = subcategory
+        if source_reference:
+            body["source_reference"] = source_reference
         if metadata:
             body["metadata"] = metadata
 
@@ -260,11 +276,30 @@ class RagSubNamespace(GatewayMixin):
 
         Args:
             slug: Corpus identifier
-            entries: List of {"identifier", "content", "category", "metadata"} dicts
+            entries: List of entry dicts with:
+                - identifier: string (required)
+                - content: string (required) - Will be sent as content_markdown
+                - name: string (optional)
+                - description: string (optional)
+                - category: string (optional)
+                - subcategory: string (optional)
+                - source_reference: dict (optional)
+                - metadata: dict (optional)
+
+        Returns:
+            Dict with "processed", "failed", "errors" counts
         """
+        # Transform 'content' to 'content_markdown' for API compatibility
+        transformed = []
+        for entry in entries:
+            e = dict(entry)
+            if "content" in e and "content_markdown" not in e:
+                e["content_markdown"] = e.pop("content")
+            transformed.append(e)
+
         return await self._api(
             endpoint=f"/api/rag/{slug}/bulk",
-            body={"entries": entries}
+            body={"entries": transformed}
         )
 
     async def search(
@@ -390,16 +425,12 @@ class ArtifactsSubNamespace(GatewayMixin):
     async def get(
         self,
         artifact_id: str,
-        conversation_id: Optional[str] = None
+        conversation_id: str
     ) -> Dict[str, Any]:
         """Get artifact by ID."""
-        body: Dict[str, Any] = {"artifact_id": artifact_id}
-        if conversation_id:
-            body["conversation_id"] = conversation_id
-
         return await self._api(
-            endpoint=f"/api/agent/artifacts/{artifact_id}",
-            body=body
+            endpoint=f"/api/agent/artifacts/{artifact_id}?conversation_id={conversation_id}",
+            method="GET"
         )
 
     async def create(
@@ -407,27 +438,28 @@ class ArtifactsSubNamespace(GatewayMixin):
         name: str,
         content: str,
         conversation_id: str,
-        artifact_type: str = "text",
+        artifact_type: str = "text/plain",
+        is_base64: bool = False,
         metadata: Optional[Dict[str, Any]] = None
     ) -> Dict[str, Any]:
         """
         Create a new artifact.
 
         Args:
-            name: Artifact name/filename
-            content: Artifact content (text or base64 for binary)
+            name: Artifact key/filename
+            content: Artifact content (text or base64-encoded for binary)
             conversation_id: Associated conversation ID
-            artifact_type: Type of artifact (text, code, image, etc.)
-            metadata: Optional metadata dict
+            artifact_type: MIME content type (e.g., "text/plain", "text/html", "image/png")
+            is_base64: If True, content is base64-encoded binary
+            metadata: Optional metadata dict (not stored, for SDK use)
         """
         body: Dict[str, Any] = {
-            "name": name,
+            "key": name,
             "content": content,
             "conversation_id": conversation_id,
-            "type": artifact_type
+            "content_type": artifact_type,
+            "is_base64": is_base64
         }
-        if metadata:
-            body["metadata"] = metadata
 
         return await self._api(
             endpoint="/api/agent/artifacts",
@@ -436,38 +468,24 @@ class ArtifactsSubNamespace(GatewayMixin):
 
     async def list(
         self,
-        conversation_id: str,
-        limit: int = 100,
-        offset: int = 0
+        conversation_id: str
     ) -> List[Dict[str, Any]]:
         """List artifacts for a conversation."""
-        body: Dict[str, Any] = {
-            "conversation_id": conversation_id,
-            "limit": limit,
-            "offset": offset
-        }
-
         result = await self._api(
-            endpoint="/api/agent/artifacts",
-            method="GET",
-            body=body
+            endpoint=f"/api/agent/artifacts?conversation_id={conversation_id}",
+            method="GET"
         )
         return result.get("artifacts", result) if isinstance(result, dict) else result
 
     async def delete(
         self,
         artifact_id: str,
-        conversation_id: Optional[str] = None
+        conversation_id: str
     ) -> Dict[str, Any]:
         """Delete an artifact."""
-        body: Dict[str, Any] = {}
-        if conversation_id:
-            body["conversation_id"] = conversation_id
-
         return await self._api(
-            endpoint=f"/api/agent/artifacts/{artifact_id}",
-            method="DELETE",
-            body=body if body else None
+            endpoint=f"/api/agent/artifacts/{artifact_id}?conversation_id={conversation_id}",
+            method="DELETE"
         )
 
 
@@ -900,10 +918,10 @@ class AiNamespace(GatewayMixin):
             List of history messages
         """
         result = await self._api(
-            endpoint=f"/api/agent/history/{conversation_id}",
-            body={"limit": limit}
+            endpoint=f"/api/agent/history/{conversation_id}?limit={limit}",
+            method="GET"
         )
-        return result.get("history", result) if isinstance(result, dict) else result
+        return result.get("messages", result) if isinstance(result, dict) else result
 
     # ========================================
     # LLM Completions

{dominus_sdk_python-2.7.1 → dominus_sdk_python-2.8.0}/dominus_sdk_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 2.7.1
+Version: 2.8.0
 Summary: Python SDK for the Dominus Orchestrator Platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License: Proprietary

{dominus_sdk_python-2.7.1 → dominus_sdk_python-2.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dominus-sdk-python"
-version = "2.7.1"
+version = "2.8.0"
 description = "Python SDK for the Dominus Orchestrator Platform"
 readme = "README.md"
 license = {text = "Proprietary"}