RequestValidator is a bad name, auth is better - also expose a global log to auth handlers

Author: GrantBirki

.rubocop.yml

@@ -14,7 +14,7 @@ AllCops:
 
 GitHub/InsecureHashAlgorithm:
   Exclude:
-    - "spec/unit/lib/hooks/plugins/request_validator/hmac_spec.rb"
+    - "spec/unit/lib/hooks/plugins/auth/hmac_spec.rb"
 
 GitHub/AvoidObjectSendWithDynamicMethod:
   Exclude:

docs/design.md

@@ -167,7 +167,7 @@ path: /team1                  # Mounted at <root_path>/team1
 handler: Team1Handler         # Class in handler_dir
 
 # Signature validation
-request_validator:
+auth:
   type: default               # 'default' uses HMACSHA256, or a custom class name
   secret_env_key: TEAM1_SECRET
   header: X-Hub-Signature
@@ -613,7 +613,7 @@ path: string                    # Endpoint path (mounted under root_path)
 handler: string                 # Handler class name
 
 # Optional signature validation
-request_validator:
+auth:
   type: string                  # 'default' or custom validator class name
   secret_env_key: string        # ENV key containing secret
   header: string                # Header containing signature (default: X-Hub-Signature)

lib/hooks/app/api.rb

@@ -5,6 +5,7 @@
 require "securerandom"
 require_relative "../handlers/base"
 require_relative "../core/logger_factory"
+require_relative "../core/log"
 
 module Hooks
   module App
@@ -22,6 +23,9 @@ def self.create(config:, endpoints:, log:, signal_handler:)
         _captured_signal_handler = signal_handler
         captured_start_time = start_time
 
+        # Set global logger instance for plugins/validators
+        Hooks::Log.instance = log
+
         # Create the API class with dynamic routes
         api_class = Class.new(Grape::API) do
           # Accept all content types but don't auto-parse
@@ -58,9 +62,9 @@ def enforce_request_limits(config)
 
             # Verify the incoming request
             def validate_request(payload, headers, endpoint_config)
-              request_validator_config = endpoint_config[:request_validator]
-              validator_type = request_validator_config[:type].downcase
-              secret_env_key = request_validator_config[:secret_env_key]
+              auth_config = endpoint_config[:auth]
+              validator_type = auth_config[:type].downcase
+              secret_env_key = auth_config[:secret_env_key]
 
               return unless secret_env_key
 
@@ -73,9 +77,9 @@ def validate_request(payload, headers, endpoint_config)
 
               case validator_type
               when "hmac"
-                validator_class = Plugins::RequestValidator::HMAC
+                validator_class = Plugins::Auth::HMAC
               when "shared_secret"
-                validator_class = Plugins::RequestValidator::SharedSecret
+                validator_class = Plugins::Auth::SharedSecret
               else
                 error!("Custom validators not implemented in POC", 500)
               end
@@ -198,8 +202,8 @@ def determine_error_code(exception)
                   raw_body = request.body.read
 
                   # Verify/validate request if configured
-                  log.info "validating request (id: #{request_id}, handler: #{handler_class_name})" if endpoint_config[:request_validator]
-                  validate_request(raw_body, headers, endpoint_config) if endpoint_config[:request_validator]
+                  log.info "validating request (id: #{request_id}, handler: #{handler_class_name})" if endpoint_config[:auth]
+                  validate_request(raw_body, headers, endpoint_config) if endpoint_config[:auth]
 
                   # Parse payload (symbolize_payload is true by default)
                   payload = parse_payload(raw_body, headers, symbolize: config[:symbolize_payload])

lib/hooks/core/config_validator.rb

@@ -30,7 +30,7 @@ class ValidationError < StandardError; end
         required(:path).filled(:string)
         required(:handler).filled(:string)
 
-        optional(:request_validator).hash do
+        optional(:auth).hash do
           required(:type).filled(:string)
           optional(:secret_env_key).filled(:string)
           optional(:header).filled(:string)

lib/hooks/core/log.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Log
+    class << self
+      attr_accessor :instance
+    end
+  end
+end

…/hooks/plugins/request_validator/base.rb lib/hooks/plugins/auth/base.rblib/hooks/plugins/request_validator/base.rb renamed to lib/hooks/plugins/auth/base.rb lib/hooks/plugins/request_validator/base.rb renamed to lib/hooks/plugins/auth/base.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
 require "rack/utils"
+require_relative "../../core/log"
 
 module Hooks
   module Plugins
-    module RequestValidator
-      # Abstract base class for request validators
+    module Auth
+      # Abstract base class for request validators via authentication
       #
-      # All custom request validators must inherit from this class
+      # All custom Auth plugins must inherit from this class
       class Base
         # Validate request
         #
