signalwire-agents 0.1.5__py3-none-any.whl → 0.1.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/swml_service.py

@@ -126,6 +126,11 @@ class SWMLService:
         self.ssl_enabled = False
         self.domain = None
         
+        # Initialize proxy detection attributes
+        self._proxy_url_base = os.environ.get('SWML_PROXY_URL_BASE')
+        self._proxy_detection_done = False
+        self._proxy_debug = os.environ.get('SWML_PROXY_DEBUG', '').lower() in ('true', '1', 'yes')
+        
         # Initialize logger for this instance
         self.log = logger.bind(service=name)
         self.log.info("service_initializing", route=self.route, host=host, port=port)
@@ -560,58 +565,41 @@ class SWMLService:
     
     def as_router(self) -> APIRouter:
         """
-        Get a FastAPI router for this service
+        Create a FastAPI router for this service
         
         Returns:
-            FastAPI router
+            APIRouter: FastAPI router
         """
-        router = APIRouter()
+        router = APIRouter(redirect_slashes=False)
         
-        # Root endpoint - without trailing slash
-        @router.get("")
-        @router.post("")
-        async def handle_root_no_slash(request: Request, response: Response):
-            """Handle GET/POST requests to the root endpoint"""
-            return await self._handle_request(request, response)
-            
-        # Root endpoint - with trailing slash
+        # Root endpoint with and without trailing slash
         @router.get("/")
         @router.post("/")
-        async def handle_root_with_slash(request: Request, response: Response):
-            """Handle GET/POST requests to the root endpoint with trailing slash"""
+        async def handle_root(request: Request, response: Response):
+            """Handle requests to the root endpoint"""
             return await self._handle_request(request, response)
         
-        # Add endpoints for all registered routing callbacks
+        # Register routing callbacks as needed
         if hasattr(self, '_routing_callbacks') and self._routing_callbacks:
             for callback_path, callback_fn in self._routing_callbacks.items():
-                # Skip the root path as it's already handled
+                # Skip the root path which is already handled
                 if callback_path == "/":
                     continue
                     
-                # Register the endpoint without trailing slash
-                @router.get(callback_path)
-                @router.post(callback_path)
-                async def handle_callback_no_slash(request: Request, response: Response, cb_path=callback_path):
-                    """Handle GET/POST requests to a registered callback path"""
-                    # Store the callback path in request state for _handle_request to use
+                # Register both versions: with and without trailing slash
+                path = callback_path.rstrip("/")
+                path_with_slash = f"{path}/"
+                
+                @router.get(path)
+                @router.get(path_with_slash)
+                @router.post(path)
+                @router.post(path_with_slash)
+                async def handle_callback(request: Request, response: Response, cb_path=callback_path):
+                    """Handle requests to callback endpoints"""
+                    # Store the callback path in the request state
                     request.state.callback_path = cb_path
                     return await self._handle_request(request, response)
-                    
-                # Register the endpoint with trailing slash if it doesn't already have one
-                if not callback_path.endswith('/'):
-                    slash_path = f"{callback_path}/"
-                    
-                    @router.get(slash_path)
-                    @router.post(slash_path)
-                    async def handle_callback_with_slash(request: Request, response: Response, cb_path=callback_path):
-                        """Handle GET/POST requests to a registered callback path with trailing slash"""
-                        # Store the callback path in request state for _handle_request to use
-                        request.state.callback_path = cb_path
-                        return await self._handle_request(request, response)
-                        
-                self.log.info("callback_endpoint_registered", path=callback_path)
         
