hooks-ruby 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae1757617b84df588de7eb343799b93d1dfc6326c3d54ab1a2d578aa2d3e3b8e
-  data.tar.gz: a39cfa8162346d536ab5a543dfcf7517162282ba3a74098cd276bc76c636a41c
+  metadata.gz: efc93a22af173a3085d2af45a0787501cf4e520e0aa917c7b4b8ee477a477820
+  data.tar.gz: 06c6177f4356d06e59ceaf2f7e9c62848752ee1a5d298981c2820c1732906424
 SHA512:
-  metadata.gz: da5353fda88b8d348e7b743e155642376ad886b5e77a38cb08148a9a6fbb5bece88c099125bb4738d41a09e3d3e0b5c29bd317bafa3789caa595d02f1c7217a2
-  data.tar.gz: 0ba9c613e80a889da7b1fd7b6b4b84b53190aae6db27184d7caa0a90806c3d266f0fff06c4bff1cef702c0879f772056fde5c1b697d817852130167eb0724ebd
+  metadata.gz: e4bed95c7e1f41cd7188847773b83e1d7e1a463122545cc5c0330348539f81b2ed254c9e7ff161b2922b8f064ec46174288b3557be4c2d63604405ab931adb0d
+  data.tar.gz: fe7cdde0b508f5bcf1e354f6c3b2583530ad27f27d63686712d05830581b849fc2d8e61cad5ba1dd8d4283e182b823625d4e164bd9fa4909ae6be7be3d0ce360

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 "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
 
+                  # TODO: 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

@@ -74,7 +74,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)

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

@@ -45,6 +45,11 @@ module Hooks
           optional(:format).filled(:string)
           optional(:version_prefix).filled(:string)
           optional(:payload_template).filled(:string)
+          optional(:header_format).filled(:string)
+          optional(:signature_key).filled(:string)
+          optional(:timestamp_key).filled(:string)
+          optional(:structured_header_separator).filled(:string)
+          optional(:key_value_separator).filled(:string)
         end
 
         optional(:opts).hash
@@ -120,11 +125,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/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
@@ -14,6 +15,10 @@ module Hooks
       class Base
         extend Hooks::Core::ComponentAccess
 
+        # Security constants shared across auth validators
+        MAX_HEADER_VALUE_LENGTH = ENV.fetch("HOOKS_MAX_HEADER_VALUE_LENGTH", 1024).to_i # Prevent DoS attacks via large header values
+        MAX_PAYLOAD_SIZE = ENV.fetch("HOOKS_MAX_PAYLOAD_SIZE", 10 * 1024 * 1024).to_i # 10MB limit for payload validation
+
         # Validate request
         #
         # @param payload [String] Raw request body
@@ -49,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
@@ -67,6 +79,61 @@ module Hooks
           end
           nil
         end
+
+        # Validate headers object for security issues
+        #
+        # @param headers [Object] Headers to validate
+        # @return [Boolean] true if headers are valid
+        def self.valid_headers?(headers)
+          unless headers.respond_to?(:each)
+            log.warn("Auth validation failed: Invalid headers object")
+            return false
+          end
+          true
+        end
+
+        # Validate payload size for security issues
+        #
+        # @param payload [String] Payload to validate
+        # @return [Boolean] true if payload is valid
+        def self.valid_payload_size?(payload)
+          return true if payload.nil?
+
+          if payload.bytesize > MAX_PAYLOAD_SIZE
+            log.warn("Auth validation failed: Payload size exceeds maximum limit of #{MAX_PAYLOAD_SIZE} bytes")
+            return false
+          end
+          true
+        end
+
+        # Validate header value for security issues
+        #
+        # @param header_value [String] Header value to validate
+        # @param header_name [String] Header name for logging
+        # @return [Boolean] true if header value is valid
+        def self.valid_header_value?(header_value, header_name)
+          return false if header_value.nil? || header_value.empty?
+
+          # Check length to prevent DoS
+          if header_value.length > MAX_HEADER_VALUE_LENGTH
+            log.warn("Auth validation failed: #{header_name} exceeds maximum length")
+            return false
+          end
+
+          # Check for whitespace tampering
+          if header_value != header_value.strip
+            log.warn("Auth validation failed: #{header_name} contains leading/trailing whitespace")
+            return false
+          end
+
+          # Check for control characters
+          if header_value.match?(/[\u0000-\u001f\u007f-\u009f]/)
+            log.warn("Auth validation failed: #{header_name} contains control characters")
+            return false
+          end
+
+          true
+        end
       end
     end
   end

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
@@ -32,7 +31,23 @@ module Hooks
       #     format: "version=signature"
       #     version_prefix: "v0"
       #     payload_template: "{version}:{timestamp}:{body}"
