hooks-ruby 0.0.2 → 0.0.4

data/lib/hooks/core/failbot.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Core
+    # Global failbot component for error reporting
+    #
+    # This is a stub implementation that does nothing by default.
+    # Users can replace this with their own implementation for services
+    # like Sentry, Rollbar, etc.
+    class Failbot
+      # Report an error or exception
+      #
+      # @param error_or_message [Exception, String] Exception object or error message
+      # @param context [Hash] Optional context information
+      # @return [void]
+      def report(error_or_message, context = {})
+        # Override in subclass for actual error reporting
+      end
+
+      # Report a critical error
+      #
+      # @param error_or_message [Exception, String] Exception object or error message
+      # @param context [Hash] Optional context information
+      # @return [void]
+      def critical(error_or_message, context = {})
+        # Override in subclass for actual error reporting
+      end
+
+      # Report a warning
+      #
+      # @param message [String] Warning message
+      # @param context [Hash] Optional context information
+      # @return [void]
+      def warning(message, context = {})
+        # Override in subclass for actual warning reporting
+      end
+
+      # Capture an exception during block execution
+      #
+      # @param context [Hash] Optional context information
+      # @return [Object] Return value of the block
+      def capture(context = {})
+        yield
+      rescue => e
+        report(e, context)
+        raise
+      end
+    end
+  end
+end

data/lib/hooks/core/global_components.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Core
+    # Global registry for shared components accessible throughout the application
+    class GlobalComponents
+      @test_stats = nil
+      @test_failbot = nil
+
+      # Get the global stats instance
+      # @return [Hooks::Plugins::Instruments::StatsBase] Stats instance for metrics reporting
+      def self.stats
+        @test_stats || PluginLoader.get_instrument_plugin(:stats)
+      end
+
+      # Get the global failbot instance
+      # @return [Hooks::Plugins::Instruments::FailbotBase] Failbot instance for error reporting
+      def self.failbot
+        @test_failbot || PluginLoader.get_instrument_plugin(:failbot)
+      end
+
+      # Set a custom stats instance (for testing)
+      # @param stats_instance [Object] Custom stats instance
+      def self.stats=(stats_instance)
+        @test_stats = stats_instance
+      end
+
+      # Set a custom failbot instance (for testing)
+      # @param failbot_instance [Object] Custom failbot instance
+      def self.failbot=(failbot_instance)
+        @test_failbot = failbot_instance
+      end
+
+      # Reset components to default instances (for testing)
+      #
+      # @return [void]
+      def self.reset
+        @test_stats = nil
+        @test_failbot = nil
+        # Clear and reload default instruments
+        PluginLoader.clear_plugins
+        require_relative "../plugins/instruments/stats"
+        require_relative "../plugins/instruments/failbot"
+        PluginLoader.instance_variable_set(:@instrument_plugins, {
+          stats: Hooks::Plugins::Instruments::Stats.new,
+          failbot: Hooks::Plugins::Instruments::Failbot.new
+        })
+      end
+    end
+  end
+end

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

@@ -5,14 +5,16 @@ require_relative "../security"
 
 module Hooks
   module Core
-    # Loads and caches all plugins (auth + handlers) at boot time
+    # Loads and caches all plugins (auth + handlers + lifecycle + instruments) at boot time
     class PluginLoader
       # Class-level registries for loaded plugins
       @auth_plugins = {}
       @handler_plugins = {}
+      @lifecycle_plugins = []
+      @instrument_plugins = { stats: nil, failbot: nil }
 
       class << self
-        attr_reader :auth_plugins, :handler_plugins
+        attr_reader :auth_plugins, :handler_plugins, :lifecycle_plugins, :instrument_plugins
 
         # Load all plugins at boot time
         #
@@ -22,6 +24,8 @@ module Hooks
           # Clear existing registries
           @auth_plugins = {}
           @handler_plugins = {}
+          @lifecycle_plugins = []
+          @instrument_plugins = { stats: nil, failbot: nil }
 
           # Load built-in plugins first
           load_builtin_plugins
@@ -29,6 +33,11 @@ module Hooks
           # Load custom plugins if directories are configured
           load_custom_auth_plugins(config[:auth_plugin_dir]) if config[:auth_plugin_dir]
           load_custom_handler_plugins(config[:handler_plugin_dir]) if config[:handler_plugin_dir]
+          load_custom_lifecycle_plugins(config[:lifecycle_plugin_dir]) if config[:lifecycle_plugin_dir]
+          load_custom_instrument_plugins(config[:instruments_plugin_dir]) if config[:instruments_plugin_dir]
+
+          # Load default instruments if no custom ones were loaded
+          load_default_instruments
 
           # Log loaded plugins
           log_loaded_plugins
@@ -65,12 +74,29 @@ module Hooks
           plugin_class
         end
 
