signalwire-agents 0.1.6__py3-none-any.whl → 1.0.7__py3-none-any.whl

signalwire_agents/core/security/session_manager.py

@@ -14,73 +14,92 @@ Session manager for handling call sessions and security tokens
 from typing import Dict, Any, Optional, Tuple
 import secrets
 import time
-from datetime import datetime
-
-
-class CallSession:
-    """
-    Represents a single call session with associated tokens and state
-    """
-    def __init__(self, call_id: str):
-        self.call_id = call_id
-        self.tokens: Dict[str, str] = {}  # function_name -> token
-        self.state = "pending"  # pending, active, expired
-        self.started_at = datetime.now()
-        self.metadata: Dict[str, Any] = {}  # Custom state for the call
+import hmac
+import hashlib
+import base64
+from datetime import datetime, timedelta
 
 
 class SessionManager:
     """
-    Manages call sessions and their associated security tokens
+    Manages security tokens for function calls
+    
+    This implementation is completely stateless - it does not track call sessions
+    or store any information in memory. All validation is done using cryptographic
+    signatures with the tokens containing all necessary information.
     """
-    def __init__(self, token_expiry_secs: int = 600):
+    def __init__(self, token_expiry_secs: int = 3600, secret_key: Optional[str] = None):
         """
         Initialize the session manager
         
         Args:
-            token_expiry_secs: Seconds until tokens expire (default: 10 minutes)
+            token_expiry_secs: Seconds until tokens expire (default: 60 minutes)
+            secret_key: Secret key for signing tokens (generated if not provided)
         """
-        self._active_calls: Dict[str, CallSession] = {}
         self.token_expiry_secs = token_expiry_secs
+        # Use provided secret key or generate a secure one
+        self.secret_key = secret_key or secrets.token_hex(32)
     
     def create_session(self, call_id: Optional[str] = None) -> str:
         """
-        Create a new call session
+        Create a new session ID if one isn't provided
         
         Args:
             call_id: Optional call ID, generated if not provided
             
         Returns:
-            The call_id for the new session
+            The call_id for the session
         """
         # Generate call_id if not provided
         if not call_id:
             call_id = secrets.token_urlsafe(16)
         
-        # Create new session
-        self._active_calls[call_id] = CallSession(call_id)
         return call_id
     
     def generate_token(self, function_name: str, call_id: str) -> str:
         """
-        Generate a secure token for a function call
+        Generate a secure self-contained token for a function call
         
         Args:
             function_name: Name of the function to generate a token for
             call_id: Call session ID
             
         Returns:
-            A secure random token
-            
-        Raises:
-            ValueError: If the call session does not exist
+            A secure token
         """
-        if call_id not in self._active_calls:
-            raise ValueError(f"No active session for call_id: {call_id}")
+        # Create token parts
+        expiry = int(time.time()) + self.token_expiry_secs
+        nonce = secrets.token_hex(4)
+        
+        # Create the message to sign
+        message = f"{call_id}:{function_name}:{expiry}:{nonce}"
+        
+        # Sign the message
+        signature = hmac.new(
+            self.secret_key.encode(),
+            message.encode(),
+            hashlib.sha256
+        ).hexdigest()[:16]  # Use first 16 chars of signature for shorter tokens
         
-        token = secrets.token_urlsafe(24)
-        self._active_calls[call_id].tokens[function_name] = token
-        return token
+        # Combine all parts into the token
+        token = f"{call_id}.{function_name}.{expiry}.{nonce}.{signature}"
+        
+        # Base64 encode for URL safety
+        return base64.urlsafe_b64encode(token.encode()).decode()
+    
+    # Alias for generate_token to maintain backward compatibility
+    def create_tool_token(self, function_name: str, call_id: str) -> str:
+        """
+        Alias for generate_token to maintain backward compatibility
+        
+        Args:
+            function_name: Name of the function to generate a token for
+            call_id: Call session ID
+            
+        Returns:
+            A secure token
+        """
+        return self.generate_token(function_name, call_id)
     
     def validate_token(self, call_id: str, function_name: str, token: str) -> bool:
         """
@@ -94,86 +113,155 @@ class SessionManager:
         Returns:
             True if valid, False otherwise
         """
