hooks-ruby 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47555e043e83129f208e5925c22dbbf12aadba0358a70272461952355251c869
-  data.tar.gz: b2760979c328b79cf82fe8b5a37a67261f2b5085208488ca928662e1915d9f06
+  metadata.gz: 8cd5b56450a97783c263526f9a1a9e3003f1ed587a0da12bfb7a21b428091d2b
+  data.tar.gz: 67954e277623e99daafc8b3d86c9bdfa62b871319f4bff759789cd32048e752f
 SHA512:
-  metadata.gz: 90b666eb68b986092e56e6db8140af3e6aae5b03a59e0e546beeee4a314a97ed75aaf4122687087cc58b258d88462a6fc5829339f56510e9d123f9b0d7c414ed
-  data.tar.gz: e50173bf684c3b458fe489667b05a65737658160c5a01603f7b8061419945fe41b07d04e61861524c8af5b445e2d63aa78b90ac1a3a07bb2fed481c50cc04406
+  metadata.gz: 41cbc5a653f452e9c6da4ffd526a1b7ea37532712ae820223ccbdb93809789e949d4370fe5ba18036a0a08b8446280ff44471088703c296f769d8c83b6003cfa
+  data.tar.gz: 99619a010a1fca90a1bda4f78850c66f705390be9677a1006cfdf72904e9ae0443bd1c0fed02dbbe014515c4df707a84b305460e111eb086fca76af3dec1ad61

data/README.md

@@ -50,9 +50,11 @@ Here is a very high-level overview of how Hooks works:
     ```yaml
     # file: config/endpoints/hello.yml
     path: /hello
-    handler: MyCustomHandler # This is a custom handler plugin you would define in the plugins/handlers directory
+    handler: my_custom_handler # This is a custom handler plugin you would define in the plugins/handlers directory (snake_case)
     ```
 
+    > Note: If your handler's class name is `MyCustomHandler`, you would define it in the `plugins/handlers/my_custom_handler.rb` file. The `handler` field in the endpoint configuration file should be the snake_case version of the class name. So if your handler class is `MyCustomHandler`, you would use `my_custom_handler` in the endpoint configuration file.
+
 3. Now create a corresponding handler plugin in the `plugins/handlers` directory. Here is an example of a simple handler plugin:
 
     ```ruby
@@ -64,7 +66,7 @@ Here is a very high-level overview of how Hooks works:
         # For this example, we will just return a success message
         {
           status: "success",
-          handler: "MyCustomHandler",
+          handler: "my_custom_handler",
           payload_received: payload,
           timestamp: Time.now.utc.iso8601
         }
@@ -208,16 +210,16 @@ Endpoint configurations are defined in the `config/endpoints` directory. Each en
 ```yaml
 # file: config/endpoints/hello.yml
 path: /hello # becomes /webhooks/hello based on the root_path in hooks.yml
-handler: HelloHandler # This is a custom handler plugin you would define in the plugins/handlers
+handler: hello_handler # This is a custom handler plugin you would define in the plugins/handlers
 ```
 
 ```yaml
 # file: config/endpoints/goodbye.yml
 path: /goodbye # becomes /webhooks/goodbye based on the root_path in hooks.yml
-handler: GoodbyeHandler # This is another custom handler plugin you would define in the plugins/handlers
+handler: goodbye_handler # This is another custom handler plugin you would define in the plugins/handlers
 
 auth:
-  type: Goodbye # This is a custom authentication plugin you would define in the plugins/auth
+  type: goodbye # This is a custom authentication plugin you would define in the plugins/auth
   secret_env_key: GOODBYE_API_KEY # the name of the environment variable containing the secret
   header: Authorization
 
@@ -255,7 +257,7 @@ class GoodbyeHandler < Hooks::Plugins::Handlers::Base
     # Ditto for the goodbye endpoint
     {
       message: "goodbye webhook processed successfully",
-      handler: "GoodbyeHandler",
+      handler: "goodbye_handler",
       timestamp: Time.now.utc.iso8601
     }
   end

data/lib/hooks/app/api.rb

@@ -4,6 +4,7 @@ require "grape"
 require "json"
 require "securerandom"
 require_relative "helpers"
+require_relative "../core/network/ip_filtering"
 require_relative "auth/auth"
 require_relative "rack_env_builder"
 require_relative "../plugins/handlers/base"