+        # Get instrument plugin instance by type
+        #
+        # @param instrument_type [Symbol] Type of instrument (:stats or :failbot)
+        # @return [Object] The instrument plugin instance
+        # @raise [StandardError] if instrument not found
+        def get_instrument_plugin(instrument_type)
+          instrument_instance = @instrument_plugins[instrument_type]
+
+          unless instrument_instance
+            raise StandardError, "Instrument plugin '#{instrument_type}' not found"
+          end
+
+          instrument_instance
+        end
+
         # Clear all loaded plugins (for testing purposes)
         #
         # @return [void]
         def clear_plugins
           @auth_plugins = {}
           @handler_plugins = {}
+          @lifecycle_plugins = []
+          @instrument_plugins = { stats: nil, failbot: nil }
         end
 
         private
@@ -97,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
@@ -113,12 +139,44 @@ 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
         end
 
+        # Load custom lifecycle plugins from directory
+        #
+        # @param lifecycle_plugin_dir [String] Directory containing custom lifecycle plugins
+        # @return [void]
+        def load_custom_lifecycle_plugins(lifecycle_plugin_dir)
+          return unless lifecycle_plugin_dir && Dir.exist?(lifecycle_plugin_dir)
+
+          Dir.glob(File.join(lifecycle_plugin_dir, "*.rb")).sort.each do |file_path|
+            begin
+              load_custom_lifecycle_plugin(file_path, lifecycle_plugin_dir)
+            rescue StandardError, SyntaxError => e
+              raise StandardError, "Failed to load lifecycle plugin from #{file_path}: #{e.message}"
+            end
+          end
+        end
+
+        # Load custom instrument plugins from directory
+        #
+        # @param instruments_plugin_dir [String] Directory containing custom instrument plugins
+        # @return [void]
+        def load_custom_instrument_plugins(instruments_plugin_dir)
+          return unless instruments_plugin_dir && Dir.exist?(instruments_plugin_dir)
+
+          Dir.glob(File.join(instruments_plugin_dir, "*.rb")).sort.each do |file_path|
+            begin
+              load_custom_instrument_plugin(file_path, instruments_plugin_dir)
+            rescue StandardError, SyntaxError => e
+              raise StandardError, "Failed to load instrument plugin from #{file_path}: #{e.message}"
+            end
+          end
+        end
+
         # Load a single custom auth plugin file
         #
         # @param file_path [String] Path to the auth plugin file
@@ -189,6 +247,90 @@ module Hooks
           @handler_plugins[class_name] = handler_class
         end
 
+        # Load a single custom lifecycle plugin file
+        #
+        # @param file_path [String] Path to the lifecycle plugin file
+        # @param lifecycle_plugin_dir [String] Base directory for lifecycle plugins
+        # @return [void]
+        def load_custom_lifecycle_plugin(file_path, lifecycle_plugin_dir)
+          # Security: Ensure the file path doesn't escape the lifecycle plugin directory
+          normalized_lifecycle_dir = Pathname.new(File.expand_path(lifecycle_plugin_dir))
+          normalized_file_path = Pathname.new(File.expand_path(file_path))
+          unless normalized_file_path.descend.any? { |path| path == normalized_lifecycle_dir }
+            raise SecurityError, "Lifecycle plugin path outside of lifecycle plugin directory: #{file_path}"
+          end
+
+          # Extract class name from file (e.g., logging_lifecycle.rb -> LoggingLifecycle)
+          file_name = File.basename(file_path, ".rb")
+          class_name = file_name.split("_").map(&:capitalize).join("")
+
+          # Security: Validate class name
+          unless valid_lifecycle_class_name?(class_name)
+            raise StandardError, "Invalid lifecycle plugin class name: #{class_name}"
+          end
+
+          # Load the file
+          require file_path
+
+          # Get the class and validate it
+          lifecycle_class = Object.const_get(class_name)
+          unless lifecycle_class < Hooks::Plugins::Lifecycle
+            raise StandardError, "Lifecycle plugin class must inherit from Hooks::Plugins::Lifecycle: #{class_name}"
+          end
+
+          # Register the plugin instance
+          @lifecycle_plugins << lifecycle_class.new
+        end
+
+        # Load a single custom instrument plugin file
+        #
+        # @param file_path [String] Path to the instrument plugin file
+        # @param instruments_plugin_dir [String] Base directory for instrument plugins
+        # @return [void]
+        def load_custom_instrument_plugin(file_path, instruments_plugin_dir)
+          # Security: Ensure the file path doesn't escape the instruments plugin directory
+          normalized_instruments_dir = Pathname.new(File.expand_path(instruments_plugin_dir))
+          normalized_file_path = Pathname.new(File.expand_path(file_path))
+          unless normalized_file_path.descend.any? { |path| path == normalized_instruments_dir }
+            raise SecurityError, "Instrument plugin path outside of instruments plugin directory: #{file_path}"
+          end
+
+          # Extract class name from file (e.g., custom_stats.rb -> CustomStats)
+          file_name = File.basename(file_path, ".rb")
+          class_name = file_name.split("_").map(&:capitalize).join("")
+
+          # Security: Validate class name
+          unless valid_instrument_class_name?(class_name)
+            raise StandardError, "Invalid instrument plugin class name: #{class_name}"
+          end
+
+          # Load the file
+          require file_path
+
+          # Get the class and validate it
+          instrument_class = Object.const_get(class_name)
+
+          # Determine instrument type based on inheritance
+          if instrument_class < Hooks::Plugins::Instruments::StatsBase
+            @instrument_plugins[:stats] = instrument_class.new
+          elsif instrument_class < Hooks::Plugins::Instruments::FailbotBase
+            @instrument_plugins[:failbot] = instrument_class.new
+          else
+            raise StandardError, "Instrument plugin class must inherit from StatsBase or FailbotBase: #{class_name}"
+          end
+        end
+
+        # Load default instrument implementations if no custom ones were loaded
+        #
+        # @return [void]
+        def load_default_instruments
+          require_relative "../plugins/instruments/stats"
+          require_relative "../plugins/instruments/failbot"
+
+          @instrument_plugins[:stats] ||= Hooks::Plugins::Instruments::Stats.new
+          @instrument_plugins[:failbot] ||= Hooks::Plugins::Instruments::Failbot.new
+        end
+
         # Log summary of loaded plugins
         #
         # @return [void]
