hooks-ruby 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc9f23a8b74aef04b7a0016673a9dd835cef5f56eecb316e58b7cb3d19936f0d
-  data.tar.gz: '05290bf35da3f0aa73e5a0b9e0661d2986df03733862f6cd85c19248257f5b09'
+  metadata.gz: 2cab1bf1a1f61011d053be5beb9d48738bd439303b87743e41e10df0b4b9d65c
+  data.tar.gz: 9b9abc62fff8f0f2f77ad94949bc7e067fff5a2f072bbf73f8e6e55c03865714
 SHA512:
-  metadata.gz: a4462d77b184ac3be6b4a0f7ac4466dace8b5d146c722205ca7f97f455dc523de2168a71e2fe61b4a0946efdb7e9b8e4b61dc1e9940c8d14fdbaebebcb8fb497
-  data.tar.gz: bc2023bf7a08efd872e69603dd81dbbb2a4798deb4b4c98db37d65f8544ba57cfbdf36b82f2b48b33250d2429eb39946a71d65d7fbdf7c2d5e0a6b724e79a9cb
+  metadata.gz: 40f769a697bd61c6c851eef217fadc66387c49d37c19639a283dd770ca8be8889a13eeba2785a41c53edcdef29327231527405a9de21b2b4620416196da792c2
+  data.tar.gz: 119a371d927f240aefe4e74c822b48318032250e7cbf060a9bd077b1375823137b419f7d1e2d27d775e6468d38843afb45ec9c8cd8a71a22d82226160c66043e

data/README.md

@@ -66,7 +66,7 @@ Here is a very high-level overview of how Hooks works:
           status: "success",
           handler: "MyCustomHandler",
           payload_received: payload,
-          timestamp: Time.now.iso8601
+          timestamp: Time.now.utc.iso8601
         }
       end
     end
@@ -229,7 +229,7 @@ class HelloHandler < Hooks::Plugins::Handlers::Base
     {
       message: "webhook processed successfully",
       handler: "HelloHandler",
-      timestamp: Time.now.iso8601
+      timestamp: Time.now.utc.iso8601
     }
   end
 end
@@ -245,7 +245,7 @@ class GoodbyeHandler < Hooks::Plugins::Handlers::Base
     {
       message: "goodbye webhook processed successfully",
       handler: "GoodbyeHandler",
-      timestamp: Time.now.iso8601
+      timestamp: Time.now.utc.iso8601
     }
   end
 end
@@ -302,6 +302,10 @@ See the [Lifecycle Plugins](docs/lifecycle_plugins.md) documentation for informa
 
 See the [Instrument Plugins](docs/instrument_plugins.md) documentation for information on how to create instrument plugins that can be used to collect metrics or report exceptions during webhook processing. These plugins can be used to integrate with monitoring and alerting systems.
 
+### Configuration
+
+See the [Configuration](docs/configuration.md) documentation for detailed information on how to configure your Hooks server, including global options, endpoint options, and more.
+
 ## Contributing 🤝
 
 See the [Contributing](CONTRIBUTING.md) document for information on how to contribute to the Hooks project, including setting up your development environment, running tests, and releasing new versions.

data/lib/hooks/app/api.rb

@@ -27,6 +27,7 @@ module Hooks
 
       # Create a new configured API class
       def self.create(config:, endpoints:, log:)
+        # :nocov:
         @server_start_time = Time.now
 
         api_class = Class.new(Grape::API) do
@@ -47,8 +48,9 @@ module Hooks
           endpoints.each do |endpoint_config|
             full_path = "#{config[:root_path]}#{endpoint_config[:path]}"
             handler_class_name = endpoint_config[:handler]
+            http_method = (endpoint_config[:method] || "post").downcase.to_sym
 
-            post(full_path) do
+            send(http_method, full_path) do
               request_id = uuid
               start_time = Time.now
 
@@ -151,6 +153,7 @@ module Hooks
         end
 
         api_class
+        # :nocov:
       end
     end
   end

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

@@ -37,12 +37,8 @@ module Hooks
         end
 
         log.debug("validating auth for request with auth_class: #{auth_class.name}")
-
-        unless auth_class.valid?(
-          payload:,
-          headers:,
-          config: endpoint_config
-        )
+        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)
         end
       end

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

@@ -10,7 +10,7 @@ module Hooks
         content_type "application/json"
         {
           status: "healthy",
-          timestamp: Time.now.iso8601,
+          timestamp: Time.now.utc.iso8601,
           version: Hooks::VERSION,
           uptime_seconds: (Time.now - Hooks::App::API.server_start_time).to_i
         }.to_json

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

@@ -10,7 +10,7 @@ module Hooks
         content_type "application/json"
         {
           version: Hooks::VERSION,
-          timestamp: Time.now.iso8601
+          timestamp: Time.now.utc.iso8601
         }.to_json
       end
     end

data/lib/hooks/app/helpers.rb

@@ -21,13 +21,15 @@ module Hooks
       # @return [void]
       # @note Timeout enforcement should be handled at the server level (e.g., Puma)
       def enforce_request_limits(config)
-        # Check content length (handle different header formats and sources)
-        content_length = headers["Content-Length"] || headers["CONTENT_LENGTH"] ||
-                        headers["content-length"] || headers["HTTP_CONTENT_LENGTH"] ||
-                        env["CONTENT_LENGTH"] || env["HTTP_CONTENT_LENGTH"]
+        # Optimized content length check - check most common sources first
+        content_length = request.content_length if respond_to?(:request) && request.respond_to?(:content_length)
 