@@ -82,6 +83,13 @@ module Hooks
                     plugin.on_request(rack_env)
                   end
 
+                  # 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
+
                   enforce_request_limits(config, request_context)
                   request.body.rewind
                   raw_body = request.body.read

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
@@ -74,7 +75,7 @@ module Hooks
 
       # Load handler class
       #
-      # @param handler_class_name [String] The name of the handler class to load
+      # @param handler_class_name [String] The name of the handler in snake_case (e.g., "github_handler")
       # @return [Object] An instance of the loaded handler class
       # @raise [StandardError] If handler cannot be found
       def load_handler(handler_class_name)
@@ -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/app/rack_env_builder.rb

@@ -72,6 +72,8 @@ module Hooks
       end
 
       # Add HTTP headers to the environment with proper Rack naming convention
+      # Note: This will generally add headers like HTTP_X_CUSTOM_HEADER. For example, the HTTP_X_FORWARDED_FOR
+      # is a common header that is used to pass the original client IP address through proxies.
       #
       # @param rack_env [Hash] Environment hash to modify
       def add_http_headers(rack_env)

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
 
@@ -125,11 +137,12 @@ module Hooks
         # Must not be empty or only whitespace
         return false if handler_name.strip.empty?
 
-        # Must match a safe pattern: alphanumeric + underscore, starting with uppercase
-        return false unless handler_name.match?(/\A[A-Z][a-zA-Z0-9_]*\z/)
+        # Must match strict snake_case pattern: starts with lowercase, no trailing/consecutive underscores
+        return false unless handler_name.match?(/\A[a-z][a-z0-9]*(?:_[a-z0-9]+)*\z/)
 
-        # Must not be a system/built-in class name
-        return false if Hooks::Security::DANGEROUS_CLASSES.include?(handler_name)
+        # Convert to PascalCase for security check (since DANGEROUS_CLASSES uses PascalCase)
+        pascal_case_name = handler_name.split("_").map(&:capitalize).join("")
+        return false if Hooks::Security::DANGEROUS_CLASSES.include?(pascal_case_name)
 
         true
       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/core/plugin_loader.rb

@@ -61,11 +61,13 @@ module Hooks
 
         # Get handler plugin class by name
         #
-        # @param handler_name [String] Name of the handler (e.g., "DefaultHandler", "Team1Handler")
+        # @param handler_name [String] Name of the handler in snake_case (e.g., "github_handler", "team_1_handler")
         # @return [Class] The handler plugin class
         # @raise [StandardError] if handler not found
         def get_handler_plugin(handler_name)
-          plugin_class = @handler_plugins[handler_name]
+          # Convert snake_case to PascalCase for registry lookup
+          pascal_case_name = handler_name.split("_").map(&:capitalize).join("")
+          plugin_class = @handler_plugins[pascal_case_name]
 
           unless plugin_class
             raise StandardError, "Handler plugin '#{handler_name}' not found. Available handlers: #{@handler_plugins.keys.join(', ')}"

data/lib/hooks/plugins/auth/base.rb

@@ -4,6 +4,7 @@ require "rack/utils"
 require_relative "../../core/log"
 require_relative "../../core/global_components"
 require_relative "../../core/component_access"
+require_relative "timestamp_validator"
 
 module Hooks
   module Plugins
@@ -53,6 +54,13 @@ module Hooks
           return secret.strip
         end
 
+        # Get timestamp validator instance
+        #
+        # @return [TimestampValidator] Singleton timestamp validator instance
+        def self.timestamp_validator
+          TimestampValidator.new
+        end
+
         # Find a header value by name with case-insensitive matching
         #
         # @param headers [Hash] HTTP headers from the request

data/lib/hooks/plugins/auth/hmac.rb

@@ -3,7 +3,6 @@
 require "openssl"
 require "time"
 require_relative "base"
-require_relative "timestamp_validator"
 
 module Hooks
   module Plugins
@@ -271,14 +270,6 @@ module Hooks
           timestamp_validator.valid?(timestamp_value, tolerance)
         end
 
-        # Get timestamp validator instance
-        #
-        # @return [TimestampValidator] Singleton timestamp validator instance
-        # @api private
-        def self.timestamp_validator
-          @timestamp_validator ||= TimestampValidator.new
-        end
-
         # Compute HMAC signature based on configuration requirements
         #
         # Generates the expected HMAC signature for the given payload using the

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.2.1".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.2.1
+  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