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

asap/transport/middleware.py

@@ -32,7 +32,6 @@ Example:
     >>> middleware = AuthenticationMiddleware(manifest, validator)
 """
 
-import hashlib
 import uuid
 from typing import Any, Awaitable, Callable, Protocol
 from collections.abc import Sequence
@@ -47,6 +46,7 @@ from starlette.middleware.base import BaseHTTPMiddleware
 
 from asap.models.entities import Manifest
 from asap.observability import get_logger
+from asap.utils.sanitization import sanitize_token
 
 logger = get_logger(__name__)
 
@@ -259,7 +259,8 @@ HTTP_TOO_MANY_REQUESTS = 429
 
 # Error messages
 ERROR_AUTH_REQUIRED = "Authentication required"
-ERROR_INVALID_TOKEN = "Invalid authentication token"
+# nosec B105: This is an error message constant, not a hardcoded password
+ERROR_INVALID_TOKEN = "Invalid authentication token"  # nosec B105
 ERROR_SENDER_MISMATCH = "Sender does not match authenticated identity"
 ERROR_RATE_LIMIT_EXCEEDED = "Rate limit exceeded"
 
@@ -498,12 +499,12 @@ class AuthenticationMiddleware:
         agent_id = self.validator(token)
 
         if agent_id is None:
-            # Log token hash instead of prefix to avoid exposing token data
-            token_hash = hashlib.sha256(token.encode()).hexdigest()[:16]
+            # Log sanitized token to avoid exposing full token data
+            token_prefix = sanitize_token(token)
             logger.warning(
                 "asap.auth.invalid_token",
                 manifest_id=self.manifest.id,
-                token_hash=token_hash,
+                token_prefix=token_prefix,
             )
             raise HTTPException(
                 status_code=HTTP_UNAUTHORIZED,

asap/transport/server.py

@@ -51,11 +51,12 @@ from fastapi.responses import JSONResponse, PlainTextResponse
 from pydantic import ValidationError
 from slowapi.errors import RateLimitExceeded
 
-from asap.errors import ThreadPoolExhaustedError
+from asap.errors import InvalidNonceError, InvalidTimestampError, ThreadPoolExhaustedError
 from asap.models.constants import MAX_REQUEST_SIZE
 from asap.models.entities import Capability, Endpoint, Manifest, Skill
 from asap.models.envelope import Envelope
 from asap.observability import get_logger, get_metrics
+from asap.utils.sanitization import sanitize_nonce
 from asap.transport.middleware import (
     AuthenticationMiddleware,
     BearerTokenValidator,
@@ -83,6 +84,12 @@ from asap.transport.jsonrpc import (
     JsonRpcRequest,
     JsonRpcResponse,
 )
+from asap.transport.validators import (
+    InMemoryNonceStore,
+    NonceStore,
+    validate_envelope_nonce,
+    validate_envelope_timestamp,
+)
 
 # Module logger
 logger = get_logger(__name__)
@@ -142,6 +149,7 @@ class ASAPRequestHandler:
         manifest: Manifest,
         auth_middleware: AuthenticationMiddleware | None = None,
         max_request_size: int = MAX_REQUEST_SIZE,
+        nonce_store: NonceStore | None = None,
     ) -> None:
         """Initialize the request handler.
 
@@ -150,11 +158,13 @@ class ASAPRequestHandler:
             manifest: Agent manifest describing capabilities
             auth_middleware: Optional authentication middleware for request validation
             max_request_size: Maximum allowed request size in bytes
+            nonce_store: Optional nonce store for replay attack prevention
         """
         self.registry = registry
         self.manifest = manifest
         self.auth_middleware = auth_middleware
         self.max_request_size = max_request_size
+        self.nonce_store = nonce_store
 
     def _normalize_payload_type_for_metrics(self, payload_type: str) -> str:
         """Normalize payload type for metrics to prevent cardinality explosion.
@@ -808,7 +818,9 @@ class ASAPRequestHandler:
             if parse_error is not None:
                 return parse_error
             # Type narrowing: rpc_request is not None here
