capiscio-sdk 2.3.0__py3-none-any.whl → 2.4.0__py3-none-any.whl

capiscio_sdk/__init__.py

@@ -14,7 +14,7 @@ Example:
     >>> result = validate_agent_card(card_dict)  # Uses Go core
 """
 
-__version__ = "0.3.1"
+__version__ = "2.3.1"
 
 # Core exports
 from .executor import CapiscioSecurityExecutor, secure, secure_agent

capiscio_sdk/_rpc/client.py

@@ -1,6 +1,6 @@
 """gRPC client wrapper for capiscio-core."""
 
-from typing import Optional
+from typing import Generator, Optional
 
 import grpc
 
@@ -9,6 +9,7 @@ from capiscio_sdk._rpc.process import ProcessManager, get_process_manager
 # Import generated stubs
 from capiscio_sdk._rpc.gen.capiscio.v1 import badge_pb2, badge_pb2_grpc
 from capiscio_sdk._rpc.gen.capiscio.v1 import did_pb2, did_pb2_grpc
+from capiscio_sdk._rpc.gen.capiscio.v1 import mcp_pb2, mcp_pb2_grpc
 from capiscio_sdk._rpc.gen.capiscio.v1 import trust_pb2, trust_pb2_grpc
 from capiscio_sdk._rpc.gen.capiscio.v1 import revocation_pb2, revocation_pb2_grpc
 from capiscio_sdk._rpc.gen.capiscio.v1 import scoring_pb2, scoring_pb2_grpc
@@ -59,6 +60,7 @@ class CapiscioRPCClient:
         # Service stubs (initialized on connect)
         self._badge_stub: Optional[badge_pb2_grpc.BadgeServiceStub] = None
         self._did_stub: Optional[did_pb2_grpc.DIDServiceStub] = None
+        self._mcp_stub: Optional[mcp_pb2_grpc.MCPServiceStub] = None
         self._trust_stub: Optional[trust_pb2_grpc.TrustStoreServiceStub] = None
         self._revocation_stub: Optional[revocation_pb2_grpc.RevocationServiceStub] = None
         self._scoring_stub: Optional[scoring_pb2_grpc.ScoringServiceStub] = None
@@ -68,6 +70,7 @@ class CapiscioRPCClient:
         # Service wrappers
         self._badge: Optional["BadgeClient"] = None
         self._did: Optional["DIDClient"] = None
+        self._mcp: Optional["MCPClient"] = None
         self._trust: Optional["TrustStoreClient"] = None
         self._revocation: Optional["RevocationClient"] = None
         self._scoring: Optional["ScoringClient"] = None
@@ -103,6 +106,7 @@ class CapiscioRPCClient:
         # Initialize stubs
         self._badge_stub = badge_pb2_grpc.BadgeServiceStub(self._channel)
         self._did_stub = did_pb2_grpc.DIDServiceStub(self._channel)
+        self._mcp_stub = mcp_pb2_grpc.MCPServiceStub(self._channel)
         self._trust_stub = trust_pb2_grpc.TrustStoreServiceStub(self._channel)
         self._revocation_stub = revocation_pb2_grpc.RevocationServiceStub(self._channel)
         self._scoring_stub = scoring_pb2_grpc.ScoringServiceStub(self._channel)
@@ -112,6 +116,7 @@ class CapiscioRPCClient:
         # Initialize service wrappers
         self._badge = BadgeClient(self._badge_stub)
         self._did = DIDClient(self._did_stub)
+        self._mcp = MCPClient(self._mcp_stub)
         self._trust = TrustStoreClient(self._trust_stub)
         self._revocation = RevocationClient(self._revocation_stub)
         self._scoring = ScoringClient(self._scoring_stub)
@@ -129,6 +134,7 @@ class CapiscioRPCClient:
         # Clear stubs
         self._badge_stub = None
         self._did_stub = None
+        self._mcp_stub = None
         self._trust_stub = None
         self._revocation_stub = None
         self._scoring_stub = None
@@ -159,6 +165,13 @@ class CapiscioRPCClient:
         assert self._did is not None
         return self._did
     
+    @property
+    def mcp(self) -> "MCPClient":
+        """Access the MCPService (RFC-006 / RFC-007)."""
+        self._ensure_connected()
+        assert self._mcp is not None
+        return self._mcp
+    
     @property
     def trust(self) -> "TrustStoreClient":
         """Access the TrustStoreService."""
@@ -501,7 +514,7 @@ class BadgeClient:
         renew_before_seconds: int = 60,
         check_interval_seconds: int = 30,
         trust_level: int = 1,
-    ):
+    ) -> Generator[dict, None, None]:
         """Start a badge keeper daemon (RFC-002 §7.3).
         
         The keeper automatically renews badges before they expire, ensuring
@@ -521,8 +534,8 @@ class BadgeClient:
             trust_level: Trust level for CA mode (1-4, default: 1)
             
         Yields:
