hooks-ruby 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a1dfcc57a6bae5c2e5bd01f7e6165218220f04258ac8fab3ab256b685454bb6
-  data.tar.gz: 724dbe5463d5bf223ef9652e566b448f38a4270d0131446e302236685ba43710
+  metadata.gz: 47555e043e83129f208e5925c22dbbf12aadba0358a70272461952355251c869
+  data.tar.gz: b2760979c328b79cf82fe8b5a37a67261f2b5085208488ca928662e1915d9f06
 SHA512:
-  metadata.gz: d21c5cce4267f7d5209e495415c90b21375686e1f8d65d9d2080d3d3aa2677344a48cbc1167e4e83bff6a27223e6f12d891a6416ad122b54ee0d36832dd08311
-  data.tar.gz: 8b0fd57ee957d8eb8d58d3556f7f4ab145a7eb5cac82286c2cefd439a77bc28f6e03abe38484154b308b59b3b30e69bd749fec968fe053ebb0b4f9560ae0eb17
+  metadata.gz: 90b666eb68b986092e56e6db8140af3e6aae5b03a59e0e546beeee4a314a97ed75aaf4122687087cc58b258d88462a6fc5829339f56510e9d123f9b0d7c414ed
+  data.tar.gz: e50173bf684c3b458fe489667b05a65737658160c5a01603f7b8061419945fe41b07d04e61861524c8af5b445e2d63aa78b90ac1a3a07bb2fed481c50cc04406

data/README.md

@@ -58,7 +58,7 @@ Here is a very high-level overview of how Hooks works:
     ```ruby
     # file: plugins/handlers/my_custom_handler.rb
     class MyCustomHandler < Hooks::Plugins::Handlers::Base
-      def call(payload:, headers:, config:)
+      def call(payload:, headers:, env:, config:)
         # Process the incoming webhook - optionally use the payload and headers
         # to perform some action or validation
         # For this example, we will just return a success message
@@ -233,7 +233,7 @@ Create custom handler plugins in the `plugins/handlers` directory to process inc
 ```ruby
 # file: plugins/handlers/hello_handler.rb
 class HelloHandler < Hooks::Plugins::Handlers::Base
-  def call(payload:, headers:, config:)
+  def call(payload:, headers:, env:, config:)
     # Process the incoming webhook - optionally use the payload and headers
     # to perform some action or validation
     # For this example, we will just return a success message