-            assert rpc_request is not None
+            # Use explicit check instead of assert to avoid removal in optimized builds
+            if rpc_request is None:
+                raise RuntimeError("Internal error: rpc_request is None after validation")
 
             # Create request context
             ctx = RequestContext(
@@ -844,6 +856,58 @@ class ASAPRequestHandler:
             if sender_error is not None:
                 return sender_error
 
+            # Validate envelope timestamp to prevent replay attacks
+            try:
+                validate_envelope_timestamp(envelope)
+            except InvalidTimestampError as e:
+                logger.warning(
+                    "asap.request.invalid_timestamp",
+                    envelope_id=envelope.id,
+                    error=e.message,
+                    details=e.details,
+                )
+                duration_seconds = time.perf_counter() - ctx.start_time
+                self.record_error_metrics(
+                    ctx.metrics, payload_type, "invalid_timestamp", duration_seconds
+                )
+                return self.build_error_response(
+                    INVALID_PARAMS,
+                    data={
+                        "error": "Invalid envelope timestamp",
+                        "code": e.code,
+                        "message": e.message,
+                        "details": e.details,
+                    },
+                    request_id=ctx.request_id,
+                )
+
+            # Validate envelope nonce if nonce store is available
+            try:
+                validate_envelope_nonce(envelope, self.nonce_store)
+            except InvalidNonceError as e:
+                # Sanitize nonce in logs to prevent full value exposure
+                nonce_sanitized = sanitize_nonce(e.nonce)
+                logger.warning(
+                    "asap.request.invalid_nonce",
+                    envelope_id=envelope.id,
+                    nonce=nonce_sanitized,
+                    error=e.message,
+                )
+                duration_seconds = time.perf_counter() - ctx.start_time
+                self.record_error_metrics(
+                    ctx.metrics, payload_type, "invalid_nonce", duration_seconds
+                )
+                return self.build_error_response(
+                    INVALID_PARAMS,
+                    data={
+                        "error": "Invalid envelope nonce",
+                        "code": e.code,
+                        "message": e.message,
+                        "details": e.details,
+                    },
+                    request_id=ctx.request_id,
+                )
+
             # Log request received
             logger.info(
                 "asap.request.received",
@@ -893,6 +957,7 @@ def create_app(
     rate_limit: str | None = None,
     max_request_size: int | None = None,
     max_threads: int | None = None,
+    require_nonce: bool = False,
 ) -> FastAPI:
     """Create and configure a FastAPI application for ASAP protocol.
 
@@ -920,6 +985,9 @@ def create_app(
         max_threads: Optional maximum number of threads for sync handlers.
             Defaults to ASAP_MAX_THREADS environment variable or min(32, cpu_count + 4).
             Set to None to use unbounded executor (not recommended for production).
+        require_nonce: If True, enables nonce validation for replay attack prevention.
+            When enabled, creates an InMemoryNonceStore and validates nonces in envelopes.
+            Defaults to False (nonce validation is optional).
 
     Returns:
         Configured FastAPI application ready to run
@@ -1003,8 +1071,17 @@ def create_app(
     if max_request_size is None:
         max_request_size = int(os.getenv("ASAP_MAX_REQUEST_SIZE", str(MAX_REQUEST_SIZE)))
 
+    # Create nonce store if required
+    nonce_store: NonceStore | None = None
+    if require_nonce:
+        nonce_store = InMemoryNonceStore()
+        logger.info(
+            "asap.server.nonce_validation_enabled",
+            manifest_id=manifest.id,
+        )
+
     # Create request handler
-    handler = ASAPRequestHandler(registry, manifest, auth_middleware, max_request_size)
+    handler = ASAPRequestHandler(registry, manifest, auth_middleware, max_request_size, nonce_store)
 
     app = FastAPI(
         title="ASAP Protocol Server",

asap/transport/validators.py

@@ -0,0 +1,324 @@
+"""Validation utilities for ASAP protocol envelopes.
+
+This module provides validation functions for envelope security checks,
+including timestamp validation for replay attack prevention and optional
+nonce validation for duplicate detection.
+"""
+
+import threading
+import time
+from datetime import datetime, timezone
+from typing import Protocol, runtime_checkable
+
+from asap.errors import InvalidNonceError, InvalidTimestampError
+from asap.models.constants import (
+    MAX_ENVELOPE_AGE_SECONDS,
+    MAX_FUTURE_TOLERANCE_SECONDS,
+    NONCE_TTL_SECONDS,
+)
+from asap.models.envelope import Envelope
+
+
+def validate_envelope_timestamp(envelope: Envelope) -> None:
+    """Validate envelope timestamp to prevent replay attacks.
+
+    Checks that the envelope timestamp is:
+    - Not older than MAX_ENVELOPE_AGE_SECONDS (default: 5 minutes)
+    - Not more than MAX_FUTURE_TOLERANCE_SECONDS in the future (default: 30 seconds)
+
+    Args:
+        envelope: The envelope to validate
+
+    Raises:
+        InvalidTimestampError: If the timestamp is too old or too far in the future
+
+    Example:
+        >>> from asap.models.envelope import Envelope
+        >>> from asap.transport.validators import validate_envelope_timestamp
+        >>>
+        >>> # Recent envelope passes
+        >>> recent = Envelope(
+        ...     asap_version="0.1",
+        ...     sender="urn:asap:agent:test",
+        ...     recipient="urn:asap:agent:test",
+        ...     payload_type="TaskRequest",
+        ...     payload={}
+        ... )
+        >>> validate_envelope_timestamp(recent)  # No exception
+        >>>
+        >>> # Old envelope raises error
+        >>> from datetime import datetime, timezone, timedelta
+        >>> old = Envelope(
+        ...     asap_version="0.1",
+        ...     sender="urn:asap:agent:test",
+        ...     recipient="urn:asap:agent:test",
+        ...     payload_type="TaskRequest",
+        ...     payload={},
+        ...     timestamp=datetime.now(timezone.utc) - timedelta(minutes=10)
+        ... )
+        >>> validate_envelope_timestamp(old)  # Raises InvalidTimestampError
+    """
+    if envelope.timestamp is None:
+        raise InvalidTimestampError(
+            timestamp="",
+            message="Envelope timestamp is required for validation",
+            details={"envelope_id": envelope.id},
+        )
+
+    now = datetime.now(timezone.utc)
+    timestamp = envelope.timestamp
+
+    # Ensure timestamp is timezone-aware (should be UTC)
+    if timestamp.tzinfo is None:
+        timestamp = timestamp.replace(tzinfo=timezone.utc)
+    else:
+        # Convert to UTC if needed
+        timestamp = timestamp.astimezone(timezone.utc)
+
+    # Calculate age in seconds
+    age_seconds = (now - timestamp).total_seconds()
+
+    # Check if envelope is too old
+    if age_seconds > MAX_ENVELOPE_AGE_SECONDS:
+        raise InvalidTimestampError(
+            timestamp=timestamp.isoformat(),
+            message=(
+                f"Envelope timestamp is too old: {age_seconds:.1f} seconds "
+                f"(max: {MAX_ENVELOPE_AGE_SECONDS} seconds)"
+            ),
+            age_seconds=age_seconds,
+            details={
+                "envelope_id": envelope.id,
+                "max_age_seconds": MAX_ENVELOPE_AGE_SECONDS,
+            },
+        )
+
+    # Check if envelope timestamp is too far in the future
+    future_offset_seconds = (timestamp - now).total_seconds()
+    if future_offset_seconds > MAX_FUTURE_TOLERANCE_SECONDS:
+        raise InvalidTimestampError(
+            timestamp=timestamp.isoformat(),
+            message=(
+                f"Envelope timestamp is too far in the future: "
+                f"{future_offset_seconds:.1f} seconds "
+                f"(max tolerance: {MAX_FUTURE_TOLERANCE_SECONDS} seconds)"
+            ),
+            future_offset_seconds=future_offset_seconds,
+            details={
+                "envelope_id": envelope.id,
+                "max_future_tolerance_seconds": MAX_FUTURE_TOLERANCE_SECONDS,
+            },
+        )
+
+
+@runtime_checkable
+class NonceStore(Protocol):
+    """Protocol for nonce storage and validation.
+
+    Implementations must provide thread-safe storage and TTL-based expiration
+    for nonce values to prevent replay attacks.
+    """
+
+    def is_used(self, nonce: str) -> bool:
+        """Check if a nonce has been used.
+
+        Args:
+            nonce: The nonce value to check
+
+        Returns:
+            True if the nonce has been used, False otherwise
+        """
+        ...
+
+    def mark_used(self, nonce: str, ttl_seconds: int) -> None:
+        """Mark a nonce as used with a TTL.
+
+        Args:
+            nonce: The nonce value to mark as used
+            ttl_seconds: Time-to-live in seconds for the nonce
+        """
+        ...
+
+    def check_and_mark(self, nonce: str, ttl_seconds: int) -> bool:
+        """Atomically check if nonce is used and mark it if not.
+
+        This method performs both check and mark operations atomically to
+        prevent race conditions between concurrent requests.
+
+        Args:
+            nonce: The nonce value to check and mark
+            ttl_seconds: Time-to-live in seconds for the nonce
+
+        Returns:
+            True if nonce was already used, False if it was newly marked
+        """
+        ...
+
+
+class InMemoryNonceStore:
+    """In-memory nonce store with TTL-based expiration.
+
+    This implementation uses a dictionary to store nonces with their
+    expiration times. Expired nonces are lazily cleaned up on access.
+
+    Attributes:
+        _store: Dictionary mapping nonce to expiration timestamp
+        _lock: Thread lock for thread-safe operations
+    """
+
+    def __init__(self) -> None:
+        """Initialize in-memory nonce store."""
+        self._store: dict[str, float] = {}
+        self._lock = threading.RLock()
+
+    def _cleanup_expired(self) -> None:
+        """Remove expired nonces from the store.
+
+        This is called lazily during access operations to keep the store
+        from growing unbounded.
+        """
+        now = time.time()
+        expired = [nonce for nonce, expiry in self._store.items() if expiry < now]
+        for nonce in expired:
+            self._store.pop(nonce, None)
+
+    def is_used(self, nonce: str) -> bool:
+        """Check if a nonce has been used.
+
+        Args:
+            nonce: The nonce value to check
+
+        Returns:
+            True if the nonce has been used and not expired, False otherwise
+        """
+        with self._lock:
+            self._cleanup_expired()
+            if nonce not in self._store:
+                return False
+            expiry = self._store[nonce]
+            return expiry >= time.time()
+
+    def mark_used(self, nonce: str, ttl_seconds: int) -> None:
+        """Mark a nonce as used with a TTL.
+
+        Args:
+            nonce: The nonce value to mark as used
+            ttl_seconds: Time-to-live in seconds for the nonce
+        """
+        with self._lock:
+            self._cleanup_expired()
+            expiry = time.time() + ttl_seconds
+            self._store[nonce] = expiry
+
+    def check_and_mark(self, nonce: str, ttl_seconds: int) -> bool:
+        """Atomically check if nonce is used and mark it if not.
+
+        This method performs both check and mark operations atomically to
+        prevent race conditions between concurrent requests with the same nonce.
+
+        Args:
+            nonce: The nonce value to check and mark
+            ttl_seconds: Time-to-live in seconds for the nonce
+
+        Returns:
+            True if nonce was already used, False if it was newly marked
+        """
+        with self._lock:
+            self._cleanup_expired()
+            if nonce in self._store and self._store[nonce] >= time.time():
+                return True  # Already used
+            self._store[nonce] = time.time() + ttl_seconds
+            return False  # Newly marked
+
+
+def validate_envelope_nonce(envelope: Envelope, nonce_store: NonceStore | None) -> None:
+    """Validate envelope nonce to prevent duplicate message replay.
+
+    If the envelope has a nonce in its extensions, checks that it hasn't
+    been used before. If no nonce is present, validation passes (nonce
+    is optional). If a nonce_store is not provided, validation is skipped.
+
+    Args:
+        envelope: The envelope to validate
+        nonce_store: Optional nonce store for duplicate detection
+
+    Raises:
+        InvalidNonceError: If the nonce has been used before
+
+    Example:
+        >>> from asap.models.envelope import Envelope
+        >>> from asap.transport.validators import (
+        ...     validate_envelope_nonce,
+        ...     InMemoryNonceStore
+        ... )
+        >>>
+        >>> store = InMemoryNonceStore()
+        >>>
+        >>> # Envelope without nonce passes
+        >>> envelope1 = Envelope(
+        ...     asap_version="0.1",
+        ...     sender="urn:asap:agent:test",
+        ...     recipient="urn:asap:agent:test",
+        ...     payload_type="TaskRequest",
+        ...     payload={}
+        ... )
+        >>> validate_envelope_nonce(envelope1, store)  # No exception
+        >>>
+        >>> # First use of nonce passes
+        >>> envelope2 = Envelope(
+        ...     asap_version="0.1",
+        ...     sender="urn:asap:agent:test",
+        ...     recipient="urn:asap:agent:test",
+        ...     payload_type="TaskRequest",
+        ...     payload={},
+        ...     extensions={"nonce": "unique-nonce-123"}
+        ... )
+        >>> validate_envelope_nonce(envelope2, store)  # No exception
+        >>>
+        >>> # Duplicate nonce raises error
+        >>> envelope3 = Envelope(
+        ...     asap_version="0.1",
+        ...     sender="urn:asap:agent:test",
+        ...     recipient="urn:asap:agent:test",
+        ...     payload_type="TaskRequest",
+        ...     payload={},
+        ...     extensions={"nonce": "unique-nonce-123"}
+        ... )
+        >>> validate_envelope_nonce(envelope3, store)  # Raises InvalidNonceError
+    """
+    # Skip validation if no nonce store provided
+    if nonce_store is None:
+        return
+
+    # Skip validation if no nonce in extensions
+    if not envelope.extensions or "nonce" not in envelope.extensions:
+        return
+
+    nonce = envelope.extensions["nonce"]
+
+    # Validate nonce is a non-empty string
+    if not isinstance(nonce, str) or not nonce:
+        raise InvalidNonceError(
+            nonce=str(nonce),
+            message=(
+                f"Nonce must be a non-empty string, got "
+                f"{type(nonce).__name__ if not isinstance(nonce, str) else 'empty string'}"
+            ),
+            details={"envelope_id": envelope.id},
+        )
+
+    # Atomically check and mark nonce as used to prevent race conditions
+    if nonce_store.check_and_mark(nonce, ttl_seconds=NONCE_TTL_SECONDS):
+        raise InvalidNonceError(
+            nonce=nonce,
+            message=f"Duplicate nonce detected: {nonce}",
+            details={"envelope_id": envelope.id},
+        )
+
+
+__all__ = [
+    "NonceStore",
+    "InMemoryNonceStore",
+    "validate_envelope_timestamp",
+    "validate_envelope_nonce",
+]

asap/utils/__init__.py

@@ -0,0 +1,7 @@
+"""Utility modules for ASAP protocol.
+
+This package contains utility functions used across the ASAP protocol
+implementation, including security utilities like log sanitization.
+"""
+
+__all__: list[str] = []

asap/utils/sanitization.py

@@ -0,0 +1,139 @@
+"""Log sanitization utilities for sensitive data protection.
+
+This module provides functions to sanitize sensitive data before logging
+to prevent credential leaks, token exposure, and other security issues.
+
+Example:
+    >>> from asap.utils.sanitization import sanitize_token, sanitize_nonce, sanitize_url
+    >>>
+    >>> # Sanitize a token (shows only first 8 characters)
+    >>> token = "sk_live_1234567890abcdef"
+    >>> sanitize_token(token)  # Returns: "sk_live_..."
+    >>>
+    >>> # Sanitize a nonce (shows first 8 characters + "...")
+    >>> nonce = "a1b2c3d4e5f6g7h8i9j0"
+    >>> sanitize_nonce(nonce)  # Returns: "a1b2c3d4..."
+    >>>
+    >>> # Sanitize a URL with credentials
+    >>> url = "https://user:password@example.com/api"
+    >>> sanitize_url(url)  # Returns: "https://user:***@example.com/api"
+"""
+
+import re
+from urllib.parse import urlparse, urlunparse
+
+# Sanitization configuration
+SANITIZE_PREFIX_LENGTH = 8
+"""Number of characters to show when truncating sensitive values.
+
+This constant defines how many characters of a sensitive value (token, nonce)
+are preserved when sanitizing for logs. The value balances security (preventing
+full exposure) with debuggability (allowing identification of value types).
+"""
+
+
+def sanitize_token(token: str) -> str:
+    """Sanitize a token for safe logging.
+
+    Returns only the first SANITIZE_PREFIX_LENGTH characters followed by "..."
+    to prevent full token exposure in logs while still allowing identification
+    of token type (e.g., "sk_live_", "pk_test_").
+
+    Args:
+        token: The token to sanitize
+
+    Returns:
+        Sanitized token string showing only prefix (e.g., "sk_live_...")
+
+    Example:
+        >>> sanitize_token("sk_live_1234567890abcdef")
+        'sk_live_...'
+        >>> sanitize_token("short")
+        'short'
+    """
+    if not token:
+        return ""
+    if len(token) <= SANITIZE_PREFIX_LENGTH:
+        return token
+    return f"{token[:SANITIZE_PREFIX_LENGTH]}..."
+
+
+def sanitize_nonce(nonce: str) -> str:
+    """Sanitize a nonce for safe logging.
+
+    Returns the first SANITIZE_PREFIX_LENGTH characters followed by "..."
+    to prevent full nonce exposure in logs while still allowing identification
+    for debugging purposes.
+
+    Args:
+        nonce: The nonce to sanitize
+
+    Returns:
+        Sanitized nonce string showing first characters + "..." (e.g., "a1b2c3d4...")
+
+    Example:
+        >>> sanitize_nonce("a1b2c3d4e5f6g7h8i9j0")
+        'a1b2c3d4...'
+        >>> sanitize_nonce("short")
+        'short'
+    """
+    if not nonce:
+        return ""
+    if len(nonce) <= SANITIZE_PREFIX_LENGTH:
+        return nonce
+    return f"{nonce[:SANITIZE_PREFIX_LENGTH]}..."
+
+
+def sanitize_url(url: str) -> str:
+    """Sanitize a URL by masking credentials in the userinfo component.
+
+    Masks passwords in URLs of the form:
+    - `https://user:password@example.com` → `https://user:***@example.com`
+    - `https://user@example.com` → `https://user@example.com` (no change)
+
+    Args:
+        url: The URL to sanitize
+
+    Returns:
+        Sanitized URL with masked credentials
+
+    Example:
+        >>> sanitize_url("https://user:secret@example.com/api")
+        'https://user:***@example.com/api'
+        >>> sanitize_url("https://example.com/api")
+        'https://example.com/api'
+    """
+    if not url:
+        return ""
+
+    try:
+        parsed = urlparse(url)
+        if (parsed.username or parsed.password) and parsed.password:
+            # Mask password if present
+            # Reconstruct netloc with masked password
+            netloc = f"{parsed.username}:***@{parsed.hostname}"
+            if parsed.port:
+                netloc = f"{netloc}:{parsed.port}"
+            # Reconstruct URL with sanitized netloc
+            return urlunparse(
+                (
+                    parsed.scheme,
+                    netloc,
+                    parsed.path,
+                    parsed.params,
+                    parsed.query,
+                    parsed.fragment,
+                )
+            )
+        return url
+    except Exception:
+        # If URL parsing fails, return a safe fallback
+        # Remove any obvious credential patterns
+        return re.sub(r"://[^:]+:[^@]+@", r"://***:***@", url)
+
+
+__all__ = [
+    "sanitize_token",
+    "sanitize_nonce",
+    "sanitize_url",
+]