asap-protocol 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

asap/__init__.py

@@ -4,4 +4,4 @@ A streamlined, scalable, asynchronous protocol for agent-to-agent communication
 and task coordination.
 """
 
-__version__ = "0.3.0"
+__version__ = "0.5.0"

asap/errors.py

@@ -190,3 +190,170 @@ class ThreadPoolExhaustedError(ASAPError):
         )
         self.max_threads = max_threads
         self.active_threads = active_threads
+
+
+class InvalidTimestampError(ASAPError):
+    """Raised when an envelope timestamp is invalid (too old or too far in the future).
+
+    This error occurs when validating envelope timestamps for replay attack prevention.
+    Envelopes with timestamps outside the acceptable window are rejected.
+
+    Attributes:
+        timestamp: The invalid timestamp value
+        age_seconds: Age of the envelope in seconds (if too old)
+        future_offset_seconds: Offset in seconds from current time (if too far in future)
+    """
+
+    def __init__(
+        self,
+        timestamp: str,
+        message: str,
+        age_seconds: float | None = None,
+        future_offset_seconds: float | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize invalid timestamp error.
+
+        Args:
+            timestamp: The invalid timestamp value
+            message: Human-readable error description
+            age_seconds: Age of the envelope in seconds (if too old)
+            future_offset_seconds: Offset in seconds from current time (if too far in future)
+            details: Optional additional context
+        """
+        # Build details dict with optional fields
+        details_dict: dict[str, Any] = {"timestamp": timestamp}
+        if age_seconds is not None:
+            details_dict["age_seconds"] = age_seconds
+        if future_offset_seconds is not None:
+            details_dict["future_offset_seconds"] = future_offset_seconds
+        if details:
+            details_dict.update(details)
+
+        super().__init__(
+            code="asap:protocol/invalid_timestamp",
+            message=message,
+            details=details_dict,
+        )
+        self.timestamp = timestamp
+        self.age_seconds = age_seconds
+        self.future_offset_seconds = future_offset_seconds
+
+
+class InvalidNonceError(ASAPError):
+    """Raised when an envelope nonce is invalid (duplicate or malformed).
+
+    This error occurs when validating envelope nonces for replay attack prevention.
+    Nonces that have been used before within the TTL window are rejected.
+
+    Attributes:
+        nonce: The invalid nonce value
+    """
+
+    def __init__(
+        self,
+        nonce: str,
+        message: str,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize invalid nonce error.
+
+        Args:
+            nonce: The invalid nonce value
+            message: Human-readable error description
+            details: Optional additional context
+        """
+        super().__init__(
+            code="asap:protocol/invalid_nonce",
+            message=message,
+            details={
+                "nonce": nonce,
+                **(details or {}),
+            },
+        )
+        self.nonce = nonce
+
+
+class CircuitOpenError(ASAPError):
+    """Raised when circuit breaker is open and request is rejected.
+
+    This error occurs when the circuit breaker pattern has detected
+    too many consecutive failures and is preventing further requests
+    to protect the system from cascading failures.
+
+    Attributes:
+        base_url: The URL for which the circuit is open
+        consecutive_failures: Number of consecutive failures that opened the circuit
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        consecutive_failures: int,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize circuit open error.
+
+        Args:
+            base_url: The URL for which the circuit is open
+            consecutive_failures: Number of consecutive failures
+            details: Optional additional context
+        """
+        message = (
+            f"Circuit breaker is OPEN for {base_url}. "
+            f"Too many consecutive failures ({consecutive_failures}). "
+            "Service temporarily unavailable."
+        )
+        super().__init__(
+            code="asap:transport/circuit_open",
+            message=message,
+            details={
+                "base_url": base_url,
+                "consecutive_failures": consecutive_failures,
+                **(details or {}),
+            },
+        )
+        self.base_url = base_url
+        self.consecutive_failures = consecutive_failures
+
+
+class UnsupportedAuthSchemeError(ASAPError):
+    """Raised when an unsupported authentication scheme is specified.
+
+    This error occurs when a Manifest specifies an authentication scheme
+    that is not supported by the current implementation.
+
+    Attributes:
+        scheme: The unsupported scheme name
+        supported_schemes: List of supported schemes
+    """
+
+    def __init__(
+        self,
+        scheme: str,
+        supported_schemes: set[str] | frozenset[str],
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize unsupported auth scheme error.
+
+        Args:
+            scheme: The unsupported scheme name
+            supported_schemes: Set of supported schemes
+            details: Optional additional context
+        """
+        supported_list = sorted(supported_schemes)
+        message = (
+            f"Unsupported authentication scheme '{scheme}'. "
+            f"Supported schemes: {', '.join(supported_list)}"
+        )
+        super().__init__(
+            code="asap:auth/unsupported_scheme",
+            message=message,
+            details={
+                "scheme": scheme,
+                "supported_schemes": list(supported_list),
+                **(details or {}),
+            },
+        )
+        self.scheme = scheme
+        self.supported_schemes = supported_schemes

asap/examples/README.md

@@ -23,3 +23,6 @@ You can run the agents separately if needed:
 
 - The echo agent exposes `/.well-known/asap/manifest.json` for readiness checks.
 - Update ports in `asap.examples.run_demo` if you change the defaults.
+- These examples use the basic ASAP API without authentication or advanced security features.
+  For production use, consider adding authentication via `manifest.auth` and enabling
+  additional security features (see `docs/security.md`).

asap/examples/run_demo.py

@@ -6,7 +6,7 @@ communication by sending a task request from the coordinator logic.
 
 import asyncio
 import signal
-import subprocess
+import subprocess  # nosec B404
 import sys
 import time
 from typing import Sequence
@@ -34,8 +34,15 @@ def start_process(command: Sequence[str]) -> subprocess.Popen[str]:
 
     Returns:
         Started subprocess handle.
+
+    Note:
+        This is example/demo code that only executes trusted commands
+        (sys.executable with known modules). The command is controlled
+        and not user input.
     """
-    return subprocess.Popen(command, text=True)
+    # nosec B404, B603: This is example code executing trusted commands only
+    # (sys.executable with known Python modules, not user input)
+    return subprocess.Popen(command, text=True)  # nosec B404, B603
 
 
 def wait_for_ready(url: str, timeout_seconds: float) -> None:

asap/models/__init__.py

@@ -12,6 +12,8 @@ from asap.models.constants import (
     AGENT_URN_PATTERN,
     ASAP_PROTOCOL_VERSION,
     DEFAULT_TIMEOUT_SECONDS,
+    MAX_ENVELOPE_AGE_SECONDS,
+    MAX_FUTURE_TOLERANCE_SECONDS,
     MAX_TASK_DEPTH,
 )
 
@@ -88,6 +90,8 @@ __all__ = [
     "AGENT_URN_PATTERN",
     "ASAP_PROTOCOL_VERSION",
     "DEFAULT_TIMEOUT_SECONDS",
+    "MAX_ENVELOPE_AGE_SECONDS",
+    "MAX_FUTURE_TOLERANCE_SECONDS",
     "MAX_TASK_DEPTH",
     # Enums
     "MessageRole",

asap/models/constants.py

@@ -11,5 +11,78 @@ DEFAULT_TIMEOUT_SECONDS = 600
 MAX_TASK_DEPTH = 10  # Maximum nesting level for subtasks
 MAX_REQUEST_SIZE = 10 * 1024 * 1024  # 10MB maximum request size
 
+# Timestamp validation constants for replay attack prevention
+MAX_ENVELOPE_AGE_SECONDS = 300  # 5 minutes
+"""Maximum age of an envelope timestamp before it is considered stale.
+
+This prevents replay attacks by rejecting envelopes that are too old.
+The 5-minute window balances security (preventing old message replays)
+with practical network latency and clock skew tolerance.
+"""
+
+MAX_FUTURE_TOLERANCE_SECONDS = 30  # 30 seconds
+"""Maximum future timestamp tolerance to account for clock skew.
+
+Envelopes with timestamps more than 30 seconds in the future are rejected
+to prevent attacks using artificially future-dated messages. This tolerance
+accounts for reasonable clock synchronization differences between systems.
+"""
+
+NONCE_TTL_SECONDS = MAX_ENVELOPE_AGE_SECONDS * 2  # 10 minutes by default
+"""Time-to-live for nonce values in seconds.
+
+Nonces are stored with a TTL of 2x the maximum envelope age to ensure they
+expire after the envelope would have been rejected anyway. This provides a
+safety margin for edge cases where an envelope might be processed near the
+age limit, while preventing the nonce store from growing unbounded.
+
+The 2x multiplier ensures that:
+- Nonces remain valid for the full envelope validation window
+- Nonces expire shortly after envelopes would be rejected, preventing unbounded growth
+- There's a buffer for clock skew and processing delays
+"""
+
 # URN patterns
 AGENT_URN_PATTERN = r"^urn:asap:agent:[a-z0-9-]+(?::[a-z0-9-]+)?$"
+
+# Authentication schemes
+SUPPORTED_AUTH_SCHEMES = frozenset({"bearer", "basic"})
+"""Supported authentication schemes for agent access.
+
+Currently supports:
+- bearer: Bearer token authentication (RFC 6750)
+- basic: HTTP Basic authentication (RFC 7617)
+
+Future support planned:
+- oauth2: OAuth 2.0 authentication flow
+- hmac: HMAC-based authentication
+"""
+
+# Retry and backoff constants
+DEFAULT_BASE_DELAY = 1.0
+"""Default base delay in seconds for exponential backoff.
+
+This is the initial delay before the first retry attempt. Subsequent retries
+will use exponential backoff: base_delay * (2 ** attempt) + jitter.
+"""
+
+DEFAULT_MAX_DELAY = 60.0
+"""Maximum delay in seconds for exponential backoff.
+
+This caps the maximum delay between retry attempts, preventing excessively
+long waits while still providing exponential backoff for transient failures.
+"""
+
+DEFAULT_CIRCUIT_BREAKER_THRESHOLD = 5
+"""Default threshold for circuit breaker pattern.
+
+Number of consecutive failures required before opening the circuit breaker
+and preventing further requests to a failing endpoint.
+"""
+
+DEFAULT_CIRCUIT_BREAKER_TIMEOUT = 60.0
+"""Default timeout in seconds before circuit breaker transitions from OPEN to HALF_OPEN.
+
+After this timeout, the circuit breaker will allow a test request to determine
+if the service has recovered before closing the circuit.
+"""

asap/models/entities.py

@@ -19,10 +19,11 @@ from datetime import datetime
 from typing import Any
 
 from packaging.version import InvalidVersion, Version
-from pydantic import Field, field_validator
+from pydantic import Field, field_validator, model_validator
 
+from asap.errors import UnsupportedAuthSchemeError
 from asap.models.base import ASAPBaseModel
-from asap.models.constants import AGENT_URN_PATTERN, ASAP_PROTOCOL_VERSION
+from asap.models.constants import AGENT_URN_PATTERN, ASAP_PROTOCOL_VERSION, SUPPORTED_AUTH_SCHEMES
 from asap.models.enums import MessageRole, TaskStatus
 from asap.models.types import (
     AgentURN,
@@ -36,6 +37,27 @@ from asap.models.types import (
 )
 
 
+def _validate_auth_scheme(auth: "AuthScheme") -> None:
+    """Validate that all authentication schemes are supported.
+
+    Checks each scheme in auth.schemes against SUPPORTED_AUTH_SCHEMES
+    and raises UnsupportedAuthSchemeError if any scheme is invalid.
+
+    Args:
+        auth: AuthScheme instance to validate
+
+    Raises:
+        UnsupportedAuthSchemeError: If any scheme is not supported
+    """
+    for scheme in auth.schemes:
+        scheme_lower = scheme.lower()
+        if scheme_lower not in SUPPORTED_AUTH_SCHEMES:
+            raise UnsupportedAuthSchemeError(
+                scheme=scheme,
+                supported_schemes=SUPPORTED_AUTH_SCHEMES,
+            )
+
+
 class Skill(ASAPBaseModel):
     """A specific capability that an agent can perform.
 
@@ -231,6 +253,20 @@ class Manifest(ASAPBaseModel):
             raise ValueError(f"Invalid semantic version '{v}': {e}") from e
         return v
 
+    @model_validator(mode="after")
+    def validate_auth_schemes(self) -> "Manifest":
+        """Validate that all authentication schemes are supported.
+
+        Raises:
+            UnsupportedAuthSchemeError: If any scheme in auth.schemes is not supported
+
+        Returns:
+            Self (for method chaining)
+        """
+        if self.auth is not None:
+            _validate_auth_scheme(self.auth)
+        return self
+
 
 class Conversation(ASAPBaseModel):
     """A context for related interactions between agents.

asap/models/envelope.py

@@ -65,7 +65,13 @@ class Envelope(ASAPBaseModel):
         default=None, description="Optional trace ID for distributed tracing"
     )
     extensions: dict[str, Any] | None = Field(
-        default=None, description="Optional custom extensions"
+        default=None,
+        description=(
+            "Optional custom extensions. "
+            "Can include a 'nonce' field (string) for replay attack prevention. "
+            "If provided, the nonce must be unique within the TTL window (typically 10 minutes). "
+            "Duplicate nonces will be rejected by the validation layer."
+        ),
     )
 
     @field_validator("id", mode="before")

asap/transport/__init__.py

@@ -18,6 +18,7 @@ Public exports:
     create_echo_handler: Factory for echo handler
     create_default_registry: Factory for default registry
     ASAPClient: Async HTTP client for agent communication
+    RetryConfig: Configuration dataclass for retry logic and circuit breaker
     ASAPConnectionError: Connection error exception
     ASAPTimeoutError: Timeout error exception
     ASAPRemoteError: Remote error exception
@@ -45,6 +46,7 @@ from asap.transport.client import (
     ASAPConnectionError,
     ASAPRemoteError,
     ASAPTimeoutError,
+    RetryConfig,
 )
 from asap.transport.handlers import (
     Handler,
@@ -81,4 +83,5 @@ __all__ = [
     "ASAPConnectionError",
     "ASAPTimeoutError",
     "ASAPRemoteError",
+    "RetryConfig",
 ]

asap/transport/circuit_breaker.py

@@ -0,0 +1,193 @@
+"""Circuit breaker implementation for resilient request handling.
+
+This module provides the CircuitBreaker pattern implementation and a registry
+for sharing circuit breaker state across multiple client instances.
+"""
+
+import threading
+import time
+from enum import Enum
+from typing import Dict
+
+from asap.models.constants import (
+    DEFAULT_CIRCUIT_BREAKER_THRESHOLD,
+    DEFAULT_CIRCUIT_BREAKER_TIMEOUT,
+)
+from asap.observability import get_logger
+
+logger = get_logger(__name__)
+
+
+class CircuitState(str, Enum):
+    """Circuit breaker states.
+
+    CLOSED: Normal operation, requests are allowed
+    OPEN: Circuit is open, requests are rejected immediately
+    HALF_OPEN: Testing state, allows one request to test if service recovered
+    """
+
+    CLOSED = "closed"
+    OPEN = "open"
+    HALF_OPEN = "half_open"
+
+
+class CircuitBreaker:
+    """Circuit breaker pattern implementation for resilient request handling.
+
+    The circuit breaker prevents cascading failures by opening the circuit
+    after a threshold of consecutive failures, then attempting to recover
+    after a timeout period.
+
+    States:
+    - CLOSED: Normal operation, all requests allowed
+    - OPEN: Circuit is open, all requests rejected immediately
+    - HALF_OPEN: Testing state, allows one request to test recovery
+
+    This implementation is thread-safe using RLock for concurrent access.
+    """
+
+    def __init__(
+        self,
+        threshold: int = DEFAULT_CIRCUIT_BREAKER_THRESHOLD,
+        timeout: float = DEFAULT_CIRCUIT_BREAKER_TIMEOUT,
+    ) -> None:
+        """Initialize circuit breaker.
+
+        Args:
+            threshold: Number of consecutive failures before opening (default: 5)
+            timeout: Seconds before transitioning OPEN -> HALF_OPEN (default: 60.0)
+        """
+        self.threshold = threshold
+        self.timeout = timeout
+        self._state = CircuitState.CLOSED
+        self._consecutive_failures = 0
+        self._last_failure_time: float | None = None
+        self._lock = threading.RLock()
+
+    def record_success(self) -> None:
+        """Record a successful request.
+
+        Resets failure count and closes circuit if it was HALF_OPEN.
+        """
+        with self._lock:
+            self._consecutive_failures = 0
+            if self._state == CircuitState.HALF_OPEN:
+                self._state = CircuitState.CLOSED
+                self._last_failure_time = None
+
+    def record_failure(self) -> None:
+        """Record a failed request.
+
+        Increments failure count and opens circuit if threshold is reached.
+        """
+        with self._lock:
+            self._consecutive_failures += 1
+            self._last_failure_time = time.time()
+
+            if self._consecutive_failures >= self.threshold and self._state == CircuitState.CLOSED:
+                self._state = CircuitState.OPEN
+
+    def can_attempt(self) -> bool:
+        """Check if a request can be attempted.
+
+        Returns:
+            True if request can be attempted, False if circuit is open
+        """
+        with self._lock:
+            # Check if we should transition from OPEN to HALF_OPEN
+            if self._state == CircuitState.OPEN:
+                if self._last_failure_time is not None:
+                    elapsed = time.time() - self._last_failure_time
+                    if elapsed >= self.timeout:
+                        # Transition to HALF_OPEN to test recovery
+                        self._state = CircuitState.HALF_OPEN
+                        return True
+                # Still in OPEN state, reject request
+                return False
+
+            # CLOSED or HALF_OPEN: allow request
+            return True
+
+    def get_state(self) -> CircuitState:
+        """Get current circuit state.
+
+        Returns:
+            Current circuit state
+        """
+        with self._lock:
+            return self._state
+
+    def get_consecutive_failures(self) -> int:
+        """Get number of consecutive failures.
+
+        Returns:
+            Number of consecutive failures
+        """
+        with self._lock:
+            return self._consecutive_failures
+
+
+class CircuitBreakerRegistry:
+    """Registry for managing shared CircuitBreaker instances.
+
+    Ensures that multiple clients connecting to the same implementation
+    share the same circuit breaker state.
+    """
+
+    def __init__(self) -> None:
+        """Initialize registry."""
+        self._breakers: Dict[str, CircuitBreaker] = {}
+        self._lock = threading.RLock()
+
+    def get_or_create(
+        self,
+        base_url: str,
+        threshold: int = DEFAULT_CIRCUIT_BREAKER_THRESHOLD,
+        timeout: float = DEFAULT_CIRCUIT_BREAKER_TIMEOUT,
+    ) -> CircuitBreaker:
+        """Get existing circuit breaker or create a new one.
+
+        Args:
+            base_url: The target URL (key for the registry)
+            threshold: Threshold for new breakers (ignored if exists)
+            timeout: Timeout for new breakers (ignored if exists)
+
+        Returns:
+            Shared CircuitBreaker instance
+        """
+        with self._lock:
+            if base_url not in self._breakers:
+                logger.info(
+                    "asap.circuit_breaker.created",
+                    base_url=base_url,
+                    threshold=threshold,
+                    timeout=timeout,
+                    message=f"Created shared circuit breaker for {base_url}",
+                )
+                self._breakers[base_url] = CircuitBreaker(threshold=threshold, timeout=timeout)
+            return self._breakers[base_url]
+
+    def clear(self) -> None:
+        """Clear all registered circuit breakers (mostly for testing)."""
+        with self._lock:
+            self._breakers.clear()
+
+
+# Global registry instance
+# In a more complex app, this might be injected, but a module-level singleton
+# is standard for this pattern in Python clients.
+_registry = CircuitBreakerRegistry()
+
+
+def get_circuit_breaker(
+    base_url: str,
+    threshold: int = DEFAULT_CIRCUIT_BREAKER_THRESHOLD,
+    timeout: float = DEFAULT_CIRCUIT_BREAKER_TIMEOUT,
+) -> CircuitBreaker:
+    """Helper to get a circuit breaker from the global registry."""
+    return _registry.get_or_create(base_url, threshold, timeout)
+
+
+def get_registry() -> CircuitBreakerRegistry:
+    """Helper to get the global registry instance."""
+    return _registry