@@ -251,7 +251,7 @@ And another handler plugin for the `/goodbye` endpoint:
 ```ruby
 # file: plugins/handlers/goodbye_handler.rb
 class GoodbyeHandler < Hooks::Plugins::Handlers::Base
-  def call(payload:, headers:, config:)
+  def call(payload:, headers:, env:, config:)
     # Ditto for the goodbye endpoint
     {
       message: "goodbye webhook processed successfully",

data/lib/hooks/app/api.rb

@@ -5,7 +5,9 @@ require "json"
 require "securerandom"
 require_relative "helpers"
 require_relative "auth/auth"
+require_relative "rack_env_builder"
 require_relative "../plugins/handlers/base"
+require_relative "../plugins/handlers/error"
 require_relative "../plugins/handlers/default"
 require_relative "../core/logger_factory"
 require_relative "../core/log"
@@ -65,41 +67,27 @@ module Hooks
               Core::LogContext.with(request_context) do
                 begin
                   # Build Rack environment for lifecycle hooks
-                  rack_env = {
-                    "REQUEST_METHOD" => request.request_method,
-                    "PATH_INFO" => request.path_info,
-                    "QUERY_STRING" => request.query_string,
-                    "HTTP_VERSION" => request.env["HTTP_VERSION"],
-                    "REQUEST_URI" => request.url,
-                    "SERVER_NAME" => request.env["SERVER_NAME"],
-                    "SERVER_PORT" => request.env["SERVER_PORT"],
-                    "CONTENT_TYPE" => request.content_type,
-                    "CONTENT_LENGTH" => request.content_length,
-                    "REMOTE_ADDR" => request.env["REMOTE_ADDR"],
-                    "hooks.request_id" => request_id,
-                    "hooks.handler" => handler_class_name,
-                    "hooks.endpoint_config" => endpoint_config,
-                    "hooks.start_time" => start_time.iso8601,
-                    "hooks.full_path" => full_path
-                  }
-
-                  # Add HTTP headers to environment
-                  headers.each do |key, value|
-                    env_key = "HTTP_#{key.upcase.tr('-', '_')}"
-                    rack_env[env_key] = value
-                  end
+                  rack_env_builder = RackEnvBuilder.new(
+                    request,
+                    headers,
+                    request_context,
+                    endpoint_config,
+                    start_time,
+                    full_path
+                  )
+                  rack_env = rack_env_builder.build
 
                   # Call lifecycle hooks: on_request
                   Core::PluginLoader.lifecycle_plugins.each do |plugin|
                     plugin.on_request(rack_env)
                   end
 
-                  enforce_request_limits(config)
+                  enforce_request_limits(config, request_context)
                   request.body.rewind
                   raw_body = request.body.read
 
                   if endpoint_config[:auth]
-                    validate_auth!(raw_body, headers, endpoint_config, config)
+                    validate_auth!(raw_body, headers, endpoint_config, config, request_context)
                   end
 
                   payload = parse_payload(raw_body, headers, symbolize: false)
@@ -109,6 +97,7 @@ module Hooks
                   response = handler.call(
                     payload:,
                     headers: processed_headers,
+                    env: rack_env,
                     config: endpoint_config
                   )
 
@@ -122,22 +111,50 @@ module Hooks
                   status 200
                   content_type "application/json"
                   response.to_json
+                rescue Hooks::Plugins::Handlers::Error => e
+                  # Handler called error! method - immediately return error response and exit the request
+                  log.debug("handler #{handler_class_name} called `error!` method")
+
+                  error_response = nil
+
+                  status e.status
+                  case e.body
+                  when String
+                    content_type "text/plain"
+                    error_response = e.body
+                  else
+                    content_type "application/json"
+                    error_response = e.body.to_json
+                  end
+
+                  return error_response
                 rescue StandardError => e
-                  # Call lifecycle hooks: on_error
+                  err_msg = "Error processing webhook event with handler: #{handler_class_name} - #{e.message} " \
+                    "- request_id: #{request_id} - path: #{full_path} - method: #{http_method} - " \
+                    "backtrace: #{e.backtrace.join("\n")}"
+                  log.error(err_msg)
+
+                  # call lifecycle hooks: on_error if the rack_env is available
+                  # if the rack_env is not available, it means the error occurred before we could build it
                   if defined?(rack_env)
                     Core::PluginLoader.lifecycle_plugins.each do |plugin|
                       plugin.on_error(e, rack_env)
                     end
                   end
 
-                  log.error("an error occuring during the processing of a webhook event - #{e.message}")
+                  # construct a standardized error response
                   error_response = {
-                    error: e.message,
-                    code: determine_error_code(e),
+                    error: "server_error",
+                    message: "an unexpected error occurred while processing the request",
                     request_id:
                   }
-                  error_response[:backtrace] = e.backtrace unless config[:production]
-                  status error_response[:code]
+
+                  # enrich the error response with details if not in production
+                  error_response[:backtrace] = e.backtrace.join("\n") unless config[:production]
+                  error_response[:message] = e.message unless config[:production]
+                  error_response[:handler] = handler_class_name unless config[:production]
+
+                  status determine_error_code(e)
                   content_type "application/json"
                   error_response.to_json
                 end

data/lib/hooks/app/auth/auth.rb

@@ -16,30 +16,45 @@ module Hooks
       # @param headers [Hash] The request headers.
       # @param endpoint_config [Hash] The endpoint configuration, must include :auth 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).
       # @raise [StandardError] Raises error if authentication fails or is misconfigured.
       # @return [void]
       # @note This method will halt execution with an error if authentication fails.
-      def validate_auth!(payload, headers, endpoint_config, global_config = {})
+      def validate_auth!(payload, headers, endpoint_config, global_config = {}, request_context = {})
         auth_config = endpoint_config[:auth]
+        request_id = request_context&.dig(:request_id)
 
         # Ensure auth type is present and valid
         auth_type = auth_config&.dig(:type)
         unless auth_type&.is_a?(String) && !auth_type.strip.empty?
-          error!("authentication configuration missing or invalid", 500)
+          log.error("authentication configuration missing or invalid - request_id: #{request_id}")
+          error!({
+            error: "authentication_configuration_error",
+            message: "authentication configuration missing or invalid",
+            request_id:
+          }, 500)
         end
 
         # Get auth plugin from loaded plugins registry (boot-time loaded only)
         begin
           auth_class = Core::PluginLoader.get_auth_plugin(auth_type)
         rescue => e
-          log.error("failed to load auth plugin '#{auth_type}': #{e.message}")
-          error!("unsupported auth type '#{auth_type}'", 400)
+          log.error("failed to load auth plugin '#{auth_type}': #{e.message} - request_id: #{request_id}")
+          error!({
+            error: "authentication_plugin_error",
+            message: "unsupported auth type '#{auth_type}'",
+            request_id:
+          }, 400)
         end
 
         log.debug("validating auth for request with auth_class: #{auth_class.name}")
         unless auth_class.valid?(payload:, headers:, config: endpoint_config)
-          log.warn("authentication failed for request with auth_class: #{auth_class.name}")
-          error!("authentication failed", 401)
+          log.warn("authentication failed for request with auth_class: #{auth_class.name} - request_id: #{request_id}")
+          error!({
+            error: "authentication_failed",
+            message: "authentication failed",
+            request_id:
+          }, 401)
         end
       end
 

data/lib/hooks/app/endpoints/catchall.rb

@@ -27,20 +27,36 @@ module Hooks
         # :nocov:
         proc do
           request_id = uuid
+          start_time = Time.now
 
           # Use captured values
           config = captured_config
           log = captured_logger
 
+          full_path = "#{config[:root_path]}/#{params[:path]}"
+
+          handler_class_name = "DefaultHandler"
+          http_method = "post"
+
           # Set request context for logging
           request_context = {
             request_id:,
-            path: "/#{params[:path]}",
-            handler: "DefaultHandler"
+            path: full_path,
+            handler: handler_class_name
           }
 
           Hooks::Core::LogContext.with(request_context) do
             begin
+              rack_env_builder = RackEnvBuilder.new(
+                request,
+                headers,
+                request_context,
+                config,
+                start_time,
+                full_path
+              )
+              rack_env = rack_env_builder.build
+
               # Enforce request limits
               enforce_request_limits(config)
 
@@ -58,32 +74,34 @@ module Hooks
               response = handler.call(
                 payload:,
                 headers:,
+                env: rack_env,
                 config: {}
               )
 
-              log.info "request processed successfully with default handler (id: #{request_id})"
-
-              # Return response as JSON string when using txt format
+              log.info("successfully processed webhook event with handler: #{handler_class_name}")
+              log.debug("processing duration: #{Time.now - start_time}s")
               status 200
               content_type "application/json"
-              (response || { status: "ok" }).to_json
-
+              response.to_json
             rescue StandardError => e
-              log.error "request failed: #{e.message} (id: #{request_id})"
+              err_msg = "Error processing webhook event with handler: #{handler_class_name} - #{e.message} " \
+                "- request_id: #{request_id} - path: #{full_path} - method: #{http_method} - " \
+                "backtrace: #{e.backtrace.join("\n")}"
+              log.error(err_msg)
 
-              # Return error response
+              # construct a standardized error response
               error_response = {
-                error: e.message,
-                code: determine_error_code(e),
-                request_id: request_id
+                error: "server_error",
+                message: "an unexpected error occurred while processing the request",
+                request_id:
               }
 
-              # Add backtrace in all environments except production
-              unless config[:production] == true
-                error_response[:backtrace] = e.backtrace
-              end
+              # enrich the error response with details if not in production
+              error_response[:backtrace] = e.backtrace.join("\n") unless config[:production]
+              error_response[:message] = e.message unless config[:production]
+              error_response[:handler] = handler_class_name unless config[:production]
 
-              status error_response[:code]
+              status determine_error_code(e)
               content_type "application/json"
               error_response.to_json
             end

data/lib/hooks/app/helpers.rb

@@ -17,10 +17,11 @@ module Hooks
       # Enforce request size and timeout limits
       #
       # @param config [Hash] The configuration hash, must include :request_limit
+      # @param request_context [Hash] Context for the request, e.g. request ID (optional)
       # @raise [StandardError] Halts with error if request body is too large
       # @return [void]
       # @note Timeout enforcement should be handled at the server level (e.g., Puma)
-      def enforce_request_limits(config)
+      def enforce_request_limits(config, request_context = {})
         # Optimized content length check - check most common sources first
         content_length = request.content_length if respond_to?(:request) && request.respond_to?(:content_length)
 
@@ -34,7 +35,8 @@ module Hooks
         content_length = content_length&.to_i
 
         if content_length && content_length > config[:request_limit]
-          error!("request body too large", 413)
+          request_id = request_context&.dig(:request_id)
+          error!({ error: "request_body_too_large", message: "request body too large", request_id: }, 413)
         end
 
         # Note: Timeout enforcement would typically be handled at the server level (Puma, etc.)
@@ -76,13 +78,14 @@ module Hooks
       # @return [Object] An instance of the loaded handler class
       # @raise [StandardError] If handler cannot be found
       def load_handler(handler_class_name)
-        # Get handler class from loaded plugins registry (boot-time loaded only)
-        begin
-          handler_class = Core::PluginLoader.get_handler_plugin(handler_class_name)
-          return handler_class.new
-        rescue => e
-          error!("failed to get handler '#{handler_class_name}': #{e.message}", 500)
-        end
+        # Get handler class from loaded plugins registry (the registry is populated at boot time)
+        # NOTE: We create a new instance per request (not reuse boot-time instances) because:
+        # - Security: Prevents state pollution and information leakage between requests
+        # - Thread Safety: Avoids race conditions from shared instance state
+        # - Performance: Handler instantiation is fast; reusing instances provides minimal gain
+        # - Memory: Allows garbage collection of short-lived objects (Ruby GC optimization)
+        handler_class = Core::PluginLoader.get_handler_plugin(handler_class_name)
+        return handler_class.new
       end
 
       private

data/lib/hooks/app/rack_env_builder.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Hooks
+  module App
+    # Builds Rack environment hash for lifecycle hooks and handler processing
+    #
+    # This class centralizes the construction of the Rack environment that gets
+    # passed to lifecycle hooks and handlers, ensuring consistency and making
+    # it easy to reference the environment structure.
+    #
+    # @example Building a Rack environment
+    #   builder = RackEnvBuilder.new(request, headers, request_context)
+    #   rack_env = builder.build
+    #
+    class RackEnvBuilder
+      # Initialize the builder with required components
+      #
+      # @param request [Grape::Request] The Grape request object
+      # @param headers [Hash] Request headers hash
+      # @param request_context [Hash] Request context containing metadata
+      # @option request_context [String] :request_id Unique request identifier
+      # @option request_context [String] :handler Handler class name
+      # @param endpoint_config [Hash] Endpoint configuration
+      # @param start_time [Time] Request start time
+      # @param full_path [String] Full request path including root path
+      def initialize(request, headers, request_context, endpoint_config, start_time, full_path)
+        @request = request
+        @headers = headers
+        @request_context = request_context
+        @endpoint_config = endpoint_config
+        @start_time = start_time
+        @full_path = full_path
+      end
+
+      # Build the Rack environment hash
+      #
+      # Constructs a hash containing standard Rack environment variables
+      # plus Hooks-specific extensions for lifecycle hooks and handlers.
+      #
+      # @return [Hash] Complete Rack environment hash
+      def build
+        rack_env = build_base_environment
+        add_http_headers(rack_env)
+        rack_env
+      end
+
+      private
+
+      # Build the base Rack environment with standard and Hooks-specific variables
+      # This pretty much creates everything plus the kitchen sink. It will be very rich in information
+      # and will be used by lifecycle hooks and handlers to access request metadata.
+      #
+      # @return [Hash] Base environment hash
+      def build_base_environment
+        {
+          "REQUEST_METHOD" => @request.request_method,
+          "PATH_INFO" => @request.path_info,
+          "QUERY_STRING" => @request.query_string,
+          "HTTP_VERSION" => @request.env["HTTP_VERSION"],
+          "REQUEST_URI" => @request.url,
+          "SERVER_NAME" => @request.env["SERVER_NAME"],
+          "SERVER_PORT" => @request.env["SERVER_PORT"],
+          "CONTENT_TYPE" => @request.content_type,
+          "CONTENT_LENGTH" => @request.content_length,
+          "REMOTE_ADDR" => @request.env["REMOTE_ADDR"],
+          "hooks.request_id" => @request_context[:request_id],
+          "hooks.handler" => @request_context[:handler],
+          "hooks.endpoint_config" => @endpoint_config,
+          "hooks.start_time" => @start_time.iso8601,
+          "hooks.full_path" => @full_path
+        }
+      end
+
+      # Add HTTP headers to the environment with proper Rack naming convention
+      #
+      # @param rack_env [Hash] Environment hash to modify
+      def add_http_headers(rack_env)
+        @headers.each do |key, value|
+          env_key = "HTTP_#{key.upcase.tr('-', '_')}"
+          rack_env[env_key] = value
+        end
+      end
+    end
+  end
+end

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/plugins/handlers/base.rb

@@ -2,6 +2,7 @@
 
 require_relative "../../core/global_components"
 require_relative "../../core/component_access"
+require_relative "error"
 
 module Hooks
   module Plugins
@@ -16,12 +17,35 @@ module Hooks
         #
         # @param payload [Hash, String] Parsed request body (JSON Hash) or raw string
         # @param headers [Hash] HTTP headers (string keys, optionally normalized - default is normalized)
+        # @param env [Hash] Rack environment (contains the request context, headers, etc - very rich context)
         # @param config [Hash] Merged endpoint configuration including opts section (symbolized keys)
         # @return [Hash, String, nil] Response body (will be auto-converted to JSON)
         # @raise [NotImplementedError] if not implemented by subclass
-        def call(payload:, headers:, config:)
+        def call(payload:, headers:, env:, config:)
           raise NotImplementedError, "Handler must implement #call method"
         end
+
+        # Terminate request processing with a custom error response
+        #
+        # This method provides the same interface as Grape's `error!` method,
+        # allowing handlers to immediately stop processing and return a specific
+        # error response to the client.
+        #
+        # @param body [Object] The error body/data to return to the client
+        # @param status [Integer] The HTTP status code to return (default: 500)
+        # @raise [Hooks::Plugins::Handlers::Error] Always raises to terminate processing
+        #
+        # @example Return a custom error with status 400
+        #   error!({ error: "validation_failed", message: "Invalid payload" }, 400)
+        #
+        # @example Return a simple string error with status 401
+        #   error!("Unauthorized", 401)
+        #
+        # @example Return an error with default 500 status
+        #   error!({ error: "internal_error", message: "Something went wrong" })
+        def error!(body, status = 500)
+          raise Error.new(body, status)
+        end
       end
     end
   end

data/lib/hooks/plugins/handlers/default.rb

@@ -20,6 +20,7 @@ class DefaultHandler < Hooks::Plugins::Handlers::Base
   #
   # @param payload [Hash, String] The webhook payload (parsed JSON or raw string)
   # @param headers [Hash<String, String>] HTTP headers from the webhook request
+  # @param env [Hash] Rack environment (contains the request context, headers, config, etc - very rich context)
   # @param config [Hash] Endpoint configuration containing handler options
   # @return [Hash] Response indicating successful processing
   # @option config [Hash] :opts Additional handler-specific configuration options
@@ -29,10 +30,11 @@ class DefaultHandler < Hooks::Plugins::Handlers::Base
   #   response = handler.call(
   #     payload: { "event" => "push" },
   #     headers: { "Content-Type" => "application/json" },
+  #     env: { "REQUEST_METHOD" => "POST", "hooks.request_id" => "12345" },
   #     config: { opts: {} }
   #   )
   #   # => { message: "webhook processed successfully", handler: "DefaultHandler", timestamp: "..." }
-  def call(payload:, headers:, config:)
+  def call(payload:, headers:, env:, config:)
 
     log.info("🔔 Default handler invoked for webhook 🔔")
 
@@ -41,6 +43,10 @@ class DefaultHandler < Hooks::Plugins::Handlers::Base
       log.debug("received payload: #{payload.inspect}")
     end
 
+    if env
+      log.debug("default handler got a request with the following request_id: #{env['hooks.request_id']}")
+    end
+
     {
       message: "webhook processed successfully",
       handler: "DefaultHandler",

data/lib/hooks/plugins/handlers/error.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Plugins
+    module Handlers
+      # Custom exception class for handler errors
+      #
+      # This exception is used when handlers call the `error!` method to
+      # immediately terminate request processing and return a specific error response.
+      # It carries the error details back to the Grape API context where it can be
+      # properly formatted and returned to the client.
+      #
+      # @example Usage in handler
+      #   error!({ error: "validation_failed", message: "Invalid payload" }, 400)
+      #
+      # @see Hooks::Plugins::Handlers::Base#error!
+      class Error < StandardError
+        # @return [Object] The error body/data to return to the client
+        attr_reader :body
+
+        # @return [Integer] The HTTP status code to return
+        attr_reader :status
+
+        # Initialize a new handler error
+        #
+        # @param body [Object] The error body/data to return to the client
+        # @param status [Integer] The HTTP status code to return (default: 500)
+        def initialize(body, status = 500)
+          @body = body
+          @status = status.to_i
+          super("Handler error: #{status} - #{body}")
+        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.1.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.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - github
@@ -129,6 +129,7 @@ files:
 - lib/hooks/app/endpoints/health.rb
 - lib/hooks/app/endpoints/version.rb
 - lib/hooks/app/helpers.rb
+- lib/hooks/app/rack_env_builder.rb
 - lib/hooks/core/builder.rb
 - lib/hooks/core/component_access.rb
 - lib/hooks/core/config_loader.rb
@@ -145,6 +146,7 @@ files:
 - lib/hooks/plugins/auth/timestamp_validator.rb
 - lib/hooks/plugins/handlers/base.rb
 - lib/hooks/plugins/handlers/default.rb
+- lib/hooks/plugins/handlers/error.rb
 - lib/hooks/plugins/instruments/failbot.rb
 - lib/hooks/plugins/instruments/failbot_base.rb
 - lib/hooks/plugins/instruments/stats.rb