-            KeeperEvent dicts with: type, badge_jti, subject, trust_level,
-            expires_at, error, error_code, timestamp, token
+            dict: KeeperEvent dicts with keys: type, badge_jti, subject, trust_level,
+                expires_at, error, error_code, timestamp, token
             
         Example:
             # CA mode
@@ -1264,6 +1277,395 @@ class SimpleGuardClient:
         }, None
 
 
+class MCPClient:
+    """Client wrapper for MCPService (RFC-006 Tool Authority + RFC-007 Server Identity).
+    
+    This client provides access to MCP security operations including:
+    - Tool access evaluation (RFC-006 §6.2-6.4)
+    - Server identity verification (RFC-007 §7.2)
+    - Server identity parsing from HTTP/JSON-RPC transports
+    
+    Example:
+        from capiscio_sdk._rpc.client import CapiscioRPCClient
+        
+        client = CapiscioRPCClient()
+        client.connect()
+        
+        # Evaluate tool access with a badge
+        result = client.mcp.evaluate_tool_access(
+            tool_name="write_file",
+            params_hash="abc123",
+            server_origin="https://files.example.com",
+            badge_jws=badge_token,
+        )
+        
+        if result["decision"] == "allow":
+            print(f"Tool access granted for {result['agent_did']}")
+        else:
+            print(f"Access denied: {result['deny_reason']}")
+            
+        # Verify server identity
+        server_result = client.mcp.verify_server_identity(
+            server_did="did:web:example.com:mcp:files",
+            server_badge=server_badge,
+            transport_origin="https://files.example.com",
+        )
+    """
+    
+    def __init__(self, stub: mcp_pb2_grpc.MCPServiceStub) -> None:
+        self._stub = stub
+    
+    def evaluate_tool_access(
+        self,
+        tool_name: str,
+        params_hash: str = "",
+        server_origin: str = "",
+        *,
+        badge_jws: Optional[str] = None,
+        api_key: Optional[str] = None,
+        policy_version: str = "",
+        trusted_issuers: Optional[list[str]] = None,
+        min_trust_level: int = 0,
+        accept_level_zero: bool = False,
+        allowed_tools: Optional[list[str]] = None,
+    ) -> dict:
+        """Evaluate tool access request (RFC-006 §6.2-6.4).
+        
+        Evaluates whether a caller (identified by badge or API key) is
+        authorized to invoke a specific tool. Returns both a decision
+        and evidence record atomically.
+        
+        Args:
+            tool_name: Name of the tool being invoked
+            params_hash: Hash of the tool parameters (for audit)
+            server_origin: Origin of the MCP server handling the request
+            badge_jws: Caller's badge JWT (for badged access)
+            api_key: Caller's API key (for API key access)
+            policy_version: Optional policy version to use
+            trusted_issuers: List of trusted badge issuers
+            min_trust_level: Minimum required trust level (0-4)
+            accept_level_zero: Accept self-signed (level 0) badges
+            allowed_tools: Explicit list of allowed tools (if set, tool_name must match)
+            
+        Returns:
+            Dict with:
+                decision: "allow" or "deny"
+                deny_reason: Reason if denied (e.g., "badge_missing", "trust_insufficient")
+                deny_detail: Detailed error message if denied
+                agent_did: DID of the authenticated agent (if authenticated)
+                badge_jti: Badge JTI (if badge was used)
+                auth_level: Authentication level ("anonymous", "api_key", "badge")
+                trust_level: Agent's trust level (0-4)
+                evidence_json: RFC-006 §7 evidence record as JSON
+                evidence_id: Unique evidence record ID
+                timestamp: Evaluation timestamp (ISO format)
+                
+        Example:
+            # Evaluate with badge
+            result = client.mcp.evaluate_tool_access(
+                tool_name="write_file",
+                params_hash=hashlib.sha256(json.dumps(params).encode()).hexdigest(),
+                server_origin="https://files.example.com",
+                badge_jws=badge_token,
+                min_trust_level=2,  # Require OV or higher
+            )
+            
+            if result["decision"] == "allow":
+                # Proceed with tool execution
+                pass
+            else:
+                raise PermissionError(result["deny_detail"])
+        """
+        # Build config
+        config = mcp_pb2.EvaluateConfig(
+            trusted_issuers=trusted_issuers or [],
+            min_trust_level=min_trust_level,
+            accept_level_zero=accept_level_zero,
+            allowed_tools=allowed_tools or [],
+        )
+        
+        # Build request with caller credential
+        request = mcp_pb2.EvaluateToolAccessRequest(
+            tool_name=tool_name,
+            params_hash=params_hash,
+            server_origin=server_origin,
+            policy_version=policy_version,
+            config=config,
+        )
+        
+        # Set credential (badge or api_key, mutually exclusive)
+        if badge_jws:
+            request.badge_jws = badge_jws
+        elif api_key:
+            request.api_key = api_key
+        
+        response = self._stub.EvaluateToolAccess(request)
+        
+        # Map enums to strings
+        decision_map = {
+            mcp_pb2.MCP_DECISION_UNSPECIFIED: "unspecified",
+            mcp_pb2.MCP_DECISION_ALLOW: "allow",
+            mcp_pb2.MCP_DECISION_DENY: "deny",
+        }
+        
+        deny_reason_map = {
+            mcp_pb2.MCP_DENY_REASON_UNSPECIFIED: "",
+            mcp_pb2.MCP_DENY_REASON_BADGE_MISSING: "badge_missing",
+            mcp_pb2.MCP_DENY_REASON_BADGE_INVALID: "badge_invalid",
+            mcp_pb2.MCP_DENY_REASON_BADGE_EXPIRED: "badge_expired",
+            mcp_pb2.MCP_DENY_REASON_BADGE_REVOKED: "badge_revoked",
+            mcp_pb2.MCP_DENY_REASON_TRUST_INSUFFICIENT: "trust_insufficient",
+            mcp_pb2.MCP_DENY_REASON_TOOL_NOT_ALLOWED: "tool_not_allowed",
+            mcp_pb2.MCP_DENY_REASON_ISSUER_UNTRUSTED: "issuer_untrusted",
+            mcp_pb2.MCP_DENY_REASON_POLICY_DENIED: "policy_denied",
+        }
+        
+        auth_level_map = {
+            mcp_pb2.MCP_AUTH_LEVEL_UNSPECIFIED: "unspecified",
+            mcp_pb2.MCP_AUTH_LEVEL_ANONYMOUS: "anonymous",
+            mcp_pb2.MCP_AUTH_LEVEL_API_KEY: "api_key",
+            mcp_pb2.MCP_AUTH_LEVEL_BADGE: "badge",
+        }
+        
+        # Format timestamp
+        timestamp_str = ""
+        if response.timestamp:
+            from datetime import datetime, timezone
+            timestamp_str = datetime.fromtimestamp(
+                response.timestamp.seconds + response.timestamp.nanos / 1e9,
+                timezone.utc
+            ).isoformat()
+        
+        return {
+            "decision": decision_map.get(response.decision, "unspecified"),
+            "deny_reason": deny_reason_map.get(response.deny_reason, ""),
+            "deny_detail": response.deny_detail,
+            "agent_did": response.agent_did,
+            "badge_jti": response.badge_jti,
+            "auth_level": auth_level_map.get(response.auth_level, "unspecified"),
+            "trust_level": response.trust_level,
+            "evidence_json": response.evidence_json,
+            "evidence_id": response.evidence_id,
+            "timestamp": timestamp_str,
+        }
+    
+    def verify_server_identity(
+        self,
+        server_did: str,
+        server_badge: str = "",
+        transport_origin: str = "",
+        endpoint_path: str = "",
+        *,
+        trusted_issuers: Optional[list[str]] = None,
+        min_trust_level: int = 0,
+        accept_level_zero: bool = False,
+        offline_mode: bool = False,
+        skip_origin_binding: bool = False,
+    ) -> dict:
+        """Verify MCP server identity (RFC-007 §7.2).
+        
+        Verifies a server's disclosed identity (DID + badge) and checks
+        that it matches the transport origin. Returns the verification
+        state and any errors.
+        
+        Args:
+            server_did: Server's DID (did:web:... or did:key:...)
+            server_badge: Server's badge JWT (optional for level 0)
+            transport_origin: Origin from the transport (e.g., "https://files.example.com")
+            endpoint_path: Endpoint path being accessed
+            trusted_issuers: List of trusted badge issuers
+            min_trust_level: Minimum required trust level (0-4)
+            accept_level_zero: Accept self-signed (level 0) servers
+            offline_mode: Skip online validation (use cache only)
+            skip_origin_binding: Skip transport origin binding check (RFC-007 §5.3)
+            
+        Returns:
+            Dict with:
+                state: Server state ("verified_principal", "declared_principal", "unverified_origin")
+                trust_level: Server's trust level (0-4)
+                server_did: Verified server DID
+                badge_jti: Server badge JTI (if badge was provided)
+                error_code: Error code if verification failed
+                error_detail: Detailed error message
+                
+        Example:
+            # Verify server before trusting tool results
+            result = client.mcp.verify_server_identity(
+                server_did="did:web:files.example.com:mcp:files",
+                server_badge=server_badge_token,
+                transport_origin="https://files.example.com",
+                min_trust_level=1,  # Require at least DV
+            )
+            
+            if result["state"] == "verified_principal":
+                print(f"Server verified at trust level {result['trust_level']}")
+            else:
+                print(f"Server verification failed: {result['error_detail']}")
+        """
+        # Build config
+        config = mcp_pb2.MCPVerifyConfig(
+            trusted_issuers=trusted_issuers or [],
+            min_trust_level=min_trust_level,
+            accept_level_zero=accept_level_zero,
+            offline_mode=offline_mode,
+            skip_origin_binding=skip_origin_binding,
+        )
+        
+        request = mcp_pb2.VerifyServerIdentityRequest(
+            server_did=server_did,
+            server_badge=server_badge,
+            transport_origin=transport_origin,
+            endpoint_path=endpoint_path,
+            config=config,
+        )
+        
+        response = self._stub.VerifyServerIdentity(request)
+        
+        # Map enums to strings
+        state_map = {
+            mcp_pb2.MCP_SERVER_STATE_UNSPECIFIED: "unspecified",
+            mcp_pb2.MCP_SERVER_STATE_VERIFIED_PRINCIPAL: "verified_principal",
+            mcp_pb2.MCP_SERVER_STATE_DECLARED_PRINCIPAL: "declared_principal",
+            mcp_pb2.MCP_SERVER_STATE_UNVERIFIED_ORIGIN: "unverified_origin",
+        }
+        
+        error_code_map = {
+            mcp_pb2.MCP_SERVER_ERROR_NONE: "",
+            mcp_pb2.MCP_SERVER_ERROR_DID_INVALID: "did_invalid",
+            mcp_pb2.MCP_SERVER_ERROR_BADGE_INVALID: "badge_invalid",
+            mcp_pb2.MCP_SERVER_ERROR_BADGE_EXPIRED: "badge_expired",
+            mcp_pb2.MCP_SERVER_ERROR_BADGE_REVOKED: "badge_revoked",
+            mcp_pb2.MCP_SERVER_ERROR_TRUST_INSUFFICIENT: "trust_insufficient",
+            mcp_pb2.MCP_SERVER_ERROR_ORIGIN_MISMATCH: "origin_mismatch",
+            mcp_pb2.MCP_SERVER_ERROR_PATH_MISMATCH: "path_mismatch",
+            mcp_pb2.MCP_SERVER_ERROR_ISSUER_UNTRUSTED: "issuer_untrusted",
+        }
+        
+        return {
+            "state": state_map.get(response.state, "unspecified"),
+            "trust_level": response.trust_level,
+            "server_did": response.server_did,
+            "badge_jti": response.badge_jti,
+            "error_code": error_code_map.get(response.error_code, ""),
+            "error_detail": response.error_detail,
+        }
+    
+    def parse_server_identity_http(
+        self,
+        capiscio_server_did: str = "",
+        capiscio_server_badge: str = "",
+    ) -> dict:
+        """Parse server identity from HTTP headers (RFC-007 §5.2).
+        
+        Extracts server identity from HTTP headers. Use this before
+        verify_server_identity() to extract the DID and badge.
+        
+        Args:
+            capiscio_server_did: Value of Capiscio-Server-DID header
+            capiscio_server_badge: Value of Capiscio-Server-Badge header
+            
+        Returns:
+            Dict with:
+                server_did: Extracted server DID
+                server_badge: Extracted server badge JWT
+                identity_present: Whether identity was present
+                
+        Example:
+            # Extract from HTTP headers
+            headers = response.headers
+            identity = client.mcp.parse_server_identity_http(
+                capiscio_server_did=headers.get("Capiscio-Server-DID", ""),
+                capiscio_server_badge=headers.get("Capiscio-Server-Badge", ""),
+            )
+            
+            if identity["identity_present"]:
+                # Verify the extracted identity
+                result = client.mcp.verify_server_identity(
+                    server_did=identity["server_did"],
+                    server_badge=identity["server_badge"],
+                    transport_origin="https://files.example.com",
+                )
+        """
+        http_headers = mcp_pb2.MCPHttpHeaders(
+            capiscio_server_did=capiscio_server_did,
+            capiscio_server_badge=capiscio_server_badge,
+        )
+        
+        request = mcp_pb2.ParseServerIdentityRequest(http_headers=http_headers)
+        response = self._stub.ParseServerIdentity(request)
+        
+        return {
+            "server_did": response.server_did,
+            "server_badge": response.server_badge,
+            "identity_present": response.identity_present,
+        }
+    
+    def parse_server_identity_jsonrpc(self, meta_json: str) -> dict:
+        """Parse server identity from JSON-RPC _meta (RFC-007 §5.3).
+        
+        Extracts server identity from JSON-RPC _meta field. Use this
+        for stdio transport or any JSON-RPC based MCP connection.
+        
+        Args:
+            meta_json: JSON string of the _meta object containing
+                       "serverDid" and "serverBadge" fields
+            
+        Returns:
+            Dict with:
+                server_did: Extracted server DID
+                server_badge: Extracted server badge JWT
+                identity_present: Whether identity was present
+                
+        Example:
+            # Extract from JSON-RPC response
+            meta = response.get("_meta", {})
+            identity = client.mcp.parse_server_identity_jsonrpc(
+                meta_json=json.dumps(meta)
+            )
+            
+            if identity["identity_present"]:
+                # Verify the extracted identity
+                result = client.mcp.verify_server_identity(
+                    server_did=identity["server_did"],
+                    server_badge=identity["server_badge"],
+                    transport_origin="",  # N/A for stdio
+                )
+        """
+        jsonrpc_meta = mcp_pb2.MCPJsonRpcMeta(meta_json=meta_json)
+        
+        request = mcp_pb2.ParseServerIdentityRequest(jsonrpc_meta=jsonrpc_meta)
+        response = self._stub.ParseServerIdentity(request)
+        
+        return {
+            "server_did": response.server_did,
+            "server_badge": response.server_badge,
+            "identity_present": response.identity_present,
+        }
+    
+    def health(self, client_version: str = "") -> dict:
+        """Check MCP service health and version compatibility.
+        
+        Args:
+            client_version: Client's version for compatibility check
+            
+        Returns:
+            Dict with:
+                healthy: Whether service is healthy
+                core_version: capiscio-core version
+                proto_version: Proto/gRPC version
+                version_compatible: Whether versions are compatible
+        """
+        request = mcp_pb2.MCPHealthRequest(client_version=client_version)
+        response = self._stub.Health(request)
+        
+        return {
+            "healthy": response.healthy,
+            "core_version": response.core_version,
+            "proto_version": response.proto_version,
+            "version_compatible": response.version_compatible,
+        }
+
+
 class RegistryClient:
     """Client wrapper for RegistryService."""
     

