signalwire-sdk 3.4.1.dev112__tar.gz → 3.4.1.dev113__tar.gz

{signalwire_sdk-3.4.1.dev112 → signalwire_sdk-3.4.1.dev113}/PKG-INFO

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

{signalwire_sdk-3.4.1.dev112 → signalwire_sdk-3.4.1.dev113}/pyproject.toml

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

{signalwire_sdk-3.4.1.dev112 → signalwire_sdk-3.4.1.dev113}/signalwire/signalwire/__init__.py

@@ -52,7 +52,7 @@ if TYPE_CHECKING:
     from signalwire.utils.schema_utils import SchemaValidationError
     from signalwire.web import WebService
 
-__version__ = "3.4.1.dev112"
+__version__ = "3.4.1.dev113"
 
 # §6.2-python (owner decision: NO packaging split — one package, all deps required;
 # IMPORT-TIME behavior only): the agent/web symbols are lazy-imported via module

{signalwire_sdk-3.4.1.dev112 → signalwire_sdk-3.4.1.dev113}/signalwire/signalwire/agent_server.py

@@ -68,7 +68,7 @@ class AgentServer:
         self.app = FastAPI(
             title="SignalWire AI Agents",
             description="Hosted SignalWire AI Agents",
-            version="3.4.1.dev112",
+            version="3.4.1.dev113",
             redirect_slashes=False,
             docs_url=None,
             redoc_url=None,

{signalwire_sdk-3.4.1.dev112 → signalwire_sdk-3.4.1.dev113}/signalwire/signalwire/core/security/__init__.py

@@ -10,9 +10,11 @@ See LICENSE file in the project root for full license information.
 from signalwire.core.security.webhook_validator import (
     validate_request,
     validate_webhook_signature,
+    validate_webhook_signature_sha256,
 )
 from signalwire.core.security.webhook_middleware import (
     SIGNALWIRE_SIGNATURE_HEADER,
+    SIGNALWIRE_SHA256_SIGNATURE_HEADER,
     TWILIO_COMPAT_SIGNATURE_HEADER,
     make_webhook_validation_dependency,
 )
@@ -25,6 +27,7 @@ from signalwire.core.security.security_utils import (
 
 __all__ = [
     "SENSITIVE_HEADERS",
+    "SIGNALWIRE_SHA256_SIGNATURE_HEADER",
     "SIGNALWIRE_SIGNATURE_HEADER",
     "TWILIO_COMPAT_SIGNATURE_HEADER",
     "filter_sensitive_headers",
@@ -33,4 +36,5 @@ __all__ = [
     "redact_url",
     "validate_request",
     "validate_webhook_signature",
+    "validate_webhook_signature_sha256",
 ]

{signalwire_sdk-3.4.1.dev112 → signalwire_sdk-3.4.1.dev113}/signalwire/signalwire/core/security/webhook_middleware.py

@@ -44,10 +44,14 @@ from collections.abc import Awaitable, Callable, Mapping
 
 from fastapi import HTTPException, Request, Response, status
 
-from signalwire.core.security.webhook_validator import validate_webhook_signature
+from signalwire.core.security.webhook_validator import (
+    validate_webhook_signature,
+    validate_webhook_signature_sha256,
+)
 
 
 SIGNALWIRE_SIGNATURE_HEADER = "x-signalwire-signature"
+SIGNALWIRE_SHA256_SIGNATURE_HEADER = "x-signalwire-sha256-signature"
 TWILIO_COMPAT_SIGNATURE_HEADER = "x-twilio-signature"
 
 
@@ -69,8 +73,9 @@ def validate(
     wrapper (:func:`make_webhook_validation_dependency` here) is the only idiom
     on top of it.
 
-    The ``headers`` map is consulted for the signature header
-    (``X-SignalWire-Signature`` or the ``X-Twilio-Signature`` alias); ``method``
+    The ``headers`` map is consulted for the signature header: the stronger
+    ``X-SignalWire-Sha256-Signature`` is preferred when present, falling back to
+    ``X-SignalWire-Signature`` (or the ``X-Twilio-Signature`` alias); ``method``
     is accepted to keep a stable signature but is not part of the HMAC. Returns
     ``(403, {}, "")`` on any failure (missing/bad
     signature, non-UTF-8 body, validator error) — no body detail, to avoid
@@ -92,6 +97,20 @@ def validate(
     if not signing_key:
         raise ValueError("signing_key is required")
 
+    # Prefer the stronger SHA-256 signature when the platform sends it
+    # (X-SignalWire-Sha256-Signature): same Scheme A message, SHA-256 hash. Fall
+    # back to the SHA-1 header below so deployments on older platform builds --
+    # and the cXML/form Scheme B path -- keep validating.
+    sha256_signature = headers.get(SIGNALWIRE_SHA256_SIGNATURE_HEADER)
+    if sha256_signature:
+        try:
+            if validate_webhook_signature_sha256(
+                signing_key, sha256_signature, url, body
+            ):
+                return None
+        except (TypeError, ValueError):
+            pass  # fall back to the SHA-1 header path below
+
     signature = headers.get(SIGNALWIRE_SIGNATURE_HEADER)
     if signature is None:
         signature = headers.get(TWILIO_COMPAT_SIGNATURE_HEADER)
@@ -146,7 +165,8 @@ def make_webhook_validation_dependency(
 
     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).
+    2. Pulls the signature header (``X-SignalWire-Sha256-Signature`` preferred,
+       then ``X-SignalWire-Signature`` 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
@@ -205,6 +225,7 @@ def make_webhook_validation_dependency(
 
 
 __all__ = [
+    "SIGNALWIRE_SHA256_SIGNATURE_HEADER",
     "SIGNALWIRE_SIGNATURE_HEADER",
     "TWILIO_COMPAT_SIGNATURE_HEADER",
     "make_webhook_validation_dependency",

{signalwire_sdk-3.4.1.dev112 → signalwire_sdk-3.4.1.dev113}/signalwire/signalwire/core/security/webhook_validator.py

@@ -4,14 +4,18 @@ Webhook signature validation for SignalWire-signed HTTP requests.
 Copyright (c) 2025 SignalWire. Licensed under the MIT License.
 See LICENSE file in the project root for full license information.
 
-Implements both SignalWire webhook signature schemes:
+Implements the SignalWire webhook signature schemes:
 
 - Scheme A (RELAY/SWML/JSON): hex(HMAC-SHA1(key, url + raw_body))
+- Scheme A / SHA-256: hex(HMAC-SHA256(key, url + raw_body)) -- the platform also
+  sends this as the ``X-SignalWire-Sha256-Signature`` header. Identical message
+  construction to Scheme A with a stronger hash; prefer it when present.
 - Scheme B (Compat/cXML form): base64(HMAC-SHA1(key, url + sortedFormParams))
   with optional bodySHA256 query-param fallback for JSON-on-compat-surface.
 
 Public API:
     validate_webhook_signature(signing_key, signature, url, raw_body) -> bool
+    validate_webhook_signature_sha256(signing_key, signature, url, raw_body) -> bool
     validate_request(signing_key, signature, url, params_or_raw_body) -> bool
 
 All comparisons use ``hmac.compare_digest`` (constant-time) so the secret
@@ -42,6 +46,15 @@ def _hex_hmac_sha1(key: str, message: str) -> str:
     ).hexdigest()
 
 
+def _hex_hmac_sha256(key: str, message: str) -> str:
+    """Scheme-A/SHA-256 digest: lowercase hex of HMAC-SHA256."""
+    return hmac.new(
+        key.encode("utf-8"),
+        message.encode("utf-8"),
+        hashlib.sha256,
+    ).hexdigest()
+
+
 def _b64_hmac_sha1(key: str, message: str) -> str:
     """Scheme-B digest: standard base64 of HMAC-SHA1."""
     return base64.b64encode(
@@ -266,6 +279,51 @@ def validate_webhook_signature(
     return False
 
 
+def validate_webhook_signature_sha256(
+    signing_key: str,
+    signature: str,
+    url: str,
+    raw_body: str,
+) -> bool:
+    """Validate the SHA-256 webhook signature (Scheme A with a stronger hash).
+
+    SignalWire sends ``X-SignalWire-Sha256-Signature`` alongside the SHA-1
+    ``X-SignalWire-Signature`` on signed webhooks. Its construction is the same
+    Scheme A message with SHA-256::
+
+        hex(HMAC-SHA256(signing_key, url + raw_body))
+
+    Only Scheme A (RELAY/SWML/JSON) is defined for this header; the legacy
+    cXML/form Scheme B stays on SHA-1 -- see :func:`validate_webhook_signature`.
+
+    Args:
+        signing_key: Customer's Signing Key. ``None`` / empty raises
+            ``ValueError`` (a programming error, not a validation failure).
+        signature: The ``X-SignalWire-Sha256-Signature`` header value (64-char
+            lowercase hex). Missing / empty returns False without raising.
+        url: The full public URL SignalWire POSTed to, exactly as the platform
+            saw it when it computed the signature.
+        raw_body: The raw request body as a UTF-8 string, BEFORE any parsing.
+            Must be a ``str`` -- passing a parsed dict raises ``TypeError``.
+
+    Returns:
+        True if the SHA-256 signature matches, False otherwise.
+
+    Raises:
+        ValueError: when ``signing_key`` is missing.
+        TypeError: when ``raw_body`` is not a string.
+    """
+    if not signing_key:
+        raise ValueError("signing_key is required")
+    if not isinstance(raw_body, str):
+        raise TypeError("raw_body must be a str — did you pass parsed JSON by mistake?")
+    if signature is None or signature == "":
+        return False
+
+    expected = _hex_hmac_sha256(signing_key, url + raw_body)
+    return _safe_eq(expected, signature)
+
+
 def validate_request(
     signing_key: str,
     signature: str,
@@ -326,4 +384,5 @@ def validate_request(
 __all__ = [
     "validate_request",
     "validate_webhook_signature",
+    "validate_webhook_signature_sha256",
 ]

{signalwire_sdk-3.4.1.dev112 → signalwire_sdk-3.4.1.dev113}/signalwire/signalwire_sdk.egg-info/PKG-INFO

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