capiscio-sdk 0.3.0__py3-none-any.whl → 2.3.1__py3-none-any.whl

capiscio_sdk/scoring/__init__.py

@@ -1,5 +1,10 @@
 """Multi-dimensional scoring system for A2A validation.
 
+.. deprecated:: 0.3.0
+    The pure Python scoring module is deprecated. Scoring is now handled by
+    capiscio-core via gRPC. Use :func:`capiscio_sdk.validate_agent_card` for
+    Agent Card validation with scoring, which delegates to Go core.
+
 This module provides three independent scoring dimensions:
 - Compliance: Protocol specification adherence (0-100)
 - Trust: Security and authenticity signals (0-100)  
@@ -7,8 +12,14 @@ This module provides three independent scoring dimensions:
 
 Each dimension has its own rating scale and breakdown structure,
 allowing users to make nuanced decisions based on their priorities.
+
+NOTE: The types in this module are still used for API compatibility.
+The scorer classes (ComplianceScorer, TrustScorer, AvailabilityScorer)
+are deprecated and should not be used directly.
 """
 
+import warnings as _warnings
+
 from .types import (
     ComplianceScore,
     TrustScore,
@@ -21,11 +32,69 @@ from .types import (
     AvailabilityRating,
     ScoringContext,
 )
-from .compliance import ComplianceScorer
-from .trust import TrustScorer
-from .availability import AvailabilityScorer
+
+# Import deprecated scorers with warnings
+from .compliance import ComplianceScorer as _LegacyComplianceScorer
+from .trust import TrustScorer as _LegacyTrustScorer
+from .availability import AvailabilityScorer as _LegacyAvailabilityScorer
+
+
+class ComplianceScorer(_LegacyComplianceScorer):
+    """Compliance scorer (DEPRECATED - scoring now handled by Go core).
+    
+    .. deprecated:: 0.3.0
+        Use :func:`capiscio_sdk.validate_agent_card` which delegates
+        scoring to capiscio-core. This class will be removed in v1.0.0.
+    """
+    
+    def __init__(self, *args, **kwargs):
+        _warnings.warn(
+            "ComplianceScorer is deprecated. Scoring is now handled by Go core. "
+            "Use capiscio_sdk.validate_agent_card() instead.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        super().__init__(*args, **kwargs)
+
+
+class TrustScorer(_LegacyTrustScorer):
+    """Trust scorer (DEPRECATED - scoring now handled by Go core).
+    
+    .. deprecated:: 0.3.0
+        Use :func:`capiscio_sdk.validate_agent_card` which delegates
+        scoring to capiscio-core. This class will be removed in v1.0.0.
+    """
+    
+    def __init__(self, *args, **kwargs):
+        _warnings.warn(
+            "TrustScorer is deprecated. Scoring is now handled by Go core. "
+            "Use capiscio_sdk.validate_agent_card() instead.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        super().__init__(*args, **kwargs)
+
+
+class AvailabilityScorer(_LegacyAvailabilityScorer):
+    """Availability scorer (DEPRECATED - scoring now handled by Go core).
+    
+    .. deprecated:: 0.3.0
+        Use :func:`capiscio_sdk.validate_agent_card` which delegates
+        scoring to capiscio-core. This class will be removed in v1.0.0.
+    """
+    
+    def __init__(self, *args, **kwargs):
+        _warnings.warn(
+            "AvailabilityScorer is deprecated. Scoring is now handled by Go core. "
+            "Use capiscio_sdk.validate_agent_card() instead.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        super().__init__(*args, **kwargs)
+
 
 __all__ = [
+    # Types (still used)
     "ComplianceScore",
     "TrustScore",
     "AvailabilityScore",
@@ -36,6 +105,7 @@ __all__ = [
     "TrustRating",
     "AvailabilityRating",
     "ScoringContext",
+    # Deprecated scorers (kept for backward compatibility)
     "ComplianceScorer",
     "TrustScorer",
     "AvailabilityScorer",

capiscio_sdk/simple_guard.py

@@ -1,45 +1,66 @@
-"""SimpleGuard: Local, zero-config security for A2A agents."""
+"""SimpleGuard - Zero-config security for A2A agents.
+
+This module provides signing and verification of A2A messages using
+the capiscio-core Go library via gRPC. All cryptographic operations
+are delegated to the Go core for consistency across SDKs.
+"""
 import os
 import json
 import logging
-import base64
-import hashlib
-import time
 from pathlib import Path
-from typing import Optional, Dict, Any, Union, cast
-
-import jwt
-from cryptography.hazmat.primitives import serialization
-from cryptography.hazmat.primitives.asymmetric import ed25519
+from typing import Optional, Dict, Any, Union
 
 from .errors import ConfigurationError, VerificationError
+from ._rpc.client import CapiscioRPCClient
 
 logger = logging.getLogger(__name__)
 
-MAX_TOKEN_AGE = 60
-CLOCK_SKEW_LEEWAY = 5
 
 class SimpleGuard:
     """
-    The "Customs Officer" for your Agent.
+    Zero-config security middleware for A2A agents.
+    
+    SimpleGuard handles message signing and verification using Ed25519
+    keys. All cryptographic operations are performed by the capiscio-core
+    Go library via gRPC, ensuring consistent behavior across all SDKs.
     
-    Enforces Identity (JWS) and Protocol (A2A) validation locally.
-    Prioritizes local utility and zero-configuration.
+    Example:
+        >>> guard = SimpleGuard(dev_mode=True)
+        >>> token = guard.sign_outbound({"sub": "test"}, body=b"hello")
+        >>> claims = guard.verify_inbound(token, body=b"hello")
+        
+        # With explicit agent_id:
+        >>> guard = SimpleGuard(agent_id="did:web:example.com:agents:myagent")
+        
+        # In dev mode, did:key is auto-generated:
+        >>> guard = SimpleGuard(dev_mode=True)
+        >>> print(guard.agent_id)  # did:key:z6Mk...
     """
 
     def __init__(
         self, 
         base_dir: Optional[Union[str, Path]] = None, 
-        dev_mode: bool = False
+        dev_mode: bool = False,
+        rpc_address: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        badge_token: Optional[str] = None,
     ) -> None:
         """
         Initialize SimpleGuard.
 
         Args:
             base_dir: Starting directory to search for config (defaults to cwd).
-            dev_mode: If True, auto-generates keys and agent-card.json.
+            dev_mode: If True, auto-generates keys with did:key identity (RFC-002 §6.1).
+            rpc_address: gRPC server address. If None, auto-starts local server.
+            agent_id: Explicit agent DID. If None:
+                - In dev_mode: Auto-generates did:key from keypair
+                - Otherwise: Loaded from agent-card.json
+            badge_token: Pre-obtained badge token to use for identity. When set,
+                make_headers() will use this token instead of signing.
         """
         self.dev_mode = dev_mode
+        self._explicit_agent_id = agent_id
+        self._badge_token = badge_token
         
         # 1. Safety Check
         if self.dev_mode and os.getenv("CAPISCIO_ENV") == "prod":
@@ -48,24 +69,25 @@ class SimpleGuard:
                 "This is insecure! Disable dev_mode in production."
             )
 
-        # 2. Resolve base_dir (Walk up logic)
+        # 2. Resolve base_dir
         self.project_root = self._resolve_project_root(base_dir)
         self.keys_dir = self.project_root / "capiscio_keys"
         self.trusted_dir = self.keys_dir / "trusted"
         self.agent_card_path = self.project_root / "agent-card.json"
-        self.private_key_path = self.keys_dir / "private.pem"
-        self.public_key_path = self.keys_dir / "public.pem"
-
-        # 3. Load or Generate agent-card.json
+        
+        # 3. Connect to gRPC server
+        self._client = CapiscioRPCClient(address=rpc_address)
+        self._client.connect()
+        
+        # 4. Load or generate agent identity
         self.agent_id: str
         self.signing_kid: str
         self._load_or_generate_card()
-
-        # 4. Load or Generate Keys
-        self._private_key: ed25519.Ed25519PrivateKey
+        
+        # 5. Load or generate keys via gRPC (may update agent_id with did:key)
         self._load_or_generate_keys()
-
-        # 5. Load Trust Store (and self-trust in dev mode)
+        
+        # 6. Load trust store
         self._setup_trust_store()
 
     def sign_outbound(self, payload: Dict[str, Any], body: Optional[bytes] = None) -> str:
@@ -83,37 +105,20 @@ class SimpleGuard:
         if "iss" not in payload:
             payload["iss"] = self.agent_id
         
-        # Replay Protection: Inject timestamps
-        now = int(time.time())
-        payload["iat"] = now
-        payload["exp"] = now + MAX_TOKEN_AGE
+        # Use body for binding if provided
+        body_bytes = body or b""
         
-        # Integrity: Calculate Body Hash if body is provided
-        if body is not None:
-            # SHA-256 hash
-            sha256_hash = hashlib.sha256(body).digest()
-            # Base64Url encode (no padding)
-            bh = base64.urlsafe_b64encode(sha256_hash).decode('utf-8').rstrip('=')
-            payload["bh"] = bh
-
-        # Prepare headers
-        headers = {
-            "kid": self.signing_kid,
-            "typ": "JWT",
-            "alg": "EdDSA"
-        }
-
-        # Sign
-        try:
-            token = jwt.encode(
-                payload,
-                self._private_key,
-                algorithm="EdDSA",
-                headers=headers
-            )
-            return token
-        except Exception as e:
-            raise ConfigurationError(f"Failed to sign payload: {e}")
+        # Sign via gRPC - use SignAttached which handles timestamps and body hash
+        jws, error = self._client.simpleguard.sign_attached(
+            payload=body_bytes,  # This gets hashed into 'bh' claim
+            key_id=self.signing_kid,
+            headers={"iss": self.agent_id},
+        )
+        
+        if error:
+            raise ConfigurationError(f"Failed to sign payload: {error}")
+        
+        return jws
 
     def verify_inbound(self, jws: str, body: Optional[bytes] = None) -> Dict[str, Any]:
         """
@@ -129,119 +134,101 @@ class SimpleGuard:
         Raises:
             VerificationError: If signature is invalid, key is untrusted, or integrity check fails.
         """
+        valid, payload_bytes, key_id, error = self._client.simpleguard.verify_attached(
+            jws=jws,
+            body=body,
+        )
+        
+        if error:
+            logger.warning(f'{{"event": "agent_call_denied", "reason": "{error}"}}')
+            raise VerificationError(error)
+        
+        if not valid:
+            raise VerificationError("Verification failed")
+        
+        # Parse payload
         try:
-            # 1. Parse Header to get kid (without verifying yet)
-            header = jwt.get_unverified_header(jws)
-            kid = header.get("kid")
-            
-            if not kid:
-                raise VerificationError("Missing 'kid' in JWS header.")
-
-            # 2. Resolution: Look for trusted key
-            trusted_key_path = self.trusted_dir / f"{kid}.pem"
-            if not trusted_key_path.exists():
-                logger.warning(f'{{"event": "agent_call_denied", "kid": "{kid}", "reason": "untrusted_key"}}')
-                raise VerificationError(f"Untrusted key ID: {kid}")
-
-            # Load the trusted public key
-            with open(trusted_key_path, "rb") as f:
-                public_key = serialization.load_pem_public_key(f.read())
-                # Ensure it is a key type compatible with jwt.decode (Ed25519PublicKey is supported)
-                # We cast to Any to satisfy mypy's strict check against the specific union
-                public_key = cast(Any, public_key)
-
-            # 3. Verify Signature
-            payload = jwt.decode(
-                jws,
-                public_key,
-                algorithms=["EdDSA"],
-                options={"verify_aud": False} # Audience verification depends on context, skipping for generic guard
-            )
-            
-            # Cast payload to Dict[str, Any]
-            payload = cast(Dict[str, Any], payload)
-
-            # 4. Integrity Check (Body Hash)
-            if "bh" in payload:
-                if body is None:
-                    raise VerificationError("JWS contains 'bh' claim but no body provided for verification.")
-                
-                # Calculate hash of received body
-                sha256_hash = hashlib.sha256(body).digest()
-                calculated_bh = base64.urlsafe_b64encode(sha256_hash).decode('utf-8').rstrip('=')
-                
-                if calculated_bh != payload["bh"]:
-                    logger.warning(f'{{"event": "agent_call_denied", "kid": "{kid}", "reason": "integrity_check_failed"}}')
-                    raise VerificationError("Integrity Check Failed: Body modified")
-
-            # 5. Replay Protection (Timestamp Enforcement)
-            now = int(time.time())
-            exp = payload.get("exp")
-            iat = payload.get("iat")
-
-            if exp is None or iat is None:
-                 raise VerificationError("Missing timestamp claims (exp, iat).")
+            payload = json.loads(payload_bytes) if payload_bytes else {}
+        except json.JSONDecodeError:
+            payload = {}
+        
+        iss = payload.get("iss", "unknown")
+        logger.info(f'{{"event": "agent_call_allowed", "iss": "{iss}", "kid": "{key_id}"}}')
+        
+        return payload
 
-            if now > (exp + CLOCK_SKEW_LEEWAY):
-                 logger.warning(f'{{"event": "agent_call_denied", "kid": "{kid}", "reason": "token_expired"}}')
-                 raise VerificationError("Token expired.")
+    def make_headers(self, payload: Dict[str, Any], body: Optional[bytes] = None) -> Dict[str, str]:
+        """
+        Generate headers containing the Badge (RFC-002 §9.1).
+        
+        If a badge_token was provided at construction, it will be used.
+        Otherwise, signs the payload to create a token.
+        
+        Args:
+            payload: The JSON payload to sign (ignored if using badge_token).
+            body: Optional HTTP body bytes to bind to the signature.
             
-            if now < (iat - CLOCK_SKEW_LEEWAY):
-                 logger.warning(f'{{"event": "agent_call_denied", "kid": "{kid}", "reason": "clock_skew"}}')
-                 raise VerificationError("Token not yet valid (Clock skew).")
-
-            # 6. Observability
-            iss = payload.get("iss", "unknown")
-            logger.info(f'{{"event": "agent_call_allowed", "iss": "{iss}", "kid": "{kid}"}}')
+        Returns:
+            Dict with X-Capiscio-Badge header.
+        """
+        if self._badge_token:
+            return {"X-Capiscio-Badge": self._badge_token}
+        
+        token = self.sign_outbound(payload, body=body)
+        return {"X-Capiscio-Badge": token}
+    
+    def set_badge_token(self, token: str) -> None:
+        """
+        Update the badge token used for outbound requests.
+        
+        This is typically called by the badge keeper when a new token is obtained.
+        
+        Args:
+            token: The new badge token (compact JWS).
+        """
+        self._badge_token = token
+        logger.debug(f"Updated badge token for agent {self.agent_id}")
 
-            return payload
+    def close(self) -> None:
+        """Close the gRPC connection."""
+        if self._client:
+            self._client.close()
 
-        except jwt.InvalidSignatureError:
-            logger.warning(f'{{"event": "agent_call_denied", "kid": "{kid}", "reason": "invalid_signature"}}')
-            raise VerificationError("Invalid signature.")
-        except jwt.ExpiredSignatureError:
-            logger.warning(f'{{"event": "agent_call_denied", "kid": "{kid}", "reason": "token_expired"}}')
-            raise VerificationError("Token expired.")
-        except jwt.DecodeError:
-            raise VerificationError("Invalid JWS format.")
-        except Exception as e:
-            if isinstance(e, VerificationError):
-                raise
-            raise VerificationError(f"Verification failed: {e}")
+    def __enter__(self) -> "SimpleGuard":
+        return self
 
-    def make_headers(self, payload: Dict[str, Any], body: Optional[bytes] = None) -> Dict[str, str]:
-        """Helper to generate the headers containing the JWS."""
-        token = self.sign_outbound(payload, body=body)
-        return {"X-Capiscio-JWS": token}
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
 
     def _resolve_project_root(self, base_dir: Optional[Union[str, Path]]) -> Path:
         """Walk up the directory tree to find agent-card.json or stop at root."""
         current = Path(base_dir or os.getcwd()).resolve()
         
-        # If we are in dev mode and nothing exists, we might just use cwd
-        # But let's try to find an existing project structure first
         search_path = current
         while search_path != search_path.parent:
             if (search_path / "agent-card.json").exists():
                 return search_path
             search_path = search_path.parent
         
-        # If not found, default to cwd
         return current
 
     def _load_or_generate_card(self) -> None:
         """Load agent-card.json or generate a minimal one in dev_mode."""
+        # If explicit agent_id was provided, use it
+        if self._explicit_agent_id:
+            self.agent_id = self._explicit_agent_id
+            self.signing_kid = "key-0"  # Will be updated when keys are generated/loaded
+            logger.info(f"Using explicit agent_id: {self.agent_id}")
+            return
+            
         if self.agent_card_path.exists():
             try:
                 with open(self.agent_card_path, "r") as f:
                     data = json.load(f)
                     self.agent_id = data.get("agent_id")
-                    # Assuming the first key is the signing key for now, or looking for a specific structure
-                    # The mandate says: "Cache self.agent_id and self.signing_kid"
-                    # We need to find the kid from the keys array.
                     keys = data.get("public_keys", [])
                     if not keys:
-                         raise ConfigurationError("agent-card.json missing 'public_keys'.")
+                        raise ConfigurationError("agent-card.json missing 'public_keys'.")
                     self.signing_kid = keys[0].get("kid")
                     
                     if not self.agent_id or not self.signing_kid:
@@ -249,18 +236,22 @@ class SimpleGuard:
             except Exception as e:
                 raise ConfigurationError(f"Failed to load agent-card.json: {e}")
         elif self.dev_mode:
-            # Generate minimal card
-            logger.info("Dev Mode: Generating minimal agent-card.json")
-            self.agent_id = "local-dev-agent"
+            logger.info("Dev Mode: Will generate did:key identity from keypair")
+            # Placeholder - will be updated with did:key after key generation
+            self.agent_id = "local-dev-agent"  # Temporary, replaced in _load_or_generate_keys
             self.signing_kid = "local-dev-key"
-            
-            # We will populate the JWK part after generating the key in the next step
-            # For now, just set the basics, we'll write the file after key gen
         else:
             raise ConfigurationError(f"agent-card.json not found at {self.project_root}")
 
     def _load_or_generate_keys(self) -> None:
-        """Load private.pem or generate it in dev_mode."""
+        """Load keys or generate them in dev_mode via gRPC.
+        
+        In dev_mode, if no explicit agent_id was provided, updates self.agent_id
+        with the did:key derived from the generated keypair (RFC-002 §6.1).
+        """
+        private_key_path = self.keys_dir / "private.pem"
+        public_key_path = self.keys_dir / "public.pem"
+        
         if not self.keys_dir.exists():
             if self.dev_mode:
                 self.keys_dir.mkdir(parents=True, exist_ok=True)
@@ -268,64 +259,56 @@ class SimpleGuard:
             else:
                 raise ConfigurationError(f"capiscio_keys directory not found at {self.keys_dir}")
 
-        if self.private_key_path.exists():
-            try:
-                with open(self.private_key_path, "rb") as f:
-                    loaded_key = serialization.load_pem_private_key(
-                        f.read(), password=None
-                    )
-                    if not isinstance(loaded_key, ed25519.Ed25519PrivateKey):
-                        raise ConfigurationError("Private key is not an Ed25519 key.")
-                    self._private_key = loaded_key
-            except Exception as e:
-                raise ConfigurationError(f"Failed to load private.pem: {e}")
+        if private_key_path.exists():
+            # Load existing key via gRPC
+            key_info, error = self._client.simpleguard.load_key(str(private_key_path))
+            if error:
+                raise ConfigurationError(f"Failed to load private.pem: {error}")
+            # Update signing kid to match the loaded key
+            self.signing_kid = key_info["key_id"]
+            logger.info(f"Loaded key: {self.signing_kid}")
         elif self.dev_mode:
-            logger.info("Dev Mode: Generating Ed25519 keypair")
-            self._private_key = ed25519.Ed25519PrivateKey.generate()
+            logger.info("Dev Mode: Generating Ed25519 keypair via gRPC")
             
-            # Save Private Key
-            with open(self.private_key_path, "wb") as f:
-                f.write(self._private_key.private_bytes(
-                    encoding=serialization.Encoding.PEM,
-                    format=serialization.PrivateFormat.PKCS8,
-                    encryption_algorithm=serialization.NoEncryption()
-                ))
-            
-            # Save Public Key
-            public_key = self._private_key.public_key()
-            pem_public = public_key.public_bytes(
-                encoding=serialization.Encoding.PEM,
-                format=serialization.PublicFormat.SubjectPublicKeyInfo
+            # Generate via gRPC
+            key_info, error = self._client.simpleguard.generate_key_pair(
+                key_id=self.signing_kid,
             )
-            with open(self.public_key_path, "wb") as f:
-                f.write(pem_public)
-                
-            # Now update agent-card.json with the JWK
-            self._update_agent_card_with_jwk(public_key)
+            if error:
+                raise ConfigurationError(f"Failed to generate keypair: {error}")
+            
+            # Update agent_id with did:key if not explicitly set (RFC-002 §6.1)
+            did_key = key_info.get("did_key")
+            if did_key and not self._explicit_agent_id:
+                self.agent_id = did_key
+                logger.info(f"Dev Mode: Using did:key identity: {self.agent_id}")
+            
+            # Save private key
+            with open(private_key_path, "w") as f:
+                f.write(key_info["private_key_pem"])
+            
+            # Save public key
+            with open(public_key_path, "w") as f:
+                f.write(key_info["public_key_pem"])
+            
+            # Update agent-card.json with JWK
+            self._update_agent_card_with_pem(key_info["public_key_pem"])
         else:
-            raise ConfigurationError(f"private.pem not found at {self.private_key_path}")
+            raise ConfigurationError(f"private.pem not found at {private_key_path}")
 
-    def _update_agent_card_with_jwk(self, public_key: ed25519.Ed25519PublicKey) -> None:
-        """Helper to write the agent-card.json with the generated key."""
-        # Convert Ed25519 public key to JWK parameters
-        # Ed25519 keys are simple: x is the raw bytes
-        raw_bytes = public_key.public_bytes(
-            encoding=serialization.Encoding.Raw,
-            format=serialization.PublicFormat.Raw
-        )
-        x_b64 = base64.urlsafe_b64encode(raw_bytes).decode('utf-8').rstrip('=')
-        
-        jwk = {
-            "kty": "OKP",
-            "crv": "Ed25519",
-            "x": x_b64,
-            "kid": self.signing_kid,
-            "use": "sig"
-        }
-        
+    def _update_agent_card_with_pem(self, public_key_pem: str) -> None:
+        """Helper to write agent-card.json with the generated key."""
+        # For simplicity, just create a minimal card
+        # In production, would convert PEM to JWK
         card_data = {
             "agent_id": self.agent_id,
-            "public_keys": [jwk],
+            "public_keys": [{
+                "kty": "OKP",
+                "crv": "Ed25519",
+                "kid": self.signing_kid,
+                "use": "sig",
+                # Note: x would need to be extracted from PEM
+            }],
             "protocolVersion": "0.3.0",
             "name": "Local Dev Agent",
             "description": "Auto-generated by SimpleGuard",
@@ -346,9 +329,18 @@ class SimpleGuard:
             self.trusted_dir.mkdir(parents=True, exist_ok=True)
             
         if self.dev_mode:
-            # Self-Trust: Copy public.pem to trusted/{kid}.pem
-            self_trust_path = self.trusted_dir / f"{self.signing_kid}.pem"
-            if not self_trust_path.exists() and self.public_key_path.exists():
+            # Self-Trust: Load public key into gRPC server's trust store
+            # Use a different key_id for trust to avoid overwriting the signing key
+            public_key_path = self.keys_dir / "public.pem"
+            trust_key_id = f"{self.signing_kid}-trust"
+            self_trust_path = self.trusted_dir / f"{trust_key_id}.pem"
+            
+            if public_key_path.exists() and not self_trust_path.exists():
                 import shutil
-                shutil.copy(self.public_key_path, self_trust_path)
-                logger.info(f"Dev Mode: Added self-trust for kid {self.signing_kid}")
+                shutil.copy(public_key_path, self_trust_path)
+                logger.info(f"Dev Mode: Added self-trust for kid {trust_key_id}")
+            
+            # Load into gRPC server trust store for verification
+            # (signing key is loaded separately during guard initialization)
+            if self_trust_path.exists():
+                self._client.simpleguard.load_key(str(self_trust_path))