hooks-ruby 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efc93a22af173a3085d2af45a0787501cf4e520e0aa917c7b4b8ee477a477820
-  data.tar.gz: 06c6177f4356d06e59ceaf2f7e9c62848752ee1a5d298981c2820c1732906424
+  metadata.gz: 8cd5b56450a97783c263526f9a1a9e3003f1ed587a0da12bfb7a21b428091d2b
+  data.tar.gz: 67954e277623e99daafc8b3d86c9bdfa62b871319f4bff759789cd32048e752f
 SHA512:
-  metadata.gz: e4bed95c7e1f41cd7188847773b83e1d7e1a463122545cc5c0330348539f81b2ed254c9e7ff161b2922b8f064ec46174288b3557be4c2d63604405ab931adb0d
-  data.tar.gz: fe7cdde0b508f5bcf1e354f6c3b2583530ad27f27d63686712d05830581b849fc2d8e61cad5ba1dd8d4283e182b823625d4e164bd9fa4909ae6be7be3d0ce360
+  metadata.gz: 41cbc5a653f452e9c6da4ffd526a1b7ea37532712ae820223ccbdb93809789e949d4370fe5ba18036a0a08b8446280ff44471088703c296f769d8c83b6003cfa
+  data.tar.gz: 99619a010a1fca90a1bda4f78850c66f705390be9677a1006cfdf72904e9ae0443bd1c0fed02dbbe014515c4df707a84b305460e111eb086fca76af3dec1ad61

data/lib/hooks/app/api.rb

@@ -4,7 +4,7 @@ require "grape"
 require "json"
 require "securerandom"
 require_relative "helpers"
-#require_relative "network/ip_filtering"
+require_relative "../core/network/ip_filtering"
 require_relative "auth/auth"
 require_relative "rack_env_builder"
 require_relative "../plugins/handlers/base"
@@ -83,12 +83,12 @@ module Hooks
                     plugin.on_request(rack_env)
                   end
 
-                  # TODO: IP filtering before processing the request if defined
+                  # IP filtering before processing the request if defined
                   # If IP filtering is enabled at either global or endpoint level, run the filtering rules
                   # before processing the request
-                  #if config[:ip_filtering] || endpoint_config[:ip_filtering]
-                    #ip_filtering!(headers, endpoint_config, config, request_context, rack_env)
-                  #end
+                  if config[:ip_filtering] || endpoint_config[:ip_filtering]
+                    ip_filtering!(headers, endpoint_config, config, request_context, rack_env)
+                  end
 
                   enforce_request_limits(config, request_context)
                   request.body.rewind

data/lib/hooks/app/helpers.rb

@@ -3,6 +3,7 @@
 require "securerandom"
 require_relative "../security"
 require_relative "../core/plugin_loader"
+require_relative "../core/network/ip_filtering"
 
 module Hooks
   module App
@@ -88,6 +89,28 @@ module Hooks
         return handler_class.new
       end
 
+      # Verifies the incoming request passes the configured IP filtering rules.
+      #
+      # This method assumes that the client IP address is available in the request headers (e.g., `X-Forwarded-For`).
+      # The headers that is used is configurable via the endpoint configuration.
+      # It checks the IP address against the allowed and denied lists defined in the endpoint configuration.
+      # If the IP address is not allowed, it instantly returns an error response via the `error!` method.
+      # If the IP filtering configuration is missing or invalid, it raises an error.
+      # If IP filtering is configured at the global level, it will also check against the global configuration first,
+      # and then against the endpoint-specific configuration.
+      #
+      # @param headers [Hash] The request headers.
+      # @param endpoint_config [Hash] The endpoint configuration, must include :ip_filtering key.
+      # @param global_config [Hash] The global configuration (optional, for compatibility).
+      # @param request_context [Hash] Context for the request, e.g. request ID, path, handler (optional).
+      # @param env [Hash] The Rack environment
+      # @raise [StandardError] Raises error if IP filtering fails or is misconfigured.
+      # @return [void]
+      # @note This method will halt execution with an error if IP filtering rules fail.
+      def ip_filtering!(headers, endpoint_config, global_config, request_context, env)
+        Hooks::Core::Network::IpFiltering.ip_filtering!(headers, endpoint_config, global_config, request_context, env)
+      end
+
       private
 
       # Safely parse JSON

data/lib/hooks/core/config_validator.rb