-        # Also try to get from request object directly
-        content_length ||= request.content_length if respond_to?(:request) && request.respond_to?(:content_length)
+        content_length ||= headers["Content-Length"] ||
+                          headers["CONTENT_LENGTH"] ||
+                          headers["content-length"] ||
+                          headers["HTTP_CONTENT_LENGTH"] ||
+                          env["CONTENT_LENGTH"] ||
+                          env["HTTP_CONTENT_LENGTH"]
 
         content_length = content_length&.to_i
 
@@ -45,16 +47,21 @@ module Hooks
       # @param symbolize [Boolean] Whether to symbolize keys in parsed JSON (default: true)
       # @return [Hash, String] Parsed JSON as Hash (optionally symbolized), or raw body if not JSON
       def parse_payload(raw_body, headers, symbolize: true)
+        # Optimized content type check - check most common header first
         content_type = headers["Content-Type"] || headers["CONTENT_TYPE"] || headers["content-type"] || headers["HTTP_CONTENT_TYPE"]
 
         # Try to parse as JSON if content type suggests it or if it looks like JSON
         if content_type&.include?("application/json") || (raw_body.strip.start_with?("{", "[") rescue false)
           begin
-            parsed_payload = JSON.parse(raw_body)
+            # Security: Limit JSON parsing depth and complexity to prevent JSON bombs
+            parsed_payload = safe_json_parse(raw_body)
             parsed_payload = parsed_payload.transform_keys(&:to_sym) if symbolize && parsed_payload.is_a?(Hash)
             return parsed_payload
-          rescue JSON::ParserError
-            # If JSON parsing fails, return raw body
+          rescue JSON::ParserError, ArgumentError => e
+            # If JSON parsing fails or security limits exceeded, return raw body
+            if e.message.include?("nesting") || e.message.include?("depth")
+              log.warn("JSON parsing limit exceeded: #{e.message}")
+            end
           end
         end
 
@@ -79,6 +86,29 @@ module Hooks
 
       private
 
+      # Safely parse JSON
+      #
+      # @param json_string [String] The JSON string to parse
+      # @return [Hash, Array] Parsed JSON object
+      # @raise [JSON::ParserError] If JSON is invalid
+      # @raise [ArgumentError] If security limits are exceeded
+      def safe_json_parse(json_string)
+        # Security limits for JSON parsing
+        max_nesting = ENV.fetch("JSON_MAX_NESTING", "20").to_i
+
+        # Additional size check before parsing
+        if json_string.length > ENV.fetch("JSON_MAX_SIZE", "10485760").to_i # 10MB default
+          raise ArgumentError, "JSON payload too large for parsing"
+        end
+
+        JSON.parse(json_string, {
+          max_nesting: max_nesting,
+          create_additions: false,  # Security: Disable object creation from JSON
+          object_class: Hash,       # Use plain Hash instead of custom classes
+          array_class: Array        # Use plain Array instead of custom classes
+        })
+      end
+
       # Determine HTTP error code from exception
       #
       # @param exception [Exception] The exception to map to an HTTP status code

data/lib/hooks/core/component_access.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Core
+    # Shared module providing access to global components (logger, stats, failbot)
+    #
+    # This module provides a consistent interface for accessing global components
+    # across all plugin types, eliminating code duplication and ensuring consistent
+    # behavior throughout the application.
+    #
+    # @example Usage in a class that needs instance methods
+    #   class MyHandler
+    #     include Hooks::Core::ComponentAccess
+    #
+    #     def process
+    #       log.info("Processing request")
+    #       stats.increment("requests.processed")
+    #       failbot.report("Error occurred") if error?
+    #     end
+    #   end
+    #
+    # @example Usage in a class that needs class methods
+    #   class MyValidator
+    #     extend Hooks::Core::ComponentAccess
+    #
+    #     def self.validate
+    #       log.info("Validating request")
+    #       stats.increment("requests.validated")
+    #     end
+    #   end
+    module ComponentAccess
+      # Short logger accessor
+      # @return [Hooks::Log] Logger instance for logging messages
+      #
+      # Provides a convenient way to log messages without needing
+      # to reference the full Hooks::Log namespace.
+      #
+      # @example Logging an error
+      #   log.error("Something went wrong")
+      def log
+        Hooks::Log.instance
+      end
+
+      # Global stats component accessor
+      # @return [Hooks::Plugins::Instruments::Stats] Stats instance for metrics reporting
+      #
+      # Provides access to the global stats component for reporting metrics
+      # to services like DataDog, New Relic, etc.
+      #
+      # @example Recording a metric
+      #   stats.increment("webhook.processed", { handler: "MyHandler" })
+      def stats
+        Hooks::Core::GlobalComponents.stats
+      end
+
+      # Global failbot component accessor
+      # @return [Hooks::Plugins::Instruments::Failbot] Failbot instance for error reporting
+      #
+      # Provides access to the global failbot component for reporting errors
+      # to services like Sentry, Rollbar, etc.
+      #
+      # @example Reporting an error
+      #   failbot.report("Something went wrong", { context: "additional info" })
+      def failbot
+        Hooks::Core::GlobalComponents.failbot
+      end
+    end
+  end
+end

data/lib/hooks/core/config_loader.rb

@@ -24,23 +24,39 @@ module Hooks
         normalize_headers: true
       }.freeze
 
+      SILENCE_CONFIG_LOADER_MESSAGES = ENV.fetch(
+        "HOOKS_SILENCE_CONFIG_LOADER_MESSAGES", "false"
+      ).downcase == "true".freeze
+
       # Load and merge configuration from various sources
       #
       # @param config_path [String, Hash] Path to config file or config hash
       # @return [Hash] Merged configuration
       def self.load(config_path: nil)
         config = DEFAULT_CONFIG.dup
+        overrides = []
 
         # Load from file if path provided
         if config_path.is_a?(String) && File.exist?(config_path)
           file_config = load_config_file(config_path)
