hooks-ruby 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae1757617b84df588de7eb343799b93d1dfc6326c3d54ab1a2d578aa2d3e3b8e
-  data.tar.gz: a39cfa8162346d536ab5a543dfcf7517162282ba3a74098cd276bc76c636a41c
+  metadata.gz: 47555e043e83129f208e5925c22dbbf12aadba0358a70272461952355251c869
+  data.tar.gz: b2760979c328b79cf82fe8b5a37a67261f2b5085208488ca928662e1915d9f06
 SHA512:
-  metadata.gz: da5353fda88b8d348e7b743e155642376ad886b5e77a38cb08148a9a6fbb5bece88c099125bb4738d41a09e3d3e0b5c29bd317bafa3789caa595d02f1c7217a2
-  data.tar.gz: 0ba9c613e80a889da7b1fd7b6b4b84b53190aae6db27184d7caa0a90806c3d266f0fff06c4bff1cef702c0879f772056fde5c1b697d817852130167eb0724ebd
+  metadata.gz: 90b666eb68b986092e56e6db8140af3e6aae5b03a59e0e546beeee4a314a97ed75aaf4122687087cc58b258d88462a6fc5829339f56510e9d123f9b0d7c414ed
+  data.tar.gz: e50173bf684c3b458fe489667b05a65737658160c5a01603f7b8061419945fe41b07d04e61861524c8af5b445e2d63aa78b90ac1a3a07bb2fed481c50cc04406

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

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

@@ -14,6 +14,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
@@ -67,6 +71,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

@@ -32,7 +32,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 +58,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 +92,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 +113,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 +127,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 +188,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 +226,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
 
@@ -321,6 +376,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.2.1".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.2.1
 platform: ruby
 authors:
 - github