+      #
+      # @example Configuration for Tailscale-style structured headers
+      #   auth:
+      #     type: HMAC
+      #     secret_env_key: WEBHOOK_SECRET
+      #     header: Tailscale-Webhook-Signature
+      #     algorithm: sha256
+      #     format: "signature_only"
+      #     header_format: "structured"
+      #     signature_key: "v1"
+      #     timestamp_key: "t"
+      #     payload_template: "{timestamp}.{body}"
+      #     timestamp_tolerance: 300  # 5 minutes
       class HMAC < Base
+        # Security constants
+        MAX_SIGNATURE_LENGTH = ENV.fetch("HOOKS_MAX_SIGNATURE_LENGTH", 1024).to_i # Prevent DoS attacks via large signatures
+
         # Default configuration values for HMAC validation
         #
         # @return [Hash<Symbol, String|Integer>] Default configuration settings
@@ -42,7 +57,8 @@ module Hooks
           format: "algorithm=signature",  # Format: algorithm=hash
           header: "X-Signature",         # Default header containing the signature
           timestamp_tolerance: 300,       # 5 minutes tolerance for timestamp validation
-          version_prefix: "v0"           # Default version prefix for versioned signatures
+          version_prefix: "v0",          # Default version prefix for versioned signatures
+          header_format: "simple"        # Header format: "simple" or "structured"
         }.freeze
 
         # Mapping of signature format strings to internal format symbols
@@ -75,6 +91,11 @@ module Hooks
         # @option config [String] :format ('algorithm=signature') Signature format
         # @option config [String] :version_prefix ('v0') Version prefix for versioned signatures
         # @option config [String] :payload_template Template for payload construction
+        # @option config [String] :header_format ('simple') Header format: 'simple' or 'structured'
+        # @option config [String] :signature_key ('v1') Key for signature in structured headers
+        # @option config [String] :timestamp_key ('t') Key for timestamp in structured headers
+        # @option config [String] :structured_header_separator (',') Separator for structured headers
+        # @option config [String] :key_value_separator ('=') Separator for key-value pairs in structured headers
         # @return [Boolean] true if signature is valid, false otherwise
         # @raise [StandardError] Rescued internally, returns false on any error
         # @note This method is designed to be safe and will never raise exceptions
@@ -91,11 +112,9 @@ module Hooks
 
           validator_config = build_config(config)
 
-          # Security: Check raw headers BEFORE normalization to detect tampering
-          unless headers.respond_to?(:each)
-            log.warn("Auth::HMAC validation failed: Invalid headers object")
-            return false
-          end
+          # Security: Check raw headers and payload BEFORE processing
+          return false unless valid_headers?(headers)
+          return false unless valid_payload_size?(payload)
 
           signature_header = validator_config[:header]
 
@@ -107,23 +126,37 @@ module Hooks
             return false
           end
 
-          # Security: Reject signatures with leading/trailing whitespace
-          if raw_signature != raw_signature.strip
-            log.warn("Auth::HMAC validation failed: Signature contains leading/trailing whitespace")
-            return false
-          end
-
-          # Security: Reject signatures containing null bytes or other control characters
-          if raw_signature.match?(/[\u0000-\u001f\u007f-\u009f]/)
-            log.warn("Auth::HMAC validation failed: Signature contains control characters")
-            return false
-          end
+          # Validate signature format using shared validation but with HMAC-specific length limit
+          return false unless validate_signature_format(raw_signature)
 
           # Now we can safely normalize headers for the rest of the validation
           normalized_headers = normalize_headers(headers)
-          provided_signature = normalized_headers[signature_header.downcase]
+
+          # Handle structured headers (e.g., Tailscale format: "t=123,v1=abc")
+          if validator_config[:header_format] == "structured"
+            parsed_signature_data = parse_structured_header(raw_signature, validator_config)
+            if parsed_signature_data.nil?
+              log.warn("Auth::HMAC validation failed: Could not parse structured signature header")
+              return false
+            end
+
+            provided_signature = parsed_signature_data[:signature]
+
+            # For structured headers, timestamp comes from the signature header itself
+            if parsed_signature_data[:timestamp]
+              normalized_headers = normalized_headers.merge(
+                "extracted_timestamp" => parsed_signature_data[:timestamp]
+              )
+              # Override timestamp_header to use our extracted timestamp
+              validator_config = validator_config.merge(timestamp_header: "extracted_timestamp")
+            end
+          else
+            provided_signature = normalized_headers[signature_header.downcase]
+          end
 
           # Validate timestamp if required (for services that include timestamp validation)
+          # It should be noted that not all HMAC implementations require timestamp validation,
+          # so this is optional based on configuration.
           if validator_config[:timestamp_header]
             unless valid_timestamp?(normalized_headers, validator_config)
               log.warn("Auth::HMAC validation failed: Invalid timestamp")
@@ -154,6 +187,22 @@ module Hooks
 
         private
 