-          config.merge!(file_config) if file_config
-        elsif config_path.is_a?(Hash)
-          config.merge!(config_path)
+          if file_config
+            overrides << "file config"
+            config.merge!(file_config)
+          end
         end
 
-        # Override with environment variables
-        config.merge!(load_env_config)
+        # Override with environment variables (before programmatic config)
+        env_config = load_env_config
+        if env_config.any?
+          overrides << "environment variables"
+          config.merge!(env_config)
+        end
+
+        # Programmatic config has highest priority
+        if config_path.is_a?(Hash)
+          overrides << "programmatic config"
+          config.merge!(config_path)
+        end
 
         # Convert string keys to symbols for consistency
         config = symbolize_keys(config)
@@ -51,6 +67,11 @@ module Hooks
           config[:production] = false
         end
 
+        # Log overrides if any were made
+        if overrides.any?
+          puts "INFO: Configuration overrides applied from: #{overrides.join(', ')}" unless SILENCE_CONFIG_LOADER_MESSAGES
+        end
+
         return config
       end
 
@@ -93,8 +114,9 @@ module Hooks
         end
 
         result
-      rescue => _e
-        # In production, we'd log this error
+      rescue => e
+        # Log this error with meaningful information
+        puts "ERROR: Failed to load config file '#{file_path}': #{e.message}" unless SILENCE_CONFIG_LOADER_MESSAGES
         nil
       end
 
@@ -105,8 +127,11 @@ module Hooks
         env_config = {}
 
         env_mappings = {
+          "HOOKS_HANDLER_DIR" => :handler_dir,
           "HOOKS_HANDLER_PLUGIN_DIR" => :handler_plugin_dir,
           "HOOKS_AUTH_PLUGIN_DIR" => :auth_plugin_dir,
+          "HOOKS_LIFECYCLE_PLUGIN_DIR" => :lifecycle_plugin_dir,
+          "HOOKS_INSTRUMENTS_PLUGIN_DIR" => :instruments_plugin_dir,
           "HOOKS_LOG_LEVEL" => :log_level,
           "HOOKS_REQUEST_LIMIT" => :request_limit,
           "HOOKS_REQUEST_TIMEOUT" => :request_timeout,
@@ -114,17 +139,24 @@ module Hooks
           "HOOKS_HEALTH_PATH" => :health_path,
           "HOOKS_VERSION_PATH" => :version_path,
           "HOOKS_ENVIRONMENT" => :environment,
-          "HOOKS_ENDPOINTS_DIR" => :endpoints_dir
+          "HOOKS_ENDPOINTS_DIR" => :endpoints_dir,
+          "HOOKS_USE_CATCHALL_ROUTE" => :use_catchall_route,
+          "HOOKS_SYMBOLIZE_PAYLOAD" => :symbolize_payload,
+          "HOOKS_NORMALIZE_HEADERS" => :normalize_headers,
+          "HOOKS_SOME_STRING_VAR" => :some_string_var # Added for test
         }
 
         env_mappings.each do |env_key, config_key|
           value = ENV[env_key]
           next unless value
 
-          # Convert numeric values
+          # Convert values to appropriate types
           case config_key
           when :request_limit, :request_timeout
             env_config[config_key] = value.to_i
+          when :use_catchall_route, :symbolize_payload, :normalize_headers
+            # Convert string to boolean
+            env_config[config_key] = %w[true 1 yes on].include?(value.downcase)
           else
             env_config[config_key] = value
           end

data/lib/hooks/core/config_validator.rb

@@ -34,6 +34,7 @@ module Hooks
       ENDPOINT_CONFIG_SCHEMA = Dry::Schema.Params do
         required(:path).filled(:string)
         required(:handler).filled(:string)
+        optional(:method).filled(:string, included_in?: %w[get post put patch delete head options])
 
         optional(:auth).hash do
           required(:type).filled(:string)

data/lib/hooks/core/log.rb

@@ -1,8 +1,23 @@
 # frozen_string_literal: true
 
 module Hooks
+  # Global logger accessor module
+  #
+  # Provides a singleton-like access pattern for the application logger.
+  # The logger instance is set during application initialization and can
+  # be accessed throughout the application lifecycle.
+  #
+  # @example Setting the logger instance
+  #   Hooks::Log.instance = Logger.new(STDOUT)
+  #
+  # @example Accessing the logger
+  #   Hooks::Log.instance.info("Application started")
   module Log
     class << self
+      # Get or set the global logger instance
+      # @return [Logger] The global logger instance
+      # @attr_reader instance [Logger] Current logger instance
+      # @attr_writer instance [Logger] Set the logger instance
       attr_accessor :instance
     end
   end

data/lib/hooks/core/plugin_loader.rb

@@ -123,7 +123,7 @@ module Hooks
           Dir.glob(File.join(auth_plugin_dir, "*.rb")).sort.each do |file_path|
             begin
               load_custom_auth_plugin(file_path, auth_plugin_dir)
-            rescue => e
+            rescue StandardError, SyntaxError => e
               raise StandardError, "Failed to load auth plugin from #{file_path}: #{e.message}"
             end
           end
@@ -139,7 +139,7 @@ module Hooks
           Dir.glob(File.join(handler_plugin_dir, "*.rb")).sort.each do |file_path|
             begin
               load_custom_handler_plugin(file_path, handler_plugin_dir)
-            rescue => e
+            rescue StandardError, SyntaxError => e
               raise StandardError, "Failed to load handler plugin from #{file_path}: #{e.message}"
             end
           end
@@ -155,7 +155,7 @@ module Hooks
           Dir.glob(File.join(lifecycle_plugin_dir, "*.rb")).sort.each do |file_path|
             begin
               load_custom_lifecycle_plugin(file_path, lifecycle_plugin_dir)