@@ -27,6 +27,12 @@ module Hooks
         optional(:endpoints_dir).filled(:string)
         optional(:use_catchall_route).filled(:bool)
         optional(:normalize_headers).filled(:bool)
+
+        optional(:ip_filtering).hash do
+          optional(:ip_header).filled(:string)
+          optional(:allowlist).array(:string)
+          optional(:blocklist).array(:string)
+        end
       end
 
       # Endpoint configuration schema
@@ -52,6 +58,12 @@ module Hooks
           optional(:key_value_separator).filled(:string)
         end
 
+        optional(:ip_filtering).hash do
+          optional(:ip_header).filled(:string)
+          optional(:allowlist).array(:string)
+          optional(:blocklist).array(:string)
+        end
+
         optional(:opts).hash
       end
 

data/lib/hooks/core/network/ip_filtering.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require_relative "../../plugins/handlers/error"
+
+module Hooks
+  module Core
+    module Network
+      # Application-level IP filtering functionality for HTTP requests.
+      #
+      # This class provides robust IP filtering capabilities supporting both allowlist
+      # and blocklist filtering with CIDR notation support. It can extract client IP
+      # addresses from various HTTP headers and validate them against configured rules.
+      #
+      # The filtering logic follows these rules:
+      # 1. If a blocklist is configured and the IP matches, access is denied
+      # 2. If an allowlist is configured, the IP must match to be allowed
+      # 3. If no allowlist is configured and IP is not blocked, access is allowed
+      #
+      # @example Basic usage with endpoint configuration
+      #   config = {
+      #     ip_filtering: {
+      #       allowlist: ["192.168.1.0/24", "10.0.0.1"],
+      #       blocklist: ["192.168.1.100"],
+      #       ip_header: "X-Real-IP"
+      #     }
+      #   }
+      #   IpFiltering.ip_filtering!(headers, config, {}, {}, env)
+      #
+      # @note This class is designed to work with Rack-based applications and
+      #   expects headers to be in a Hash format.
+      class IpFiltering
+        # Default HTTP header to check for client IP address.
+        # @return [String] the default header name
+        DEFAULT_IP_HEADER = "X-Forwarded-For"
+
+        # Verifies that an incoming request passes the configured IP filtering rules.
+        #
+        # This method extracts the client IP address from request headers and validates
+        # it against configured allowlist and blocklist rules. The method will halt
+        # execution by raising an error if the IP filtering rules fail.
+        #
+        # The IP filtering configuration can be defined at both global and endpoint levels,
+        # with endpoint configuration taking precedence. If no IP filtering is configured,
+        # the method returns early without performing any checks.
+        #
+        # The client IP is extracted from HTTP headers, with support for configurable
+        # header names. The default header is X-Forwarded-For, which can contain multiple
+        # comma-separated IPs (the first IP is used as the original client).
+        #
+        # @param headers [Hash] The request headers as key-value pairs
+        # @param endpoint_config [Hash] The endpoint-specific configuration containing :ip_filtering
+        # @param global_config [Hash] The global configuration (optional, for compatibility)
+        # @param request_context [Hash] Context information for the request (e.g., request_id, path, handler)
+        # @param env [Hash] The Rack environment hash
+        #
+        # @raise [Hooks::Plugins::Handlers::Error] Raises a 403 error if IP filtering rules fail
+        # @return [void] Returns nothing if IP filtering passes or is not configured
+        #
+        # @example Successful IP filtering
+        #   headers = { "X-Forwarded-For" => "192.168.1.50" }
+        #   config = { ip_filtering: { allowlist: ["192.168.1.0/24"] } }
+        #   IpFiltering.ip_filtering!(headers, config, {}, { request_id: "123" }, env)
+        #
+        # @example IP filtering failure
+        #   headers = { "X-Forwarded-For" => "10.0.0.1" }
+        #   config = { ip_filtering: { allowlist: ["192.168.1.0/24"] } }
+        #   # Raises Hooks::Plugins::Handlers::Error with 403 status
+        #   IpFiltering.ip_filtering!(headers, config, {}, { request_id: "123" }, env)
+        #
+        # @note This method assumes that the client IP address is available in the request headers
+        # @note If the IP filtering configuration is missing or invalid, it raises an error
+        # @note This method will halt execution with an error if IP filtering rules fail
+        def self.ip_filtering!(headers, endpoint_config, global_config, request_context, env)
+          # Determine which IP filtering configuration to use
+          ip_config = resolve_ip_config(endpoint_config, global_config)
+          return unless ip_config # No IP filtering configured
+
+          # Extract client IP from headers
+          client_ip = extract_client_ip(headers, ip_config)
+          return unless client_ip # No client IP found
+
+          # Validate IP against filtering rules
+          unless ip_allowed?(client_ip, ip_config)
+            request_id = request_context&.dig(:request_id) || request_context&.dig("request_id")
+            error_msg = {
+              error: "ip_filtering_failed",
+              message: "IP address not allowed",
+              request_id: request_id
+            }
+            raise Hooks::Plugins::Handlers::Error.new(error_msg, 403)
+          end
+        end
+
+        # Resolves the IP filtering configuration to use for the current request.
+        #
+        # This method determines which IP filtering configuration should be applied
+        # by checking endpoint-specific configuration first, then falling back to
+        # global configuration. This allows for flexible configuration inheritance
+        # with endpoint-level overrides.
+        #
+        # @param endpoint_config [Hash] The endpoint-specific configuration
+        # @param global_config [Hash] The global application configuration
+        #
+        # @return [Hash, nil] The IP filtering configuration hash, or nil if none configured
+        #
+        # @example With endpoint configuration
+        #   endpoint_config = { ip_filtering: { allowlist: ["192.168.1.0/24"] } }
+        #   global_config = { ip_filtering: { allowlist: ["10.0.0.0/8"] } }
+        #   resolve_ip_config(endpoint_config, global_config)
+        #   # => { allowlist: ["192.168.1.0/24"] }
+        #
+        # @example With only global configuration
+        #   endpoint_config = {}
+        #   global_config = { ip_filtering: { allowlist: ["10.0.0.0/8"] } }
+        #   resolve_ip_config(endpoint_config, global_config)
+        #   # => { allowlist: ["10.0.0.0/8"] }
+        #
+        # @note Endpoint-level configuration takes precedence over global configuration
+        private_class_method def self.resolve_ip_config(endpoint_config, global_config)
+          # Endpoint-level configuration takes precedence over global configuration
+          endpoint_config[:ip_filtering] || global_config[:ip_filtering]
+        end
+
+        # Extracts the client IP address from request headers.
+        #
+        # This method looks for the client IP in the specified header (or default
+        # X-Forwarded-For header). It performs case-insensitive header matching
+        # and handles comma-separated IP lists by taking the first IP address,
+        # which represents the original client in proxy chains.
+        #
+        # @param headers [Hash] The request headers as key-value pairs
+        # @param ip_config [Hash] The IP filtering configuration containing :ip_header
+        #
+        # @return [String, nil] The client IP address, or nil if not found or empty
+        #
+        # @example Extracting from X-Forwarded-For
+        #   headers = { "X-Forwarded-For" => "192.168.1.50, 10.0.0.1" }
+        #   ip_config = { ip_header: "X-Forwarded-For" }
+        #   extract_client_ip(headers, ip_config)
+        #   # => "192.168.1.50"
+        #
+        # @example Extracting from custom header
+        #   headers = { "X-Real-IP" => "203.0.113.45" }
+        #   ip_config = { ip_header: "X-Real-IP" }
+        #   extract_client_ip(headers, ip_config)
+        #   # => "203.0.113.45"
+        #
+        # @note Case-insensitive header lookup is performed
+        # @note For comma-separated IP lists, only the first IP is returned
+        private_class_method def self.extract_client_ip(headers, ip_config)
+          # Use configured header or default to X-Forwarded-For
+          ip_header = ip_config[:ip_header] || DEFAULT_IP_HEADER
+
+          # Case-insensitive header lookup
+          headers.each do |key, value|
+            if key.to_s.downcase == ip_header.downcase
+              # X-Forwarded-For can contain multiple IPs, take the first one (original client)
+              client_ip = value.to_s.split(",").first&.strip
+              return client_ip unless client_ip.nil? || client_ip.empty?
+            end
+          end
+
+          nil
+        end
+
+        # Determines if a client IP address is allowed based on filtering rules.
+        #
+        # This method implements the core IP filtering logic by checking the client
+        # IP against configured blocklist and allowlist rules. The filtering follows
+        # these precedence rules:
+        # 1. If blocklist exists and IP matches, deny access (return false)
+        # 2. If allowlist exists, IP must match to be allowed (return true/false)
+        # 3. If no allowlist exists and IP not blocked, allow access (return true)
+        #
+        # @param client_ip [String] The client IP address to validate
+        # @param ip_config [Hash] The IP filtering configuration containing :blocklist and/or :allowlist
+        #
+        # @return [Boolean] true if IP is allowed, false if blocked or invalid
+        #
+        # @example IP allowed by allowlist
+        #   client_ip = "192.168.1.50"
+        #   ip_config = { allowlist: ["192.168.1.0/24"] }
+        #   ip_allowed?(client_ip, ip_config)
+        #   # => true
+        #
+        # @example IP blocked by blocklist
+        #   client_ip = "192.168.1.100"
+        #   ip_config = { blocklist: ["192.168.1.100"] }
+        #   ip_allowed?(client_ip, ip_config)
+        #   # => false
+        #
+        # @example Invalid IP format
+        #   client_ip = "invalid-ip"
+        #   ip_config = { allowlist: ["192.168.1.0/24"] }
+        #   ip_allowed?(client_ip, ip_config)
+        #   # => false
+        #
+        # @note Invalid IP addresses are automatically denied
+        # @note Blocklist rules take precedence over allowlist rules
+        private_class_method def self.ip_allowed?(client_ip, ip_config)
+          # Parse client IP
+          begin
+            client_addr = IPAddr.new(client_ip)
+          rescue IPAddr::InvalidAddressError
+            return false # Invalid IP format
+          end
+
+          # Check blocklist first (if IP is blocked, deny immediately)
+          if ip_config[:blocklist]&.any?
+            return false if ip_matches_list?(client_addr, ip_config[:blocklist])
+          end
+
+          # Check allowlist (if defined, IP must be in allowlist)
+          if ip_config[:allowlist]&.any?
+            return ip_matches_list?(client_addr, ip_config[:allowlist])
+          end
+
+          # If no allowlist is defined and IP is not in blocklist, allow
+          true
+        end
+
+        # Checks if a client IP address matches any pattern in an IP list.
+        #
+        # This method iterates through a list of IP patterns (which can include
+        # individual IPs or CIDR ranges) and determines if the client IP matches
+        # any of them. It uses Ruby's IPAddr class for robust IP address and
+        # CIDR range matching, with error handling for invalid IP patterns.
+        #
+        # @param client_addr [IPAddr] The client IP address as an IPAddr object
+        # @param ip_list [Array<String>] Array of IP patterns (IPs or CIDR ranges)
+        #
+        # @return [Boolean] true if client IP matches any pattern in the list, false otherwise
+        #
+        # @example Matching individual IP
+        #   client_addr = IPAddr.new("192.168.1.50")
+        #   ip_list = ["192.168.1.50", "10.0.0.1"]
+        #   ip_matches_list?(client_addr, ip_list)
+        #   # => true
+        #
+        # @example Matching CIDR range
+        #   client_addr = IPAddr.new("192.168.1.50")
+        #   ip_list = ["192.168.1.0/24", "10.0.0.0/8"]
+        #   ip_matches_list?(client_addr, ip_list)
+        #   # => true
+        #
+        # @example No match found
+        #   client_addr = IPAddr.new("203.0.113.45")
+        #   ip_list = ["192.168.1.0/24", "10.0.0.0/8"]
+        #   ip_matches_list?(client_addr, ip_list)
+        #   # => false
+        #
+        # @note Invalid IP patterns in the list are silently skipped
+        # @note Supports both IPv4 and IPv6 addresses and ranges
+        private_class_method def self.ip_matches_list?(client_addr, ip_list)
+          ip_list.each do |ip_pattern|
+            begin
+              pattern_addr = IPAddr.new(ip_pattern.to_s)
+              return true if pattern_addr.include?(client_addr)
+            rescue IPAddr::InvalidAddressError
+              # Skip invalid IP patterns
+              next
+            end
+          end
+          false
+        end
+      end
+    end
+  end
+end

data/lib/hooks/version.rb

@@ -4,5 +4,5 @@
 module Hooks
   # Current version of the Hooks webhook framework
   # @return [String] The version string following semantic versioning
-  VERSION = "0.3.0".freeze
+  VERSION = "0.3.1".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hooks-ruby
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - github
@@ -138,6 +138,7 @@ files:
 - lib/hooks/core/global_components.rb
 - lib/hooks/core/log.rb
 - lib/hooks/core/logger_factory.rb
+- lib/hooks/core/network/ip_filtering.rb
 - lib/hooks/core/plugin_loader.rb
 - lib/hooks/core/stats.rb
 - lib/hooks/plugins/auth/base.rb