@@ -20,6 +21,18 @@ class Base
         def self.valid?(payload:, headers:, secret:, 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
       end
     end
   end

…/hooks/plugins/request_validator/hmac.rb lib/hooks/plugins/auth/hmac.rblib/hooks/plugins/request_validator/hmac.rb renamed to lib/hooks/plugins/auth/hmac.rb lib/hooks/plugins/request_validator/hmac.rb renamed to lib/hooks/plugins/auth/hmac.rb

@@ -6,22 +6,22 @@
 
 module Hooks
   module Plugins
-    module RequestValidator
+    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
-      #   request_validator:
+      #   auth:
       #     type: HMAC
       #     secret_env_key: WEBHOOK_SECRET
       #     header: X-Hub-Signature-256
       #     algorithm: sha256
       #     format: "algorithm=signature"
       #
       # @example Configuration with timestamp validation
-      #   request_validator:
+      #   auth:
       #     type: HMAC
       #     secret_env_key: WEBHOOK_SECRET
       #     header: X-Signature
@@ -66,7 +66,7 @@ class HMAC < Base
         # @param headers [Hash<String, String>] HTTP headers from the request
         # @param secret [String] Secret key for HMAC computation
         # @param config [Hash] Endpoint configuration containing validator settings
-        # @option config [Hash] :request_validator Validator-specific configuration
+        # @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
@@ -83,7 +83,7 @@ class HMAC < Base
         #     payload: request_body,
         #     headers: request.headers,
         #     secret: ENV['WEBHOOK_SECRET'],
-        #     config: { request_validator: { header: 'X-Signature' } }
+        #     config: { auth: { header: 'X-Signature' } }
         #   )
         def self.valid?(payload:, headers:, secret:, config:)
           return false if secret.nil? || secret.empty?
@@ -131,8 +131,8 @@ def self.valid?(payload:, headers:, secret:, config:)
 
           # Use secure comparison to prevent timing attacks
           Rack::Utils.secure_compare(computed_signature, provided_signature)
-        rescue StandardError => _e
-          # Log error in production - for now just return false
+        rescue StandardError => e
+          log.error("Auth::HMAC validation failed: #{e.message}")
           false
         end
 
@@ -148,7 +148,7 @@ def self.valid?(payload:, headers:, secret:, config:)
         # @note Missing configuration values are filled with DEFAULT_CONFIG values
         # @api private
         def self.build_config(config)
-          validator_config = config.dig(:request_validator) || {}
+          validator_config = config.dig(:auth) || {}
 
           algorithm = validator_config[:algorithm] || DEFAULT_CONFIG[:algorithm]
           tolerance = validator_config[:timestamp_tolerance] || DEFAULT_CONFIG[:timestamp_tolerance]

…ugins/request_validator/shared_secret.rb lib/hooks/plugins/auth/shared_secret.rblib/hooks/plugins/request_validator/shared_secret.rb renamed to lib/hooks/plugins/auth/shared_secret.rb lib/hooks/plugins/request_validator/shared_secret.rb renamed to lib/hooks/plugins/auth/shared_secret.rb

@@ -4,7 +4,7 @@
 
 module Hooks
   module Plugins
-    module RequestValidator
+    module Auth
       # Generic shared secret validator for webhooks
       #
       # This validator provides simple shared secret authentication for webhook requests.
@@ -13,13 +13,13 @@ module RequestValidator
       # used by various webhook providers.
       #
       # @example Basic configuration
-      #   request_validator:
+      #   auth:
       #     type: shared_secret
       #     secret_env_key: WEBHOOK_SECRET
       #     header: Authorization
       #
       # @example Custom header configuration
-      #   request_validator:
+      #   auth:
       #     type: shared_secret
       #     secret_env_key: SOME_OTHER_WEBHOOK_SECRET
       #     header: X-API-Key
@@ -45,7 +45,7 @@ class SharedSecret < Base
         # @param headers [Hash<String, String>] HTTP headers from the request
         # @param secret [String] Expected secret value for comparison
         # @param config [Hash] Endpoint configuration containing validator settings
-        # @option config [Hash] :request_validator Validator-specific configuration
+        # @option config [Hash] :auth Validator-specific configuration
         # @option config [String] :header ('Authorization') Header containing the secret
         # @return [Boolean] true if secret is valid, false otherwise
         # @raise [StandardError] Rescued internally, returns false on any error
@@ -56,7 +56,7 @@ class SharedSecret < Base
         #     payload: request_body,
         #     headers: request.headers,
         #     secret: ENV['WEBHOOK_SECRET'],
-        #     config: { request_validator: { header: 'Authorization' } }
+        #     config: { auth: { header: 'Authorization' } }
         #   )
         def self.valid?(payload:, headers:, secret:, config:)
           return false if secret.nil? || secret.empty?
@@ -90,7 +90,6 @@ def self.valid?(payload:, headers:, secret:, config:)
           # Use secure comparison to prevent timing attacks
           Rack::Utils.secure_compare(secret, stripped_secret)
         rescue StandardError => _e
-          # Log error in production - for now just return false
           false
         end
 
@@ -106,7 +105,7 @@ def self.valid?(payload:, headers:, secret:, config:)
         # @note Missing configuration values are filled with DEFAULT_CONFIG values
         # @api private
         def self.build_config(config)
-          validator_config = config.dig(:request_validator) || {}
+          validator_config = config.dig(:auth) || {}
 
           DEFAULT_CONFIG.merge({
             header: validator_config[:header] || DEFAULT_CONFIG[:header]

spec/acceptance/config/endpoints/github.yaml

@@ -3,7 +3,7 @@ path: /github
 handler: GithubHandler
 
 # GitHub uses HMAC SHA256 signature validation
-request_validator:
+auth:
   type: hmac
   secret_env_key: GITHUB_WEBHOOK_SECRET
   header: X-Hub-Signature-256

spec/acceptance/config/endpoints/okta.yaml

@@ -1,7 +1,7 @@
 path: /okta
 handler: OktaHandler
 
-request_validator:
+auth:
   type: shared_secret
   secret_env_key: SHARED_SECRET # the name of the environment variable containing the shared secret
   header: Authorization