signalwire-sdk 2.0.0

data/lib/signalwire/security/webhook_middleware.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2025 SignalWire
+#
+# Licensed under the MIT License.
+# See LICENSE file in the project root for full license information.
+#
+# Rack middleware for SignalWire webhook signature validation.
+#
+# This adapter wraps {SignalWire::Security::WebhookValidator} so it can be
+# inserted into any Rack pipeline (Rails, Sinatra, plain Rack).
+#
+# Why a custom middleware rather than vanilla Rack?
+#
+# - We MUST capture the raw bytes BEFORE any JSON / form parser consumes
+#   the stream — re-serialization changes whitespace and key order, which
+#   breaks the Scheme A digest. The middleware reads ``rack.input``, then
+#   rewinds the IO and stashes the bytes on
+#   ``env['signalwire.raw_body']`` so downstream handlers 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 middleware honors
+#   ``X-Forwarded-Proto`` / ``X-Forwarded-Host`` when ``trust_proxy``
+#   is true, plus the ``SWML_PROXY_URL_BASE`` env var, with the 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::
+#
+#     use SignalWire::Security::WebhookMiddleware,
+#         signing_key: ENV['SIGNALWIRE_SIGNING_KEY'],
+#         trust_proxy: true,
+#         paths: ['/', '/swaig', '/post_prompt']
+
+require 'rack'
+require_relative 'webhook_validator'
+
+module SignalWire
+  module Security
+    # Rack middleware that rejects webhook requests with bad signatures.
+    #
+    # Configure with the customer's Signing Key (and optional ``trust_proxy``
+    # to honor X-Forwarded headers). Mount upstream of any body-parsing
+    # middleware so the raw bytes survive intact.
+    class WebhookMiddleware
+      SIGNALWIRE_SIGNATURE_HEADER = 'HTTP_X_SIGNALWIRE_SIGNATURE'
+      TWILIO_COMPAT_SIGNATURE_HEADER = 'HTTP_X_TWILIO_SIGNATURE'
+
+      # Key under which the captured raw body is stashed on the request env.
+      RAW_BODY_ENV_KEY = 'signalwire.raw_body'
+
+      # @param app [#call] the wrapped Rack app.
+      # @param signing_key [String] customer Signing Key (required, non-empty).
+      # @param trust_proxy [Boolean] honor X-Forwarded-Proto / X-Forwarded-Host
+      #   when reconstructing the request URL. Default false — proxy headers
+      #   are spoofable, so opt in only when you control the proxy.
+      # @param paths [Array<String>, nil] when set, only apply the validation
+      #   on these PATH_INFO values; everything else passes through. When nil,
+      #   apply to every request.
+      # @param methods [Array<String>, nil] limit to these HTTP methods. When
+      #   nil, apply to every method.
+      #
+      # @raise [ArgumentError] when ``signing_key`` is missing.
+      def initialize(app, signing_key:, trust_proxy: false, paths: nil, methods: ['POST'])
+        raise ArgumentError, 'signing_key is required' if signing_key.nil? || signing_key.to_s.empty?
+
+        @app          = app
+        @signing_key  = signing_key
+        @trust_proxy  = trust_proxy
+        @paths        = paths.nil? ? nil : Array(paths).map(&:to_s)
+        @methods      = methods.nil? ? nil : Array(methods).map { |m| m.to_s.upcase }
+      end
+
+      # @api private
+      def call(env)
+        return @app.call(env) unless _applies?(env)
+
+        # Capture raw body BEFORE any other middleware reads the stream.
+        raw_body = _read_raw_body(env)
+        env[RAW_BODY_ENV_KEY] = raw_body
+
+        signature = _extract_signature_header(env)
+        return _forbidden if signature.nil? || signature.empty?
+
+        url = _reconstruct_url(env)
+
+        valid = begin
+          WebhookValidator.validate_webhook_signature(@signing_key, signature, url, raw_body)
+        rescue ArgumentError, TypeError
+          # Programming errors at the boundary — never leak which branch
+          # tripped. Reject the request without raising.
+          return _forbidden
+        end
+
+        return _forbidden unless valid
+
+        @app.call(env)
+      end
+
+      private
+
+      # @api private
+      def _applies?(env)
+        if @methods
+          method = env['REQUEST_METHOD'].to_s.upcase
+          return false unless @methods.include?(method)
+        end
+        if @paths
+          path = env['PATH_INFO'].to_s
+          # Exact match — paths is intentionally a tight allowlist.
+          return false unless @paths.include?(path)
+        end
+        true
+      end
+
+      # @api private
+      def _read_raw_body(env)
+        input = env['rack.input']
+        return '' if input.nil?
+
+        body = input.read
+        # Rewind so downstream middleware / handlers can read the body too.
+        # Some Rack inputs (e.g. Tempfile-backed) are seekable; StringIO is
+        # always rewindable.
+        input.rewind if input.respond_to?(:rewind)
+        body.to_s
+      rescue StandardError
+        ''
+      end
+
+      # @api private
+      def _extract_signature_header(env)
+        sig = env[SIGNALWIRE_SIGNATURE_HEADER]
+        sig = env[TWILIO_COMPAT_SIGNATURE_HEADER] if sig.nil? || sig.empty?
+        sig
+      end
+
+      # @api private
+      # Reconstruct 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, when
+      #    ``trust_proxy`` is true and X-Forwarded-Host is present.
+      # 3. ``scheme://host[:port]/path?query`` derived from the rack env.
+      def _reconstruct_url(env)
+        path = env['PATH_INFO'].to_s
+        path = '/' if path.empty?
+        query = env['QUERY_STRING'].to_s
+        path_and_query = query.empty? ? path : "#{path}?#{query}"
+
+        proxy_base = ENV['SWML_PROXY_URL_BASE']
+        return "#{proxy_base.sub(%r{/+\z}, '')}#{path_and_query}" if proxy_base && !proxy_base.empty?
+
+        if @trust_proxy
+          fwd_host  = env['HTTP_X_FORWARDED_HOST']
+          fwd_proto = env['HTTP_X_FORWARDED_PROTO'] || 'https'
+          if fwd_host && !fwd_host.empty?
+            return "#{fwd_proto}://#{fwd_host}#{path_and_query}"
+          end
+        end
+
+        scheme = env['rack.url_scheme'] || 'http'
+        host = env['HTTP_HOST'] || env['SERVER_NAME']
+        port = env['SERVER_PORT']
+        # Only include port if it's non-standard AND not already in HTTP_HOST.
+        host_with_port =
+          if host && host.include?(':')
+            host
+          elsif port && (
+            (scheme == 'http'  && port.to_s != '80') ||
+            (scheme == 'https' && port.to_s != '443')
+          )
+            "#{host}:#{port}"
+          else
+            host
+          end
+
+        "#{scheme}://#{host_with_port}#{path_and_query}"
+      end
+
+      # @api private
+      def _forbidden
+        # No body detail — never leak which branch tripped.
+        [403, { 'content-type' => 'text/plain' }, ['']]
+      end
+    end
+  end
+end

data/lib/signalwire/security/webhook_validator.rb

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2025 SignalWire
+#
+# Licensed under the MIT License.
+# See LICENSE file in the project root for full license information.
+#
+# Webhook signature validation for SignalWire-signed HTTP requests.
+#
+# Implements both schemes from porting-sdk/webhooks.md:
+#
+# - Scheme A (RELAY/SWML/JSON): hex(HMAC-SHA1(key, url + raw_body))
+# - Scheme B (Compat/cXML form): base64(HMAC-SHA1(key, url + sortedFormParams))
+#   with optional bodySHA256 query-param fallback for JSON-on-compat-surface.
+#
+# Public API:
+#     SignalWire::Security::WebhookValidator.validate_webhook_signature(
+#         signing_key, signature, url, raw_body) -> Boolean
+#     SignalWire::Security::WebhookValidator.validate_request(
+#         signing_key, signature, url, params_or_raw_body) -> Boolean
+#
+# All comparisons use ``Rack::Utils.secure_compare`` (constant-time) so the
+# secret is not leaked over repeated requests.
+
+require 'base64'
+require 'cgi'
+require 'digest'
+require 'openssl'
+require 'rack/utils'
+require 'uri'
+
+module SignalWire
+  module Security
+    # Stateless validator for SignalWire-signed webhook requests.
+    #
+    # Both Scheme A (JSON, hex digest) and Scheme B (form-encoded, base64
+    # digest with bodySHA256 fallback) per porting-sdk/webhooks.md are
+    # tried by the combined entry point.
+    #
+    # The two public entry points are exposed via ``module_function`` so
+    # they can be invoked as ``WebhookValidator.validate_webhook_signature(...)``.
+    # All internal helpers are deliberately ``_``-prefixed and private so
+    # they don't pollute the public surface (``audit_no_cheat_tests`` and
+    # ``signature_dump.rb`` skip ``_``-prefixed methods).
+    module WebhookValidator
+      # Validate a SignalWire webhook signature against both schemes.
+      #
+      # @param signing_key [String] Customer's Signing Key from the Dashboard.
+      #   UTF-8 string, secret. ``nil`` / empty raises ``ArgumentError`` —
+      #   that's a programming error, not a validation failure.
+      # @param signature [String, nil] The ``X-SignalWire-Signature`` header
+      #   value (or ``X-Twilio-Signature`` for cXML compat). Missing / empty
+      #   returns false without raising.
+      # @param url [String] The full URL SignalWire POSTed to (scheme, host,
+      #   optional port, path, query). Must match what the platform saw —
+      #   see the URL reconstruction section of porting-sdk/webhooks.md.
+      # @param raw_body [String] The raw request body bytes as a UTF-8 string,
+      #   BEFORE any JSON / form parsing. Must be a ``String`` — passing a
+      #   parsed Hash raises ``TypeError``.
+      #
+      # @return [Boolean] true if the signature matches either Scheme A or
+      #   Scheme B (with port-normalization variants and optional bodySHA256
+      #   fallback). false otherwise.
+      #
+      # @raise [ArgumentError] when ``signing_key`` is missing.
+      # @raise [TypeError] when ``raw_body`` is not a String.
+      def self.validate_webhook_signature(signing_key, signature, url, raw_body)
+        raise ArgumentError, 'signing_key is required' if signing_key.nil? || signing_key.to_s.empty?
+        unless raw_body.is_a?(String)
+          raise TypeError,
+                'raw_body must be a String — did you pass parsed JSON by mistake?'
+        end
+        return false if signature.nil? || signature.to_s.empty?
+
+        # ------------------------------------------------------------------
+        # Scheme A — RELAY/SWML/JSON: hex(HMAC-SHA1(key, url + raw_body))
+        # ------------------------------------------------------------------
+        expected_a = _hex_hmac_sha1(signing_key, url.to_s + raw_body)
+        return true if _safe_eq(expected_a, signature)
+
+        # ------------------------------------------------------------------
+        # Scheme B — Compat/cXML form: base64(HMAC-SHA1(key, url + sorted_concat))
+        # Try parsed form params and the empty-params fallback (for JSON on
+        # the compat surface). Try with-port and without-port URL variants.
+        # ------------------------------------------------------------------
+        parsed_params = _parse_form_body(raw_body)
+        param_shapes  = [parsed_params, []]
+
+        _candidate_urls(url.to_s).each do |candidate_url|
+          param_shapes.each do |shape|
+            concat = _sorted_concat_params(shape)
+            expected_b = _b64_hmac_sha1(signing_key, candidate_url + concat)
+            next unless _safe_eq(expected_b, signature)
+
+            # If the URL carries bodySHA256, the body hash must match too.
+            return true if _check_body_sha256(candidate_url, raw_body)
+            # bodySHA256 mismatched — keep trying other shapes/urls.
+          end
+        end
+
+        false
+      end
+
+      # Legacy ``@signalwire/compatibility-api`` drop-in entry point.
+      #
+      # If ``params_or_raw_body`` is a ``String``, delegates to
+      # {validate_webhook_signature} (Scheme A then Scheme B with parsed form).
+      #
+      # If it's a ``Hash`` or an array of (key, value) pairs, treats it as
+      # pre-parsed form params and runs Scheme B directly (with URL port
+      # normalization and optional bodySHA256 fallback).
+      #
+      # @param signing_key [String]
+      # @param signature [String, nil]
+      # @param url [String]
+      # @param params_or_raw_body [String, Hash, Array, nil]
+      # @return [Boolean]
+      # @raise [ArgumentError] when ``signing_key`` is missing.
+      # @raise [TypeError] when ``params_or_raw_body`` is neither a String,
+      #   Hash, nor an array of pairs.
+      def self.validate_request(signing_key, signature, url, params_or_raw_body)
+        raise ArgumentError, 'signing_key is required' if signing_key.nil? || signing_key.to_s.empty?
+        return false if signature.nil? || signature.to_s.empty?
+
+        if params_or_raw_body.is_a?(String)
+          return validate_webhook_signature(signing_key, signature, url, params_or_raw_body)
+        end
+
+        params_or_raw_body = [] if params_or_raw_body.nil?
+
+        unless params_or_raw_body.is_a?(Hash) || params_or_raw_body.is_a?(Array)
+          raise TypeError,
+                'params_or_raw_body must be a String (raw body) or a Hash/Array of form params'
+        end
+
+        # Pre-parsed form params → Scheme B only.
+        concat = _sorted_concat_params(params_or_raw_body)
+        _candidate_urls(url.to_s).each do |candidate_url|
+          expected_b = _b64_hmac_sha1(signing_key, candidate_url + concat)
+          # bodySHA256 has no raw body to verify here — skip that check.
+          return true if _safe_eq(expected_b, signature)
+        end
+        false
+      end
+
+      # ----------------------------------------------------------------------
+      # Internal helpers (underscore-prefixed: not part of the public surface).
+      # ----------------------------------------------------------------------
+
+      # @api private
+      def self._hex_hmac_sha1(key, message)
+        OpenSSL::HMAC.hexdigest('SHA1', key.to_s, message.to_s)
+      end
+
+      # @api private
+      def self._b64_hmac_sha1(key, message)
+        Base64.strict_encode64(
+          OpenSSL::HMAC.digest('SHA1', key.to_s, message.to_s)
+        )
+      end
+
+      # @api private
+      # Constant-time string compare. Returns false on any error so malformed
+      # inputs never raise.
+      def self._safe_eq(a, b)
+        Rack::Utils.secure_compare(a.to_s, b.to_s)
+      rescue StandardError
+        false
+      end
+
+      # @api private
+      # Concatenate form params per Scheme B rules:
+      # - Sort by key, ASCII ascending.
+      # - For repeated keys (Array values OR multiple [k,v] pairs): keep
+      #   original submission order, emit ``key + value`` once per occurrence.
+      # - Non-string values are stringified via ``to_s``.
+      def self._sorted_concat_params(params)
+        return '' if params.nil? || (params.respond_to?(:empty?) && params.empty?)
+
+        items = []
+        if params.is_a?(Hash)
+          params.each do |k, v|
+            if v.is_a?(Array)
+              v.each { |vi| items << [k.to_s, vi] }
+            else
+              items << [k.to_s, v]
+            end
+          end
+        elsif params.is_a?(Array)
+          params.each do |pair|
+            # Accept [k, v] pairs (the most common form).
+            next unless pair.is_a?(Array) && pair.length >= 2
+
+            items << [pair[0].to_s, pair[1]]
+          end
+        else
+          return ''
+        end
+
+        # Stable sort by key — preserves original order within repeated keys.
+        items = items.each_with_index.sort_by { |(k, _v), idx| [k, idx] }.map(&:first)
+
+        items.map { |k, v| "#{k}#{v.nil? ? '' : v}" }.join
+      end
+
+      # @api private
+      # Best-effort parse of an x-www-form-urlencoded body. Returns an
+      # array of [key, value] pairs (preserving order, including duplicate
+      # keys). Returns [] if the body doesn't decode as form data.
+      def self._parse_form_body(raw_body)
+        return [] if raw_body.nil? || raw_body.empty?
+
+        pairs = []
+        raw_body.split('&').each do |chunk|
+          next if chunk.empty?
+
+          k, _eq, v = chunk.partition('=')
+          decoded_k = CGI.unescape(k)
+          decoded_v = CGI.unescape(v)
+          pairs << [decoded_k, decoded_v]
+        end
+        pairs
+      rescue StandardError
+        []
+      end
+
+      # @api private
+      # Return the URL variants to try for Scheme B port normalization.
+      #
+      # - If the URL already has a non-standard port: just the input URL.
+      # - If https + no port: input URL AND url with ``:443``.
+      # - If http + no port: input URL AND url with ``:80``.
+      # - If https + ``:443`` / http + ``:80``: input URL AND url without port.
+      # - Otherwise (any explicit non-standard port): just the input URL.
+      def self._candidate_urls(url)
+        parsed = URI.parse(url)
+        host = parsed.host
+        return [url] if host.nil? || host.empty?
+
+        scheme = (parsed.scheme || '').downcase
+        standard = { 'http' => 80, 'https' => 443 }[scheme]
+        port = parsed.port
+
+        candidates = [url]
+
+        if standard && parsed.respond_to?(:default_port) && port == parsed.default_port &&
+           !_explicit_port?(url, scheme)
+          # No explicit port in original URL; URI added the default.
+          with_port_url = _build_url_with_port(parsed, standard)
+          candidates << with_port_url if with_port_url != url
+        elsif standard && port == standard && _explicit_port?(url, scheme)
+          # Original URL had the standard port spelled out — also try without.
+          without_port_url = _build_url_without_port(parsed)
+          candidates << without_port_url if without_port_url != url
+        end
+        # Else: non-standard explicit port — only try as-is.
+
+        candidates
+      rescue URI::InvalidURIError
+        [url]
+      end
+
+      # @api private
+      # Heuristic: was a port explicitly written into the URL string?
+      # ``URI`` always populates ``port`` (with the default), so we have to
+      # look at the raw string.
+      def self._explicit_port?(url, _scheme)
+        # Look for ``:NNN`` between the host and the path / query / end.
+        # Avoid false positives in ``://``, userinfo, IPv6 brackets, etc.
+        no_scheme = url.sub(%r{\A[^:]+://}, '')
+        no_userinfo = no_scheme.sub(/\A[^@\/?#]*@/, '')
+        # Strip IPv6 zone if any: "[..]" then look after ]
+        if no_userinfo.start_with?('[')
+          after_bracket = no_userinfo.sub(/\A\[[^\]]*\]/, '')
+          !!(after_bracket =~ /\A:\d+/)
+        else
+          host_and_rest = no_userinfo
+          host_part, _sep, _rest = host_and_rest.partition(%r{[/?#]})
+          !!(host_part =~ /:\d+\z/)
+        end
+      end
+
+      # @api private
+      def self._build_url_with_port(parsed, port)
+        netloc_host = parsed.host.include?(':') ? "[#{parsed.host}]" : parsed.host
+        prefix = "#{parsed.scheme}://"
+        prefix += "#{parsed.userinfo}@" if parsed.userinfo
+        rest = +''
+        rest << (parsed.path || '')
+        rest << "?#{parsed.query}" if parsed.query
+        rest << "##{parsed.fragment}" if parsed.fragment
+        "#{prefix}#{netloc_host}:#{port}#{rest}"
+      end
+
+      # @api private
+      def self._build_url_without_port(parsed)
+        netloc_host = parsed.host.include?(':') ? "[#{parsed.host}]" : parsed.host
+        prefix = "#{parsed.scheme}://"
+        prefix += "#{parsed.userinfo}@" if parsed.userinfo
+        rest = +''
+        rest << (parsed.path || '')
+        rest << "?#{parsed.query}" if parsed.query
+        rest << "##{parsed.fragment}" if parsed.fragment
+        "#{prefix}#{netloc_host}#{rest}"
+      end
+
+      # @api private
+      # If URL has ``?bodySHA256=<hex>``, verify ``sha256_hex(raw_body)`` matches.
+      # Returns true if the param is absent (no constraint), or present and
+      # matches. Returns false only when the param is present and mismatches.
+      def self._check_body_sha256(url, raw_body)
+        parsed = URI.parse(url)
+        return true if parsed.query.nil? || parsed.query.empty?
+
+        # Use _parse_form_body for consistency (handles repeated keys etc).
+        qparams = _parse_form_body(parsed.query)
+        body_hash = qparams.find { |(k, _)| k == 'bodySHA256' }
+        return true if body_hash.nil?
+
+        actual = Digest::SHA256.hexdigest(raw_body.to_s)
+        _safe_eq(actual, body_hash[1])
+      rescue URI::InvalidURIError
+        true
+      end
+    end
+  end
+end