volidator-python 0.1.0__py3-none-any.whl

volidator/client.py

@@ -0,0 +1,1129 @@
+import asyncio
+import base64
+import contextlib
+import contextvars
+import json
+import hashlib
+import os
+import re
+import time
+import urllib.request
+import urllib.error
+import urllib.parse
+import threading
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+try:
+    import httpx
+    HAS_HTTPX = True
+except ImportError:
+    httpx = None
+    HAS_HTTPX = False
+
+# Global thread pool executor for urllib async fallbacks
+import concurrent.futures
+_executor = concurrent.futures.ThreadPoolExecutor(max_workers=10)
+
+# Context variables for trace propagation and logical clocks
+agent_context_store = contextvars.ContextVar("agent_context_store", default=None)
+logical_clock_store = contextvars.ContextVar("logical_clock_store", default=None)
+
+
+class VolidatorClient:
+    def __init__(
+        self,
+        api_key: str,
+        encryption_key: Optional[str] = None,
+        keyring: Optional[dict[str, str]] = None,
+        active_encryption_key_id: Optional[str] = None,
+        endpoint: str = "https://ingestion.volidator.com",
+        project_id: Optional[str] = None,
+        client_secret: Optional[str] = None,
+        telemetry: Optional[dict[str, Any]] = None,
+        redact_keys: Optional[list[str]] = None,
+        reference_keys: Optional[list[str]] = None,
+        max_metadata_size: int = 10240,
+        max_retries: int = 3,
+        on_delivery_failure: Optional[Callable[[dict[str, Any], Exception], None]] = None,
+    ):
+        self.api_key = api_key
+        self.endpoint = endpoint.rstrip("/")
+        self.project_id = project_id
+        self.client_secret = client_secret
+        self.redact_keys = redact_keys or []
+        self.reference_keys = reference_keys or []
+        self.max_metadata_size = max_metadata_size
+        self.max_retries = max_retries
+        self.on_delivery_failure = on_delivery_failure
+        self._fallback_logical_clock = 0
+
+        # Set up keyring
+        if keyring and active_encryption_key_id:
+            self.keyring = keyring
+            self.active_key_id = active_encryption_key_id
+        elif encryption_key:
+            self.active_key_id = "v1"
+            self.keyring = {"v1": encryption_key}
+        else:
+            raise ValueError(
+                "Either encryption_key OR (keyring AND active_encryption_key_id) must be provided in VolidatorClient constructor."
+            )
+
+        if len(self.keyring) > 5:
+            raise ValueError("Keyring size cannot exceed 5 keys.")
+
+        if self.active_key_id not in self.keyring:
+            raise ValueError(f"Active key ID '{self.active_key_id}' must exist in the keyring.")
+
+        self._hashed_keyring = {}
+        
+        # Telemetry config resolution
+        telemetry = telemetry or {"preset": "standard"}
+        self.telemetry_config = self._resolve_telemetry_config(telemetry)
+
+        # Lazy HTTPX Client for async
+        self._httpx_client = None
+
+        # API Sub-namespaces
+        from .compliance import VolidatorCompliance
+        from .agent import VolidatorAgent
+        self.compliance = VolidatorCompliance(self)
+        self.agent = VolidatorAgent(self)
+
+    async def _get_httpx_client(self):
+        if self._httpx_client is None and HAS_HTTPX:
+            self._httpx_client = httpx.AsyncClient(timeout=10.0)
+        return self._httpx_client
+
+    async def close(self):
+        if self._httpx_client is not None:
+            await self._httpx_client.aclose()
+            self._httpx_client = None
+
+    def _resolve_telemetry_config(self, config: dict[str, Any]) -> dict[str, Any]:
+        preset = config.get("preset", "standard")
+        ip = "anonymize"
+        user_agent = "parse"
+        location = True
+
+        if preset == "strict":
+            ip = "skip"
+            user_agent = "skip"
+            location = False
+        elif preset == "full":
+            ip = "track"
+            user_agent = "track"
+            location = True
+
+        if "ip" in config:
+            ip = config["ip"]
+        if "userAgent" in config:
+            user_agent = config["userAgent"]
+        if "location" in config:
+            location = config["location"]
+
+        return {"ip": ip, "userAgent": user_agent, "location": location}
+
+    @contextlib.contextmanager
+    def run_in_agent_context(self, context: dict[str, Any]):
+        token = agent_context_store.set(context)
+        try:
+            yield
+        finally:
+            agent_context_store.reset(token)
+
+    @contextlib.contextmanager
+    def trace_from_langchain(self, config: Optional[dict[str, Any]]):
+        run_id = str(config.get("run_id", "")) if config else ""
+        configurable = config.get("configurable") or {} if config else {}
+        thread_id = str(configurable.get("thread_id", ""))
+        
+        trace_id = run_id or thread_id or None
+        ctx = {}
+        if trace_id:
+            ctx["traceId"] = trace_id
+            
+        token = agent_context_store.set(ctx)
+        try:
+            yield
+        finally:
+            agent_context_store.reset(token)
+
+    @contextlib.contextmanager
+    def run_in_clock_context(self, initial_clock: int = 0):
+        token = logical_clock_store.set({"clock": initial_clock})
+        try:
+            yield
+        finally:
+            logical_clock_store.reset(token)
+
+    def get_and_increment_clock(self, incoming_clock: Optional[int] = None) -> int:
+        store = logical_clock_store.get()
+        if store is not None:
+            store["clock"] = max(store.get("clock", 0), incoming_clock or 0) + 1
+            return store["clock"]
+        
+        self._fallback_logical_clock = max(self._fallback_logical_clock, incoming_clock or 0) + 1
+        return self._fallback_logical_clock
+
+    def _get_hashed_key(self, key_id: str) -> bytes:
+        if key_id in self._hashed_keyring:
+            return self._hashed_keyring[key_id]
+        raw_key = self.keyring[key_id]
+        hashed = hashlib.sha256(raw_key.encode("utf-8")).digest()
+        self._hashed_keyring[key_id] = hashed
+        return hashed
+
+    def generate_blind_index(self, value: str, key_buffer: bytes) -> str:
+        import hmac
+        sig = hmac.digest(key_buffer, value.encode("utf-8"), "sha256")
+        return sig.hex()
+
+    def encrypt_payload(self, payload: dict[str, Any]) -> str:
+        text = json.dumps(payload, separators=(",", ":"))
+        iv = os.urandom(12)
+        active_hashed_key = self._get_hashed_key(self.active_key_id)
+        aesgcm = AESGCM(active_hashed_key)
+        encrypted_data = aesgcm.encrypt(iv, text.encode("utf-8"), None)
+        final_buf = iv + encrypted_data
+        base64_str = base64.b64encode(final_buf).decode("utf-8")
+        return f"{self.active_key_id}:{base64_str}"
+
+    def decrypt_payload(self, encrypted_str: str) -> dict[str, Any]:
+        if ":" not in encrypted_str:
+            raise ValueError("Invalid encrypted payload format")
+        key_id, base64_data = encrypted_str.split(":", 1)
+        if key_id not in self.keyring:
+            raise ValueError(f"Decryption key '{key_id}' not found in keyring")
+        hashed_key = self._get_hashed_key(key_id)
+        final_buf = base64.b64decode(base64_data)
+        if len(final_buf) < 28:
+            raise ValueError("Encrypted data is too short")
+        iv = final_buf[:12]
+        encrypted_data = final_buf[12:]
+        aesgcm = AESGCM(hashed_key)
+        decrypted_bytes = aesgcm.decrypt(iv, encrypted_data, None)
+        return json.loads(decrypted_bytes.decode("utf-8"))
+
+    def _parse_user_agent(self, ua: str) -> dict[str, str]:
+        browser = "Unknown Browser"
+        os_name = "Unknown OS"
+        device_type = "Desktop"
+
+        if not ua:
+            return {"browser": browser, "os": os_name, "type": device_type}
+
+        if re.search(r"Volidator-Ingest-Worker", ua, re.IGNORECASE):
+            return {
+                "browser": "Volidator Ingest Worker",
+                "os": "Linux Server",
+                "type": "Server",
+            }
+
+        if re.search(r"mobile", ua, re.IGNORECASE):
+            device_type = "Mobile"
+        elif re.search(r"tablet|ipad", ua, re.IGNORECASE):
+            device_type = "Tablet"
+        elif re.search(r"server|bot", ua, re.IGNORECASE):
+            device_type = "Server"
+
+        if re.search(r"chrome|crios", ua, re.IGNORECASE) and not re.search(r"edge|edg", ua, re.IGNORECASE) and not re.search(r"opr", ua, re.IGNORECASE):
+            match = re.search(r"(?:chrome|crios)\/([0-9.]+)", ua, re.IGNORECASE)
+            browser_ver = match.group(1).split(".")[0] if match else ""
+            browser = f"Chrome {browser_ver}".strip()
+        elif re.search(r"safari", ua, re.IGNORECASE) and not re.search(r"chrome|crios", ua, re.IGNORECASE) and not re.search(r"android", ua, re.IGNORECASE):
+            browser = "Safari Mobile" if re.search(r"mobile", ua, re.IGNORECASE) else "Safari"
+        elif re.search(r"firefox|fxios", ua, re.IGNORECASE):
+            browser = "Firefox"
+        elif re.search(r"edge|edg", ua, re.IGNORECASE):
+            browser = "Edge"
+
+        if re.search(r"windows", ua, re.IGNORECASE):
+            os_name = "Windows"
+        elif re.search(r"macintosh|mac os x", ua, re.IGNORECASE):
+            os_name = "macOS"
+        elif re.search(r"iphone|ipad|ipod", ua, re.IGNORECASE):
+            os_name = "iOS"
+        elif re.search(r"android", ua, re.IGNORECASE):
+            os_name = "Android"
+        elif re.search(r"linux", ua, re.IGNORECASE):
+            os_name = "Linux"
+
+        return {"browser": browser, "os": os_name, "type": device_type}
+
+    def _extract_context(self, req: Any) -> dict[str, Any]:
+        if not req:
+            return {}
+
+        headers = {}
+        if hasattr(req, "headers"):
+            # Check if headers has a get method (FastAPI/Flask-like)
+            headers = req.headers
+        elif hasattr(req, "META") and isinstance(req.META, dict):
+            # Django META
+            headers = {
+                k.replace("HTTP_", "").replace("_", "-").lower(): v
+                for k, v in req.META.items()
+            }
+            if "CONTENT_TYPE" in req.META:
+                headers["content-type"] = req.META["CONTENT_TYPE"]
+            if "CONTENT_LENGTH" in req.META:
+                headers["content-length"] = req.META["CONTENT_LENGTH"]
+            if "REMOTE_ADDR" in req.META:
+                headers["remote-addr"] = req.META["REMOTE_ADDR"]
+        elif isinstance(req, dict):
+            headers = req
+
+        def get_header(name: str) -> str:
+            if hasattr(headers, "get"):
+                return headers.get(name) or headers.get(name.lower()) or ""
+            try:
+                return headers[name] or headers[name.lower()] or ""
+            except (KeyError, TypeError):
+                return ""
+
+        cf_ip = get_header("cf-connecting-ip")
+        x_real_ip = get_header("x-real-ip")
+        x_forwarded = get_header("x-forwarded-for")
+        
+        raw_ip = cf_ip or x_real_ip or x_forwarded
+        ip = ""
+        if raw_ip:
+            ip = raw_ip.split(",")[0].strip()
+        else:
+            if hasattr(req, "remote_addr"):
+                ip = req.remote_addr or ""
+            elif "remote-addr" in headers:
+                ip = headers["remote-addr"]
+                
+        ua = get_header("user-agent")
+
+        return {
+            "ip": ip,
+            "userAgent": ua,
+            "location": {
+                "country": get_header("cf-ipcountry") or get_header("x-vercel-ip-country") or "",
+                "region": get_header("cf-region-code") or get_header("x-vercel-ip-country-region") or "",
+                "city": get_header("cf-ipcity") or get_header("x-vercel-ip-city") or "",
+            }
+        }
+
+    def _extract_trace_context(self, req: Any) -> dict[str, Any]:
+        if not req:
+            return {}
+
+        headers = {}
+        if hasattr(req, "headers"):
+            headers = req.headers
+        elif hasattr(req, "META") and isinstance(req.META, dict):
+            headers = {
+                k.replace("HTTP_", "").replace("_", "-").lower(): v
+                for k, v in req.META.items()
+            }
+        elif isinstance(req, dict):
+            headers = req
+
+        def get_header(name: str) -> str:
+            if hasattr(headers, "get"):
+                return headers.get(name) or headers.get(name.lower()) or ""
+            try:
+                return headers[name] or headers[name.lower()] or ""
+            except (KeyError, TypeError):
+                return ""
+
+        result = {}
+        clock_val = get_header("x-volidator-clock")
+        if clock_val:
+            try:
+                result["logicalClock"] = int(clock_val)
+            except ValueError:
+                pass
+
+        traceparent = get_header("traceparent")
+        if traceparent:
+            parts = traceparent.split("-")
+            if len(parts) == 4:
+                result["traceId"] = parts[1]
+                result["spanId"] = parts[2]
+
+        return result
+
+    def _prepare_log_entry_common(self, payload: dict[str, Any], max_meta_override: Optional[int] = None) -> tuple[dict[str, Any], dict[str, Any], str, str, str, str, Optional[str]]:
+        metadata = payload.get("metadata") or {}
+        payload_size = len(json.dumps(metadata, separators=(",", ":")).encode("utf-8"))
+
+        if payload_size > 5 * 1024 * 1024:
+            raise ValueError(
+                f"Volidator SDK Error: Audit log payload exceeds the 5MB hard limit ({payload_size} bytes)."
+            )
+
+        actor_raw = payload.get("actor") or payload.get("actorId") or "unknown"
+        target_raw = payload.get("target") or payload.get("targetId") or "unknown"
+        tenant_raw = payload.get("tenant") or payload.get("tenantId") or ""
+        action = payload.get("action", "unknown")
+
+        def truncate(s: str, max_len: int) -> str:
+            return s[:max_len] + "..." if len(s) > max_len else s
+
+        def extract_pii(v: Any) -> str:
+            if isinstance(v, dict) and "pii" in v:
+                return v["pii"]
+            if hasattr(v, "pii"):
+                return getattr(v, "pii")
+            return str(v)
+
+        def extract_id(v: Any) -> str:
+            if isinstance(v, dict) and "id" in v:
+                return v["id"]
+            if hasattr(v, "id"):
+                return getattr(v, "id")
+            return str(v)
+
+        actor_plain = truncate(extract_pii(actor_raw), 255)
+        target_plain = truncate(extract_pii(target_raw), 255)
+        tenant_plain = truncate(extract_pii(tenant_raw), 255) if tenant_raw else ""
+        action_plain = truncate(action, 255)
+
+        log_telemetry = self.telemetry_config
+        if "telemetry" in payload:
+            log_telemetry = self._resolve_telemetry_config({**self.telemetry_config, **payload["telemetry"]})
+
+        payload_ctx = payload.get("context") or {}
+        if payload.get("req"):
+            extracted = self._extract_context(payload["req"])
+            payload_ctx = {
+                **extracted,
+                **payload_ctx,
+                "location": {
+                    **extracted.get("location", {}),
+                    **payload_ctx.get("location", {}),
+                },
+                "device": {
+                    **extracted.get("device", {}),
+                    **payload_ctx.get("device", {}),
+                }
+            }
+
+        context = {}
+        raw_ip = payload_ctx.get("ip") or ""
+        raw_ua = payload_ctx.get("userAgent") or ""
+
+        if log_telemetry.get("location"):
+            context["location"] = {}
+            if payload_ctx.get("location"):
+                context["location"]["country"] = payload_ctx["location"].get("country") or ""
+                context["location"]["region"] = payload_ctx["location"].get("region") or ""
+                is_full = (
+                    payload.get("telemetry", {}).get("preset") == "full" or
+                    (not payload.get("telemetry") and self.telemetry_config.get("ip") == "track")
+                )
+                if log_telemetry.get("ip") == "track" or is_full:
+                    context["location"]["city"] = payload_ctx["location"].get("city") or ""
+
+        active_hashed_key = self._get_hashed_key(self.active_key_id)
+        if log_telemetry.get("ip") == "anonymize" and raw_ip:
+            context["ip"] = self.generate_blind_index(raw_ip, active_hashed_key)
+        elif log_telemetry.get("ip") == "track" and raw_ip:
+            context["ip"] = raw_ip
+
+        if log_telemetry.get("userAgent") != "skip":
+            if raw_ua:
+                context["device"] = self._parse_user_agent(raw_ua)
+                if log_telemetry.get("userAgent") == "track":
+                    context["userAgent"] = truncate(raw_ua, 1000)
+            elif payload_ctx.get("device"):
+                context["device"] = payload_ctx["device"]
+
+        def scrub(val: str, key: str) -> str:
+            return f"[REDACTED:{key}]" if key in self.redact_keys else val
+
+        def apply_ref(raw_val: Any, key: str) -> str:
+            if key in self.reference_keys:
+                ref_id = extract_id(raw_val)
+                return f"[REF:{ref_id}]"
+            return scrub(extract_pii(raw_val), key)
+
+        safe_metadata = {}
+        for k, v in metadata.items():
+            meta_key = f"metadata.{k}"
+            if meta_key in self.reference_keys and isinstance(v, dict) and "id" in v:
+                safe_metadata[k] = f"[REF:{v['id']}]"
+            elif meta_key in self.redact_keys and isinstance(v, str):
+                safe_metadata[k] = f"[REDACTED:{k}]"
+            else:
+                safe_metadata[k] = v
+
+        did_truncate_depth = False
+        did_truncate_string = False
+
+        def limit_depth(obj, current_depth=1):
+            nonlocal did_truncate_depth, did_truncate_string
+            if current_depth > 5:
+                did_truncate_depth = True
+                return "[Truncated - Depth Exceeded]"
+            if obj is None:
+                return None
+            if isinstance(obj, str):
+                truncated_val = truncate(obj, 1000)
+                if len(truncated_val) != len(obj):
+                    did_truncate_string = True
+                return truncated_val
+            if isinstance(obj, (int, float, bool)):
+                return obj
+            if isinstance(obj, list):
+                return [limit_depth(item, current_depth + 1) for item in obj]
+            if isinstance(obj, dict):
+                return {k: limit_depth(val, current_depth + 1) for k, val in obj.items()}
+            return limit_depth(str(obj), current_depth)
+
+        processed_metadata = limit_depth(safe_metadata)
+
+        serialized_meta = json.dumps(processed_metadata, separators=(",", ":"))
+        max_meta_limit = max_meta_override or self.max_metadata_size
+        if len(serialized_meta) > max_meta_limit:
+            raise ValueError(f"Metadata size exceeds maximum allowed limit of {max_meta_limit / 1024}KB.")
+
+        safe_actor = apply_ref(actor_raw, "actor")
+        safe_target = apply_ref(target_raw, "target")
+        safe_tenant = apply_ref(tenant_raw, "tenant") if tenant_raw else None
+
+        enriched_payload = {
+            "actor": safe_actor,
+            "action": action_plain,
+            "target": safe_target,
+            "metadata": processed_metadata,
+        }
+        if safe_tenant:
+            enriched_payload["tenant"] = safe_tenant
+        if context:
+            enriched_payload["context"] = context
+
+        # Extract trace variables
+        trace_id = payload.get("traceId")
+        span_id = payload.get("spanId")
+        parent_span_id = payload.get("parentSpanId")
+        logical_clock = payload.get("logicalClock")
+
+        agent_ctx = agent_context_store.get()
+        if agent_ctx:
+            if not trace_id and "traceId" in agent_ctx:
+                trace_id = agent_ctx["traceId"]
+            if not span_id and "spanId" in agent_ctx:
+                span_id = agent_ctx["spanId"]
+
+        if payload.get("req"):
+            extracted_trace = self._extract_trace_context(payload["req"])
+            if not trace_id and "traceId" in extracted_trace:
+                trace_id = extracted_trace["traceId"]
+            if not span_id and "spanId" in extracted_trace:
+                span_id = extracted_trace["spanId"]
+            if logical_clock is None and "logicalClock" in extracted_trace:
+                logical_clock = extracted_trace["logicalClock"]
+
+        resolved_clock = self.get_and_increment_clock(logical_clock)
+
+        if span_id:
+            enriched_payload["spanId"] = span_id
+        if parent_span_id:
+            enriched_payload["parentSpanId"] = parent_span_id
+
+        # Return parameters for final cryptographic serialization
+        return enriched_payload, active_hashed_key, actor_plain, action_plain, target_plain, tenant_plain, trace_id
+
+    def prepare_log_entry(self, payload: dict[str, Any], max_meta_override: Optional[int] = None) -> dict[str, Any]:
+        enriched_payload, active_hashed_key, actor, action, target, tenant, trace_id = self._prepare_log_entry_common(
+            payload, max_meta_override
+        )
+
+        actor_blind = self.generate_blind_index(actor, active_hashed_key)
+        action_blind = self.generate_blind_index(action, active_hashed_key)
+        target_blind = self.generate_blind_index(target, active_hashed_key)
+        tenant_blind = self.generate_blind_index(tenant, active_hashed_key) if tenant else None
+        trace_blind = self.generate_blind_index(trace_id, active_hashed_key) if trace_id else None
+
+        encrypted_payload = self.encrypt_payload(enriched_payload)
+        is_claim_check = False
+
+        if len(encrypted_payload) > 30720:
+            hash_hex = hashlib.sha256(encrypted_payload.encode("utf-8")).hexdigest()
+            # Upload encrypted payload to edge worker storage endpoint synchronously
+            try:
+                headers = {
+                    "Authorization": f"Bearer {self.api_key}",
+                    "Content-Type": "application/octet-stream",
+                }
+                self._fetch_with_retry(
+                    f"{self.endpoint}/v1/log/upload/{hash_hex}",
+                    "PUT",
+                    headers,
+                    encrypted_payload.encode("utf-8"),
+                )
+                encrypted_payload = hash_hex
+                is_claim_check = True
+            except Exception as err:
+                # Fall back to original payload
+                pass
+
+        rationale = payload.get("rationale") or (agent_context_store.get() or {}).get("rationale")
+        tool_name = payload.get("toolName") or (agent_context_store.get() or {}).get("toolName")
+
+        agent_context = None
+        if rationale or tool_name:
+            truncated_rationale = rationale[:1000] if rationale else None
+            agent_context = self.encrypt_payload({
+                "rationale": truncated_rationale,
+                "toolName": tool_name,
+            })
+
+        attestation_proof = json.dumps(payload["attestation"], separators=(",", ":")) if payload.get("attestation") else None
+
+        return {
+            "actorBlindIndex": actor_blind,
+            "actionBlindIndex": action_blind,
+            "targetBlindIndex": target_blind,
+            "tenantBlindIndex": tenant_blind,
+            "traceBlindIndex": trace_blind,
+            "encryptedPayload": encrypted_payload,
+            "logicalClock": enriched_payload.get("logicalClock", self._fallback_logical_clock),
+            "isClaimCheck": is_claim_check,
+            "agentContext": agent_context,
+            "attestationProof": attestation_proof,
+        }
+
+    async def prepare_log_entry_async(self, payload: dict[str, Any], max_meta_override: Optional[int] = None) -> dict[str, Any]:
+        # Perform synchronous core preparation
+        enriched_payload, active_hashed_key, actor, action, target, tenant, trace_id = self._prepare_log_entry_common(
+            payload, max_meta_override
+        )
+
+        actor_blind = self.generate_blind_index(actor, active_hashed_key)
+        action_blind = self.generate_blind_index(action, active_hashed_key)
+        target_blind = self.generate_blind_index(target, active_hashed_key)
+        tenant_blind = self.generate_blind_index(tenant, active_hashed_key) if tenant else None
+        trace_blind = self.generate_blind_index(trace_id, active_hashed_key) if trace_id else None
+
+        encrypted_payload = self.encrypt_payload(enriched_payload)
+        is_claim_check = False
+
+        if len(encrypted_payload) > 30720:
+            hash_hex = hashlib.sha256(encrypted_payload.encode("utf-8")).hexdigest()
+            # Upload encrypted payload asynchronously
+            try:
+                headers = {
+                    "Authorization": f"Bearer {self.api_key}",
+                    "Content-Type": "application/octet-stream",
+                }
+                await self._fetch_with_retry_async(
+                    f"{self.endpoint}/v1/log/upload/{hash_hex}",
+                    "PUT",
+                    headers,
+                    encrypted_payload.encode("utf-8"),
+                )
+                encrypted_payload = hash_hex
+                is_claim_check = True
+            except Exception as err:
+                pass
+
+        rationale = payload.get("rationale") or (agent_context_store.get() or {}).get("rationale")
+        tool_name = payload.get("toolName") or (agent_context_store.get() or {}).get("toolName")
+
+        agent_context = None
+        if rationale or tool_name:
+            truncated_rationale = rationale[:1000] if rationale else None
+            agent_context = self.encrypt_payload({
+                "rationale": truncated_rationale,
+                "toolName": tool_name,
+            })
+
+        attestation_proof = json.dumps(payload["attestation"], separators=(",", ":")) if payload.get("attestation") else None
+
+        return {
+            "actorBlindIndex": actor_blind,
+            "actionBlindIndex": action_blind,
+            "targetBlindIndex": target_blind,
+            "tenantBlindIndex": tenant_blind,
+            "traceBlindIndex": trace_blind,
+            "encryptedPayload": encrypted_payload,
+            "logicalClock": enriched_payload.get("logicalClock", self._fallback_logical_clock),
+            "isClaimCheck": is_claim_check,
+            "agentContext": agent_context,
+            "attestationProof": attestation_proof,
+        }
+
+    def _fetch_with_retry(self, url: str, method: str, headers: dict[str, str], body: bytes, max_retries: Optional[int] = None) -> bytes:
+        if max_retries is None:
+            max_retries = self.max_retries
+
+        attempt = 0
+        delay = 0.5
+        last_error = Exception("Unknown error")
+
+        while attempt <= max_retries:
+            req = urllib.request.Request(
+                url,
+                data=body if method in ("POST", "PUT") else None,
+                headers=headers,
+                method=method,
+            )
+            try:
+                with urllib.request.urlopen(req, timeout=10.0) as response:
+                    return response.read()
+            except urllib.error.HTTPError as e:
+                last_error = e
+                if 400 <= e.code < 500:
+                    raise e
+            except Exception as e:
+                last_error = e
+
+            attempt += 1
+            if attempt <= max_retries:
+                time.sleep(delay)
+                delay *= 3
+
+        raise last_error
+
+    async def _fetch_with_retry_async(self, url: str, method: str, headers: dict[str, str], body: bytes, max_retries: Optional[int] = None) -> bytes:
+        if HAS_HTTPX:
+            if max_retries is None:
+                max_retries = self.max_retries
+
+            attempt = 0
+            delay = 0.5
+            last_error = Exception("Unknown error")
+            client = await self._get_httpx_client()
+
+            while attempt <= max_retries:
+                try:
+                    response = await client.request(
+                        method,
+                        url,
+                        headers=headers,
+                        content=body,
+                        timeout=10.0,
+                    )
+                    if response.is_success:
+                        return response.content
+                    response.raise_for_status()
+                except httpx.HTTPStatusError as e:
+                    last_error = e
+                    if 400 <= e.response.status_code < 500:
+                        raise e
+                except Exception as e:
+                    last_error = e
+
+                attempt += 1
+                if attempt <= max_retries:
+                    await asyncio.sleep(delay)
+                    delay *= 3
+
+            raise last_error
+        else:
+            # Fall back to running urllib inside the thread pool executor
+            loop = asyncio.get_running_loop()
+            return await loop.run_in_executor(
+                _executor,
+                lambda: self._fetch_with_retry(url, method, headers, body, max_retries)
+            )
+
+    def log(self, payload: dict[str, Any], max_meta_override: Optional[int] = None) -> bool:
+        try:
+            entry = self.prepare_log_entry(payload, max_meta_override)
+            headers = {
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            }
+            body = json.dumps(entry, separators=(",", ":")).encode("utf-8")
+            self._fetch_with_retry(f"{self.endpoint}/v1/log", "POST", headers, body)
+            return True
+        except Exception as e:
+            import sys
+            print(f"[Volidator] Failed to send log: {str(e)}", file=sys.stderr)
+            if self.on_delivery_failure:
+                try:
+                    self.on_delivery_failure(payload, e)
+                except Exception as cb_err:
+                    print(f"[Volidator] Error in on_delivery_failure callback: {str(cb_err)}", file=sys.stderr)
+            return False
+
+    async def log_async(self, payload: dict[str, Any], max_meta_override: Optional[int] = None) -> bool:
+        try:
+            entry = await self.prepare_log_entry_async(payload, max_meta_override)
+            headers = {
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            }
+            body = json.dumps(entry, separators=(",", ":")).encode("utf-8")
+            await self._fetch_with_retry_async(f"{self.endpoint}/v1/log", "POST", headers, body)
+            return True
+        except Exception as e:
+            import sys
+            print(f"[Volidator] Failed to send log async: {str(e)}", file=sys.stderr)
+            if self.on_delivery_failure:
+                try:
+                    self.on_delivery_failure(payload, e)
+                except Exception as cb_err:
+                    print(f"[Volidator] Error in on_delivery_failure callback: {str(cb_err)}", file=sys.stderr)
+            return False
+
+    def log_batch(self, payloads: list[dict[str, Any]], max_meta_override: Optional[int] = None) -> dict[str, int]:
+        if not payloads:
+            return {"accepted": 0, "rejected": 0}
+
+        batch = payloads[:100]
+        prepared_entries = []
+        rejected = len(payloads) - len(batch)
+
+        for p in batch:
+            try:
+                prepared_entries.append(self.prepare_log_entry(p, max_meta_override))
+            except Exception as e:
+                import sys
+                print(f"[Volidator] Failed to prepare batch entry: {str(e)}", file=sys.stderr)
+                rejected += 1
+
+        if not prepared_entries:
+            return {"accepted": 0, "rejected": rejected}
+
+        try:
+            headers = {
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            }
+            body = json.dumps({"logs": prepared_entries}, separators=(",", ":")).encode("utf-8")
+            self._fetch_with_retry(f"{self.endpoint}/v1/logs/batch", "POST", headers, body)
+            return {"accepted": len(prepared_entries), "rejected": rejected}
+        except Exception as e:
+            import sys
+            print(f"[Volidator] Failed to send log batch: {str(e)}", file=sys.stderr)
+            if self.on_delivery_failure:
+                for payload in batch:
+                    try:
+                        self.on_delivery_failure(payload, e)
+                    except Exception as cb_err:
+                        pass
+            return {"accepted": 0, "rejected": rejected + len(prepared_entries)}
+
+    async def log_batch_async(self, payloads: list[dict[str, Any]], max_meta_override: Optional[int] = None) -> dict[str, int]:
+        if not payloads:
+            return {"accepted": 0, "rejected": 0}
+
+        batch = payloads[:100]
+        prepared_entries = []
+        rejected = len(payloads) - len(batch)
+
+        # Crytographic parallelization is handled implicitly in Python async via gather
+        tasks = [self.prepare_log_entry_async(p, max_meta_override) for p in batch]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        for i, res in enumerate(results):
+            if isinstance(res, Exception):
+                import sys
+                print(f"[Volidator] Failed to prepare batch entry async: {str(res)}", file=sys.stderr)
+                rejected += 1
+            else:
+                prepared_entries.append(res)
+
+        if not prepared_entries:
+            return {"accepted": 0, "rejected": rejected}
+
+        try:
+            headers = {
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            }
+            body = json.dumps({"logs": prepared_entries}, separators=(",", ":")).encode("utf-8")
+            await self._fetch_with_retry_async(f"{self.endpoint}/v1/logs/batch", "POST", headers, body)
+            return {"accepted": len(prepared_entries), "rejected": rejected}
+        except Exception as e:
+            import sys
+            print(f"[Volidator] Failed to send log batch async: {str(e)}", file=sys.stderr)
+            if self.on_delivery_failure:
+                for payload in batch:
+                    try:
+                        self.on_delivery_failure(payload, e)
+                    except Exception:
+                        pass
+            return {"accepted": 0, "rejected": rejected + len(prepared_entries)}
+
+    def batcher(self, options: Optional[dict[str, Any]] = None) -> "VolidatorBatcher":
+        options = options or {}
+        return VolidatorBatcher(
+            self,
+            auto_flush_count=options.get("autoFlushCount", 100),
+            auto_flush_interval=options.get("autoFlushInterval"),
+        )
+
+    def generate_embed_token(
+        self,
+        config: dict[str, Any]
+    ) -> dict[str, str]:
+        project_id = config.get("projectId") or self.project_id
+        client_secret = config.get("clientSecret") or self.client_secret
+
+        if not project_id or not client_secret:
+            raise ValueError(
+                "generate_embed_token() requires projectId and clientSecret in either config or VolidatorClient constructor."
+            )
+
+        actor_id = config.get("actorId")
+        target_id = config.get("targetId")
+        tenant_id = config.get("tenantId")
+        scope = config.get("scope")
+        expires_in = config.get("expiresIn", "2h")
+        dashboard_url = config.get("dashboardUrl", "https://dash.volidator.com").rstrip("/")
+        host_origin = config.get("hostOrigin")
+        view = config.get("view")
+
+        default_scope = scope or ("tenant" if tenant_id else "actor")
+
+        if default_scope != "auditor" and not actor_id and not target_id and not tenant_id:
+            raise ValueError(
+                "At least one of actorId, targetId, or tenantId must be provided to generate_embed_token()."
+            )
+
+        actor_blinds = [
+            self.generate_blind_index(actor_id, self._get_hashed_key(kid))
+            for kid in self.keyring
+        ] if actor_id else None
+
+        target_blinds = [
+            self.generate_blind_index(target_id, self._get_hashed_key(kid))
+            for kid in self.keyring
+        ] if target_id else None
+
+        tenant_blinds = [
+            self.generate_blind_index(tenant_id, self._get_hashed_key(kid))
+            for kid in self.keyring
+        ] if tenant_id else None
+
+        def parse_expiry(exp_str: str) -> int:
+            match = re.match(r"^(\d+)(s|m|h|d)$", exp_str)
+            if not match:
+                return 7200
+            num, unit = match.groups()
+            n = int(num)
+            if unit == "s":
+                return n
+            if unit == "m":
+                return n * 60
+            if unit == "h":
+                return n * 3600
+            if unit == "d":
+                return n * 86400
+            return 7200
+
+        parsed_exp = parse_expiry(expires_in)
+        max_exp = 604800 if default_scope == "auditor" else 3600
+        expires_seconds = min(parsed_exp, max_exp)
+        now = int(time.time())
+
+        payload = {
+            "pid": project_id,
+            "scope": default_scope,
+            "iat": now,
+            "exp": now + expires_seconds,
+        }
+
+        if actor_blinds:
+            payload["abi"] = actor_blinds
+        if target_blinds:
+            payload["tgb"] = target_blinds
+        if tenant_blinds:
+            payload["tbi"] = tenant_blinds
+
+        if view:
+            compressed = {}
+            if isinstance(view.get("columns"), list):
+                cols = []
+                for col in view["columns"]:
+                    if col == "createdAt":
+                        cols.append("cat")
+                    elif col == "actor":
+                        cols.append("act")
+                    elif col == "action":
+                        cols.append("acn")
+                    elif col == "target":
+                        cols.append("tgt")
+                    elif col.startswith("metadata."):
+                        cols.append(f"m.{col[9:]}")
+                    else:
+                        cols.append(col)
+                compressed["cols"] = cols
+
+            if view.get("defaultFilter"):
+                flt = {}
+                df = view["defaultFilter"]
+                if "search" in df:
+                    flt["q"] = df["search"]
+                if "action" in df:
+                    flt["act"] = df["action"]
+                compressed["flt"] = flt
+            payload["view"] = compressed
+
+        client_secret_hash = hashlib.sha256(client_secret.encode("utf-8")).hexdigest()
+        token = self._sign_hs256_jwt(payload, client_secret_hash)
+
+        keyring_str = ",".join(f"{k}:{v}" for k, v in self.keyring.items())
+        host_param = f"?host={urllib.parse.quote(host_origin)}" if host_origin else ""
+        embed_url = f"{dashboard_url}/embed/{token}{host_param}#{keyring_str}"
+
+        return {"token": token, "embedUrl": embed_url}
+
+    async def generate_embed_token_async(self, config: dict[str, Any]) -> dict[str, str]:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(_executor, lambda: self.generate_embed_token(config))
+
+    def _sign_hs256_jwt(self, payload: dict[str, Any], secret: str) -> str:
+        import hmac
+        header = {"alg": "HS256", "typ": "JWT"}
+
+        def base64url(data: bytes) -> str:
+            return base64.urlsafe_b64encode(data).rstrip(b"=").decode("utf-8")
+
+        unsigned = f"{base64url(json.dumps(header, separators=(',', ':')).encode('utf-8'))}.{base64url(json.dumps(payload, separators=(',', ':')).encode('utf-8'))}"
+        signature = hmac.digest(secret.encode("utf-8"), unsigned.encode("utf-8"), "sha256")
+        return f"{unsigned}.{base64url(signature)}"
+
+    def purge_actor_logs(self, actor_id: str, options: Optional[dict[str, Any]] = None) -> dict[str, int]:
+        active_key_buffer = self._get_hashed_key(self.active_key_id)
+        actor_blind = self.generate_blind_index(actor_id, active_key_buffer)
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+        }
+        body = None
+        if options:
+            headers["Content-Type"] = "application/json"
+            body = json.dumps(options, separators=(",", ":")).encode("utf-8")
+
+        res_bytes = self._fetch_with_retry(
+            f"{self.endpoint}/v1/projects/{self.project_id}/actors/{actor_blind}",
+            "DELETE",
+            headers,
+            body or b"",
+        )
+        return json.loads(res_bytes.decode("utf-8"))
+
+    async def purge_actor_logs_async(self, actor_id: str, options: Optional[dict[str, Any]] = None) -> dict[str, int]:
+        active_key_buffer = self._get_hashed_key(self.active_key_id)
+        actor_blind = self.generate_blind_index(actor_id, active_key_buffer)
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+        }
+        body = None
+        if options:
+            headers["Content-Type"] = "application/json"
+            body = json.dumps(options, separators=(",", ":")).encode("utf-8")
+
+        res_bytes = await self._fetch_with_retry_async(
+            f"{self.endpoint}/v1/projects/{self.project_id}/actors/{actor_blind}",
+            "DELETE",
+            headers,
+            body or b"",
+        )
+        return json.loads(res_bytes.decode("utf-8"))
+
+
+class VolidatorBatcher:
+    def __init__(self, client: VolidatorClient, auto_flush_count: int = 100, auto_flush_interval: Optional[float] = None):
+        self.client = client
+        self.auto_flush_count = min(auto_flush_count, 100)
+        # auto_flush_interval is in seconds
+        self.auto_flush_interval = auto_flush_interval
+
+        self.buffer = []
+        self.lock = threading.Lock()
+        self.timer = None
+
+        self.start_timer()
+
+    def push(self, payload: dict[str, Any]):
+        with self.lock:
+            self.buffer.append(payload)
+            if len(self.buffer) >= self.auto_flush_count:
+                threading.Thread(target=self.flush).start()
+
+    def flush(self) -> dict[str, int]:
+        with self.lock:
+            self.stop_timer()
+            if not self.buffer:
+                self.start_timer()
+                return {"accepted": 0, "rejected": 0}
+
+            payloads_to_flush = list(self.buffer)
+            self.buffer.clear()
+            self.start_timer()
+
+        return self.client.log_batch(payloads_to_flush)
+
+    async def flush_async(self) -> dict[str, int]:
+        with self.lock:
+            self.stop_timer()
+            if not self.buffer:
+                self.start_timer()
+                return {"accepted": 0, "rejected": 0}
+
+            payloads_to_flush = list(self.buffer)
+            self.buffer.clear()
+            self.start_timer()
+
+        return await self.client.log_batch_async(payloads_to_flush)
+
+    def size(self) -> int:
+        with self.lock:
+            return len(self.buffer)
+
+    def start_timer(self):
+        if self.auto_flush_interval and not self.timer:
+            self.timer = threading.Timer(self.auto_flush_interval, self._timer_flush)
+            self.timer.daemon = True
+            self.timer.start()
+
+    def stop_timer(self):
+        if self.timer:
+            self.timer.cancel()
+            self.timer = None
+
+    def _timer_flush(self):
+        try:
+            self.flush()
+        except Exception:
+            pass
+
+
+def canonicalize(obj: Any) -> str:
+    if obj is None:
+        return "null"
+    if isinstance(obj, (str, int, float, bool)):
+        return json.dumps(obj, separators=(",", ":"))
+    import datetime
+    if isinstance(obj, (datetime.datetime, datetime.date)):
+        if isinstance(obj, datetime.datetime):
+            if obj.tzinfo is not None:
+                obj = obj.astimezone(datetime.timezone.utc)
+            else:
+                obj = obj.replace(tzinfo=datetime.timezone.utc)
+            val = obj.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+        else:
+            val = obj.isoformat()
+        return json.dumps(val)
+    if isinstance(obj, list):
+        items = []
+        for item in obj:
+            val = canonicalize(item)
+            items.append("null" if val == "" else val)
+        return "[" + ",".join(items) + "]"
+    if isinstance(obj, dict):
+        keys = sorted(obj.keys())
+        pairs = []
+        for k in keys:
+            val = obj[k]
+            if val is None:
+                pairs.append(json.dumps(k, separators=(",", ":")) + ":null")
+            else:
+                pairs.append(json.dumps(k, separators=(",", ":")) + ":" + canonicalize(val))
+        return "{" + ",".join(pairs) + "}"
+    return json.dumps(str(obj))
+