capiscio_sdk/badge.py

@@ -30,7 +30,7 @@ Example usage:
 from dataclasses import dataclass, field
 from datetime import datetime
 from enum import Enum
-from typing import List, Optional, Union
+from typing import Generator, List, Optional, Union
 
 from capiscio_sdk._rpc.client import CapiscioRPCClient
 
@@ -64,16 +64,30 @@ class VerifyMode(Enum):
 
 
 class TrustLevel(Enum):
-    """Trust level as defined in RFC-002."""
+    """Trust level as defined in RFC-002 §5.
+    
+    Levels:
+        LEVEL_0 (SS): Self-Signed - did:key, iss == sub. Development only.
+        LEVEL_1 (REG): Registered - Account registration with CA.
+        LEVEL_2 (DV): Domain Validated - DNS/HTTP domain ownership proof.
+        LEVEL_3 (OV): Organization Validated - Legal entity verification.
+        LEVEL_4 (EV): Extended Validated - Manual review + security audit.
+    """
+
+    LEVEL_0 = "0"
+    """Self-Signed (SS) - did:key, iss == sub. Development only."""
 
     LEVEL_1 = "1"
-    """Domain Validated (DV) - Basic verification."""
+    """Registered (REG) - Account registration with CA."""
 
     LEVEL_2 = "2"
