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

capiscio_sdk/badge_keeper.py

@@ -0,0 +1,304 @@
+"""BadgeKeeper - Automatic badge renewal for continuous operation.
+
+BadgeKeeper monitors badge expiration and automatically renews badges
+before they expire, ensuring uninterrupted agent authentication.
+
+Example:
+    >>> from capiscio_sdk import BadgeKeeper, SimpleGuard
+    >>> 
+    >>> # Basic usage
+    >>> keeper = BadgeKeeper(
+    ...     api_url="https://registry.capisc.io",
+    ...     api_key="your-api-key",
+    ...     agent_id="your-agent-id",
+    ...     renewal_threshold=10,  # Renew 10s before expiry
+    ... )
+    >>> keeper.start()
+    >>> # Badge automatically renews in background
+    >>> current_badge = keeper.get_current_badge()
+    >>> keeper.stop()
+    >>> 
+    >>> # Integration with SimpleGuard
+    >>> guard = SimpleGuard()
+    >>> keeper = BadgeKeeper(
+    ...     api_url="https://registry.capisc.io",
+    ...     api_key="your-api-key",
+    ...     agent_id="your-agent-id",
+    ...     on_renew=lambda token: guard.set_badge_token(token),
+    ... )
+    >>> keeper.start()
+"""
+
+import logging
+import threading
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Optional, Callable, Dict, Any
+
+from capiscio_sdk._rpc.client import CapiscioRPCClient
+from capiscio_sdk.errors import CapiscioSecurityError
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class BadgeKeeperConfig:
+    """Configuration for BadgeKeeper.
+    
+    Attributes:
+        api_url: Badge CA URL (e.g., https://registry.capisc.io)
+        api_key: API key for badge issuance
+        agent_id: Agent identifier (UUID or DID)
+        mode: Keeper mode ('ca' or 'pop', default: 'ca')
+        output_file: Path to write badge file (default: badge.jwt)
+        ttl_seconds: Badge TTL in seconds (default: 300 = 5 minutes)
+        renewal_threshold: Renew this many seconds before expiry (default: 10)
+        check_interval: Check interval in seconds (default: 5)
+        trust_level: Trust level for CA mode (1-4, default: 1)
+        rpc_address: Optional custom RPC address for capiscio-core
+        on_renew: Optional callback(token: str) called when badge renews
+        max_retries: Max retry attempts on renewal failure (default: 3)
+        retry_backoff: Base backoff seconds for exponential retry (default: 2)
+    """
+    api_url: str
+    api_key: str
+    agent_id: str
+    mode: str = "ca"
+    output_file: str = "badge.jwt"
+    ttl_seconds: int = 300
+    renewal_threshold: int = 10
+    check_interval: int = 5
+    trust_level: int = 1
+    rpc_address: Optional[str] = None
+    on_renew: Optional[Callable[[str], None]] = None
+    max_retries: int = 3
+    retry_backoff: int = 2
+
+
+class BadgeKeeper:
+    """Automatic badge renewal manager.
+    
+    BadgeKeeper runs a background thread that monitors badge expiration
+    and automatically requests new badges before they expire. This ensures
+    continuous agent authentication without manual intervention.
+    
+    The keeper integrates with SimpleGuard via the on_renew callback,
+    allowing seamless badge token updates for outbound request signing.
+    """
+
+    def __init__(
+        self,
+        api_url: str,
+        api_key: str,
+        agent_id: str,
+        mode: str = "ca",
+        output_file: str = "badge.jwt",
+        ttl_seconds: int = 300,
+        renewal_threshold: int = 10,
+        check_interval: int = 5,
+        trust_level: int = 1,
+        rpc_address: Optional[str] = None,
+        on_renew: Optional[Callable[[str], None]] = None,
+        max_retries: int = 3,
+        retry_backoff: int = 2,
+    ):
+        """Initialize BadgeKeeper.
+        
+        Args:
+            api_url: Badge CA URL (e.g., https://registry.capisc.io)
+            api_key: API key for badge issuance
+            agent_id: Agent identifier (UUID or DID)
+            mode: Keeper mode ('ca' or 'pop', default: 'ca')
+            output_file: Path to write badge file (default: badge.jwt)
+            ttl_seconds: Badge TTL in seconds (default: 300 = 5 minutes)
+            renewal_threshold: Renew this many seconds before expiry (default: 10)
+            check_interval: Check interval in seconds (default: 5)
+            trust_level: Trust level for CA mode (1-4, default: 1)
+            rpc_address: Optional custom RPC address for capiscio-core
+            on_renew: Optional callback(token: str) called when badge renews
+            max_retries: Max retry attempts on renewal failure (default: 3)
+            retry_backoff: Base backoff seconds for exponential retry (default: 2)
+        """
+        self.config = BadgeKeeperConfig(
+            api_url=api_url,
+            api_key=api_key,
+            agent_id=agent_id,
+            mode=mode,
+            output_file=output_file,
+            ttl_seconds=ttl_seconds,
+            renewal_threshold=renewal_threshold,
+            check_interval=check_interval,
+            trust_level=trust_level,
+            rpc_address=rpc_address,
+            on_renew=on_renew,
+            max_retries=max_retries,
+            retry_backoff=retry_backoff,
+        )
+        
+        self._rpc_client: Optional[CapiscioRPCClient] = None
+        self._thread: Optional[threading.Thread] = None
+        self._stop_event = threading.Event()
+        self._current_badge: Optional[str] = None
+        self._badge_lock = threading.Lock()
+        self._running = False
+
+    def start(self) -> None:
+        """Start the badge keeper background thread.
+        
+        Raises:
+            CapiscioSecurityError: If keeper is already running
+        """
+        if self._running:
+            raise CapiscioSecurityError("BadgeKeeper is already running")
+        
+        logger.info(
+            f"Starting BadgeKeeper (mode={self.config.mode}, "
+            f"threshold={self.config.renewal_threshold}s)"
+        )
+        
+        self._stop_event.clear()
+        self._running = True
+        self._thread = threading.Thread(target=self._run_keeper, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Stop the badge keeper background thread."""
+        if not self._running:
+            return
+        
+        logger.info("Stopping BadgeKeeper...")
+        self._stop_event.set()
+        
+        if self._thread:
+            self._thread.join(timeout=5)
+            self._thread = None
+        
+        if self._rpc_client:
+            self._rpc_client.close()
+            self._rpc_client = None
+        
+        self._running = False
+        logger.info("BadgeKeeper stopped")
+
+    def get_current_badge(self) -> Optional[str]:
+        """Get the current badge token.
+        
+        Returns:
+            Current badge token, or None if no badge yet
+        """
+        with self._badge_lock:
+            return self._current_badge
+
+    def is_running(self) -> bool:
+        """Check if keeper is running.
+        
+        Returns:
+            True if keeper is running, False otherwise
+        """
+        return self._running
+
+    def _run_keeper(self) -> None:
+        """Background thread that runs the keeper loop."""
+        try:
+            # Initialize RPC client
+            self._rpc_client = CapiscioRPCClient(
+                address=self.config.rpc_address or "unix:///tmp/capiscio.sock"
+            )
+            
+            logger.debug("BadgeKeeper thread started, streaming events from core...")
+            
+            # Stream events from capiscio-core keeper
+            for event in self._rpc_client.badge.start_keeper(
+                mode=self.config.mode,
+                output_file=self.config.output_file,
+                agent_id=self.config.agent_id,
+                api_key=self.config.api_key,
+                ca_url=self.config.api_url,
+                ttl_seconds=self.config.ttl_seconds,
+                renew_before_seconds=self.config.renewal_threshold,
+                check_interval_seconds=self.config.check_interval,
+                trust_level=self.config.trust_level,
+            ):
+                # Check stop signal
+                if self._stop_event.is_set():
+                    logger.debug("Stop event detected, exiting keeper loop")
+                    break
+                
+                self._handle_keeper_event(event)
+            
+            logger.debug("Keeper event stream ended")
+            
+        except Exception as e:
+            logger.error(f"BadgeKeeper error: {e}", exc_info=True)
+            self._running = False
+        finally:
+            if self._rpc_client:
+                self._rpc_client.close()
+                self._rpc_client = None
+
+    def _handle_keeper_event(self, event: Dict[str, Any]) -> None:
+        """Handle a keeper event from the stream.
+        
+        Args:
+            event: Event dict from start_keeper stream
+        """
+        event_type = event.get("type")
+        
+        if event_type == "started":
+            logger.info(
+                f"BadgeKeeper started for agent {self.config.agent_id}"
+            )
+        
+        elif event_type == "renewed":
+            badge_token = event.get("token")
+            badge_jti = event.get("badge_jti", "unknown")
+            expires_ts = event.get("expires_at", 0)
+            
+            if badge_token:
+                with self._badge_lock:
+                    self._current_badge = badge_token
+                
+                # Call renewal callback if configured
+                if self.config.on_renew:
+                    try:
+                        self.config.on_renew(badge_token)
+                        logger.debug("Called on_renew callback")
+                    except Exception as e:
+                        logger.error(f"Error in on_renew callback: {e}")
+                
+                # Format expiry time
+                if expires_ts > 0:
+                    expires_dt = datetime.fromtimestamp(expires_ts, timezone.utc)
+                    logger.info(
+                        f"Badge renewed (jti={badge_jti[:8]}..., "
+                        f"expires={expires_dt.isoformat()})"
+                    )
+                else:
+                    logger.info(f"Badge renewed (jti={badge_jti[:8]}...)")
+            else:
+                logger.warning("Renewed event but no token in response")
+        
+        elif event_type == "error":
+            error_msg = event.get("error", "Unknown error")
+            error_code = event.get("error_code", "")
+            logger.error(
+                f"BadgeKeeper error: {error_msg} "
+                f"(code={error_code})"
+            )
+        
+        elif event_type == "stopped":
+            logger.info("BadgeKeeper stopped by core")
+            self._stop_event.set()
+        
+        else:
+            logger.debug(f"Unknown keeper event type: {event_type}")
+
+    def __enter__(self):
+        """Context manager entry."""
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.stop()
+        return False

capiscio_sdk/config.py

@@ -1,4 +1,4 @@
-"""Configuration for Capiscio A2A Security."""
+"""Configuration for Capiscio Python SDK."""
 import os
 from typing import Literal
 from pydantic import BaseModel, Field

capiscio_sdk/dv.py

@@ -0,0 +1,296 @@
+"""Domain Validation (DV) Badge API for CapiscIO agents.
+
+This module provides high-level API for DV badge orders (RFC-002 v1.2).
+DV badges provide Level 1 trust with domain ownership verification.
+
+Uses the capiscio-core gRPC service for all operations, following the
+established RPC pattern.
+
+Example usage:
+
+    from capiscio_sdk.dv import create_dv_order, get_dv_order, finalize_dv_order
+    import json
+
+    # Load agent's public key
+    with open("public.jwk") as f:
+        jwk = json.load(f)
+
+    # Create a DV order
+    order = create_dv_order(
+        domain="example.com",
+        challenge_type="http-01",
+        jwk=jwk,
+    )
+
+    print(f"Order ID: {order.order_id}")
+    print(f"Place this token at: {order.validation_url}")
+    print(f"Token: {order.challenge_token}")
+
+    # After completing the challenge, finalize the order
+    grant = finalize_dv_order(order.order_id)
+    print(f"Grant JWT: {grant.grant}")
+
+    # Save the grant for later use
+    with open("grant.jwt", "w") as f:
+        f.write(grant.grant)
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Optional
+import json
+
+from capiscio_sdk._rpc.client import CapiscioRPCClient
+
+
+@dataclass
+class DVOrder:
+    """Domain Validation badge order.
+
+    Attributes:
+        order_id: Unique order identifier (UUID).
+        domain: Domain being validated.
+        challenge_type: Type of challenge (http-01 or dns-01).
+        challenge_token: Token to place for validation.
+        status: Order status (pending, valid, invalid, expired).
+        validation_url: URL where token should be placed (http-01).
+        dns_record: DNS record to create (dns-01).
+        expires_at: When the order expires.
+        finalized_at: When the order was finalized (if applicable).
+    """
+
+    order_id: str
+    domain: str
+    challenge_type: str
+    challenge_token: str
+    status: str
+    validation_url: str = ""
+    dns_record: str = ""
+    expires_at: Optional[datetime] = None
+    finalized_at: Optional[datetime] = None
+
+
+@dataclass
+class DVGrant:
+    """Domain Validation grant JWT.
+
+    Attributes:
+        grant: The signed grant JWT token.
+        expires_at: When the grant expires.
+    """
+
+    grant: str
+    expires_at: Optional[datetime] = None
+
+
+# Module-level client (lazy initialization)
+_client: Optional[CapiscioRPCClient] = None
+
+
+def _get_client() -> CapiscioRPCClient:
+    """Get or create the module-level gRPC client."""
+    global _client
+    if _client is None:
+        _client = CapiscioRPCClient()
+        _client.connect()
+    return _client
+
+
+def _parse_timestamp(ts: str) -> Optional[datetime]:
+    """Parse ISO 8601 timestamp string to datetime."""
+    if not ts:
+        return None
+    try:
+        return datetime.fromisoformat(ts.replace("Z", "+00:00"))
+    except (ValueError, AttributeError):
+        return None
+
+
+def create_dv_order(
+    domain: str,
+    challenge_type: str,
+    jwk: dict,
+    ca_url: str = "https://registry.capisc.io",
+) -> DVOrder:
+    """Create a new DV badge order.
+
+    Uses the capiscio-core gRPC service to create the order.
+
+    Args:
+        domain: Domain to validate (e.g., "example.com").
+        challenge_type: Challenge type ("http-01" or "dns-01").
+        jwk: Agent's public key in JWK format (dict).
+        ca_url: Certificate Authority URL.
+
+    Returns:
+        DVOrder with challenge details.
+
+    Raises:
+        ValueError: If the CA returns an error.
+
+    Example:
+        import json
+
+        with open("public.jwk") as f:
+            jwk = json.load(f)
+
+        order = create_dv_order(
+            domain="example.com",
+            challenge_type="http-01",
+            jwk=jwk,
+        )
+
+        print(f"Place token at: {order.validation_url}")
+    """
+    if challenge_type not in ("http-01", "dns-01"):
+        raise ValueError(
+            f"Invalid challenge_type: {challenge_type}. Must be 'http-01' or 'dns-01'"
+        )
+
+    try:
+        client = _get_client()
+
+        # Convert JWK dict to JSON string
+        jwk_str = json.dumps(jwk)
+
+        success, order_dict, error = client.badge.create_dv_order(
+            domain=domain,
+            challenge_type=challenge_type,
+            jwk=jwk_str,
+            ca_url=ca_url,
+        )
+
+        if not success:
+            raise ValueError(f"CA rejected DV order: {error}")
+
+        if not order_dict:
+            raise ValueError("CA response missing order data")
+
+        return DVOrder(
+            order_id=order_dict["order_id"],
+            domain=order_dict["domain"],
+            challenge_type=order_dict["challenge_type"],
+            challenge_token=order_dict["challenge_token"],
+            status=order_dict["status"],
+            validation_url=order_dict.get("validation_url", ""),
+            dns_record=order_dict.get("dns_record", ""),
+            expires_at=_parse_timestamp(order_dict.get("expires_at", "")),
+        )
+
+    except Exception as e:
+        if isinstance(e, ValueError):
+            raise
+        raise ValueError(f"Failed to create DV order: {e}") from e
+
+
+def get_dv_order(
+    order_id: str,
+    ca_url: str = "https://registry.capisc.io",
+) -> DVOrder:
+    """Get the status of a DV badge order.
+
+    Uses the capiscio-core gRPC service to check order status.
+
+    Args:
+        order_id: Order ID from create_dv_order.
+        ca_url: Certificate Authority URL.
+
+    Returns:
+        DVOrder with current status.
+
+    Raises:
+        ValueError: If the CA returns an error.
+
+    Example:
+        order = get_dv_order("550e8400-e29b-41d4-a716-446655440000")
+        print(f"Status: {order.status}")
+    """
+    try:
+        client = _get_client()
+
+        success, order_dict, error = client.badge.get_dv_order(
+            order_id=order_id,
+            ca_url=ca_url,
+        )
+
+        if not success:
+            raise ValueError(f"Failed to get DV order: {error}")
+
+        if not order_dict:
+            raise ValueError("CA response missing order data")
+
+        return DVOrder(
+            order_id=order_dict["order_id"],
+            domain=order_dict["domain"],
+            challenge_type=order_dict["challenge_type"],
+            challenge_token=order_dict["challenge_token"],
+            status=order_dict["status"],
+            validation_url=order_dict.get("validation_url", ""),
+            dns_record=order_dict.get("dns_record", ""),
+            expires_at=_parse_timestamp(order_dict.get("expires_at", "")),
+            finalized_at=_parse_timestamp(order_dict.get("finalized_at", "")),
+        )
+
+    except Exception as e:
+        if isinstance(e, ValueError):
+            raise
+        raise ValueError(f"Failed to get DV order: {e}") from e
+
+
+def finalize_dv_order(
+    order_id: str,
+    ca_url: str = "https://registry.capisc.io",
+) -> DVGrant:
+    """Finalize a DV badge order and receive a grant.
+
+    Uses the capiscio-core gRPC service to finalize the order.
+
+    Args:
+        order_id: Order ID from create_dv_order.
+        ca_url: Certificate Authority URL.
+
+    Returns:
+        DVGrant with the signed grant JWT.
+
+    Raises:
+        ValueError: If the CA returns an error.
+
+    Example:
+        grant = finalize_dv_order("550e8400-e29b-41d4-a716-446655440000")
+
+        # Save grant
+        with open("grant.jwt", "w") as f:
+            f.write(grant.grant)
+    """
+    try:
+        client = _get_client()
+
+        success, grant_dict, error = client.badge.finalize_dv_order(
+            order_id=order_id,
+            ca_url=ca_url,
+        )
+
+        if not success:
+            raise ValueError(f"Failed to finalize DV order: {error}")
+
+        if not grant_dict:
+            raise ValueError("CA response missing grant data")
+
+        return DVGrant(
+            grant=grant_dict["grant"],
+            expires_at=_parse_timestamp(grant_dict.get("expires_at", "")),
+        )
+
+    except Exception as e:
+        if isinstance(e, ValueError):
+            raise
+        raise ValueError(f"Failed to finalize DV order: {e}") from e
+
+
+__all__ = [
+    "DVOrder",
+    "DVGrant",
+    "create_dv_order",
+    "get_dv_order",
+    "finalize_dv_order",
+]

capiscio_sdk/errors.py

@@ -1,4 +1,4 @@
-"""Error types for Capiscio A2A Security."""
+"""Error types for Capiscio Python SDK."""
 from typing import Optional, List, Dict, Any
 from .types import ValidationResult
 
@@ -67,3 +67,13 @@ class CapiscioTimeoutError(CapiscioSecurityError):
     """Operation timed out."""
 
     pass
+
+
+class ConfigurationError(CapiscioSecurityError):
+    """Missing keys or invalid paths (SimpleGuard)."""
+    pass
+
+
+class VerificationError(CapiscioSecurityError):
+    """Invalid signature, expired token, or untrusted key (SimpleGuard)."""
+    pass

capiscio_sdk/executor.py

@@ -138,6 +138,23 @@ class CapiscioSecurityExecutor:
         # Cancellation just passes through - no security checks needed
         await self.delegate.cancel(context, event_queue)
 
+    async def validate_agent_card(self, url: str) -> ValidationResult:
+        """
+        Validate an agent card from a URL.
+        
+        Uses CoreValidator which delegates to Go core for consistent
+        validation across all CapiscIO SDKs.
+        
+        Args:
+            url: URL to the agent card or agent root
+            
+        Returns:
+            ValidationResult with scores
+        """
+        from .validators import CoreValidator
+        with CoreValidator() as validator:
+            return await validator.fetch_and_validate(url)
+
     def _validate_message(self, message: Dict[str, Any]) -> ValidationResult:
         """Validate message with caching."""
         # Try cache first