-        session = self._active_calls.get(call_id)
-        if not session or session.state != "active":
-            return False
-        
-        # Check if token matches and is not expired
-        expected_token = session.tokens.get(function_name)
-        if not expected_token or expected_token != token:
-            return False
+        try:
+            # Decode the token
+            decoded_token = base64.urlsafe_b64decode(token.encode()).decode()
             
-        # Check expiry
-        now = datetime.now()
-        seconds_elapsed = (now - session.started_at).total_seconds()
-        if seconds_elapsed > self.token_expiry_secs:
-            session.state = "expired"
-            return False
+            # Split the token parts
+            parts = decoded_token.split('.')
+            if len(parts) != 5:
+                return False
+                
+            token_call_id, token_function, token_expiry, token_nonce, token_signature = parts
             
-        return True
+            # Special case: if call_id is None or empty, use the call_id from the token
+            # This helps with scenarios where the call_id isn't provided in the request
+            if not call_id:
+                call_id = token_call_id
+            
+            # Verify the function matches
+            if token_function != function_name:
+                return False
+                
+            # Check if the token has expired
+            expiry = int(token_expiry)
+            if expiry < time.time():
+                return False
+                
+            # Recreate the message and verify the signature
+            message = f"{token_call_id}:{token_function}:{token_expiry}:{token_nonce}"
+            expected_signature = hmac.new(
+                self.secret_key.encode(),
+                message.encode(),
+                hashlib.sha256
+            ).hexdigest()[:16]
+            
+            if token_signature != expected_signature:
+                return False
+                
+            # Finally, verify the call_id matches unless we're in special case
+            # This check is done last to ensure the token is otherwise valid
+            if token_call_id != call_id:
+                return False
+                
+            return True
+        except Exception:
+            # Any exception during validation means the token is invalid
+            return False
     
-    def activate_session(self, call_id: str) -> bool:
+    # Alias for validate_token to maintain backward compatibility
+    def validate_tool_token(self, function_name: str, token: str, call_id: str) -> bool:
         """
-        Activate a call session (called by startup_hook)
+        Alias for validate_token to maintain backward compatibility
         
         Args:
+            function_name: Name of the function being called
+            token: Token to validate
             call_id: Call session ID
             
         Returns:
-            True if successful, False otherwise
+            True if valid, False otherwise
+        """
+        # Reorder parameters to match validate_token signature (call_id first, then function_name)
+        return self.validate_token(call_id=call_id, function_name=function_name, token=token)
+    
+    # Legacy methods that now don't track state but provide API compatibility
+    
+    def activate_session(self, call_id: str) -> bool:
+        """
+        Legacy method, does nothing but returns success
         """
-        session = self._active_calls.get(call_id)
-        if not session:
-            return False
-            
-        session.state = "active"
         return True
     
     def end_session(self, call_id: str) -> bool:
         """
-        End a call session (called by hangup_hook)
-        
-        Args:
-            call_id: Call session ID
-            
-        Returns:
-            True if successful, False otherwise
+        Legacy method, does nothing but returns success
         """
-        if call_id in self._active_calls:
-            del self._active_calls[call_id]
-            return True
-        return False
+        return True
     
     def get_session_metadata(self, call_id: str) -> Optional[Dict[str, Any]]:
         """
-        Get custom metadata for a call session
-        
-        Args:
-            call_id: Call session ID
-            
-        Returns:
-            Metadata dict or None if session not found
+        Legacy method, always returns empty metadata
         """