-    """Organization Validated (OV) - Business verification."""
+    """Domain Validated (DV) - DNS/HTTP domain ownership proof."""
 
     LEVEL_3 = "3"
-    """Extended Validation (EV) - Rigorous vetting."""
+    """Organization Validated (OV) - Legal entity verification."""
+
+    LEVEL_4 = "4"
+    """Extended Validated (EV) - Manual review + security audit."""
 
     @classmethod
     def from_string(cls, value: str) -> "TrustLevel":
@@ -81,7 +95,7 @@ class TrustLevel(Enum):
         for level in cls:
             if level.value == value:
                 return level
-        raise ValueError(f"Unknown trust level: {value}")
+        raise ValueError(f"Unknown trust level: {value}. Valid levels: 0 (SS), 1 (REG), 2 (DV), 3 (OV), 4 (EV)")
 
 
 @dataclass
@@ -90,15 +104,24 @@ class BadgeClaims:
 
     Attributes:
         jti: Unique badge identifier (UUID).
-        issuer: Badge issuer URL (CA).
+        issuer: Badge issuer URL (CA) or did:key for self-signed.
         subject: Agent DID (did:web format).
         audience: Optional list of intended audience URLs.
         issued_at: When the badge was issued.
         expires_at: When the badge expires.
-        trust_level: Trust level (1=DV, 2=OV, 3=EV).
+        trust_level: Trust level per RFC-002 §5:
+            - 0 (SS): Self-Signed - Development only
+            - 1 (REG): Registered - Account registration
+            - 2 (DV): Domain Validated - DNS/HTTP proof
+            - 3 (OV): Organization Validated - Legal entity
+            - 4 (EV): Extended Validated - Security audit
         domain: Agent's verified domain.
         agent_name: Human-readable agent name.
         agent_id: Extracted agent ID from subject DID.