-        self._router = router
         return router
     
     def register_routing_callback(self, callback_fn: Callable[[Request, Dict[str, Any]], Optional[str]], 
@@ -691,6 +679,11 @@ class SWMLService:
         Returns:
             Response with SWML document or error
         """
+        # Auto-detect proxy on first request if not explicitly configured
+        if not self._proxy_detection_done and not self._proxy_url_base:
+            self._detect_proxy_from_request(request)
+            self._proxy_detection_done = True
+            
         # Check auth
         if not self._check_basic_auth(request):
             response.headers["WWW-Authenticate"] = "Basic"
@@ -779,20 +772,22 @@ class SWMLService:
         Start a web server for this service
         
         Args:
-            host: Optional host to override the default
-            port: Optional port to override the default
+            host: Host to bind to (defaults to self.host)
+            port: Port to bind to (defaults to self.port)
             ssl_cert: Path to SSL certificate file
-            ssl_key: Path to SSL private key file
-            ssl_enabled: Whether to enable SSL/HTTPS
-            domain: Domain name for the SSL certificate and external URLs
+            ssl_key: Path to SSL key file
+            ssl_enabled: Whether to enable SSL
+            domain: Domain name for SSL certificate
         """
         import uvicorn
         
-        # Determine SSL settings from parameters or environment variables
-        self.ssl_enabled = ssl_enabled if ssl_enabled is not None else os.environ.get('SWML_SSL_ENABLED', '').lower() in ('true', '1', 'yes')
-        ssl_cert_path = ssl_cert or os.environ.get('SWML_SSL_CERT_PATH', '')
-        ssl_key_path = ssl_key or os.environ.get('SWML_SSL_KEY_PATH', '')
-        self.domain = domain or os.environ.get('SWML_DOMAIN', '')
+        # Store SSL configuration
+        self.ssl_enabled = ssl_enabled if ssl_enabled is not None else False
+        self.domain = domain
+        
+        # Set SSL paths
+        ssl_cert_path = ssl_cert
+        ssl_key_path = ssl_key
         
         # Validate SSL configuration if enabled
         if self.ssl_enabled:
@@ -807,9 +802,64 @@ class SWMLService:
                 # We'll continue, but URLs might not be correctly generated
         
         if self._app is None:
-            app = FastAPI()
+            # Use redirect_slashes=False to be consistent with AgentBase
+            app = FastAPI(redirect_slashes=False)
             router = self.as_router()
-            app.include_router(router, prefix=self.route)
+            
+            # Normalize the route to ensure it starts with a slash and doesn't end with one
+            # This avoids the FastAPI error about prefixes ending with slashes
+            normalized_route = "/" + self.route.strip("/")
+            
+            # Include router with the normalized prefix
+            app.include_router(router, prefix=normalized_route)
+            
+            # Add a catch-all route handler that will handle both /path and /path/ formats
+            # This provides the same behavior without using a trailing slash in the prefix
+            @app.get("/{full_path:path}")
+            @app.post("/{full_path:path}")
+            async def handle_all_routes(request: Request, response: Response, full_path: str):
+                # Get our route path without leading slash for comparison
+                route_path = normalized_route.lstrip("/")
+                route_with_slash = route_path + "/"
+                
+                # Log the incoming path for debugging
+                print(f"Catch-all received: '{full_path}', route: '{route_path}'")
+                
+                # Check for exact match to our route (without trailing slash)
+                if full_path == route_path:
+                    # This is our exact route - handle it directly
+                    return await self._handle_request(request, response)
+                    
+                # Check for our route with a trailing slash or subpaths
+                elif full_path == route_with_slash or full_path.startswith(route_with_slash):
+                    # This is our route with a trailing slash
+                    # Extract the path after our route prefix
+                    sub_path = full_path[len(route_with_slash):]
+                    
+                    # Forward to the appropriate handler in our router
+                    if not sub_path:
+                        # Root endpoint
+                        return await self._handle_request(request, response)
+                    
+                    # Check for routing callbacks if there are any
+                    if hasattr(self, '_routing_callbacks'):
+                        for callback_path, callback_fn in self._routing_callbacks.items():
+                            cb_path_clean = callback_path.strip("/")
+                            if sub_path == cb_path_clean or sub_path.startswith(cb_path_clean + "/"):
+                                # Store the callback path in request state for handlers to use
+                                request.state.callback_path = callback_path
+                                return await self._handle_request(request, response)
+                
+                # Not our route or not matching our patterns
+                print(f"No match for path: '{full_path}'")
+                return {"error": "Path not found"}
+            
+            # Print all routes for debugging
+            print(f"All routes for {self.name}:")
+            for route in app.routes:
+                if hasattr(route, "path"):
+                    print(f"  {route.path}")
+            
             self._app = app
         
         host = host or self.host
@@ -830,13 +880,14 @@ class SWMLService:
         
         print(f"Service '{self.name}' is available at:")
         print(f"URL: {protocol}://{display_host}{self.route}")
+        print(f"URL with trailing slash: {protocol}://{display_host}{self.route}/")
         print(f"Basic Auth: {username}:{password}")
         
         # Check if SIP routing is enabled and print additional info
         if self._routing_callbacks:
             print(f"Callback endpoints:")
             for path in self._routing_callbacks:
-                print(f"{protocol}://{display_host}{path}")
+                print(f"{protocol}://{display_host}{self.route}{path}")
         
         # Start uvicorn with or without SSL
         if self.ssl_enabled and ssl_cert_path and ssl_key_path:
@@ -1054,4 +1105,98 @@ class SWMLService:
                 params = "&".join([f"{k}={v}" for k, v in filtered_params.items()])
                 url = f"{url}?{params}"
             
-        return url 
+        return url 
+
+    def _detect_proxy_from_request(self, request: Request) -> None:
+        """
+        Detect if we're behind a proxy by examining request headers
+        and auto-configure proxy_url_base if needed
+        
+        Args:
+            request: FastAPI Request object
+        """
+        # First check for standard X-Forwarded headers (used by most proxies including ngrok)
+        forwarded_host = request.headers.get("X-Forwarded-Host")
+        forwarded_proto = request.headers.get("X-Forwarded-Proto", "http")
+        
+        if forwarded_host:
+            # Direct X-Forwarded-* headers - most common case
+            self._proxy_url_base = f"{forwarded_proto}://{forwarded_host}"
+            self.log.info("proxy_auto_detected", proxy_url_base=self._proxy_url_base, 
+                        source="X-Forwarded headers")
+            return
+            
+        # If no standard headers, check other proxy detection methods
+        
+        # Check for Forwarded header (RFC 7239)
+        forwarded = request.headers.get("Forwarded")
+        if forwarded:
+            # Parse RFC 7239 Forwarded header
+            try:
+                # Extract host and proto from Forwarded: for=X;host=Y;proto=Z
+                parts = [p.strip() for p in forwarded.split(';')]
+                host_part = next((p for p in parts if p.startswith("host=")), None)
+                proto_part = next((p for p in parts if p.startswith("proto=")), None)
+                
+                if host_part:
+                    host = host_part.split('=', 1)[1].strip('"')
+                    proto = proto_part.split('=', 1)[1].strip('"') if proto_part else "http"
+                    self._proxy_url_base = f"{proto}://{host}"
+                    self.log.info("proxy_auto_detected", proxy_url_base=self._proxy_url_base,
+                                source="Forwarded header")
+                    return
+            except Exception as e:
+                self.log.warning("forwarded_header_parse_error", error=str(e))
+        
+        # Try to detect from the URL itself for transparent proxies
+        if str(request.url).startswith(("https://", "http://")) and not any(
+            str(request.url).startswith(f"http://{h}") for h in ["localhost", "127.0.0.1", self.host, "0.0.0.0"]
+        ):
+            # This is likely a transparent proxy - extract base URL
+            parsed = urlparse(str(request.url))
+            base_url = f"{parsed.scheme}://{parsed.netloc}"
+            self._proxy_url_base = base_url
+            self.log.info("proxy_auto_detected", proxy_url_base=base_url,
+                        source="request URL (transparent proxy)")
+            return
+        
+        # Check for other common proxy setups
+        original_host = request.headers.get("X-Original-Host") or request.headers.get("Host")
+        if original_host:
+            # Only use Host if it doesn't look like our local server
+            local_hosts = [self.host, "localhost", "127.0.0.1", "0.0.0.0"]
+            local_port = f":{self.port}"
+            
+            # If host doesn't look like local server or doesn't contain our port
+            if not any(h in original_host for h in local_hosts) and local_port not in original_host:
+                proto = "https" if request.url.scheme == "https" else "http"
+                self._proxy_url_base = f"{proto}://{original_host}"
+                self.log.info("proxy_auto_detected", proxy_url_base=self._proxy_url_base,
+                            source="Host header")
+                return
+        
+        # If forward_for header exists, we're likely behind a proxy but couldn't determine the URL
+        forwarded_for = request.headers.get("X-Forwarded-For")
+        if forwarded_for:
+            self.log.warning("proxy_detected_but_url_unknown", 
+                          client_ip=forwarded_for,
+                          message="Proxy detected via X-Forwarded-For header but could not determine public URL")
+            
+        # No proxy detected, or unable to determine the public URL
+        if self._proxy_debug:
+            self.log.info("proxy_detection_failed", 
+                        message="Could not auto-detect proxy. If you are behind a proxy, set SWML_PROXY_URL_BASE manually.")
+    
+    def manual_set_proxy_url(self, proxy_url: str) -> None:
+        """
+        Manually set the proxy URL base for webhook callbacks
+        
+        This can be called at runtime to set or update the proxy URL
+        
+        Args:
+            proxy_url: The base URL to use for webhooks (e.g., https://example.ngrok.io)
+        """
+        if proxy_url:
+            self._proxy_url_base = proxy_url.rstrip('/')
+            self.log.info("proxy_url_manually_set", proxy_url_base=self._proxy_url_base)
+            self._proxy_detection_done = True