starkgate-sdk 0.2.0__py3-none-any.whl

starkgate/__init__.py

@@ -0,0 +1,42 @@
+from starkgate.client import StarkGate
+from starkgate.models import EvaluationResult, Policy, Rule
+from starkgate.ed25519 import (
+    sign_ed25519,
+    verify_ed25519,
+    ed25519_public_key,
+)
+from starkgate.local_audit import (
+    audit_hash,
+    chain_hash,
+    verify_chain,
+    verify_audit_entry,
+    verify_verdict_local,
+)
+from starkgate.engine import (
+    evaluate as evaluate,
+    evaluate_condition,
+    evaluate_operator,
+    get_nested_value,
+    StarkGateLocalError,
+)
+
+__version__ = "0.2.0"
+__all__ = [
+    "StarkGate",
+    "EvaluationResult",
+    "Policy",
+    "Rule",
+    "sign_ed25519",
+    "verify_ed25519",
+    "ed25519_public_key",
+    "audit_hash",
+    "chain_hash",
+    "verify_chain",
+    "verify_audit_entry",
+    "verify_verdict_local",
+    "evaluate",
+    "evaluate_condition",
+    "evaluate_operator",
+    "get_nested_value",
+    "StarkGateLocalError",
+]

starkgate/client.py

@@ -0,0 +1,388 @@
+from __future__ import annotations
+
+import functools
+import hashlib
+import json
+import hmac as hmac_module
+import inspect
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Optional, Tuple
+
+import httpx
+
+from .models import EvaluationResult
+
+
+class StarkGateError(Exception):
+    """Base exception for all StarkGate SDK errors."""
+
+
+class StarkGateDenied(StarkGateError):
+    """Raised by protect() when StarkGate policy DENIES an action."""
+
+    def __init__(
+        self,
+        message: str = "Action denied by StarkGate policy.",
+        result: Optional[EvaluationResult] = None,
+    ) -> None:
+        super().__init__(message)
+        self.result = result
+
+
+class StarkGateAPIError(StarkGateError):
+    """Raised when the StarkGate API returns an error or the request fails."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class StarkGate:
+    """Python client for the StarkGate API — The Universal Firewall for AI Agents."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://starkgate-api.wenjoseph16.workers.dev",
+        timeout: float = 5.0,
+        transport: Optional[httpx.BaseTransport] = None,
+        signing_key: Optional[str] = None,
+        strict_mode: bool = False,
+        user_agent: str = "Mozilla/5.0 (compatible; starkgate-sdk/0.2.0)",
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.signing_key = signing_key
+        self.strict_mode = strict_mode
+        self._transport = transport
+        self.user_agent = user_agent
+        # NB : un User-Agent non-navigateur est bloqué par le WAF Cloudflare
+        # (erreur 1010). On envoie donc un UA compatible navigateur par défaut,
+        # surchargeable par l'appelant via le paramètre user_agent.
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "User-Agent": user_agent,
+            },
+            timeout=timeout,
+            transport=transport,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "StarkGate":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        try:
+            response = self._client.request(method, path, **kwargs)
+        except httpx.HTTPError as exc:
+            raise StarkGateAPIError(f"Request failed: {exc}") from exc
+        return self._parse(response)
+
+    @staticmethod
+    def _anti_replay() -> Dict[str, str]:
+        return {
+            "nonce": uuid.uuid4().hex,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+
+    @staticmethod
+    def _canonicalize(fields: Dict[str, Any]) -> str:
+        parts: list[str] = []
+        for key in sorted(fields):
+            value = fields[key]
+            if value is None:
+                continue
+            if isinstance(value, bool):
+                value = "true" if value else "false"
+            elif isinstance(value, (dict, list)):
+                value = StarkGate._canonical_json(value)
+            else:
+                value = str(value)
+            parts.append(f"{key}={value}")
+        return "&".join(parts)
+
+    @staticmethod
+    def _canonical_json(value: Any) -> str:
+        """JSON déterministe (F2) — mêmes règles que `canonical_json` (Rust)
+        et `canonicalNested` (TS) : clés triées récursivement, compact, UTF-8."""
+        if isinstance(value, bool):
+            return "true" if value else "false"
+        if value is None:
+            return "null"
+        if isinstance(value, dict):
+            inner = ",".join(
+                f"{json.dumps(k, ensure_ascii=False, separators=(',', ':'))}"
+                f":{StarkGate._canonical_json(v)}"
+                for k, v in sorted(value.items(), key=lambda kv: kv[0])
+            )
+            return "{" + inner + "}"
+        if isinstance(value, list):
+            inner = ",".join(StarkGate._canonical_json(v) for v in value)
+            return "[" + inner + "]"
+        return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+
+    @staticmethod
+    def _normalize_hash(value: str, prefix: str) -> str:
+        return value[len(prefix) :] if value.startswith(prefix) else value
+
+    @staticmethod
+    def verify_merkle_proof(
+        leaf: str,
+        index: int,
+        siblings: list,
+        root: str,
+    ) -> bool:
+        """Recontruit la racine de Merkle à partir d'une feuille et vérifie la preuve."""
+        acc = bytes.fromhex(StarkGate._normalize_hash(leaf, "sha256:"))
+        cursor = index
+        for sibling in siblings:
+            sibling_bytes = bytes.fromhex(StarkGate._normalize_hash(sibling, "sha256:"))
+            digester = hashlib.sha256()
+            if cursor % 2 == 0:
+                digester.update(acc)
+                digester.update(sibling_bytes)
+            else:
+                digester.update(sibling_bytes)
+                digester.update(acc)
+            acc = digester.digest()
+            cursor //= 2
+        expected = StarkGate._normalize_hash(root, "merkle:")
+        return hmac_module.compare_digest(acc.hex(), expected)
+
+    def verify(self, verdict: Dict[str, Any]) -> bool:
+        """Recalculates and verifies the HMAC signature of a signed verdict."""
+        if not self.signing_key:
+            raise StarkGateError("Provide signing_key to verify()")
+        signature = verdict.get("signature", "")
+        signed = verdict.get("signed")
+        if not isinstance(signed, dict):
+            return False
+        message = self._canonicalize(signed)
+        expected_hex = hmac_module.new(
+            self.signing_key.encode(), message.encode(), hashlib.sha256
+        ).hexdigest()
+        provided_hex = signature[5:] if signature.startswith("hmac:") else signature
+        return hmac_module.compare_digest(expected_hex, provided_hex)
+
+    async def _async_request(self, method: str, path: str, **kwargs: Any) -> Any:
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+        try:
+            async with httpx.AsyncClient(
+                base_url=self.base_url,
+                headers=headers,
+                timeout=self.timeout,
+                transport=self._transport,
+            ) as client:
+                response = await client.request(method, path, **kwargs)
+        except httpx.HTTPError as exc:
+            raise StarkGateAPIError(f"Request failed: {exc}") from exc
+        return self._parse(response)
+
+    @staticmethod
+    def _parse(response: httpx.Response) -> Any:
+        try:
+            body = response.json()
+        except ValueError:
+            body = {}
+        if not isinstance(body, dict):
+            body = {}
+        if not (200 <= response.status_code < 300):
+            raise StarkGateAPIError(
+                body.get("error") or f"HTTP {response.status_code}",
+                status_code=response.status_code,
+            )
+        if body.get("success") is False:
+            raise StarkGateAPIError(
+                body.get("error") or "Unknown API error",
+                status_code=response.status_code,
+            )
+        return body.get("data")
+
+    def evaluate(
+        self,
+        agent_id: str,
+        policy_id: str,
+        action_type: str,
+        payload: Optional[Dict[str, Any]] = None,
+    ) -> EvaluationResult:
+        return EvaluationResult.from_dict(
+            self._evaluate_raw(agent_id, policy_id, action_type, payload)
+        )
+
+    def _evaluate_raw(
+        self,
+        agent_id: str,
+        policy_id: str,
+        action_type: str,
+        payload: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        data = self._request(
+            "POST",
+            "/v1/evaluate",
+            json={
+                "agentId": agent_id,
+                "policyId": policy_id,
+                "actionType": action_type,
+                "payload": payload or {},
+                **self._anti_replay(),
+            },
+        )
+        if not isinstance(data, dict):
+            raise StarkGateAPIError("Unexpected response shape")
+        return data
+
+    async def async_evaluate(
+        self,
+        agent_id: str,
+        policy_id: str,
+        action_type: str,
+        payload: Optional[Dict[str, Any]] = None,
+    ) -> EvaluationResult:
+        data = await self._async_request(
+            "POST",
+            "/v1/evaluate",
+            json={
+                "agentId": agent_id,
+                "policyId": policy_id,
+                "actionType": action_type,
+                "payload": payload or {},
+                **self._anti_replay(),
+            },
+        )
+        return EvaluationResult.from_dict(data)
+
+    def dry_run(
+        self,
+        agent_id: str,
+        policy_id: str,
+        action_type: str,
+        payload: Optional[Dict[str, Any]] = None,
+    ) -> EvaluationResult:
+        """Évalue sans bloquer : ALLOW + would_block si une règle aurait interdit l'action."""
+        data = self._request(
+            "POST",
+            "/v1/evaluate",
+            json={
+                "agentId": agent_id,
+                "policyId": policy_id,
+                "actionType": action_type,
+                "payload": payload or {},
+                "dryRun": True,
+                **self._anti_replay(),
+            },
+        )
+        return EvaluationResult.from_dict(data)
+
+    async def async_dry_run(
+        self,
+        agent_id: str,
+        policy_id: str,
+        action_type: str,
+        payload: Optional[Dict[str, Any]] = None,
+    ) -> EvaluationResult:
+        data = await self._async_request(
+            "POST",
+            "/v1/evaluate",
+            json={
+                "agentId": agent_id,
+                "policyId": policy_id,
+                "actionType": action_type,
+                "payload": payload or {},
+                "dryRun": True,
+                **self._anti_replay(),
+            },
+        )
+        return EvaluationResult.from_dict(data)
+
+    def evaluate_batch(
+        self,
+        actions: list[Dict[str, Any]],
+    ) -> Dict[str, Any]:
+        """Evaluate N actions in a single API call (≤1000).
+
+        Each action dict must contain: agentId, policyId, actionType, payload, nonce, timestamp.
+        Returns: { verdicts: [...], batch: { count, chainHash } }
+        """
+        if len(actions) > 1000:
+            raise StarkGateAPIError("Batch size exceeds limit of 1000")
+        data = self._request(
+            "POST",
+            "/v1/evaluate/batch",
+            json={"actions": actions},
+        )
+        if not isinstance(data, dict):
+            raise StarkGateAPIError("Unexpected response shape")
+        return data
+
+    async def async_evaluate_batch(
+        self,
+        actions: list[Dict[str, Any]],
+    ) -> Dict[str, Any]:
+        """Async version of evaluate_batch."""
+        if len(actions) > 1000:
+            raise StarkGateAPIError("Batch size exceeds limit of 1000")
+        data = await self._async_request(
+            "POST",
+            "/v1/evaluate/batch",
+            json={"actions": actions},
+        )
+        return data
+
+    def protect(
+        self,
+        agent_id: str,
+        policy_id: str,
+        action_type: str,
+        payload: Optional[Dict[str, Any]] = None,
+        strict: Optional[bool] = None,
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        effective = self.strict_mode if strict is None else strict
+        if self.strict_mode and strict is False:
+            raise StarkGateError("Bypassing the guard is forbidden in strict_mode")
+        if effective and not self.signing_key:
+            raise StarkGateError("strict_mode requires a signing_key to verify verdicts")
+
+        def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+            signature = inspect.signature(func)
+
+            @functools.wraps(func)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                bound = signature.bind_partial(*args, **kwargs)
+                evaluation_payload: Dict[str, Any] = dict(bound.arguments)
+                if payload:
+                    evaluation_payload.update(payload)
+                verdict = self._evaluate_raw(
+                    agent_id=agent_id,
+                    policy_id=policy_id,
+                    action_type=action_type,
+                    payload=evaluation_payload,
+                )
+                if effective:
+                    if not verdict.get("signature"):
+                        raise StarkGateError("No signed verdict returned — failing closed")
+                    if not self.verify(verdict):
+                        raise StarkGateError("Verdict signature invalid — failing closed")
+                result = EvaluationResult.from_dict(verdict)
+                if result.is_denied:
+                    raise StarkGateDenied(
+                        result.reason or "Action denied by StarkGate policy.",
+                        result=result,
+                    )
+                return func(*args, **kwargs)
+
+            return wrapper
+
+        return decorator

starkgate/ed25519.py

@@ -0,0 +1,58 @@
+"""Ed25519 (RFC 8032) — preuve vérifiable par tiers, en parallèle de HMAC.
+
+Même corps compacté que HMAC (`canonicalize`), préfixe `ed25519:<hex>`.
+Déterministe : même seed + même corps => même signature (TS/Python/Rust/WASM).
+Clé privée (seed 32 octets hex) passée en paramètre, jamais stockée ici.
+"""
+
+from typing import Dict, Any
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+from cryptography.exceptions import InvalidSignature
+
+_ED25519_PREFIX = "ed25519:"
+
+
+def canonicalize(fields: Dict[str, Any]) -> str:
+    """Canonicalisation identique à TS `canonicalizeVerdict` / Rust
+    `canonicalize_verdict` (tri des clés, F2 imbriqué via JSON déterministe)."""
+    from starkgate.client import StarkGate
+
+    return StarkGate._canonicalize(fields)
+
+
+def _strip_prefix(value: str) -> str:
+    return value[len(_ED25519_PREFIX) :] if value.startswith(_ED25519_PREFIX) else value
+
+
+def sign_ed25519(seed_hex: str, fields: Dict[str, Any]) -> str:
+    """Signe un verdict en Ed25519. Retourne `ed25519:<hex>`."""
+    seed = bytes.fromhex(_strip_prefix(seed_hex))
+    msg = canonicalize(fields).encode("utf-8")
+    sk = Ed25519PrivateKey.from_private_bytes(seed)
+    sig = sk.sign(msg)
+    return _ED25519_PREFIX + sig.hex()
+
+
+def ed25519_public_key(seed_hex: str) -> str:
+    """Dérive la clé publique (32 octets hex) depuis une seed privée."""
+    seed = bytes.fromhex(_strip_prefix(seed_hex))
+    sk = Ed25519PrivateKey.from_private_bytes(seed)
+    return sk.public_key().public_bytes_raw().hex()
+
+
+def verify_ed25519(public_key_hex: str, fields: Dict[str, Any], signature: str) -> bool:
+    """Vérifie une signature `ed25519:<hex>`. Fail-closed sur toute erreur."""
+    if not signature.startswith(_ED25519_PREFIX):
+        return False
+    try:
+        pub = Ed25519PublicKey.from_public_bytes(bytes.fromhex(_strip_prefix(public_key_hex)))
+        sig = bytes.fromhex(signature[len(_ED25519_PREFIX) :])
+        msg = canonicalize(fields).encode("utf-8")
+        pub.verify(sig, msg)
+        return True
+    except (InvalidSignature, ValueError, TypeError):
+        return False