feat: implement custom auth plugins support

Co-authored-by: GrantBirki <[email protected]>

Author: Copilot

docs/example-config-with-auth-plugins.yaml

@@ -0,0 +1,20 @@
+# Sample configuration for Hooks webhook server with custom auth plugins
+handler_plugin_dir: ./spec/acceptance/handlers
+auth_plugin_dir: ./spec/acceptance/plugins/auth # NEW! Directory for custom auth plugins
+log_level: debug
+
+# Request handling
+request_limit: 1048576    # 1MB max body size
+request_timeout: 15       # 15 seconds timeout
+
+# Path configuration
+root_path: /webhooks
+health_path: /health
+version_path: /version
+
+# Runtime behavior
+environment: development
+
+# Available endpoints
+# Each endpoint configuration file should be placed in the endpoints directory
+endpoints_dir: ./spec/acceptance/config/endpoints

docs/example-endpoint-with-custom-auth.yaml

@@ -0,0 +1,7 @@
+path: /example
+handler: CoolNewHandler
+
+auth:
+  type: some_cool_auth_plugin
+  secret_env_key: SUPER_COOL_SECRET # the name of the environment variable containing the shared secret
+  header: Authorization

docs/example_custom_auth_plugin.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+# Example custom auth plugin implementation
+module Hooks
+  module Plugins
+    module Auth
+      class SomeCoolAuthPlugin < Base
+        def self.valid?(payload:, headers:, config:)
+          # Get the secret from environment variable
+          secret = fetch_secret(config)
+
+          # Get the authorization header (case-insensitive)
+          auth_header = nil
+          headers.each do |key, value|
+            if key.downcase == "authorization"
+              auth_header = value
+              break
+            end
+          end
+
+          # Check if the header matches our expected format
+          return false unless auth_header
+
+          # Extract the token from "Bearer <token>" format
+          return false unless auth_header.start_with?("Bearer ")
+
+          token = auth_header[7..-1] # Remove "Bearer " prefix
+
+          # Simple token comparison (in practice, this might be more complex)
+          token == secret
+        end
+      end
+    end
+  end
+end

lib/hooks/app/api.rb

@@ -65,11 +65,11 @@ def self.create(config:, endpoints:, log:)
 
                   if endpoint_config[:auth]
                     log.info "validating request (id: #{request_id}, handler: #{handler_class_name})"
-                    validate_auth!(raw_body, headers, endpoint_config)
+                    validate_auth!(raw_body, headers, endpoint_config, config)
                   end
 
                   payload = parse_payload(raw_body, headers, symbolize: config[:symbolize_payload])
