hooks-ruby 0.0.2

data/lib/hooks/core/plugin_loader.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "../security"
+
+module Hooks
+  module Core
+    # Loads and caches all plugins (auth + handlers) at boot time
+    class PluginLoader
+      # Class-level registries for loaded plugins
+      @auth_plugins = {}
+      @handler_plugins = {}
+
+      class << self
+        attr_reader :auth_plugins, :handler_plugins
+
+        # Load all plugins at boot time
+        #
+        # @param config [Hash] Global configuration containing plugin directories
+        # @return [void]
+        def load_all_plugins(config)
+          # Clear existing registries
+          @auth_plugins = {}
+          @handler_plugins = {}
+
+          # Load built-in plugins first
+          load_builtin_plugins
+
+          # 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]
+
+          # Log loaded plugins
+          log_loaded_plugins
+        end
+
+        # Get auth plugin class by name
+        #
+        # @param plugin_name [String] Name of the auth plugin (e.g., "hmac", "shared_secret", "custom_auth")
+        # @return [Class] The auth plugin class
+        # @raise [StandardError] if plugin not found
+        def get_auth_plugin(plugin_name)
+          plugin_key = plugin_name.downcase
+          plugin_class = @auth_plugins[plugin_key]
+
+          unless plugin_class
+            raise StandardError, "Auth plugin '#{plugin_name}' not found. Available plugins: #{@auth_plugins.keys.join(', ')}"
+          end
+
+          plugin_class
+        end
+
+        # Get handler plugin class by name
+        #
+        # @param handler_name [String] Name of the handler (e.g., "DefaultHandler", "Team1Handler")
+        # @return [Class] The handler plugin class
+        # @raise [StandardError] if handler not found
+        def get_handler_plugin(handler_name)
+          plugin_class = @handler_plugins[handler_name]
+
+          unless plugin_class
+            raise StandardError, "Handler plugin '#{handler_name}' not found. Available handlers: #{@handler_plugins.keys.join(', ')}"
+          end
+
+          plugin_class
+        end
+
+        # Clear all loaded plugins (for testing purposes)
+        #
+        # @return [void]
+        def clear_plugins
+          @auth_plugins = {}
+          @handler_plugins = {}
+        end
+
+        private
+
+        # Load built-in plugins into registries
+        #
+        # @return [void]
+        def load_builtin_plugins
+          # Load built-in auth plugins
+          @auth_plugins["hmac"] = Hooks::Plugins::Auth::HMAC
+          @auth_plugins["shared_secret"] = Hooks::Plugins::Auth::SharedSecret
+
+          # Load built-in handler plugins
+          @handler_plugins["DefaultHandler"] = DefaultHandler
+        end
+
+        # Load custom auth plugins from directory
+        #
+        # @param auth_plugin_dir [String] Directory containing custom auth plugins
+        # @return [void]
+        def load_custom_auth_plugins(auth_plugin_dir)
+          return unless auth_plugin_dir && Dir.exist?(auth_plugin_dir)
+
+          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
+              raise StandardError, "Failed to load auth plugin from #{file_path}: #{e.message}"
+            end
+          end
+        end
+
+        # Load custom handler plugins from directory
+        #
+        # @param handler_plugin_dir [String] Directory containing custom handler plugins
+        # @return [void]
+        def load_custom_handler_plugins(handler_plugin_dir)
+          return unless handler_plugin_dir && Dir.exist?(handler_plugin_dir)
+
+          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
+              raise StandardError, "Failed to load handler 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
+        # @param auth_plugin_dir [String] Base directory for auth plugins
+        # @return [void]
+        def load_custom_auth_plugin(file_path, auth_plugin_dir)
+          # Security: Ensure the file path doesn't escape the auth plugin directory
+          normalized_auth_plugin_dir = Pathname.new(File.expand_path(auth_plugin_dir))
+          normalized_file_path = Pathname.new(File.expand_path(file_path))
+          unless normalized_file_path.descend.any? { |path| path == normalized_auth_plugin_dir }
+            raise SecurityError, "Auth plugin path outside of auth plugin directory: #{file_path}"
+          end
+
+          # Extract plugin name from file (e.g., custom_auth.rb -> CustomAuth)
+          file_name = File.basename(file_path, ".rb")
+          class_name = file_name.split("_").map(&:capitalize).join("")
+
+          # Security: Validate class name
+          unless valid_auth_plugin_class_name?(class_name)
+            raise StandardError, "Invalid auth plugin class name: #{class_name}"
+          end
+
+          # Load the file
+          require file_path
+
+          # Get the class and validate it
+          auth_plugin_class = Object.const_get("Hooks::Plugins::Auth::#{class_name}")
+          unless auth_plugin_class < Hooks::Plugins::Auth::Base
+            raise StandardError, "Auth plugin class must inherit from Hooks::Plugins::Auth::Base: #{class_name}"
+          end
+
+          # Register the plugin (using the file_name as the key for lookup)
+          @auth_plugins[file_name] = auth_plugin_class
+        end
+
+        # Load a single custom handler plugin file
+        #
+        # @param file_path [String] Path to the handler plugin file
+        # @param handler_plugin_dir [String] Base directory for handler plugins
+        # @return [void]
+        def load_custom_handler_plugin(file_path, handler_plugin_dir)
+          # Security: Ensure the file path doesn't escape the handler plugin directory
+          normalized_handler_dir = Pathname.new(File.expand_path(handler_plugin_dir))
+          normalized_file_path = Pathname.new(File.expand_path(file_path))
+          unless normalized_file_path.descend.any? { |path| path == normalized_handler_dir }
+            raise SecurityError, "Handler plugin path outside of handler plugin directory: #{file_path}"
+          end
+
+          # Extract class name from file (e.g., team1_handler.rb -> Team1Handler)
+          file_name = File.basename(file_path, ".rb")
+          class_name = file_name.split("_").map(&:capitalize).join("")
+
+          # Security: Validate class name
+          unless valid_handler_class_name?(class_name)
+            raise StandardError, "Invalid handler class name: #{class_name}"
+          end
+
+          # Load the file
+          require file_path
+
+          # Get the class and validate it
+          handler_class = Object.const_get(class_name)
+          unless handler_class < Hooks::Plugins::Handlers::Base
+            raise StandardError, "Handler class must inherit from Hooks::Plugins::Handlers::Base: #{class_name}"
+          end
+
+          # Register the handler (using the class name as the key for lookup)
+          @handler_plugins[class_name] = handler_class
+        end
+
+        # Log summary of loaded plugins
+        #
+        # @return [void]
+        def log_loaded_plugins
+          return unless defined?(Hooks::Log) && Hooks::Log.instance
+
+          log = Hooks::Log.instance
+          # Skip logging if the logger is a test double (class name contains "Double")
+          return if log.class.name.include?("Double")
+
+          log.info "Loaded #{@auth_plugins.size} auth plugins: #{@auth_plugins.keys.join(', ')}"
+          log.info "Loaded #{@handler_plugins.size} handler plugins: #{@handler_plugins.keys.join(', ')}"
+        end
+
+        # Validate that an auth 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_auth_plugin_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: MyAuthPlugin, SomeCoolAuthPlugin, CustomAuth
+          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 a handler 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_handler_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: MyHandler, Team1Handler, GitHubHandler
+          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
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "rack/utils"
+require_relative "../../core/log"
+
+module Hooks
+  module Plugins
+    module Auth
+      # Abstract base class for request validators via authentication
+      #
+      # All custom Auth plugins must inherit from this class
+      class Base
+        # Validate request
+        #
+        # @param payload [String] Raw request body
+        # @param headers [Hash<String, String>] HTTP headers
+        # @param config [Hash] Endpoint configuration
+        # @return [Boolean] true if request is valid
+        # @raise [NotImplementedError] if not implemented by subclass
+        def self.valid?(payload:, headers:, config:)
+          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
+        # It is a helper method and may not work with all authentication types
+        #
+        # @param config [Hash] Configuration hash containing :auth key
+        # @param secret_env_key [Symbol] The key to look up in the config for the environment variable name
+        # @return [String] The secret
+        # @raise [StandardError] if secret_env_key is missing or empty
+        def self.fetch_secret(config, secret_env_key_name: :secret_env_key)
+          secret_env_key = config.dig(:auth, secret_env_key_name)
+          if secret_env_key.nil? || !secret_env_key.is_a?(String) || secret_env_key.strip.empty?
+            raise StandardError, "authentication configuration incomplete: missing secret_env_key"
+          end
+
+          secret = ENV[secret_env_key]
+
+          if secret.nil? || !secret.is_a?(String) || secret.strip.empty?
+            raise StandardError, "authentication configuration incomplete: missing secret value bound to #{secret_env_key_name}"
+          end
+
+          return secret.strip
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "time"
+require_relative "base"
+
+module Hooks
+  module Plugins
+    module Auth
+      # Generic HMAC signature validator for webhooks
+      #
+      # This validator supports multiple webhook providers with different signature formats.
+      # It provides flexible configuration options to handle various HMAC-based authentication schemes.
+      #
+      # @example Basic configuration with algorithm prefix
+      #   auth:
+      #     type: HMAC
+      #     secret_env_key: WEBHOOK_SECRET
+      #     header: X-Hub-Signature-256
+      #     algorithm: sha256
+      #     format: "algorithm=signature"
+      #
+      # @example Configuration with timestamp validation
+      #   auth:
+      #     type: HMAC
+      #     secret_env_key: WEBHOOK_SECRET
+      #     header: X-Signature
+      #     timestamp_header: X-Request-Timestamp
+      #     timestamp_tolerance: 300  # 5 minutes
+      #     algorithm: sha256
+      #     format: "version=signature"
+      #     version_prefix: "v0"
+      #     payload_template: "{version}:{timestamp}:{body}"
+      class HMAC < Base
+        # Default configuration values for HMAC validation
+        #
+        # @return [Hash<Symbol, String|Integer>] Default configuration settings
+        # @note These values provide sensible defaults for most webhook implementations
+        DEFAULT_CONFIG = {
+          algorithm: "sha256",
+          format: "algorithm=signature",  # Format: algorithm=hash
+          timestamp_tolerance: 300,       # 5 minutes tolerance for timestamp validation
+          version_prefix: "v0"           # Default version prefix for versioned signatures
+        }.freeze
+
+        # Mapping of signature format strings to internal format symbols
+        #
+        # @return [Hash<String, Symbol>] Format string to symbol mapping
+        # @note Supports three common webhook signature formats:
+        #   - algorithm=signature: "sha256=abc123..." (GitHub, GitLab style)
+        #   - signature_only: "abc123..." (Shopify style)
+        #   - version=signature: "v0=abc123..." (Slack style)
+        FORMATS = {
+          "algorithm=signature" => :algorithm_prefixed,  # "sha256=abc123..."
+          "signature_only" => :hash_only,                # "abc123..."
+          "version=signature" => :version_prefixed       # "v0=abc123..."
+        }.freeze
+
+        # Validate HMAC signature from webhook requests
+        #
+        # Performs comprehensive HMAC signature validation with support for multiple
+        # signature formats and optional timestamp validation. Uses secure comparison
+        # to prevent timing attacks.
+        #
+        # @param payload [String] Raw request body to validate
+        # @param headers [Hash<String, String>] HTTP headers from the request
+        # @param config [Hash] Endpoint configuration containing validator settings
+        # @option config [Hash] :auth Validator-specific configuration
+        # @option config [String] :header ('X-Signature') Header containing the signature
+        # @option config [String] :timestamp_header Header containing timestamp (optional)
+        # @option config [Integer] :timestamp_tolerance (300) Timestamp tolerance in seconds
+        # @option config [String] :algorithm ('sha256') HMAC algorithm to use
+        # @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
+        # @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
+        # @note Uses Rack::Utils.secure_compare to prevent timing attacks
+        # @example Basic validation
+        #   HMAC.valid?(
+        #     payload: request_body,
+        #     headers: request.headers,
+        #     config: { auth: { header: 'X-Signature' } }
+        #   )
+        def self.valid?(payload:, headers:, config:)
+          # fetch the required secret from environment variable as specified in the config
+          secret = fetch_secret(config)
+
+          validator_config = build_config(config)
+
+          # Security: Check raw headers BEFORE normalization to detect tampering
+          return false unless headers.respond_to?(:each)
+
+          signature_header = validator_config[:header]
+
+          # Find the signature header with case-insensitive matching but preserve original value
+          raw_signature = nil
+          headers.each do |key, value|
+            if key.to_s.downcase == signature_header.downcase
+              raw_signature = value.to_s
+              break
+            end
+          end
+
+          return false if raw_signature.nil? || raw_signature.empty?
+
+          # Security: Reject signatures with leading/trailing whitespace
+          return false if raw_signature != raw_signature.strip
+
+          # Security: Reject signatures containing null bytes or other control characters
+          return false if raw_signature.match?(/[\u0000-\u001f\u007f-\u009f]/)
+
+          # Now we can safely normalize headers for the rest of the validation
+          normalized_headers = normalize_headers(headers)
+          provided_signature = normalized_headers[signature_header.downcase]
+
+          # Validate timestamp if required (for services that include timestamp validation)
+          if validator_config[:timestamp_header]
+            return false unless valid_timestamp?(normalized_headers, validator_config)
+          end
+
+          # Compute expected signature
+          computed_signature = compute_signature(
+            payload:,
+            headers: normalized_headers,
+            secret:,
+            config: validator_config
+          )
+
+          # Use secure comparison to prevent timing attacks
+          Rack::Utils.secure_compare(computed_signature, provided_signature)
+        rescue StandardError => e
+          log.error("Auth::HMAC validation failed: #{e.message}")
+          false
+        end
+
+        private
+
+        # Build final configuration by merging defaults with provided config
+        #
+        # Combines default configuration values with user-provided settings,
+        # ensuring all required configuration keys are present with sensible defaults.
+        #
+        # @param config [Hash] Raw endpoint configuration
+        # @return [Hash<Symbol, Object>] Merged configuration with defaults applied
+        # @note Missing configuration values are filled with DEFAULT_CONFIG values
+        # @api private
+        def self.build_config(config)
+          validator_config = config.dig(:auth) || {}
+
+          algorithm = validator_config[:algorithm] || DEFAULT_CONFIG[:algorithm]
+          tolerance = validator_config[:timestamp_tolerance] || DEFAULT_CONFIG[:timestamp_tolerance]
+
+          DEFAULT_CONFIG.merge({
+            header: validator_config[:header] || "X-Signature",
+            timestamp_header: validator_config[:timestamp_header],
+            timestamp_tolerance: tolerance,
+            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]
+          })
+        end
+
+        # Normalize headers using the Utils::Normalize class
+        #
+        # Converts header hash to normalized format with lowercase keys for
+        # case-insensitive header matching.
+        #
+        # @param headers [Hash<String, String>] Raw HTTP headers
+        # @return [Hash<String, String>] Normalized headers with lowercase keys
+        # @note Returns empty hash if headers is nil
+        # @api private
+        def self.normalize_headers(headers)
+          Utils::Normalize.headers(headers) || {}
+        end
+
+        # Validate timestamp if timestamp validation is configured
+        #
+        # Checks if the provided timestamp is within the configured tolerance
+        # of the current time. This prevents replay attacks using old requests.
+        #
+        # @param headers [Hash<String, String>] Normalized HTTP headers
+        # @param config [Hash<Symbol, Object>] Validator configuration
+        # @return [Boolean] true if timestamp is valid or not required, false otherwise
+        # @note Returns false if timestamp header is missing when required
+        # @note Tolerance is applied as absolute difference (past or future)
+        # @api private
+        def self.valid_timestamp?(headers, config)
+          timestamp_header = config[:timestamp_header]
+          return false unless timestamp_header
+
+          timestamp_header = timestamp_header.downcase
+          timestamp_value = headers[timestamp_header]
+
+          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]
+
+          (current_time - timestamp).abs <= tolerance
+        end
+
+        # Compute HMAC signature based on configuration requirements
+        #
+        # Generates the expected HMAC signature for the given payload using the
+        # specified algorithm and formatting rules.
+        #
+        # @param payload [String] Raw request body
+        # @param headers [Hash<String, String>] Normalized HTTP headers
+        # @param secret [String] Secret key for HMAC computation
+        # @param config [Hash<Symbol, Object>] Validator configuration
+        # @return [String] Formatted HMAC signature
+        # @note The returned signature format depends on the configured format style
+        # @api private
+        def self.compute_signature(payload:, headers:, secret:, config:)
+          # Determine what to sign based on payload template
+          signing_payload = build_signing_payload(
+            payload:,
+            headers:,
+            config:
+          )
+
+          # Compute HMAC hash
+          algorithm = config[:algorithm]
+          computed_hash = OpenSSL::HMAC.hexdigest(
+            OpenSSL::Digest.new(algorithm),
+            secret,
+            signing_payload
+          )
+
+          # Format according to provider requirements
+          format_signature(computed_hash, config)
+        end
+
+        # Build the payload string to sign (handles templated payload requirements)
+        #
+        # Constructs the signing payload based on configuration. Some webhook services
+        # require specific payload formats that include metadata like timestamps.
+        #
+        # @param payload [String] Raw request body
+        # @param headers [Hash<String, String>] Normalized HTTP headers
+        # @param config [Hash<Symbol, Object>] Validator configuration
+        # @return [String] Payload string ready for HMAC computation
+        # @note When payload_template is provided, it supports variable substitution:
+        #   - {version}: Replaced with version_prefix
+        #   - {timestamp}: Replaced with timestamp from headers
+        #   - {body}: Replaced with the raw payload
+        # @example Template usage
+        #   template: "{version}:{timestamp}:{body}"
+        #   result: "v0:1609459200:{"event":"push"}"
+        # @api private
+        def self.build_signing_payload(payload:, headers:, config:)
+          template = config[:payload_template]
+
+          if template
+            # Templated payload format (e.g., "v0:timestamp:body" for timestamp-based validation)
+            timestamp = headers[config[:timestamp_header].downcase]
+            template
+              .gsub("{version}", config[:version_prefix])
+              .gsub("{timestamp}", timestamp.to_s)
+              .gsub("{body}", payload)
+          else
+            # Standard: just the payload
+            payload
+          end
+        end
+
+        # Format the computed signature based on configuration requirements
+        #
+        # Applies the appropriate formatting to the computed HMAC hash based on
+        # the configured signature format style.
+        #
+        # @param hash [String] Raw HMAC hash (hexadecimal string)
+        # @param config [Hash<Symbol, Object>] Validator configuration
+        # @return [String] Formatted signature string
+        # @note Supported formats:
+        #   - :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
+        # @api private
+        def self.format_signature(hash, config)
+          format_style = FORMATS[config[:format]]
+
+          case format_style
+          when :algorithm_prefixed
+            # Algorithm-prefixed format: "sha256=abc123..." (used by GitHub, GitLab, etc.)
+            "#{config[:algorithm]}=#{hash}"
+          when :hash_only
+            # Hash-only format: "abc123..." (used by Shopify, etc.)
+            hash
+          when :version_prefixed
+            # Version-prefixed format: "v0=abc123..." (used by Slack, etc.)
+            "#{config[:version_prefix]}=#{hash}"
+          else
+            # Default to algorithm-prefixed format
+            "#{config[:algorithm]}=#{hash}"
+          end
+        end
+      end
+    end
+  end
+end