-            rescue => e
+            rescue StandardError, SyntaxError => e
               raise StandardError, "Failed to load lifecycle plugin from #{file_path}: #{e.message}"
             end
           end
@@ -171,7 +171,7 @@ module Hooks
           Dir.glob(File.join(instruments_plugin_dir, "*.rb")).sort.each do |file_path|
             begin
               load_custom_instrument_plugin(file_path, instruments_plugin_dir)
-            rescue => e
+            rescue StandardError, SyntaxError => e
               raise StandardError, "Failed to load instrument plugin from #{file_path}: #{e.message}"
             end
           end

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

@@ -3,6 +3,7 @@
 require "rack/utils"
 require_relative "../../core/log"
 require_relative "../../core/global_components"
+require_relative "../../core/component_access"
 
 module Hooks
   module Plugins
@@ -11,6 +12,8 @@ module Hooks
       #
       # All custom Auth plugins must inherit from this class
       class Base
+        extend Hooks::Core::ComponentAccess
+
         # Validate request
         #
         # @param payload [String] Raw request body
@@ -22,42 +25,6 @@ module Hooks
           raise NotImplementedError, "Validator must implement .valid? class method"
         end
 
-        # Short logger accessor for all subclasses
-        # @return [Hooks::Log] Logger instance for request validation
-        #
-        # Provides a convenient way for validators to log messages without needing
-        # to reference the full Hooks::Log namespace.
-        #
-        # @example Logging an error in an inherited class
-        #   log.error("oh no an error occured")
-        def self.log
-          Hooks::Log.instance
-        end
-
-        # Global stats component accessor
-        # @return [Hooks::Core::Stats] Stats instance for metrics reporting
-        #
-        # Provides access to the global stats component for reporting metrics
-        # to services like DataDog, New Relic, etc.
-        #
-        # @example Recording a metric in an inherited class
-        #   stats.increment("auth.validation", { plugin: "hmac" })
-        def self.stats
-          Hooks::Core::GlobalComponents.stats
-        end
-
-        # Global failbot component accessor
-        # @return [Hooks::Core::Failbot] Failbot instance for error reporting
-        #
-        # Provides access to the global failbot component for reporting errors
-        # to services like Sentry, Rollbar, etc.
-        #
-        # @example Reporting an error in an inherited class
-        #   failbot.report("Auth validation failed", { plugin: "hmac" })
-        def self.failbot
-          Hooks::Core::GlobalComponents.failbot
-        end
-
         # Retrieve the secret from the environment variable based on the key set in the configuration
         #
         # Note: This method is intended to be used by subclasses

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

@@ -3,6 +3,7 @@
 require "openssl"
 require "time"
 require_relative "base"
+require_relative "timestamp_validator"
 
 module Hooks
   module Plugins
@@ -39,6 +40,7 @@ module Hooks
         DEFAULT_CONFIG = {
           algorithm: "sha256",
           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
         }.freeze
@@ -117,7 +119,10 @@ module Hooks
 
           # Validate timestamp if required (for services that include timestamp validation)
           if validator_config[:timestamp_header]
-            return false unless valid_timestamp?(normalized_headers, validator_config)
+            unless valid_timestamp?(normalized_headers, validator_config)
+              log.warn("Auth::HMAC validation failed: Invalid timestamp")
+              return false
+            end
           end
 
           # Compute expected signature
