feat: support custom auth plugins

[Copilot]

This PR implements support for custom auth plugins, allowing users to "bring their own" authentication implementations for webhook validation beyond the built-in HMAC and SharedSecret plugins.

New Features

Custom Auth Plugin Support

• Users can now create custom auth plugins by extending Hooks::Plugins::Auth::Base
• Plugins are automatically loaded from a configurable directory at runtime
• The system converts snake_case plugin names to CamelCase class names (e.g., some_cool_auth_plugin → SomeCoolAuthPlugin)

Configuration Updates

• Added auth_plugin_dir configuration option to specify custom auth plugin directory
• Renamed handler_dir to handler_plugin_dir for naming consistency
• Maintained full backward compatibility - existing handler_dir configurations continue to work

Example Usage

Configuration (hooks.yaml):

handler_plugin_dir: ./handlers
auth_plugin_dir: ./plugins/auth  # NEW!
endpoints_dir: ./config/endpoints

Endpoint Configuration:

path: /example
handler: CoolNewHandler
auth:
  type: some_cool_auth_plugin
  secret_env_key: SUPER_COOL_SECRET
  header: Authorization

Custom Auth Plugin (plugins/auth/some_cool_auth_plugin.rb):

module Hooks
  module Plugins
    module Auth
      class SomeCoolAuthPlugin < Base
        def self.valid?(payload:, headers:, config:)
          secret = fetch_secret(config)
          bearer_token = headers["authorization"]
          bearer_token == "Bearer #{secret}"
        end
      end
    end
  end
end

Security Features

• Custom auth plugins must inherit from Hooks::Plugins::Auth::Base
• Plugin class names are validated to prevent arbitrary code execution
• File path validation prevents directory traversal attacks
• Plugins are loaded from a restricted, configurable directory

Backward Compatibility

• Existing handler_dir configuration continues to work unchanged
• All existing auth plugins (HMAC, SharedSecret) work exactly as before
• If auth_plugin_dir is not configured, the system falls back to the original "Custom validators not implemented in POC" error

Testing

• Added comprehensive unit tests covering all new functionality
• Added integration tests demonstrating end-to-end usage scenarios
• Added tests for security edge cases and error handling
• All existing tests continue to pass (396 examples, 86.04% coverage)

Fixes #15.

[Copilot]

Pull Request Overview

This PR adds support for user-defined authentication plugins, updates configuration for auth and handler directories (with backward-compatibility), extends the core loader/validator, and updates the runtime to load and invoke custom plugins.

• Update defaults and env mappings to include auth_plugin_dir and rename handler_dir → handler_plugin_dir (with sync logic).
• Introduce load_auth_plugin and name-validation helpers, and modify validate_auth! + API entrypoint to use custom plugins.
• Add extensive unit & integration specs and documentation examples.

Reviewed Changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
spec/unit/lib/hooks/core/config_loader_spec.rb	Tests for auth_plugin_dir and handler-dir backward compatibility
spec/unit/lib/hooks/app/auth/custom_auth_plugin_spec.rb	Unit tests for custom plugin loading, failures, and security checks
spec/unit/lib/hooks/app/auth/custom_auth_integration_spec.rb	End-to-end integration tests for custom auth plugins
lib/hooks/core/config_validator.rb	Schema updated with auth_plugin_dir and backward-compat comment
lib/hooks/core/config_loader.rb	Defaults and loading logic extended for plugin dirs
lib/hooks/app/helpers.rb	New load_auth_plugin & valid_auth_plugin_class_name?
lib/hooks/app/auth/auth.rb	validate_auth! enhanced to handle custom plugins
lib/hooks/app/api.rb	Pass global config into auth and use handler_plugin_dir
docs/...	Example plugin & config documentation
.bundle/config	CI-specific bundle path updated (should be reverted)

Comments suppressed due to low confidence (1)

.bundle/config:3

• [nitpick] This CI-specific absolute path should not be committed in repo. Revert to the relative vendor path or add this file to .gitignore to avoid environment leaks.

BUNDLE_PATH: "/home/runner/work/hooks/hooks/vendor/bundle"