@@ -201,6 +343,8 @@ module Hooks
 
           log.info "Loaded #{@auth_plugins.size} auth plugins: #{@auth_plugins.keys.join(', ')}"
           log.info "Loaded #{@handler_plugins.size} handler plugins: #{@handler_plugins.keys.join(', ')}"
+          log.info "Loaded #{@lifecycle_plugins.size} lifecycle plugins"
+          log.info "Loaded instruments: #{@instrument_plugins.keys.select { |k| @instrument_plugins[k] }.join(', ')}"
         end
 
         # Validate that an auth plugin class name is safe to load
@@ -244,6 +388,48 @@ module Hooks
 
           true
         end
+
+        # Validate that a lifecycle plugin class name is safe to load
+        #
+        # @param class_name [String] The class name to validate
+        # @return [Boolean] true if the class name is safe, false otherwise
+        def valid_lifecycle_class_name?(class_name)
+          # Must be a string
+          return false unless class_name.is_a?(String)
+
+          # Must not be empty or only whitespace
+          return false if class_name.strip.empty?
+
+          # Must match a safe pattern: alphanumeric + underscore, starting with uppercase
+          # Examples: LoggingLifecycle, MetricsLifecycle, CustomLifecycle
+          return false unless class_name.match?(/\A[A-Z][a-zA-Z0-9_]*\z/)
+
+          # Must not be a system/built-in class name
+          return false if Hooks::Security::DANGEROUS_CLASSES.include?(class_name)
+
+          true
+        end
+
+        # Validate that an instrument plugin class name is safe to load
+        #
+        # @param class_name [String] The class name to validate
+        # @return [Boolean] true if the class name is safe, false otherwise
+        def valid_instrument_class_name?(class_name)
+          # Must be a string
+          return false unless class_name.is_a?(String)
+
+          # Must not be empty or only whitespace
+          return false if class_name.strip.empty?
+
+          # Must match a safe pattern: alphanumeric + underscore, starting with uppercase
+          # Examples: CustomStats, CustomFailbot, DatadogStats
+          return false unless class_name.match?(/\A[A-Z][a-zA-Z0-9_]*\z/)
+
+          # Must not be a system/built-in class name
+          return false if Hooks::Security::DANGEROUS_CLASSES.include?(class_name)
+
+          true
+        end
       end
     end
   end

data/lib/hooks/core/stats.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Core
+    # Global stats component for metrics reporting
+    #
+    # 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.
+    class Stats
+      # Record a metric
+      #
+      # @param metric_name [String] Name of the metric
+      # @param value [Numeric] Value to record
+      # @param tags [Hash] Optional tags/labels for the metric
+      # @return [void]
+      def record(metric_name, value, tags = {})
+        # Override in subclass for actual metrics reporting
+      end
+
+      # Increment a counter
+      #
+      # @param metric_name [String] Name of the counter
+      # @param tags [Hash] Optional tags/labels for the metric
+      # @return [void]
+      def increment(metric_name, tags = {})
+        # Override in subclass for actual metrics reporting
+      end
+
+      # Record a timing metric
+      #
+      # @param metric_name [String] Name of the timing metric
+      # @param duration [Numeric] Duration in seconds
+      # @param tags [Hash] Optional tags/labels for the metric
+      # @return [void]
+      def timing(metric_name, duration, tags = {})
+        # Override in subclass for actual metrics reporting
+      end
+
+      # Measure execution time of a block
+      #
+      # @param metric_name [String] Name of the timing metric
+      # @param tags [Hash] Optional tags/labels for the metric
+      # @return [Object] Return value of the block
+      def measure(metric_name, tags = {})
+        start_time = Time.now
+        result = yield
+        duration = Time.now - start_time
+        timing(metric_name, duration, tags)
+        result
+      end
+    end
+  end
+end

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

@@ -2,6 +2,8 @@
 
 require "rack/utils"
 require_relative "../../core/log"
+require_relative "../../core/global_components"
+require_relative "../../core/component_access"
 
 module Hooks
   module Plugins
@@ -10,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
@@ -21,18 +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
-
         # 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]]