+        # Validate signature format for HMAC (uses HMAC-specific length limit)
+        #
+        # @param signature [String] Raw signature to validate
+        # @return [Boolean] true if signature is valid
+        # @api private
+        def self.validate_signature_format(signature)
+          # Check signature length with HMAC-specific limit
+          if signature.length > MAX_SIGNATURE_LENGTH
+            log.warn("Auth::HMAC validation failed: Signature length exceeds maximum limit of #{MAX_SIGNATURE_LENGTH} characters")
+            return false
+          end
+
+          # Use shared validation for other checks
+          valid_header_value?(signature, "Signature")
+        end
+
         # Build final configuration by merging defaults with provided config
         #
         # Combines default configuration values with user-provided settings,
@@ -176,7 +225,12 @@ module Hooks
             algorithm: algorithm,
             format: validator_config[:format] || DEFAULT_CONFIG[:format],
             version_prefix: validator_config[:version_prefix] || DEFAULT_CONFIG[:version_prefix],
-            payload_template: validator_config[:payload_template]
+            payload_template: validator_config[:payload_template],
+            header_format: validator_config[:header_format] || DEFAULT_CONFIG[:header_format],
+            signature_key: validator_config[:signature_key] || "v1",
+            timestamp_key: validator_config[:timestamp_key] || "t",
+            structured_header_separator: validator_config[:structured_header_separator] || ",",
+            key_value_separator: validator_config[:key_value_separator] || "="
           })
         end
 
@@ -216,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
@@ -321,6 +367,44 @@ module Hooks
             "#{config[:algorithm]}=#{hash}"
           end
         end
+
+        # Parse structured signature header containing comma-separated key-value pairs
+        #
+        # Parses signature headers like "t=1663781880,v1=0123456789abcdef..." used by
+        # providers like Tailscale that include multiple values in a single header.
+        #
+        # @param header_value [String] Raw signature header value
+        # @param config [Hash<Symbol, Object>] Validator configuration
+        # @return [Hash<Symbol, String>, nil] Parsed data with :signature and :timestamp keys, or nil if parsing fails
+        # @note Returns nil if the header format is invalid or required keys are missing
+        # @api private
+        def self.parse_structured_header(header_value, config)
+          signature_key = config[:signature_key]
+          timestamp_key = config[:timestamp_key]
+          separator = config[:structured_header_separator]
+          key_value_separator = config[:key_value_separator]
+
+          # Parse comma-separated key-value pairs
+          pairs = {}
+          header_value.split(separator).each do |pair|
+            key, value = pair.split(key_value_separator, 2)
+            return nil if key.nil? || value.nil?
+
+            pairs[key.strip] = value.strip
+          end
+
+          # Extract required signature
+          signature = pairs[signature_key]
+          return nil if signature.nil? || signature.empty?
+
+          result = { signature: signature }
+
+          # Extract optional timestamp
+          timestamp = pairs[timestamp_key]
+          result[:timestamp] = timestamp if timestamp && !timestamp.empty?
+
+          result
+        end
       end
     end
   end

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

@@ -61,11 +61,9 @@ module Hooks
 
           validator_config = build_config(config)
 
-          # Security: Check raw headers BEFORE normalization to detect tampering
-          unless headers.respond_to?(:each)
-            log.warn("Auth::SharedSecret validation failed: Invalid headers object")
-            return false
-          end
+          # Security: Check raw headers and payload BEFORE processing
+          return false unless valid_headers?(headers)
+          return false unless valid_payload_size?(payload)
 
           secret_header = validator_config[:header]
 
@@ -77,19 +75,13 @@ module Hooks
             return false
           end
 
-          stripped_secret = raw_secret.strip
-
-          # Security: Reject secrets with leading/trailing whitespace
-          if raw_secret != stripped_secret
-            log.warn("Auth::SharedSecret validation failed: Secret contains leading/trailing whitespace")
+          # Validate secret format using shared validation
+          unless valid_header_value?(raw_secret, "Secret")
+            log.warn("Auth::SharedSecret validation failed: Invalid secret format")
             return false
           end
 
-          # Security: Reject secrets containing null bytes or other control characters
-          if raw_secret.match?(/[\u0000-\u001f\u007f-\u009f]/)
-            log.warn("Auth::SharedSecret validation failed: Secret contains control characters")
-            return false
-          end
+          stripped_secret = raw_secret.strip
 
           # Use secure comparison to prevent timing attacks
           result = Rack::Utils.secure_compare(secret, stripped_secret)
@@ -106,12 +98,6 @@ module Hooks
 
         private
 
-        # Short logger accessor for auth module
-        # @return [Hooks::Log] Logger instance
-        def self.log
-          Hooks::Log.instance
-        end
-
         # Build final configuration by merging defaults with provided config
         #
         # Combines default configuration values with user-provided settings,

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.0".freeze
+  VERSION = "0.3.0".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hooks-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - github