parse-stack-next 4.5.0

data/lib/parse/webhooks/registration.rb

@@ -0,0 +1,199 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/inflector"
+require "active_support/core_ext/object"
+require "active_support/core_ext/string"
+require "active_support/core_ext"
+require "ipaddr"
+require "resolv"
+require "uri"
+require_relative "../model/file"
+
+module Parse
+  # Interface to the CloudCode webhooks API.
+  class Webhooks
+    # Module to support registering Parse CloudCode webhooks.
+    module Registration
+      # The set of allowed trigger types.
+      ALLOWED_HOOKS = Parse::API::Hooks::TRIGGER_NAMES + [:function]
+
+      # @!visibility private
+      # Validates that a webhook endpoint URL is safe to register with
+      # Parse Server. Rejects non-http(s) schemes, embedded userinfo, and
+      # hostnames that resolve to loopback, link-local, RFC1918, CGNAT,
+      # multicast, or cloud-metadata addresses (covered by
+      # +Parse::File::BLOCKED_CIDRS+). Without these checks an attacker who
+      # can reach +register_webhook!+ could redirect Parse Server's trigger
+      # POSTs to an internal host (e.g. the cloud metadata service) and
+      # exfiltrate request bodies. Returns the input URL unchanged on
+      # success.
+      # @raise [ArgumentError] on any disallowed input.
+      def assert_webhook_url_safe!(url)
+        raise ArgumentError, "Webhook URL is required" if url.nil? || url.to_s.empty?
+        uri = begin
+          URI.parse(url.to_s)
+        rescue URI::InvalidURIError => e
+          raise ArgumentError, "Invalid webhook URL: #{e.message}"
+        end
+        unless %w[http https].include?(uri.scheme)
+          raise ArgumentError, "Webhook URL must be http(s) (got #{uri.scheme.inspect})"
+        end
+        host = uri.host
+        if host.nil? || host.empty?
+          raise ArgumentError, "Webhook URL missing host"
+        end
+        if uri.userinfo
+          raise ArgumentError, "Webhook URL must not include userinfo credentials"
+        end
+        if Parse::Webhooks.allow_private_webhook_urls
+          return url
+        end
+        addrs = Parse::File.resolve_addresses(host)
+        if addrs.empty?
+          raise ArgumentError, "Webhook URL host #{host} could not be resolved"
+        end
+        addrs.each do |ip|
+          if Parse::File::BLOCKED_CIDRS.any? { |cidr| cidr.include?(ip) }
+            raise ArgumentError,
+                  "Refusing to register webhook with private/internal " \
+                  "address #{ip} for host #{host}"
+          end
+        end
+        url
+      end
+
+      # removes all registered webhook functions with Parse Server.
+      def remove_all_functions!
+        client.functions.results.sort_by { |f| f["functionName"] }.each do |f|
+          next unless f["url"].present?
+          client.delete_function f["functionName"]
+          yield(f["functionName"]) if block_given?
+        end
+      end
+
+      # removes all registered webhook triggers with Parse Server.
+      def remove_all_triggers!
+        client.triggers.results.sort_by { |f| [f["triggerName"], f["className"]] }.each do |f|
+          next unless f["url"].present?
+          triggerName = f["triggerName"]
+          className = f[Parse::Model::KEY_CLASS_NAME]
+          client.delete_trigger triggerName, className
+          yield(f["triggerName"], f[Parse::Model::KEY_CLASS_NAME]) if block_given?
+        end
+      end
+
+      # Registers all webhook functions registered with Parse::Stack with Parse server.
+      # @param endpoint [String] a https url that points to the webhook server.
+      def register_functions!(endpoint)
+        unless endpoint.present? && (endpoint.starts_with?("http://") || endpoint.starts_with?("https://"))
+          raise ArgumentError, "The HOOKS_URL must be http/s: '#{endpoint}''"
+        end
+        assert_webhook_url_safe!(endpoint)
+        endpoint += "/" unless endpoint.ends_with?("/")
+        functionsMap = {}
+        client.functions.results.each do |f|
+          next unless f["url"].present?
+          functionsMap[f["functionName"]] = f["url"]
+        end
+
+        routes.function.keys.sort.each do |functionName|
+          url = endpoint + functionName
+          if functionsMap[functionName].present? #you may need to update
+            next if functionsMap[functionName] == url
+            client.update_function(functionName, url)
+          else
+            client.create_function(functionName, url)
+          end
+          yield(functionName) if block_given?
+        end
+      end
+
+      # Registers all webhook triggers registered with Parse::Stack with Parse server.
+      # @param endpoint [String] a https url that points to the webhook server.
+      # @param include_wildcard [Boolean] Allow wildcard registrations
+      def register_triggers!(endpoint, include_wildcard: false)
+        unless endpoint.present? && (endpoint.starts_with?("http://") || endpoint.starts_with?("https://"))
+          raise ArgumentError, "The HOOKS_URL must be http/s: '#{endpoint}''"
+        end
+        assert_webhook_url_safe!(endpoint)
+        endpoint += "/" unless endpoint.ends_with?("/")
+        all_triggers = Parse::API::Hooks::TRIGGER_NAMES_LOCAL
+
+        current_triggers = {}
+        all_triggers.each { |t| current_triggers[t] = {} }
+
+        client.triggers.each do |t|
+          next unless t["url"].present?
+          trigger_name = t["triggerName"].underscore.to_sym
+          current_triggers[trigger_name] ||= {}
+          current_triggers[trigger_name][t["className"]] = t["url"]
+        end
+
+        all_triggers.each do |trigger|
+          classNames = routes[trigger].keys.dup
+          if include_wildcard && classNames.include?("*") #then create the list for all classes
+            classNames.delete "*" #delete the wildcard before we expand it
+            classNames = classNames + Parse.registered_classes
+            classNames.uniq!
+          end
+
+          classNames.sort.each do |className|
+            next if className == "*"
+            url = endpoint + "#{trigger}/#{className}"
+            if current_triggers[trigger][className].present? #then you may need to update
+              next if current_triggers[trigger][className] == url
+              client.update_trigger(trigger, className, url)
+            else
+              client.create_trigger(trigger, className, url)
+            end
+            yield(trigger.columnize, className) if block_given?
+          end
+        end
+      end
+
+      # Registers a webhook trigger with a given endpoint url.
+      # @param trigger [Symbol] Trigger type based on Parse::API::Hooks::TRIGGER_NAMES or :function.
+      # @param name [String] the name of the webhook.
+      # @param url [String] the https url endpoint that will handle the request.
+      # @see Parse::API::Hooks::TRIGGER_NAMES
+      def register_webhook!(trigger, name, url)
+        trigger = trigger.to_s.camelize(:lower).to_sym
+        raise ArgumentError, "Invalid hook trigger #{trigger}" unless ALLOWED_HOOKS.include?(trigger)
+        assert_webhook_url_safe!(url)
+        if trigger == :function
+          response = client.fetch_function(name)
+          # if it is either an error (which has no results) or there is a result but
+          # no registered item with a URL (which implies either none registered or only cloud code registered)
+          # then create it.
+          if response.results.none? { |d| d.has_key?("url") }
+            response = client.create_function(name, url)
+          else
+            # update it
+            response = client.update_function(name, url)
+          end
+          warn "Webhook Registration warning: #{response.result["warning"]}" if response.result.has_key?("warning")
+          warn "Failed to register Cloud function #{name} with #{url}" if response.error?
+          return response
+        else # must be trigger
+          response = client.fetch_trigger(trigger, name)
+          # if it is either an error (which has no results) or there is a result but
+          # no registered item with a URL (which implies either none registered or only cloud code registered)
+          # then create it.
+          if response.results.none? { |d| d.has_key?("url") }
+            # create it
+            response = client.create_trigger(trigger, name, url)
+          else
+            # update it
+            response = client.update_trigger(trigger, name, url)
+          end
+
+          warn "Webhook Registration warning: #{response.result["warning"]}" if response.result.has_key?("warning")
+          warn "Webhook Registration error: #{response.error}" if response.error?
+          return response
+        end
+      end
+    end
+  end
+end

data/lib/parse/webhooks/replay_protection.rb

@@ -0,0 +1,189 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "digest"
+require "openssl"
+require "monitor"
+require "active_support/security_utils"
+
+module Parse
+  class Webhooks
+    # NEW-EXT-4: webhook freshness and replay protection.
+    #
+    # Parse Server's default webhook delivery is authenticated only by the
+    # static +X-Parse-Webhook-Key+ header. A captured POST is therefore
+    # indefinitely replayable -- a Ruby-initiated save bearing an +_RB_+
+    # request id will continue to suppress server-side after_* callbacks
+    # every time it is replayed, and a generic trigger payload can be
+    # delivered repeatedly to fire double-charges or other side effects.
+    #
+    # This module adds two layers on top of the existing static-key check:
+    #
+    # 1. **Always-on body+request-id dedup.** A bounded LRU records a
+    #    SHA-256 of +(request_id || "")+ joined with the request body. A
+    #    duplicate seen within +replay_window_seconds+ is rejected with
+    #    +"Webhook replay detected."+. Cooperation with Parse Server is not
+    #    required; this protects against in-window replays only, but those
+    #    are the cheapest attack to mount (proxy retries, captured fast
+    #    loops, retransmits).
+    #
+    # 2. **Opt-in HMAC freshness verification.** When a +signing_secret+ is
+    #    configured (programmatically or via
+    #    +PARSE_WEBHOOK_SIGNING_SECRET+) the dispatcher requires two extra
+    #    headers on every request:
+    #
+    #    * +X-Parse-Webhook-Timestamp+ -- decimal Unix epoch seconds.
+    #    * +X-Parse-Webhook-Signature+ -- hex-encoded HMAC-SHA256 of the
+    #      bytes +"#{timestamp}.#{body}"+ keyed with the signing secret.
+    #
+    #    Requests outside +signing_max_skew_seconds+ (default 300) or with
+    #    an invalid signature are rejected. Once enabled, this gives full
+    #    binding between the body and the time of delivery and closes the
+    #    replay window beyond the freshness skew.
+    #
+    # Operators wanting layer 2 must arrange for Parse Server to add these
+    # headers. Parse Server does not natively sign webhook deliveries, so
+    # this is typically done with a thin Cloud Code wrapper or an egress
+    # proxy. Until enabled, layer 1 still applies.
+    module ReplayProtection
+      # @!visibility private
+      HEADER_TIMESTAMP = "HTTP_X_PARSE_WEBHOOK_TIMESTAMP"
+      # @!visibility private
+      HEADER_SIGNATURE = "HTTP_X_PARSE_WEBHOOK_SIGNATURE"
+      # @!visibility private
+      DEFAULT_REPLAY_WINDOW = 300
+      # @!visibility private
+      DEFAULT_REPLAY_CACHE_SIZE = 10_000
+      # @!visibility private
+      DEFAULT_MAX_SKEW = 300
+
+      class << self
+        attr_writer :signing_secret, :signing_max_skew_seconds,
+                    :replay_window_seconds, :replay_cache_size
+
+        # Shared HMAC secret used to verify +X-Parse-Webhook-Signature+.
+        # When nil/empty, signature verification is skipped (layer 1 still
+        # applies). Defaults to +ENV["PARSE_WEBHOOK_SIGNING_SECRET"]+.
+        def signing_secret
+          return @signing_secret if defined?(@signing_secret) && !@signing_secret.nil?
+          ENV["PARSE_WEBHOOK_SIGNING_SECRET"]
+        end
+
+        # Maximum allowed clock skew (in seconds) between the timestamp
+        # header and the receiver. Requests outside this window are
+        # rejected as stale when +signing_secret+ is set.
+        def signing_max_skew_seconds
+          @signing_max_skew_seconds || DEFAULT_MAX_SKEW
+        end
+
+        # How long a +(request_id, body)+ digest stays in the dedup cache.
+        # Duplicates seen within this window are rejected.
+        def replay_window_seconds
+          @replay_window_seconds || DEFAULT_REPLAY_WINDOW
+        end
+
+        # Maximum number of entries retained in the dedup LRU. Older
+        # entries are evicted to keep memory bounded.
+        def replay_cache_size
+          @replay_cache_size || DEFAULT_REPLAY_CACHE_SIZE
+        end
+
+        # Reset all configuration (intended for tests).
+        # @!visibility private
+        def reset!
+          @signing_secret = nil
+          @signing_max_skew_seconds = nil
+          @replay_window_seconds = nil
+          @replay_cache_size = nil
+          @cache = nil
+        end
+
+        # Clear the dedup cache (intended for tests).
+        # @!visibility private
+        def clear_cache!
+          cache.clear
+        end
+
+        # @!visibility private
+        def cache
+          @cache ||= LruCache.new
+        end
+
+        # @!visibility private
+        # Returns nil when the request passes both replay and signature
+        # checks; otherwise returns a short error string suitable for the
+        # webhook error response. The headers come from +env+ so this
+        # works with any Rack request.
+        def verify!(env, body_str, request_id)
+          secret = signing_secret
+          if secret && !secret.empty?
+            ts_header = env[HEADER_TIMESTAMP].to_s
+            sig_header = env[HEADER_SIGNATURE].to_s
+            return "Missing webhook signature." if ts_header.empty? || sig_header.empty?
+            return "Invalid webhook timestamp." unless ts_header =~ /\A-?\d{1,12}\z/
+            ts = ts_header.to_i
+            skew = (Time.now.to_i - ts).abs
+            return "Stale webhook timestamp." if skew > signing_max_skew_seconds
+            expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{ts}.#{body_str}")
+            unless ActiveSupport::SecurityUtils.secure_compare(expected, sig_header)
+              return "Invalid webhook signature."
+            end
+          end
+
+          digest = Digest::SHA256.hexdigest("#{request_id}\x1f#{body_str}")
+          if cache.seen?(digest, replay_window_seconds)
+            return "Webhook replay detected."
+          end
+          cache.record(digest, replay_cache_size)
+          nil
+        end
+      end
+
+      # Bounded, thread-safe LRU keyed on a digest string with per-entry
+      # insertion timestamps. Used only by ReplayProtection; intentionally
+      # private to avoid leaking another caching primitive into the public
+      # API. Ruby Hashes preserve insertion order, so a delete+insert on
+      # touch is enough to maintain LRU ordering.
+      class LruCache
+        include MonitorMixin
+
+        def initialize
+          super()
+          @entries = {}
+        end
+
+        def seen?(key, window_seconds)
+          synchronize do
+            ts = @entries[key]
+            return false unless ts
+            if Time.now.to_i - ts > window_seconds
+              @entries.delete(key)
+              return false
+            end
+            @entries.delete(key)
+            @entries[key] = ts # touch
+            true
+          end
+        end
+
+        def record(key, max_size)
+          synchronize do
+            @entries.delete(key)
+            @entries[key] = Time.now.to_i
+            while @entries.size > max_size
+              @entries.shift
+            end
+          end
+        end
+
+        def clear
+          synchronize { @entries.clear }
+        end
+
+        def size
+          synchronize { @entries.size }
+        end
+      end
+    end
+  end
+end