+        ial: Identity Assurance Level (RFC-002 §7.2.1):
+            - "0": Account-attested (no key proof)
+            - "1": Proof of Possession (key holder verified, has cnf claim)
+        raw_claims: Original JWT claims dict for advanced access.
     """
 
     jti: str
@@ -110,6 +133,8 @@ class BadgeClaims:
     domain: str
     agent_name: str = ""
     audience: List[str] = field(default_factory=list)
+    ial: str = "0"  # RFC-002 §7.2.1: Default IAL-0 (account-attested)
+    raw_claims: Optional[dict] = field(default=None, repr=False)  # For advanced access
 
     @property
     def agent_id(self) -> str:
@@ -133,6 +158,11 @@ class BadgeClaims:
     @classmethod
     def from_dict(cls, data: dict) -> "BadgeClaims":
         """Create BadgeClaims from a dictionary."""
+        # Handle audience - can be string or list
+        aud = data.get("aud", [])
+        if isinstance(aud, str):
+            aud = [aud] if aud else []
+        
         return cls(
             jti=data.get("jti", ""),
             issuer=data.get("iss", ""),
@@ -142,12 +172,18 @@ class BadgeClaims:
             trust_level=TrustLevel.from_string(data.get("trust_level", "1")),
             domain=data.get("domain", ""),
             agent_name=data.get("agent_name", ""),
-            audience=data.get("aud", []),
+            audience=aud,
+            ial=data.get("ial", "0"),  # RFC-002 §7.2.1
+            raw_claims=data,  # Preserve for advanced access (cnf, key, etc.)
         )
 
     def to_dict(self) -> dict:
-        """Convert to dictionary."""
-        return {
+        """Convert to dictionary.
+        
+        Preserves the cnf (confirmation) claim for IAL-1 badges to support
+        round-trip serialization.
+        """
+        result = {
             "jti": self.jti,
             "iss": self.issuer,
             "sub": self.subject,
@@ -157,7 +193,36 @@ class BadgeClaims:
             "domain": self.domain,
             "agent_name": self.agent_name,
             "aud": self.audience,
+            "ial": self.ial,
         }
+        # Preserve cnf claim for IAL-1 / key-bound badges if it was present
+        if self.raw_claims is not None and "cnf" in self.raw_claims:
+            result["cnf"] = self.raw_claims["cnf"]
+        return result
+    
+    @property
+    def has_key_binding(self) -> bool:
+        """Check if this badge has IAL-1 key binding (ial='1' and cnf claim).
+        
+        Per RFC-002 §7.2.1, IAL-1 badges MUST include a 'cnf' (confirmation) claim
+        that cryptographically binds the badge to the agent's private key.
+        """
+        return (
+            self.ial == "1"
+            and self.raw_claims is not None
+            and "cnf" in self.raw_claims
+        )
+    
+    @property
+    def confirmation_key(self) -> Optional[dict]:
+        """Get the confirmation key (cnf claim) if present.
+        
+        Returns the JWK thumbprint or key from the cnf claim for IAL-1 badges.
+        Returns None for IAL-0 badges or if cnf is not present.
+        """
+        if self.raw_claims is None:
+            return None
+        return self.raw_claims.get("cnf")
 
 
 @dataclass
@@ -454,7 +519,12 @@ async def request_badge(
         ca_url: Certificate Authority URL (default: CapiscIO registry).
         api_key: API key for authentication with the CA.
         domain: Agent's domain (required for verification).
-        trust_level: Requested trust level (1=DV, 2=OV, 3=EV).
+        trust_level: Requested trust level per RFC-002 §5:
+            - 1 (REG): Registered - Account registration
+            - 2 (DV): Domain Validated - DNS/HTTP proof
+            - 3 (OV): Organization Validated - Legal entity
+            - 4 (EV): Extended Validated - Security audit
+            Note: LEVEL_0 (Self-Signed) is not available via CA request.
         audience: Optional audience restrictions for the badge.
         timeout: Request timeout in seconds (not used with gRPC).
 
@@ -652,7 +722,7 @@ def start_badge_keeper(
     renew_before_seconds: int = 60,
     check_interval_seconds: int = 30,
     trust_level: Union[TrustLevel, str, int] = TrustLevel.LEVEL_1,
-):
+) -> Generator[dict, None, None]:
     """Start a badge keeper daemon (RFC-002 §7.3).
     
     The keeper automatically renews badges before they expire, ensuring