-                  handler = load_handler(handler_class_name, config[:handler_dir])
+                  handler = load_handler(handler_class_name, config[:handler_plugin_dir])
                   normalized_headers = config[:normalize_headers] ? Hooks::Utils::Normalize.headers(headers) : headers
 
                   response = handler.call(

lib/hooks/app/auth/auth.rb

@@ -13,10 +13,11 @@ module Auth
       # @param payload [String, Hash] The request payload to authenticate.
       # @param headers [Hash] The request headers.
       # @param endpoint_config [Hash] The endpoint configuration, must include :auth key.
+      # @param global_config [Hash] The global configuration (optional, needed for custom auth plugins).
       # @raise [StandardError] Raises error if authentication fails or is misconfigured.
       # @return [void]
       # @note This method will halt execution with an error if authentication fails.
-      def validate_auth!(payload, headers, endpoint_config)
+      def validate_auth!(payload, headers, endpoint_config, global_config = {})
         auth_config = endpoint_config[:auth]
 
         # Security: Ensure auth type is present and valid
@@ -35,7 +36,24 @@ def validate_auth!(payload, headers, endpoint_config)
         when "shared_secret"
           auth_class = Plugins::Auth::SharedSecret
         else
-          error!("Custom validators not implemented in POC", 500)
+          # Try to load custom auth plugin if auth_plugin_dir is configured
+          if global_config[:auth_plugin_dir]
+            # Convert auth_type to CamelCase class name
+            auth_plugin_class_name = auth_type.split("_").map(&:capitalize).join("")
+
+            # Validate the converted class name before attempting to load
+            unless valid_auth_plugin_class_name?(auth_plugin_class_name)
+              error!("invalid auth plugin type '#{auth_type}'", 400)
+            end
+
+            begin
+              auth_class = load_auth_plugin(auth_plugin_class_name, global_config[:auth_plugin_dir])
+            rescue => e
+              error!("failed to load custom auth plugin '#{auth_type}': #{e.message}", 500)
+            end
+          else
+            error!("Custom validators not implemented in POC", 500)
+          end
         end
 
         unless auth_class.valid?(

lib/hooks/app/helpers.rb

@@ -104,6 +104,47 @@ def load_handler(handler_class_name, handler_dir)
         error!("failed to load handler: #{e.message}", 500)
       end
 
+      # Load auth plugin class
+      #
+      # @param auth_plugin_class_name [String] The name of the auth plugin class to load
+      # @param auth_plugin_dir [String] The directory containing auth plugin files
+      # @return [Class] The loaded auth plugin class
+      # @raise [LoadError] If the auth plugin file or class cannot be found
+      # @raise [StandardError] Halts with error if auth plugin cannot be loaded
+      def load_auth_plugin(auth_plugin_class_name, auth_plugin_dir)
+        # Security: Validate auth plugin class name to prevent arbitrary class loading
+        unless valid_auth_plugin_class_name?(auth_plugin_class_name)
+          error!("invalid auth plugin class name: #{auth_plugin_class_name}", 400)
+        end
+
+        # Convert class name to file name (e.g., SomeCoolAuthPlugin -> some_cool_auth_plugin.rb)
+        file_name = auth_plugin_class_name.gsub(/([A-Z])/, '_\1').downcase.sub(/^_/, "") + ".rb"
+        file_path = File.join(auth_plugin_dir, file_name)
+
+        # 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 }
+          error!("auth plugin path outside of auth plugin directory", 400)
+        end
+
+        if File.exist?(file_path)
+          require file_path
+          auth_plugin_class = Object.const_get("Hooks::Plugins::Auth::#{auth_plugin_class_name}")
+
+          # Security: Ensure the loaded class inherits from the expected base class
+          unless auth_plugin_class < Hooks::Plugins::Auth::Base
+            error!("auth plugin class must inherit from Hooks::Plugins::Auth::Base", 400)
+          end
+
+          auth_plugin_class
+        else
+          error!("Auth plugin #{auth_plugin_class_name} not found at #{file_path}", 500)
+        end
+      rescue => e
+        error!("failed to load auth plugin: #{e.message}", 500)
+      end
+
       private
 
       # Validate that a handler class name is safe to load
@@ -127,6 +168,27 @@ def valid_handler_class_name?(class_name)
         true
       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
+
       # Determine HTTP error code from exception
       #
       # @param exception [Exception] The exception to map to an HTTP status code

lib/hooks/core/config_loader.rb

@@ -8,7 +8,9 @@ module Core
     # Loads and merges configuration from files and environment variables
     class ConfigLoader
       DEFAULT_CONFIG = {
-        handler_dir: "./handlers",
+        handler_dir: "./handlers",  # For backward compatibility
+        handler_plugin_dir: "./handlers",
+        auth_plugin_dir: nil,
         log_level: "info",
         request_limit: 1_048_576,
         request_timeout: 30,
@@ -29,6 +31,7 @@ class ConfigLoader
       # @return [Hash] Merged configuration
       def self.load(config_path: nil)
         config = DEFAULT_CONFIG.dup
+        default_handler_dir = config[:handler_dir]
 
         # Load from file if path provided
         if config_path.is_a?(String) && File.exist?(config_path)
@@ -44,6 +47,19 @@ def self.load(config_path: nil)
         # Convert string keys to symbols for consistency
         config = symbolize_keys(config)
 
+        # Support backward compatibility for handler_dir <-> handler_plugin_dir
+        # Check if values changed from default
+        if config[:handler_plugin_dir] != default_handler_dir && config[:handler_dir] == default_handler_dir
+          # Only handler_plugin_dir was changed, sync handler_dir
+          config[:handler_dir] = config[:handler_plugin_dir]
+        elsif config[:handler_dir] != default_handler_dir && config[:handler_plugin_dir] == default_handler_dir
+          # Only handler_dir was changed, sync handler_plugin_dir
+          config[:handler_plugin_dir] = config[:handler_dir]
+        elsif config[:handler_plugin_dir] != default_handler_dir && config[:handler_dir] != default_handler_dir
+          # Both changed, handler_plugin_dir takes precedence
+          config[:handler_dir] = config[:handler_plugin_dir]
+        end
+
         if config[:environment] == "production"
           config[:production] = true
         else
@@ -104,7 +120,9 @@ def self.load_env_config
         env_config = {}
 
         env_mappings = {
-          "HOOKS_HANDLER_DIR" => :handler_dir,
+          "HOOKS_HANDLER_DIR" => :handler_dir,  # For backward compatibility
+          "HOOKS_HANDLER_PLUGIN_DIR" => :handler_plugin_dir,
+          "HOOKS_AUTH_PLUGIN_DIR" => :auth_plugin_dir,
           "HOOKS_LOG_LEVEL" => :log_level,
           "HOOKS_REQUEST_LIMIT" => :request_limit,
           "HOOKS_REQUEST_TIMEOUT" => :request_timeout,

lib/hooks/core/config_validator.rb

@@ -12,7 +12,9 @@ class ValidationError < StandardError; end
 
       # Global configuration schema
       GLOBAL_CONFIG_SCHEMA = Dry::Schema.Params do
-        optional(:handler_dir).filled(:string)
+        optional(:handler_dir).filled(:string)  # For backward compatibility
+        optional(:handler_plugin_dir).filled(:string)
+        optional(:auth_plugin_dir).maybe(:string)
         optional(:log_level).filled(:string, included_in?: %w[debug info warn error])
         optional(:request_limit).filled(:integer, gt?: 0)
         optional(:request_timeout).filled(:integer, gt?: 0)

spec/unit/lib/hooks/app/auth/custom_auth_integration_spec.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative "../../../../spec_helper"
+
+describe "Custom Auth Plugin Integration" do
+  let(:custom_auth_plugin_dir) { "/tmp/test_auth_plugins" }
+  let(:plugin_file_content) do
+    <<~RUBY
+      module Hooks
+        module Plugins
+          module Auth
+            class SomeCoolAuthPlugin < Base
+              def self.valid?(payload:, headers:, config:)
+                # Mock implementation: check for specific header
+                secret = fetch_secret(config)
+                bearer_token = headers["authorization"]
+                bearer_token == "Bearer \#{secret}"
+              end
+            end
+          end
+        end
+      end
+    RUBY
+  end
+
+  let(:global_config) do
+    {
+      auth_plugin_dir: custom_auth_plugin_dir,
+      handler_plugin_dir: "./spec/acceptance/handlers"
+    }
+  end
+
+  let(:endpoint_config) do
+    {
+      path: "/example",
+      handler: "DefaultHandler",
+      auth: {
+        type: "some_cool_auth_plugin",
+        secret_env_key: "SUPER_COOL_SECRET",
+        header: "Authorization"
+      }
+    }
+  end
+
+  before do
+    FileUtils.mkdir_p(custom_auth_plugin_dir)
+    File.write(File.join(custom_auth_plugin_dir, "some_cool_auth_plugin.rb"), plugin_file_content)
+    ENV["SUPER_COOL_SECRET"] = "test-secret"
+  end
+
+  after do
+    FileUtils.rm_rf(custom_auth_plugin_dir) if Dir.exist?(custom_auth_plugin_dir)
+    ENV.delete("SUPER_COOL_SECRET")
+  end
+
+  it "successfully validates using a custom auth plugin" do
+    # Create a test API class using the same pattern as the real API
+    test_api_class = Class.new do
+      include Hooks::App::Helpers
+      include Hooks::App::Auth
+
+      def error!(message, code)
+        raise StandardError, "#{message} (#{code})"
+      end
+    end
+
+    instance = test_api_class.new
+    payload = '{"test": "data"}'
+    headers = { "authorization" => "Bearer test-secret" }
+
+    # This should not raise any error
+    expect do
+      instance.validate_auth!(payload, headers, endpoint_config, global_config)
+    end.not_to raise_error
+  end
+
+  it "rejects requests with invalid credentials using custom auth plugin" do
+    test_api_class = Class.new do
+      include Hooks::App::Helpers
+      include Hooks::App::Auth
+
+      def error!(message, code)
+        raise StandardError, "#{message} (#{code})"
+      end
+    end
+
+    instance = test_api_class.new
+    payload = '{"test": "data"}'
+    headers = { "authorization" => "Bearer wrong-secret" }
+
+    # This should raise authentication failed error
+    expect do
+      instance.validate_auth!(payload, headers, endpoint_config, global_config)
+    end.to raise_error(StandardError, /authentication failed/)
+  end
+
+  it "works with the new configuration format" do
+    # Test the new auth_plugin_dir configuration
+    config = Hooks::Core::ConfigLoader.load(config_path: {
+      auth_plugin_dir: "./custom/auth/plugins",
+      handler_plugin_dir: "./custom/handlers"
+    })
+
+    expect(config[:auth_plugin_dir]).to eq("./custom/auth/plugins")
+    expect(config[:handler_plugin_dir]).to eq("./custom/handlers")
+    expect(config[:handler_dir]).to eq("./custom/handlers") # backward compatibility
+  end
+
+  it "maintains backward compatibility with handler_dir" do
+    # Test that old handler_dir configuration still works
+    config = Hooks::Core::ConfigLoader.load(config_path: {
+      handler_dir: "./legacy/handlers"
+    })
+
+    expect(config[:handler_dir]).to eq("./legacy/handlers")
+    expect(config[:handler_plugin_dir]).to eq("./legacy/handlers")
+  end
+end