-        session = self._active_calls.get(call_id)
-        if not session:
-            return None
-        return session.metadata
+        return {}
     
     def set_session_metadata(self, call_id: str, key: str, value: Any) -> bool:
         """
-        Set custom metadata for a call session
+        Legacy method, does nothing but returns success
+        """
+        return True
+    
+    def debug_token(self, token: str) -> Dict[str, Any]:
+        """
+        Debug a token without validating it
+        
+        This method decodes the token and extracts its components for debugging purposes
+        without performing validation.
         
         Args:
-            call_id: Call session ID
-            key: Metadata key
-            value: Metadata value
+            token: The token to debug
             
         Returns:
-            True if successful, False otherwise
+            Dictionary with token components and analysis
         """
-        session = self._active_calls.get(call_id)
-        if not session:
-            return False
+        try:
+            # Decode the token
+            decoded_token = base64.urlsafe_b64decode(token.encode()).decode()
             
-        session.metadata[key] = value
-        return True
+            # Split the token parts
+            parts = decoded_token.split('.')
+            if len(parts) != 5:
+                return {
+                    "valid_format": False,
+                    "parts_count": len(parts),
+                    "decoded": decoded_token
+                }
+                
+            token_call_id, token_function, token_expiry, token_nonce, token_signature = parts
+            
+            # Check expiration
+            current_time = int(time.time())
+            try:
+                expiry = int(token_expiry)
+                is_expired = expiry < current_time
+                expires_in = expiry - current_time if not is_expired else 0
+                expiry_date = datetime.fromtimestamp(expiry).isoformat()
+            except ValueError:
+                expiry = None
+                is_expired = None
+                expires_in = None
+                expiry_date = None
+            
+            return {
+                "valid_format": True,
+                "components": {
+                    "call_id": token_call_id,
+                    "function": token_function,
+                    "expiry": token_expiry,
+                    "expiry_date": expiry_date,
+                    "nonce": token_nonce,
+                    "signature": token_signature
+                },
+                "status": {
+                    "current_time": current_time,
+                    "is_expired": is_expired,
+                    "expires_in_seconds": expires_in
+                }
+            }
+        except Exception as e:
+            # Any exception during parsing
+            return {
+                "valid_format": False,
+                "error": str(e),
+                "token": token
+            }

signalwire_agents/core/security_config.py