@@ -672,8 +742,8 @@ def start_badge_keeper(
         trust_level: Trust level for CA mode (1-4, default: 1)
         
     Yields:
-        KeeperEvent dicts with: type, badge_jti, subject, trust_level,
-        expires_at, error, error_code, timestamp, token
+        dict: KeeperEvent dicts with keys: type, badge_jti, subject, trust_level,
+            expires_at, error, error_code, timestamp, token
         
     Example:
         # CA mode - production

capiscio_sdk/integrations/fastapi.py

@@ -1,5 +1,5 @@
 """FastAPI integration for Capiscio SimpleGuard."""
-from typing import Callable, Awaitable, Any, Dict
+from typing import Callable, Awaitable, Any, Dict, List, Optional
 try:
     from starlette.middleware.base import BaseHTTPMiddleware
     from starlette.requests import Request
@@ -15,22 +15,34 @@ import time
 class CapiscioMiddleware(BaseHTTPMiddleware):
     """
     Middleware to enforce A2A identity verification on incoming requests.
+    
+    Args:
+        app: The ASGI application.
+        guard: SimpleGuard instance for verification.
+        exclude_paths: List of paths to skip verification (e.g., ["/health", "/.well-known/agent-card.json"]).
     """
-    def __init__(self, app: ASGIApp, guard: SimpleGuard) -> None:
+    def __init__(
+        self, 
+        app: ASGIApp, 
+        guard: SimpleGuard, 
+        exclude_paths: Optional[List[str]] = None
+    ) -> None:
         super().__init__(app)
         self.guard = guard
+        self.exclude_paths = exclude_paths or []
 
     async def dispatch(
         self, 
         request: Request, 
         call_next: Callable[[Request], Awaitable[Response]]
     ) -> Response:
-        # Allow health checks or public endpoints if needed
-        # For now, we assume everything under /agent/ needs protection
-        # But let's just check for the header.
-        
+        # Allow CORS preflight
         if request.method == "OPTIONS":
             return await call_next(request)
+        
+        # Skip verification for excluded paths
+        if request.url.path in self.exclude_paths:
+            return await call_next(request)
 
         # RFC-002 §9.1: X-Capiscio-Badge header
         auth_header = request.headers.get("X-Capiscio-Badge")

capiscio_sdk/validators/message.py

@@ -1,7 +1,8 @@
 """Message validation logic."""
 from typing import TYPE_CHECKING, Any, Dict, List
 from ..types import ValidationResult, ValidationIssue, ValidationSeverity
-from ..scoring import TrustScorer, AvailabilityScorer
+# Import legacy scorer directly to avoid deprecation warning (we only use score_not_tested)
+from ..scoring.availability import AvailabilityScorer as _LegacyAvailabilityScorer
 
 if TYPE_CHECKING:
     from ..scoring.types import ComplianceScore
@@ -19,8 +20,8 @@ class MessageValidator:
     def __init__(self) -> None:
         """Initialize message validator."""
         self._url_validator = URLSecurityValidator()
-        self._trust_scorer = TrustScorer()
-        self._availability_scorer = AvailabilityScorer()
+        # Use legacy scorer directly (not the deprecated wrapper) for score_not_tested()
+        self._availability_scorer = _LegacyAvailabilityScorer()
 
     def validate(self, message: Dict[str, Any], skip_signature_verification: bool = True) -> ValidationResult:
         """

{capiscio_sdk-2.3.0.dist-info → capiscio_sdk-2.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capiscio-sdk
-Version: 2.3.0
+Version: 2.4.0
 Summary: Runtime security middleware for A2A agents
 Project-URL: Homepage, https://capisc.io
 Project-URL: Documentation, https://docs.capisc.io/sdk-python

{capiscio_sdk-2.3.0.dist-info → capiscio_sdk-2.4.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
-capiscio_sdk/__init__.py,sha256=obPQ1c-sPLj8DOMUKtJwbHhy_kO9nVjOd8wYx5kesUo,2683
-capiscio_sdk/badge.py,sha256=6dGyv12oweTVRf5L7mZqNDW5LYAnruOGmJAvepCzTVI,24219
+capiscio_sdk/__init__.py,sha256=s4wpl1PgPbYiF75ArKjBNSlkmXPqnzm99YzkWMcx3UY,2683
+capiscio_sdk/badge.py,sha256=nUdsJNtUfSD-wWpIpeyzoM7JsBbkoLpxsQRKQAmtpkE,27446
 capiscio_sdk/badge_keeper.py,sha256=JrxksWiGM7zfKi8BxCqVbVfg4RKEQELH0rUx3Jf-nfg,10900
 capiscio_sdk/config.py,sha256=-1KNubnRE06SENRXcnGvrj-y1EfKz2uAMdz7s0n6ark,3972
 capiscio_sdk/dv.py,sha256=wCHjkWTpeKR0INcrusYG-ub3-rnI-e3JiO0nWgaKoF4,8078
@@ -9,13 +9,13 @@ capiscio_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 capiscio_sdk/simple_guard.py,sha256=ZOmJQCN0MVud07pqAzFJYf0tYBkwMv2t2zXUKC6IDLg,13717
 capiscio_sdk/types.py,sha256=A_0SLhrbX7apkH5yYGTkG-_284xRjCK0N3lEseVRJRs,7978
 capiscio_sdk/_rpc/__init__.py,sha256=nMnCp5CIisoEA2SX3tYgLprAOyMxVxFfKIWj3glkneA,275
-capiscio_sdk/_rpc/client.py,sha256=_CYmNhOQp1suZt9-5I3mm53Y_cEjDeWkwuQMOlgAhAA,47104
+capiscio_sdk/_rpc/client.py,sha256=8XNDx4TeWzkZcv1oSlyhSuBerUkJuVjt23WsADkwWzo,63639
 capiscio_sdk/_rpc/process.py,sha256=5jyPUDT3Ig1x2UXhAPWPuKqQScAeMkzvs8USshqYrCM,7445
 capiscio_sdk/_rpc/gen/__init__.py,sha256=JgqmySPbQjyx56NVnyIe_BvNdjwWy-or_OcZPomydYE,29
 capiscio_sdk/infrastructure/__init__.py,sha256=5yK7kbk1tcHqlnFIN0lR5N_4ZWWquNivLfHkXOAtso0,152
 capiscio_sdk/infrastructure/cache.py,sha256=FjIRRzNbsPxFZrxdeek51IwFSmR682Wpj1bvvmgqwiU,1841
 capiscio_sdk/infrastructure/rate_limiter.py,sha256=7Q_GfcooWKjioDeB46PpPb00laDmkLpUYGM0Ui8nXqI,3642
-capiscio_sdk/integrations/fastapi.py,sha256=zww7Pg8OMG7Ts03Omq1-1h4ZRR08819FpsTkHW-M8Ak,2949
+capiscio_sdk/integrations/fastapi.py,sha256=EQ28RmG6Gu_DTamMxH0jFZmWW4d6rzvSk4CBkmx070s,3308
 capiscio_sdk/scoring/__init__.py,sha256=ldC3WyM7jbcGjsEWQK_anB7VjG8y9mZMbNaBUwPgRrY,3621
 capiscio_sdk/scoring/availability.py,sha256=CzXA1ED48U1Cc06sh0Mtl_kxZP6af-9cceBumTXQhO8,9130
 capiscio_sdk/scoring/compliance.py,sha256=JZyYuT18A_eiDNdOz-doTIYwW6YhVPvfRj_siNAkkTY,9780
@@ -25,12 +25,12 @@ capiscio_sdk/validators/__init__.py,sha256=q1UjIFUkztKgfC-5N8mGb-zfET3vsEbKbxtN7
 capiscio_sdk/validators/_core.py,sha256=S76QX_KTdqDbuQPy9WxV2Z0jP4o1H65rABWBwp_6R74,13301
 capiscio_sdk/validators/agent_card.py,sha256=d8VfGXvtHiuU0DuC1W64Z_JPVqOVh-nRMVShOAznJbk,18506
 capiscio_sdk/validators/certificate.py,sha256=7RguWk9ahtrxe3TuRqiv5t5vBGta_cUp4qjcx7GwAl0,14373
-capiscio_sdk/validators/message.py,sha256=TGVCAwFHcen1v9KLK5UtxVXq61yOqOnd4yudxSxFMmw,15472
+capiscio_sdk/validators/message.py,sha256=vQ8LJGmKL_P_V3oicr15j9dLgwLDjNtUkhbpKngt1ho,15646
 capiscio_sdk/validators/protocol.py,sha256=bkaJJXseulTJ4Sdiio8gE8Q_Pyqj0BRsJe6BGHSQSnA,5377
 capiscio_sdk/validators/semver.py,sha256=mlF3GO5ZPA-w6FzSxhjcr56sgCdS0YVVAd1dUr1bxWs,6385
 capiscio_sdk/validators/signature.py,sha256=lI8XzaKfG_dXSOQXZ40Lda0ntga9EqqC4zAId2kOt6g,8072
 capiscio_sdk/validators/url_security.py,sha256=SdpOrB48hrfgAMuLvpWH2P0LLCJtg6QBohGDIye8f1E,9802
-capiscio_sdk-2.3.0.dist-info/METADATA,sha256=esm8I3-_3y1S0VFgtzreTQtURLwTIJdCDpLiGtZx0cs,17302
-capiscio_sdk-2.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-capiscio_sdk-2.3.0.dist-info/licenses/LICENSE,sha256=AMM_E-ILcCpX0JALqX3BL9yfgSx654BtkhX-CBFYp1Q,10758
-capiscio_sdk-2.3.0.dist-info/RECORD,,
+capiscio_sdk-2.4.0.dist-info/METADATA,sha256=G2WODrHlhYHQqNdGhGbQxGC4M36kIpeDcQ5VFOdwy_g,17302
+capiscio_sdk-2.4.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+capiscio_sdk-2.4.0.dist-info/licenses/LICENSE,sha256=AMM_E-ILcCpX0JALqX3BL9yfgSx654BtkhX-CBFYp1Q,10758
+capiscio_sdk-2.4.0.dist-info/RECORD,,