@@ -153,7 +158,7 @@ module Hooks
           tolerance = validator_config[:timestamp_tolerance] || DEFAULT_CONFIG[:timestamp_tolerance]
 
           DEFAULT_CONFIG.merge({
-            header: validator_config[:header] || "X-Signature",
+            header: validator_config[:header] || DEFAULT_CONFIG[:header],
             timestamp_header: validator_config[:timestamp_header],
             timestamp_tolerance: tolerance,
             algorithm: algorithm,
@@ -180,6 +185,7 @@ module Hooks
         #
         # Checks if the provided timestamp is within the configured tolerance
         # of the current time. This prevents replay attacks using old requests.
+        # Supports both ISO 8601 UTC timestamps and Unix timestamps.
         #
         # @param headers [Hash<String, String>] Normalized HTTP headers
         # @param config [Hash<Symbol, Object>] Validator configuration
@@ -189,25 +195,21 @@ module Hooks
         # @api private
         def self.valid_timestamp?(headers, config)
           timestamp_header = config[:timestamp_header]
+          tolerance = config[:timestamp_tolerance] || 300
           return false unless timestamp_header
 
-          timestamp_header = timestamp_header.downcase
-          timestamp_value = headers[timestamp_header]
-
+          timestamp_value = headers[timestamp_header.downcase]
           return false unless timestamp_value
 
-          # Security: Strict timestamp validation - must be only digits with no leading zeros
-          return false unless timestamp_value.match?(/\A[1-9]\d*\z/) || timestamp_value == "0"
-
-          timestamp = timestamp_value.to_i
-
-          # Ensure timestamp is a positive integer (reject zero and negative)
-          return false unless timestamp > 0
-
-          current_time = Time.now.to_i
-          tolerance = config[:timestamp_tolerance]
+          timestamp_validator.valid?(timestamp_value, tolerance)
+        end
 
-          (current_time - timestamp).abs <= tolerance
+        # 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
@@ -257,7 +259,7 @@ module Hooks
         #   - {body}: Replaced with the raw payload
         # @example Template usage
         #   template: "{version}:{timestamp}:{body}"
-        #   result: "v0:1609459200:{"event":"push"}"
+        #   result: "v0:1609459200:{\"event\":\"push\"}"
         # @api private
         def self.build_signing_payload(payload:, headers:, config:)
           template = config[:payload_template]
@@ -287,7 +289,7 @@ module Hooks
         #   - :algorithm_prefixed: "sha256=abc123..." (GitHub style)
         #   - :hash_only: "abc123..." (Shopify style)
         #   - :version_prefixed: "v0=abc123..." (Slack style)
-        # @note Defaults to algorithm_prefixed format for unknown format styles
+        # @note Defaults to algorithm-prefixed format for unknown format styles
         # @api private
         def self.format_signature(hash, config)
           format_style = FORMATS[config[:format]]

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

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Hooks
+  module Plugins
+    module Auth
+      # Validates and parses timestamps for webhook authentication
+      #
+      # This class provides secure timestamp validation supporting both
+      # ISO 8601 UTC format and Unix timestamp format. It includes
+      # strict validation to prevent various injection attacks.
+      #
+      # @example Basic usage
+      #   validator = TimestampValidator.new
+      #   validator.valid?("1609459200", 300)  # => true/false
+      #   validator.parse("2021-01-01T00:00:00Z")  # => 1609459200
+      #
+      # @api private
+      class TimestampValidator
+        # Validate timestamp against current time with tolerance
+        #
+        # @param timestamp_value [String] The timestamp string to validate
+        # @param tolerance [Integer] Maximum age in seconds (default: 300)
+        # @return [Boolean] true if timestamp is valid and within tolerance
+        def valid?(timestamp_value, tolerance = 300)
+          return false if timestamp_value.nil? || timestamp_value.strip.empty?
+
+          parsed_timestamp = parse(timestamp_value.strip)
+          return false unless parsed_timestamp.is_a?(Integer)
+
+          now = Time.now.utc.to_i
+          (now - parsed_timestamp).abs <= tolerance
+        end
+
+        # Parse timestamp value supporting both ISO 8601 UTC and Unix formats
+        #
+        # @param timestamp_value [String] The timestamp string to parse
+        # @return [Integer, nil] Epoch seconds if parsing succeeds, nil otherwise
+        # @note Security: Strict validation prevents various injection attacks
+        def parse(timestamp_value)
+          return nil if invalid_characters?(timestamp_value)
+
+          parse_iso8601_timestamp(timestamp_value) || parse_unix_timestamp(timestamp_value)
+        end
+
+        private
+
+        # Check for control characters, whitespace, or null bytes
+        #
+        # @param timestamp_value [String] The timestamp to check
+        # @return [Boolean] true if contains invalid characters
+        def invalid_characters?(timestamp_value)
+          if timestamp_value =~ /[\u0000-\u001F\u007F-\u009F]/
+            log_warning("Timestamp contains invalid characters")
+            true
+          else
+            false
+          end
+        end
+
+        # Parse ISO 8601 UTC timestamp string (must have UTC indicator)
+        #
+        # @param timestamp_value [String] ISO 8601 timestamp string
+        # @return [Integer, nil] Epoch seconds if parsing succeeds, nil otherwise
+        def parse_iso8601_timestamp(timestamp_value)
+          # Handle space-separated format and convert to standard ISO format
+          if timestamp_value =~ /\A(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2}(?:\.\d+)?)(?: )\+0000\z/
+            timestamp_value = "#{$1}T#{$2}+00:00"
+          end
+
+          # Ensure the timestamp explicitly includes a UTC indicator
+          return nil unless timestamp_value =~ /(Z|\+00:00|\+0000)\z/
+          return nil unless iso8601_format?(timestamp_value)
+
+          parsed_time = parse_time_safely(timestamp_value)
+          return nil unless parsed_time&.utc_offset&.zero?
+
+          parsed_time.to_i
+        end
+
+        # Parse Unix timestamp string (must be positive integer, no leading zeros except for "0")
+        #
+        # @param timestamp_value [String] Unix timestamp string
+        # @return [Integer, nil] Epoch seconds if parsing succeeds, nil otherwise
+        def parse_unix_timestamp(timestamp_value)
+          return nil unless unix_format?(timestamp_value)
+
+          ts = timestamp_value.to_i
+          return nil if ts <= 0
+
+          ts
+        end
+
+        # Check if timestamp string looks like ISO 8601 format
+        #
+        # @param timestamp_value [String] The timestamp string to check
+        # @return [Boolean] true if it appears to be ISO 8601 format
+        def iso8601_format?(timestamp_value)
+          !!(timestamp_value =~ /\A\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(Z|\+00:00|\+0000)?\z/)
+        end
+
+        # Check if timestamp string looks like Unix timestamp format
+        #
+        # @param timestamp_value [String] The timestamp string to check
+        # @return [Boolean] true if it appears to be Unix timestamp format
+        def unix_format?(timestamp_value)
+          return true if timestamp_value == "0"
+          !!(timestamp_value =~ /\A[1-9]\d*\z/)
+        end
+
+        # Safely parse time string with error handling
+        #
+        # @param timestamp_value [String] The timestamp string to parse
+        # @return [Time, nil] Parsed time object or nil if parsing fails
+        def parse_time_safely(timestamp_value)
+          Time.parse(timestamp_value)
+        rescue ArgumentError
+          nil
+        end
+
+        # Log warning message
+        #
+        # @param message [String] Warning message to log
+        def log_warning(message)
+          return unless defined?(Hooks::Log) && Hooks::Log.instance
+
+          Hooks::Log.instance.warn("Auth::TimestampValidator validation failed: #{message}")
+        end
+      end
+    end
+  end
+end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../../core/global_components"
+require_relative "../../core/component_access"
 
 module Hooks
   module Plugins
@@ -9,6 +10,8 @@ module Hooks
       #
       # All custom handlers must inherit from this class and implement the #call method
       class Base
+        include Hooks::Core::ComponentAccess
+
         # Process a webhook request
         #
         # @param payload [Hash, String] Parsed request body (JSON Hash) or raw string
@@ -19,42 +22,6 @@ module Hooks
         def call(payload:, headers:, config:)
           raise NotImplementedError, "Handler must implement #call method"
         end
-
-        # Short logger accessor for all subclasses
-        # @return [Hooks::Log] Logger instance
-        #
-        # Provides a convenient way for handlers to log messages without needing
-        # to reference the full Hooks::Log namespace.
-        #
-        # @example Logging an error in an inherited class
-        #   log.error("oh no an error occured")
-        def log
-          Hooks::Log.instance
-        end
-
-        # Global stats component accessor
-        # @return [Hooks::Core::Stats] Stats instance for metrics reporting
-        #
-        # Provides access to the global stats component for reporting metrics
-        # to services like DataDog, New Relic, etc.
-        #
-        # @example Recording a metric in an inherited class
-        #   stats.increment("webhook.processed", { handler: "MyHandler" })
-        def stats
-          Hooks::Core::GlobalComponents.stats
-        end
-
-        # Global failbot component accessor
-        # @return [Hooks::Core::Failbot] Failbot instance for error reporting
-        #
-        # Provides access to the global failbot component for reporting errors
-        # to services like Sentry, Rollbar, etc.
-        #
-        # @example Reporting an error in an inherited class
-        #   failbot.report("Something went wrong", { handler: "MyHandler" })
-        def failbot
-          Hooks::Core::GlobalComponents.failbot
-        end
       end
     end
   end

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

@@ -1,8 +1,37 @@
 # frozen_string_literal: true
 
-# Default handler when no custom handler is found
-# This handler simply acknowledges receipt of the webhook and shows a few of the built-in features
+# Default webhook handler implementation
+#
+# This handler provides a basic webhook processing implementation that can be used
+# as a fallback when no custom handler is configured for an endpoint. It demonstrates
+# the standard handler interface and provides basic logging functionality.
+#
+# @example Usage in endpoint configuration
+#   handler:
+#     type: DefaultHandler
+#
+# @see Hooks::Plugins::Handlers::Base
 class DefaultHandler < Hooks::Plugins::Handlers::Base
+  # Process a webhook request with basic acknowledgment
+  #
+  # Provides a simple webhook processing implementation that logs the request
+  # and returns a standard acknowledgment response. This is useful for testing
+  # webhook endpoints or as a placeholder during development.
+  #
+  # @param payload [Hash, String] The webhook payload (parsed JSON or raw string)
+  # @param headers [Hash<String, String>] HTTP headers from the webhook request
+  # @param config [Hash] Endpoint configuration containing handler options
+  # @return [Hash] Response indicating successful processing
+  # @option config [Hash] :opts Additional handler-specific configuration options
+  #
+  # @example Basic usage
+  #   handler = DefaultHandler.new
+  #   response = handler.call(
+  #     payload: { "event" => "push" },
+  #     headers: { "Content-Type" => "application/json" },
+  #     config: { opts: {} }
+  #   )
+  #   # => { message: "webhook processed successfully", handler: "DefaultHandler", timestamp: "..." }
   def call(payload:, headers:, config:)
 
     log.info("🔔 Default handler invoked for webhook 🔔")
@@ -15,7 +44,7 @@ class DefaultHandler < Hooks::Plugins::Handlers::Base
     {
       message: "webhook processed successfully",
       handler: "DefaultHandler",
-      timestamp: Time.now.iso8601
+      timestamp: Time.now.utc.iso8601
     }
   end
 end

data/lib/hooks/plugins/instruments/failbot.rb

@@ -7,11 +7,25 @@ module Hooks
     module Instruments
       # Default failbot instrument implementation
       #
-      # This is a stub implementation that does nothing by default.
-      # Users can replace this with their own implementation for services
-      # like Sentry, Rollbar, etc.
+      # This is a no-op implementation that provides the error reporting interface
+      # without actually sending errors anywhere. It serves as a safe default when
+      # no custom error reporting implementation is configured.
+      #
+      # Users should replace this with their own implementation for services
+      # like Sentry, Rollbar, Honeybadger, etc.
+      #
+      # @example Replacing with a custom implementation
+      #   # In your application initialization:
+      #   custom_failbot = MySentryFailbotImplementation.new
+      #   Hooks::Core::GlobalComponents.failbot = custom_failbot
+      #
+      # @see Hooks::Plugins::Instruments::FailbotBase
+      # @see Hooks::Core::GlobalComponents
       class Failbot < FailbotBase
-        # Inherit from FailbotBase to provide a default implementation of the failbot instrument.
+        # Inherit from FailbotBase to provide a default no-op implementation
+        # of the error reporting instrument interface.
+        #
+        # All methods from FailbotBase are inherited and provide safe no-op behavior.
       end
     end
   end

data/lib/hooks/plugins/instruments/failbot_base.rb

@@ -1,23 +1,70 @@
 # frozen_string_literal: true
 
+require_relative "../../core/component_access"
+
 module Hooks
   module Plugins
     module Instruments
       # Base class for all failbot instrument plugins
       #
-      # All custom failbot implementations must inherit from this class and implement
-      # the required methods for error reporting.
+      # This class provides the foundation for implementing custom error reporting
+      # instruments. Subclasses should implement specific methods for their target
+      # error reporting service (Sentry, Rollbar, Honeybadger, etc.).
+      #
+      # @abstract Subclass and implement service-specific error reporting methods
+      # @example Implementing a custom failbot instrument
+      #   class MySentryFailbot < Hooks::Plugins::Instruments::FailbotBase
+      #     def report(error_or_message, context = {})
+      #       case error_or_message
+      #       when Exception
+      #         Sentry.capture_exception(error_or_message, extra: context)
+      #       else
+      #         Sentry.capture_message(error_or_message.to_s, extra: context)
+      #       end
+      #       log.debug("Reported error to Sentry")
+      #     end
+      #   end
+      #
+      # @see Hooks::Plugins::Instruments::Failbot
       class FailbotBase
-        # Short logger accessor for all subclasses
-        # @return [Hooks::Log] Logger instance
+        include Hooks::Core::ComponentAccess
+
+        # Report an error or message to the error tracking service
+        #
+        # This is a no-op implementation that subclasses should override
+        # to provide actual error reporting functionality.
+        #
+        # @param error_or_message [Exception, String] The error to report or message string
+        # @param context [Hash] Additional context information about the error
+        # @return [void]
+        # @note Subclasses should implement this method for their specific service
+        # @example Override in subclass
+        #   def report(error_or_message, context = {})
+        #     if error_or_message.is_a?(Exception)
+        #       ErrorService.report_exception(error_or_message, context)
+        #     else
+        #       ErrorService.report_message(error_or_message, context)
+        #     end
+        #   end
+        def report(error_or_message, context = {})
+          # No-op implementation for base class
+        end
+
+        # Report a warning-level message
         #
-        # Provides a convenient way for instruments to log messages without needing
-        # to reference the full Hooks::Log namespace.
+        # This is a no-op implementation that subclasses should override
+        # to provide actual warning reporting functionality.
         #
-        # @example Logging debug info in an inherited class
-        #   log.debug("Sending error to external service")
-        def log
-          Hooks::Log.instance
+        # @param message [String] Warning message to report
+        # @param context [Hash] Additional context information
+        # @return [void]
+        # @note Subclasses should implement this method for their specific service
+        # @example Override in subclass
+        #   def warn(message, context = {})
+        #     ErrorService.report_warning(message, context)
+        #   end
+        def warn(message, context = {})
+          # No-op implementation for base class
         end
       end
     end

data/lib/hooks/plugins/instruments/stats.rb

@@ -7,11 +7,25 @@ module Hooks
     module Instruments
       # Default stats instrument implementation
       #
-      # This is a stub implementation that does nothing by default.
-      # Users can replace this with their own implementation for services
-      # like DataDog, New Relic, etc.
+      # This is a no-op implementation that provides the stats interface without
+      # actually sending metrics anywhere. It serves as a safe default when no
+      # custom stats implementation is configured.
+      #
+      # Users should replace this with their own implementation for services
+      # like DataDog, New Relic, StatsD, etc.
+      #
+      # @example Replacing with a custom implementation
+      #   # In your application initialization:
+      #   custom_stats = MyCustomStatsImplementation.new
+      #   Hooks::Core::GlobalComponents.stats = custom_stats
+      #
+      # @see Hooks::Plugins::Instruments::StatsBase
+      # @see Hooks::Core::GlobalComponents
       class Stats < StatsBase
-        # Inherit from StatsBase to provide a default implementation of the stats instrument.
+        # Inherit from StatsBase to provide a default no-op implementation
+        # of the stats instrument interface.
+        #
+        # All methods from StatsBase are inherited and provide safe no-op behavior.
       end
     end
   end

data/lib/hooks/plugins/instruments/stats_base.rb

@@ -1,23 +1,86 @@
 # frozen_string_literal: true
 
+require_relative "../../core/component_access"
+
 module Hooks
   module Plugins
     module Instruments
       # Base class for all stats instrument plugins
       #
-      # All custom stats implementations must inherit from this class and implement
-      # the required methods for metrics reporting.
+      # This class provides the foundation for implementing custom metrics reporting
+      # instruments. Subclasses should implement specific methods for their target
+      # metrics service (DataDog, New Relic, StatsD, etc.).
+      #
+      # @abstract Subclass and implement service-specific metrics methods
+      # @example Implementing a custom stats instrument
+      #   class MyStatsImplementation < Hooks::Plugins::Instruments::StatsBase
+      #     def increment(metric_name, tags = {})
+      #       # Send increment metric to your service
+      #       MyMetricsService.increment(metric_name, tags)
+      #       log.debug("Sent increment metric: #{metric_name}")
+      #     end
+      #
+      #     def timing(metric_name, duration, tags = {})
+      #       # Send timing metric to your service
+      #       MyMetricsService.timing(metric_name, duration, tags)
+      #     end
+      #   end
+      #
+      # @see Hooks::Plugins::Instruments::Stats
       class StatsBase
-        # Short logger accessor for all subclasses
-        # @return [Hooks::Log] Logger instance
+        include Hooks::Core::ComponentAccess
+
+        # Record an increment metric
+        #
+        # This is a no-op implementation that subclasses should override
+        # to provide actual metrics reporting functionality.
+        #
+        # @param metric_name [String] Name of the metric to increment
+        # @param tags [Hash] Optional tags/labels for the metric
+        # @return [void]
+        # @note Subclasses should implement this method for their specific service
+        # @example Override in subclass
+        #   def increment(metric_name, tags = {})
+        #     statsd.increment(metric_name, tags: tags)
+        #   end
+        def increment(metric_name, tags = {})
+          # No-op implementation for base class
+        end
+
+        # Record a timing/duration metric
+        #
+        # This is a no-op implementation that subclasses should override
+        # to provide actual metrics reporting functionality.
+        #
+        # @param metric_name [String] Name of the timing metric
+        # @param duration [Numeric] Duration value (typically in milliseconds)
+        # @param tags [Hash] Optional tags/labels for the metric
+        # @return [void]
+        # @note Subclasses should implement this method for their specific service
+        # @example Override in subclass
+        #   def timing(metric_name, duration, tags = {})
+        #     statsd.timing(metric_name, duration, tags: tags)
+        #   end
+        def timing(metric_name, duration, tags = {})
+          # No-op implementation for base class
+        end
+
+        # Record a gauge metric
         #
-        # Provides a convenient way for instruments to log messages without needing
-        # to reference the full Hooks::Log namespace.
+        # This is a no-op implementation that subclasses should override
+        # to provide actual metrics reporting functionality.
         #
-        # @example Logging an error in an inherited class
-        #   log.error("Failed to send metric to external service")
-        def log
-          Hooks::Log.instance
+        # @param metric_name [String] Name of the gauge metric
+        # @param value [Numeric] Current value for the gauge
+        # @param tags [Hash] Optional tags/labels for the metric
+        # @return [void]
+        # @note Subclasses should implement this method for their specific service
+        # @example Override in subclass
+        #   def gauge(metric_name, value, tags = {})
+        #     statsd.gauge(metric_name, value, tags: tags)
+        #   end
+        def gauge(metric_name, value, tags = {})
+          # No-op implementation for base class
         end
       end
     end

data/lib/hooks/plugins/lifecycle.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../core/global_components"
+require_relative "../core/component_access"
 
 module Hooks
   module Plugins
@@ -8,6 +9,8 @@ module Hooks
     #
     # Plugins can hook into request/response/error lifecycle events
     class Lifecycle
+      include Hooks::Core::ComponentAccess
+
       # Called before handler execution
       #
       # @param env [Hash] Rack environment
@@ -30,42 +33,6 @@ module Hooks
       def on_error(exception, env)
         # Override in subclass for error handling logic
       end
-
-      # Short logger accessor for all subclasses
-      # @return [Hooks::Log] Logger instance
-      #
-      # Provides a convenient way for lifecycle plugins to log messages without needing
-      # to reference the full Hooks::Log namespace.
-      #
-      # @example Logging an error in an inherited class
-      #   log.error("oh no an error occured")
-      def log
-        Hooks::Log.instance
-      end
-
-      # Global stats component accessor
-      # @return [Hooks::Core::Stats] Stats instance for metrics reporting
-      #
-      # Provides access to the global stats component for reporting metrics
-      # to services like DataDog, New Relic, etc.
-      #
-      # @example Recording a metric in an inherited class
-      #   stats.increment("lifecycle.request_processed")
-      def stats
-        Hooks::Core::GlobalComponents.stats
-      end
-
-      # Global failbot component accessor
-      # @return [Hooks::Core::Failbot] Failbot instance for error reporting
-      #
-      # Provides access to the global failbot component for reporting errors
-      # to services like Sentry, Rollbar, etc.
-      #
-      # @example Reporting an error in an inherited class
-      #   failbot.report("Lifecycle hook failed")
-      def failbot
-        Hooks::Core::GlobalComponents.failbot
-      end
     end
   end
 end

data/lib/hooks/version.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# Main Hooks module containing version information
 module Hooks
-  VERSION = "0.0.3"
+  # Current version of the Hooks webhook framework
+  # @return [String] The version string following semantic versioning
+  VERSION = "0.0.4".freeze
 end

data/lib/hooks.rb

@@ -2,21 +2,29 @@
 
 require_relative "hooks/version"
 require_relative "hooks/core/builder"
-
-# Load all core components
-Dir[File.join(__dir__, "hooks/core/**/*.rb")].sort.each do |file|
-  require file
-end
-
-# Load all plugins (auth plugins, handler plugins, lifecycle hooks, etc.)
-Dir[File.join(__dir__, "hooks/plugins/**/*.rb")].sort.each do |file|
-  require file
-end
-
-# Load all utils
-Dir[File.join(__dir__, "hooks/utils/**/*.rb")].sort.each do |file|
-  require file
-end
+require_relative "hooks/core/config_loader"
+require_relative "hooks/core/config_validator"
+require_relative "hooks/core/logger_factory"
+require_relative "hooks/core/plugin_loader"
+require_relative "hooks/core/global_components"
+require_relative "hooks/core/component_access"
+require_relative "hooks/core/log"
+require_relative "hooks/core/failbot"
+require_relative "hooks/core/stats"
+require_relative "hooks/plugins/auth/base"
+require_relative "hooks/plugins/auth/hmac"
+require_relative "hooks/plugins/auth/shared_secret"
+require_relative "hooks/plugins/handlers/base"
+require_relative "hooks/plugins/handlers/default"
+require_relative "hooks/plugins/lifecycle"
+require_relative "hooks/plugins/instruments/stats_base"
+require_relative "hooks/plugins/instruments/failbot_base"
+require_relative "hooks/plugins/instruments/stats"
+require_relative "hooks/plugins/instruments/failbot"
+require_relative "hooks/utils/normalize"
+require_relative "hooks/utils/retry"
+require_relative "hooks/security"
+require_relative "hooks/version"
 
 # Main module for the Hooks webhook server framework
 module Hooks

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hooks-ruby
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - github
@@ -130,6 +130,7 @@ files:
 - lib/hooks/app/endpoints/version.rb
 - lib/hooks/app/helpers.rb
 - lib/hooks/core/builder.rb
+- lib/hooks/core/component_access.rb
 - lib/hooks/core/config_loader.rb
 - lib/hooks/core/config_validator.rb
 - lib/hooks/core/failbot.rb
@@ -141,6 +142,7 @@ files:
 - lib/hooks/plugins/auth/base.rb
 - lib/hooks/plugins/auth/hmac.rb
 - lib/hooks/plugins/auth/shared_secret.rb
+- lib/hooks/plugins/auth/timestamp_validator.rb
 - lib/hooks/plugins/handlers/base.rb
 - lib/hooks/plugins/handlers/default.rb
 - lib/hooks/plugins/instruments/failbot.rb