@@ -0,0 +1,333 @@
+"""
+Copyright (c) 2025 SignalWire
+
+This file is part of the SignalWire AI Agents SDK.
+
+Licensed under the MIT License.
+See LICENSE file in the project root for full license information.
+"""
+
+import os
+import secrets
+from typing import Dict, Any, Optional, Tuple, List, Union
+from signalwire_agents.core.logging_config import get_logger
+from signalwire_agents.core.config_loader import ConfigLoader
+
+logger = get_logger("security_config")
+
+
+class SecurityConfig:
+    """
+    Unified security configuration for SignalWire services.
+    
+    This class provides centralized security settings that can be used by
+    both SWML and Search services, ensuring consistent security behavior.
+    """
+    
+    # Security environment variable names
+    SSL_ENABLED = 'SWML_SSL_ENABLED'
+    SSL_CERT_PATH = 'SWML_SSL_CERT_PATH'
+    SSL_KEY_PATH = 'SWML_SSL_KEY_PATH'
+    SSL_DOMAIN = 'SWML_DOMAIN'
+    SSL_VERIFY_MODE = 'SWML_SSL_VERIFY_MODE'
+    
+    # Additional security settings
+    ALLOWED_HOSTS = 'SWML_ALLOWED_HOSTS'
+    CORS_ORIGINS = 'SWML_CORS_ORIGINS'
+    MAX_REQUEST_SIZE = 'SWML_MAX_REQUEST_SIZE'
+    RATE_LIMIT = 'SWML_RATE_LIMIT'
+    REQUEST_TIMEOUT = 'SWML_REQUEST_TIMEOUT'
+    USE_HSTS = 'SWML_USE_HSTS'
+    HSTS_MAX_AGE = 'SWML_HSTS_MAX_AGE'
+    
+    # Authentication
+    BASIC_AUTH_USER = 'SWML_BASIC_AUTH_USER'
+    BASIC_AUTH_PASSWORD = 'SWML_BASIC_AUTH_PASSWORD'
+    
+    # Defaults (secure by default)
+    DEFAULTS = {
+        SSL_ENABLED: False,  # Off by default, but secure when enabled
+        SSL_VERIFY_MODE: 'CERT_REQUIRED',
+        ALLOWED_HOSTS: '*',  # Accept all hosts by default for backward compatibility
+        CORS_ORIGINS: '*',  # Accept all origins by default for backward compatibility
+        MAX_REQUEST_SIZE: 10 * 1024 * 1024,  # 10MB
+        RATE_LIMIT: 60,  # Requests per minute
+        REQUEST_TIMEOUT: 30,  # Seconds
+        USE_HSTS: True,  # Enable HSTS when HTTPS is on
+        HSTS_MAX_AGE: 31536000,  # 1 year
+    }
+    
+    def __init__(self, config_file: Optional[str] = None, service_name: Optional[str] = None):
+        """
+        Initialize security configuration.
+        
+        Args:
+            config_file: Optional path to config file
+            service_name: Optional service name for finding service-specific config
+        """
+        # First, set defaults
+        self._set_defaults()
+        
+        # Then load from environment variables (backward compatibility)
+        self.load_from_env()
+        
+        # Finally, apply config file if available (highest priority)
+        self._load_config_file(config_file, service_name)
+    
+    def _set_defaults(self):
+        """Set default values for all configuration"""
+        # SSL configuration
+        self.ssl_enabled = self.DEFAULTS[self.SSL_ENABLED]
+        self.ssl_cert_path = None
+        self.ssl_key_path = None
+        self.domain = None
+        self.ssl_verify_mode = self.DEFAULTS[self.SSL_VERIFY_MODE]
+        
+        # Additional settings
+        self.allowed_hosts = self._parse_list(self.DEFAULTS[self.ALLOWED_HOSTS])
+        self.cors_origins = self._parse_list(self.DEFAULTS[self.CORS_ORIGINS])
+        self.max_request_size = self.DEFAULTS[self.MAX_REQUEST_SIZE]
+        self.rate_limit = self.DEFAULTS[self.RATE_LIMIT]
+        self.request_timeout = self.DEFAULTS[self.REQUEST_TIMEOUT]
+        self.use_hsts = self.DEFAULTS[self.USE_HSTS]
+        self.hsts_max_age = self.DEFAULTS[self.HSTS_MAX_AGE]
+        
+        # Authentication
+        self.basic_auth_user = None
+        self.basic_auth_password = None
+    
+    def _load_config_file(self, config_file: Optional[str], service_name: Optional[str]):
+        """Load configuration from config file if available"""
+        # Find config file
+        if not config_file:
+            config_file = ConfigLoader.find_config_file(service_name)
+        
+        if not config_file:
+            return
+        
+        # Load config
+        config_loader = ConfigLoader([config_file])
+        if not config_loader.has_config():
+            return
+        
+        logger.info("loading_config_from_file", file=config_file)
+        
+        # Get security section
+        security_config = config_loader.get_section('security')
+        if not security_config:
+            return
+        
+        # Apply security settings (config file takes precedence)
+        if 'ssl_enabled' in security_config:
+            self.ssl_enabled = security_config['ssl_enabled']
+        
+        if 'ssl_cert_path' in security_config:
+            self.ssl_cert_path = security_config['ssl_cert_path']
+            
+        if 'ssl_key_path' in security_config:
+            self.ssl_key_path = security_config['ssl_key_path']
+            
+        if 'domain' in security_config:
+            self.domain = security_config['domain']
+            
+        if 'ssl_verify_mode' in security_config:
+            self.ssl_verify_mode = security_config['ssl_verify_mode']
+        
+        # Additional settings
+        if 'allowed_hosts' in security_config:
+            self.allowed_hosts = self._parse_list(security_config['allowed_hosts'])
+            
+        if 'cors_origins' in security_config:
+            self.cors_origins = self._parse_list(security_config['cors_origins'])
+            
+        if 'max_request_size' in security_config:
+            self.max_request_size = int(security_config['max_request_size'])
+            
+        if 'rate_limit' in security_config:
+            self.rate_limit = int(security_config['rate_limit'])
+            
+        if 'request_timeout' in security_config:
+            self.request_timeout = int(security_config['request_timeout'])
+            
+        if 'use_hsts' in security_config:
+            self.use_hsts = security_config['use_hsts']
+            
+        if 'hsts_max_age' in security_config:
+            self.hsts_max_age = int(security_config['hsts_max_age'])
+        
+        # Authentication from config
+        auth_config = security_config.get('auth', {})
+        if isinstance(auth_config, dict):
+            basic_auth = auth_config.get('basic', {})
+            if isinstance(basic_auth, dict):
+                if 'user' in basic_auth:
+                    self.basic_auth_user = basic_auth['user']
+                if 'password' in basic_auth:
+                    self.basic_auth_password = basic_auth['password']
+        
+    def load_from_env(self):
+        """Load configuration from environment variables"""
+        # SSL configuration
+        ssl_enabled_env = os.environ.get(self.SSL_ENABLED, '').lower()
+        self.ssl_enabled = ssl_enabled_env in ('true', '1', 'yes')
+        self.ssl_cert_path = os.environ.get(self.SSL_CERT_PATH)
+        self.ssl_key_path = os.environ.get(self.SSL_KEY_PATH)
+        self.domain = os.environ.get(self.SSL_DOMAIN)
+        self.ssl_verify_mode = os.environ.get(self.SSL_VERIFY_MODE, self.DEFAULTS[self.SSL_VERIFY_MODE])
+        
+        # Additional security settings
+        self.allowed_hosts = self._parse_list(os.environ.get(self.ALLOWED_HOSTS, self.DEFAULTS[self.ALLOWED_HOSTS]))
+        self.cors_origins = self._parse_list(os.environ.get(self.CORS_ORIGINS, self.DEFAULTS[self.CORS_ORIGINS]))
+        self.max_request_size = int(os.environ.get(self.MAX_REQUEST_SIZE, self.DEFAULTS[self.MAX_REQUEST_SIZE]))
+        self.rate_limit = int(os.environ.get(self.RATE_LIMIT, self.DEFAULTS[self.RATE_LIMIT]))
+        self.request_timeout = int(os.environ.get(self.REQUEST_TIMEOUT, self.DEFAULTS[self.REQUEST_TIMEOUT]))
+        
+        # HSTS settings
+        use_hsts_env = os.environ.get(self.USE_HSTS, '').lower()
+        self.use_hsts = use_hsts_env != 'false' if use_hsts_env else self.DEFAULTS[self.USE_HSTS]
+        self.hsts_max_age = int(os.environ.get(self.HSTS_MAX_AGE, self.DEFAULTS[self.HSTS_MAX_AGE]))
+        
+        # Authentication
+        self.basic_auth_user = os.environ.get(self.BASIC_AUTH_USER)
+        self.basic_auth_password = os.environ.get(self.BASIC_AUTH_PASSWORD)
+        
+    def _parse_list(self, value: Union[str, list]) -> list:
+        """Parse comma-separated list from environment variable or list from config"""
+        if isinstance(value, list):
+            return value
+        if value == '*':
+            return ['*']
+        return [item.strip() for item in value.split(',') if item.strip()]
+    
+    def validate_ssl_config(self) -> Tuple[bool, Optional[str]]:
+        """
+        Validate SSL configuration.
+        
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not self.ssl_enabled:
+            return True, None
+            
+        if not self.ssl_cert_path:
+            return False, "SSL enabled but SWML_SSL_CERT_PATH not set"
+            
+        if not self.ssl_key_path:
+            return False, "SSL enabled but SWML_SSL_KEY_PATH not set"
+            
+        if not os.path.exists(self.ssl_cert_path):
+            return False, f"SSL certificate file not found: {self.ssl_cert_path}"
+            
+        if not os.path.exists(self.ssl_key_path):
+            return False, f"SSL key file not found: {self.ssl_key_path}"
+            
+        return True, None
+    
+    def get_ssl_context_kwargs(self) -> Dict[str, Any]:
+        """
+        Get SSL context kwargs for uvicorn.
+        
+        Returns:
+            Dictionary of SSL parameters for uvicorn
+        """
+        if not self.ssl_enabled:
+            return {}
+            
+        is_valid, error = self.validate_ssl_config()
+        if not is_valid:
+            logger.error("ssl_validation_failed", error=error)
+            return {}
+            
+        return {
+            'ssl_certfile': self.ssl_cert_path,
+            'ssl_keyfile': self.ssl_key_path,
+            # Additional SSL options can be added here
+        }
+    
+    def get_basic_auth(self) -> Tuple[str, str]:
+        """
+        Get basic auth credentials, generating if not set.
+        
+        Returns:
+            Tuple of (username, password)
+        """
+        username = self.basic_auth_user or "signalwire"
+        password = self.basic_auth_password or secrets.token_urlsafe(32)
+        
+        return username, password
+    
+    def get_security_headers(self, is_https: bool = False) -> Dict[str, str]:
+        """
+        Get security headers to add to responses.
+        
+        Args:
+            is_https: Whether the connection is over HTTPS
+            
+        Returns:
+            Dictionary of security headers
+        """
+        headers = {
+            'X-Content-Type-Options': 'nosniff',
+            'X-Frame-Options': 'DENY',
+            'X-XSS-Protection': '1; mode=block',
+            'Referrer-Policy': 'strict-origin-when-cross-origin',
+        }
+        
+        # Add HSTS header if HTTPS and enabled
+        if is_https and self.use_hsts:
+            headers['Strict-Transport-Security'] = f'max-age={self.hsts_max_age}; includeSubDomains'
+            
+        return headers
+    
+    def should_allow_host(self, host: str) -> bool:
+        """
+        Check if a host is allowed.
+        
+        Args:
+            host: The host to check
+            
+        Returns:
+            True if the host is allowed
+        """
+        if '*' in self.allowed_hosts:
+            return True
+            
+        return host in self.allowed_hosts
+    
+    def get_cors_config(self) -> Dict[str, Any]:
+        """
+        Get CORS configuration for FastAPI.
+        
+        Returns:
+            Dictionary of CORS settings
+        """
+        return {
+            'allow_origins': self.cors_origins,
+            'allow_credentials': True,
+            'allow_methods': ['*'],
+            'allow_headers': ['*'],
+        }
+    
+    def get_url_scheme(self) -> str:
+        """Get the URL scheme based on SSL configuration"""
+        return 'https' if self.ssl_enabled else 'http'
+    
+    def log_config(self, service_name: str):
+        """Log the current security configuration"""
+        logger.info(
+            "security_config_loaded",
+            service=service_name,
+            ssl_enabled=self.ssl_enabled,
+            domain=self.domain,
+            allowed_hosts=self.allowed_hosts,
+            cors_origins=self.cors_origins,
+            max_request_size=self.max_request_size,
+            rate_limit=self.rate_limit,
+            use_hsts=self.use_hsts,
+            has_basic_auth=bool(self.basic_auth_user and self.basic_auth_password)
+        )
+
+
+# Global instance for easy access (backward compatibility)
+# Services can create their own instances with specific config files
+security_config = SecurityConfig()