signalwire-sdk 3.0.2.dev33__tar.gz → 3.0.2.dev35__tar.gz

{signalwire_sdk-3.0.2.dev33/signalwire/signalwire_sdk.egg-info → signalwire_sdk-3.0.2.dev35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire-sdk
-Version: 3.0.2.dev33
+Version: 3.0.2.dev35
 Summary: SignalWire SDK
 Author-email: SignalWire Team <info@signalwire.com>
 License: MIT

{signalwire_sdk-3.0.2.dev33 → signalwire_sdk-3.0.2.dev35}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "signalwire-sdk"
-version = "3.0.2.dev33"
+version = "3.0.2.dev35"
 description = "SignalWire SDK"
 authors = [
     {name = "SignalWire Team", email = "info@signalwire.com"}

{signalwire_sdk-3.0.2.dev33 → signalwire_sdk-3.0.2.dev35}/signalwire/signalwire/__init__.py

@@ -18,7 +18,7 @@ A package for building AI agents using SignalWire's AI and SWML capabilities.
 from .core.logging_config import configure_logging
 configure_logging()
 
-__version__ = "3.0.2.dev33"
+__version__ = "3.0.2.dev35"
 
 # Import core classes for easier access
 from .core.agent_base import AgentBase

{signalwire_sdk-3.0.2.dev33 → signalwire_sdk-3.0.2.dev35}/signalwire/signalwire/agent_server.py

@@ -61,7 +61,7 @@ class AgentServer:
         self.app = FastAPI(
             title="SignalWire AI Agents",
             description="Hosted SignalWire AI Agents",
-            version="3.0.2.dev33",
+            version="3.0.2.dev35",
             redirect_slashes=False,
             docs_url=None,
             redoc_url=None,

{signalwire_sdk-3.0.2.dev33 → signalwire_sdk-3.0.2.dev35}/signalwire/signalwire/core/agent_base.py

@@ -126,11 +126,13 @@ class AgentBase(
         enable_post_prompt_override: bool = False,
         check_for_input_override: bool = False,
         config_file: Optional[str] = None,
-        schema_validation: bool = True
+        schema_validation: bool = True,
+        signing_key: Optional[str] = None,
+        trust_proxy_for_signature: bool = False
     ):
         """
         Initialize a new agent
-        
+
         Args:
             name: Agent name/identifier
             route: HTTP route path for this agent
@@ -153,6 +155,17 @@ class AgentBase(
             config_file: Optional path to configuration file
             schema_validation: Enable SWML schema validation. Default True. Can also
                               be disabled via SWML_SKIP_SCHEMA_VALIDATION=1 env var.
+            signing_key: Optional SignalWire Signing Key (from Dashboard → API
+                         Credentials). When set, webhook signature validation is
+                         enforced on POST /, /swaig, /post_prompt — unsigned or
+                         invalidly-signed requests get a 403. Falls back to the
+                         SIGNALWIRE_SIGNING_KEY env var if not passed.
+                         See porting-sdk/webhooks.md for the contract.
+            trust_proxy_for_signature: If True, honor X-Forwarded-Proto /
+                         X-Forwarded-Host when reconstructing the URL during
+                         signature validation. Default False — proxy headers
+                         are spoofable, so opt in only when you control the
+                         proxy chain.
         """
         # Import SWMLService here to avoid circular imports
         from signalwire.core.swml_service import SWMLService
@@ -214,7 +227,24 @@ class AgentBase(
         
         # Initialize session manager
         self._session_manager = SessionManager(token_expiry_secs=token_expiry_secs)
-        
+
+        # Webhook signature validation (porting-sdk/webhooks.md).
+        # Resolution order: explicit constructor arg → SIGNALWIRE_SIGNING_KEY env.
+        # When unset, web_mixin._register_routes does NOT mount the validator
+        # and the SDK logs a one-time WARNING so users notice in production.
+        self.signing_key = signing_key or os.environ.get("SIGNALWIRE_SIGNING_KEY")
+        self._trust_proxy_for_signature = trust_proxy_for_signature
+        if self.signing_key:
+            self.log.info("webhook_signature_validation_enabled")
+        else:
+            self.log.warning(
+                "webhook_signature_validation_disabled",
+                message=(
+                    "[signalwire] webhook signature validation is disabled — "
+                    "set signing_key or SIGNALWIRE_SIGNING_KEY to enable"
+                ),
+            )
+
         # URL override variables
         self._web_hook_url_override = None
         self._post_prompt_url_override = None

{signalwire_sdk-3.0.2.dev33 → signalwire_sdk-3.0.2.dev35}/signalwire/signalwire/core/mixins/web_mixin.py

@@ -17,11 +17,14 @@ import contextvars
 from typing import Optional, Dict, Any, Callable
 from urllib.parse import urlparse, urlunparse
 
-from fastapi import FastAPI, APIRouter, Request, Response
+from fastapi import Depends, FastAPI, APIRouter, Request, Response
 from fastapi.middleware.cors import CORSMiddleware
 
 from signalwire.core.logging_config import get_execution_mode
 from signalwire.core.function_result import FunctionResult
+from signalwire.core.security.webhook_middleware import (
+    make_webhook_validation_dependency,
+)
 
 # Per-request proxy URL to avoid race conditions in concurrent async contexts
 _request_proxy_url = contextvars.ContextVar('_request_proxy_url', default=None)
@@ -343,22 +346,37 @@ class WebMixin:
     def _register_routes(self, router):
         """
         Register routes for this agent
-        
-        This method ensures proper route registration by handling the routes 
+
+        This method ensures proper route registration by handling the routes
         directly in AgentBase rather than inheriting from SWMLService.
-        
+
         Args:
             router: FastAPI router to register routes with
         """
         # Health check endpoints are now registered directly on the main app
-        
+
+        # Build webhook signature validation dependency once if signing_key is set.
+        # See porting-sdk/webhooks.md and signalwire.core.security.webhook_middleware.
+        # When unset, signed_post_deps stays empty and routes register without it.
+        signed_post_deps = []
+        if getattr(self, "signing_key", None):
+            sig_dep = make_webhook_validation_dependency(
+                self.signing_key,
+                trust_proxy=getattr(self, "_trust_proxy_for_signature", False),
+            )
+            signed_post_deps = [Depends(sig_dep)]
+
         # Root endpoint (handles both with and without trailing slash)
         @router.get("/")
-        @router.post("/")
-        async def handle_root(request: Request, response: Response):
-            """Handle GET/POST requests to the root endpoint"""
+        async def handle_root_get(request: Request, response: Response):
+            """Handle GET requests to the root endpoint"""
             return await self._handle_root_request(request)
-            
+
+        @router.post("/", dependencies=signed_post_deps)
+        async def handle_root_post(request: Request, response: Response):
+            """Handle POST requests to the root endpoint (signature-validated when signing_key is set)"""
+            return await self._handle_root_request(request)
+
         # Debug endpoint - Both versions
         @router.get("/debug")
         @router.get("/debug/")
@@ -367,23 +385,31 @@ class WebMixin:
         async def handle_debug(request: Request):
             """Handle GET/POST requests to the debug endpoint"""
             return await self._handle_debug_request(request)
-            
-        # SWAIG endpoint - Both versions 
+
+        # SWAIG endpoint - Both versions
         @router.get("/swaig")
         @router.get("/swaig/")
-        @router.post("/swaig")
-        @router.post("/swaig/")
-        async def handle_swaig(request: Request, response: Response):
-            """Handle GET/POST requests to the SWAIG endpoint"""
+        async def handle_swaig_get(request: Request, response: Response):
+            """Handle GET requests to the SWAIG endpoint"""
             return await self._handle_swaig_request(request, response)
-            
+
+        @router.post("/swaig", dependencies=signed_post_deps)
+        @router.post("/swaig/", dependencies=signed_post_deps)
+        async def handle_swaig_post(request: Request, response: Response):
+            """Handle POST requests to the SWAIG endpoint (signature-validated when signing_key is set)"""
+            return await self._handle_swaig_request(request, response)
+
         # Post prompt endpoint - Both versions
         @router.get("/post_prompt")
         @router.get("/post_prompt/")
-        @router.post("/post_prompt")
-        @router.post("/post_prompt/")
-        async def handle_post_prompt(request: Request):
-            """Handle GET/POST requests to the post_prompt endpoint"""
+        async def handle_post_prompt_get(request: Request):
+            """Handle GET requests to the post_prompt endpoint"""
+            return await self._handle_post_prompt_request(request)
+
+        @router.post("/post_prompt", dependencies=signed_post_deps)
+        @router.post("/post_prompt/", dependencies=signed_post_deps)
+        async def handle_post_prompt_post(request: Request):
+            """Handle POST requests to the post_prompt endpoint (signature-validated when signing_key is set)"""
             return await self._handle_post_prompt_request(request)
             
         # Check for input endpoint - Both versions

signalwire_sdk-3.0.2.dev35/signalwire/signalwire/core/security/__init__.py

@@ -0,0 +1,26 @@
+"""
+Copyright (c) 2025 SignalWire
+
+This file is part of the SignalWire SDK.
+
+Licensed under the MIT License.
+See LICENSE file in the project root for full license information.
+"""
+
+from signalwire.core.security.webhook_validator import (
+    validate_request,
+    validate_webhook_signature,
+)
+from signalwire.core.security.webhook_middleware import (
+    SIGNALWIRE_SIGNATURE_HEADER,
+    TWILIO_COMPAT_SIGNATURE_HEADER,
+    make_webhook_validation_dependency,
+)
+
+__all__ = [
+    "validate_request",
+    "validate_webhook_signature",
+    "make_webhook_validation_dependency",
+    "SIGNALWIRE_SIGNATURE_HEADER",
+    "TWILIO_COMPAT_SIGNATURE_HEADER",
+]

signalwire_sdk-3.0.2.dev35/signalwire/signalwire/core/security/webhook_middleware.py

@@ -0,0 +1,164 @@
+"""
+FastAPI middleware / dependency for SignalWire webhook signature validation.
+
+Copyright (c) 2025 SignalWire. Licensed under the MIT License.
+See LICENSE file in the project root for full license information.
+
+This module ships a small, framework-aware adapter around
+:func:`signalwire.core.security.webhook_validator.validate_webhook_signature`.
+
+Why a custom dependency rather than a vanilla ``Depends`` on ``request.body()``?
+
+- We MUST capture the raw bytes BEFORE FastAPI's JSON parser consumes the
+  stream — re-serialization changes whitespace and key order, which breaks
+  the Scheme A digest. The dependency stashes the raw body on
+  ``request.state.raw_body`` so the downstream handler can re-parse without
+  re-reading the stream.
+- Reverse-proxy / ngrok deployments need the URL the platform POSTed to,
+  which differs from the URL the SDK sees. The dependency honors
+  ``X-Forwarded-Proto`` / ``X-Forwarded-Host`` when ``trust_proxy=True``,
+  plus the ``SWML_PROXY_URL_BASE`` env var, with ``request.url`` as last
+  resort.
+- The legacy cXML/Compatibility scheme used the ``X-Twilio-Signature``
+  header. We accept it as an alias of ``X-SignalWire-Signature`` so users
+  migrating from the legacy SDK can keep their callers unchanged.
+
+Usage::
+
+    from signalwire.core.security.webhook_middleware import (
+        make_webhook_validation_dependency,
+    )
+
+    dep = make_webhook_validation_dependency(signing_key="PSK...")
+
+    @app.post("/webhook", dependencies=[Depends(dep)])
+    async def webhook(request: Request):
+        body = request.state.raw_body  # bytes; re-parse if you need JSON
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Awaitable, Callable, Optional
+
+from fastapi import HTTPException, Request, Response, status
+
+from signalwire.core.security.webhook_validator import validate_webhook_signature
+
+
+SIGNALWIRE_SIGNATURE_HEADER = "x-signalwire-signature"
+TWILIO_COMPAT_SIGNATURE_HEADER = "x-twilio-signature"
+
+
+def _reconstruct_url(request: Request, *, trust_proxy: bool) -> str:
+    """Rebuild the public URL SignalWire POSTed to.
+
+    Resolution order (highest priority first):
+
+    1. ``SWML_PROXY_URL_BASE`` env var (joined with the request path + query).
+    2. ``X-Forwarded-Proto`` / ``X-Forwarded-Host`` headers, if
+       ``trust_proxy=True`` and both headers are present.
+    3. ``request.url`` (FastAPI's view of the URL).
+    """
+    path_and_query = request.url.path
+    if request.url.query:
+        path_and_query = f"{path_and_query}?{request.url.query}"
+
+    proxy_base = os.environ.get("SWML_PROXY_URL_BASE")
+    if proxy_base:
+        return f"{proxy_base.rstrip('/')}{path_and_query}"
+
+    if trust_proxy:
+        fwd_host = request.headers.get("x-forwarded-host")
+        fwd_proto = request.headers.get("x-forwarded-proto", "https")
+        if fwd_host:
+            return f"{fwd_proto}://{fwd_host}{path_and_query}"
+
+    return str(request.url)
+
+
+def _extract_signature_header(request: Request) -> Optional[str]:
+    """Return the SignalWire signature header (or ``X-Twilio-Signature`` alias)."""
+    sig = request.headers.get(SIGNALWIRE_SIGNATURE_HEADER)
+    if sig is None:
+        sig = request.headers.get(TWILIO_COMPAT_SIGNATURE_HEADER)
+    return sig
+
+
+def make_webhook_validation_dependency(
+    signing_key: str,
+    *,
+    trust_proxy: bool = False,
+) -> Callable[[Request, Response], Awaitable[Optional[Response]]]:
+    """Build a FastAPI dependency that enforces signature validation.
+
+    The returned coroutine:
+
+    1. Reads ``await request.body()`` and stashes the bytes on
+       ``request.state.raw_body``.
+    2. Pulls the ``X-SignalWire-Signature`` header (or the Twilio alias).
+    3. Reconstructs the public URL (proxy headers / env / fallback).
+    4. Calls :func:`validate_webhook_signature`.
+    5. On invalid signature: raises ``HTTPException(403)`` to short-circuit
+       the handler. FastAPI's ``dependencies=[Depends(...)]`` only honors
+       short-circuiting via raised exceptions — returning a Response from a
+       dependency does not stop the endpoint.
+    6. On valid: returns ``None`` so the handler runs as normal.
+
+    Args:
+        signing_key: The customer's Signing Key. Required, non-empty.
+        trust_proxy: If True, honor ``X-Forwarded-Proto`` / ``X-Forwarded-Host``
+            when reconstructing the URL. Default False — proxy headers are
+            spoofable, so opt in only when you control the proxy.
+
+    Returns:
+        Async callable suitable for ``Depends(...)``.
+
+    Raises:
+        ValueError: at construction time if ``signing_key`` is empty.
+    """
+    if not signing_key:
+        raise ValueError("signing_key is required")
+
+    def _forbidden() -> None:
+        # Single canonical 403 short-circuit. No body detail (would leak
+        # which branch failed); validators MUST NOT log scheme details.
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN)
+
+    async def dependency(request: Request, response: Response) -> None:
+        # Capture raw body BEFORE any other consumer reads the stream.
+        # request.body() caches internally so subsequent calls are safe.
+        raw_bytes = await request.body()
+        request.state.raw_body = raw_bytes
+        try:
+            raw_body_str = raw_bytes.decode("utf-8")
+        except UnicodeDecodeError:
+            # Non-UTF-8 body cannot match an HMAC over UTF-8 input.
+            _forbidden()
+
+        signature = _extract_signature_header(request)
+        if not signature:
+            _forbidden()
+
+        url = _reconstruct_url(request, trust_proxy=trust_proxy)
+
+        try:
+            ok = validate_webhook_signature(signing_key, signature, url, raw_body_str)
+        except (TypeError, ValueError):
+            # Programming errors or non-string body — treat as invalid for the
+            # request without leaking which branch tripped.
+            _forbidden()
+            return
+
+        if not ok:
+            _forbidden()
+        # Valid — fall through and let the handler run.
+
+    return dependency
+
+
+__all__ = [
+    "make_webhook_validation_dependency",
+    "SIGNALWIRE_SIGNATURE_HEADER",
+    "TWILIO_COMPAT_SIGNATURE_HEADER",
+]