hooks-ruby 0.0.2

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Hooks
+  module Plugins
+    module Auth
+      # Generic shared secret validator for webhooks
+      #
+      # This validator provides simple shared secret authentication for webhook requests.
+      # It compares a secret value sent in a configurable HTTP header against the expected
+      # secret value. This is a common (though less secure than HMAC) authentication pattern
+      # used by various webhook providers.
+      #
+      # @example Basic configuration
+      #   auth:
+      #     type: shared_secret
+      #     secret_env_key: WEBHOOK_SECRET
+      #     header: Authorization
+      #
+      # @example Custom header configuration
+      #   auth:
+      #     type: shared_secret
+      #     secret_env_key: SOME_OTHER_WEBHOOK_SECRET
+      #     header: X-API-Key
+      #
+      # @note This validator performs direct string comparison of the shared secret.
+      #   While simpler than HMAC, it provides less security since the secret is
+      #   transmitted directly in the request header.
+      class SharedSecret < Base
+        # Default configuration values for shared secret validation
+        #
+        # @return [Hash<Symbol, String>] Default configuration settings
+        DEFAULT_CONFIG = {
+          header: "Authorization"
+        }.freeze
+
+        # Validate shared secret from webhook requests
+        #
+        # Performs secure comparison of the shared secret value from the configured
+        # header against the expected secret. Uses secure comparison to prevent
+        # timing attacks.
+        #
+        # @param payload [String] Raw request body (unused but required by interface)
+        # @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 ('Authorization') Header containing the secret
+        # @return [Boolean] true if secret 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
+        #   SharedSecret.valid?(
+        #     payload: request_body,
+        #     headers: request.headers,
+        #     config: { auth: { header: 'Authorization' } }
+        #   )
+        def self.valid?(payload:, headers:, 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)
+
+          secret_header = validator_config[:header]
+
+          # Find the secret header with case-insensitive matching but preserve original value
+          raw_secret = nil
+          headers.each do |key, value|
+            if key.to_s.downcase == secret_header.downcase
+              raw_secret = value.to_s
+              break
+            end
+          end
+
+          return false if raw_secret.nil? || raw_secret.empty?
+
+          stripped_secret = raw_secret.strip
+
+          # Security: Reject secrets with leading/trailing whitespace
+          return false if raw_secret != stripped_secret
+
+          # Security: Reject secrets containing null bytes or other control characters
+          return false if raw_secret.match?(/[\u0000-\u001f\u007f-\u009f]/)
+
+          # Use secure comparison to prevent timing attacks
+          Rack::Utils.secure_compare(secret, stripped_secret)
+        rescue StandardError => _e
+          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) || {}
+
+          DEFAULT_CONFIG.merge({
+            header: validator_config[:header] || DEFAULT_CONFIG[:header]
+          })
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Plugins
+    module Handlers
+      # Base class for all webhook handlers
+      #
+      # All custom handlers must inherit from this class and implement the #call method
+      class Base
+        # Process a webhook request
+        #
+        # @param payload [Hash, String] Parsed request body (JSON Hash) or raw string
+        # @param headers [Hash<String, String>] HTTP headers
+        # @param config [Hash] Merged endpoint configuration including opts section
+        # @return [Hash, String, nil] Response body (will be auto-converted to JSON)
+        # @raise [NotImplementedError] if not implemented by subclass
+        def call(payload:, headers:, config:)
+          raise NotImplementedError, "Handler must implement #call method"
+        end
+
+        # Short logger accessor for all subclasses
+        # @return [Hooks::Log] Logger instance
+        #
+        # Provides a convenient way for handlers 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 log
+          Hooks::Log.instance
+        end
+      end
+    end
+  end
+end

data/lib/hooks/plugins/handlers/default.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Default handler when no custom handler is found
+# This handler simply acknowledges receipt of the webhook and shows a few of the built-in features
+class DefaultHandler < Hooks::Plugins::Handlers::Base
+  def call(payload:, headers:, config:)
+
+    log.info("🔔 Default handler invoked for webhook 🔔")
+
+    # do some basic processing
+    if payload
+      log.debug("received payload: #{payload.inspect}")
+    end
+
+    {
+      message: "webhook processed successfully",
+      handler: "DefaultHandler",
+      timestamp: Time.now.iso8601
+    }
+  end
+end

data/lib/hooks/plugins/lifecycle.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Plugins
+    # Base class for global lifecycle plugins
+    #
+    # Plugins can hook into request/response/error lifecycle events
+    class Lifecycle
+      # Called before handler execution
+      #
+      # @param env [Hash] Rack environment
+      def on_request(env)
+        # Override in subclass for pre-processing logic
+      end
+
+      # Called after successful handler execution
+      #
+      # @param env [Hash] Rack environment
+      # @param response [Hash] Handler response
+      def on_response(env, response)
+        # Override in subclass for post-processing logic
+      end
+
+      # Called when any error occurs during request processing
+      #
+      # @param exception [Exception] The raised exception
+      # @param env [Hash] Rack environment
+      def on_error(exception, env)
+        # Override in subclass for error handling logic
+      end
+    end
+  end
+end

data/lib/hooks/security.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Security
+    # List of dangerous class names that should not be loaded as handlers
+    # for security reasons. These classes provide system access that could
+    # be exploited if loaded dynamically.
+    #
+    # @return [Array<String>] Array of dangerous class names
+    DANGEROUS_CLASSES = %w[
+      File Dir Kernel Object Class Module Proc Method
+      IO Socket TCPSocket UDPSocket BasicSocket
+      Process Thread Fiber Mutex ConditionVariable
+      Marshal YAML JSON Pathname
+    ].freeze
+  end
+end

data/lib/hooks/utils/normalize.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Utils
+    # Utility class for normalizing HTTP headers
+    #
+    # Provides a robust method to consistently format HTTP headers
+    # across the application, handling various edge cases and formats.
+    class Normalize
+      # Normalize a hash of HTTP headers
+      #
+      # @param headers [Hash, #each] Headers hash or hash-like object
+      # @return [Hash] Normalized headers hash with downcased keys and trimmed values
+      #
+      # @example Hash of headers normalization
+      #   headers = { "Content-Type" => "  application/json  ", "X-GitHub-Event" => "push" }
+      #   normalized = Normalize.headers(headers)
+      #   # => { "content-type" => "application/json", "x-github-event" => "push" }
+      #
+      # @example Handle various input types
+      #   Normalize.headers(nil)                    # => nil
+      #   Normalize.headers({})                     # => {}
+      #   Normalize.headers({ "KEY" => ["a", "b"] }) # => { "key" => "a" }
+      #   Normalize.headers({ "Key" => 123 })       # => { "key" => "123" }
+      def self.headers(headers)
+        # Handle nil input
+        return nil if headers.nil?
+
+        # Fast path for non-enumerable inputs (numbers, etc.)
+        return {} unless headers.respond_to?(:each)
+
+        normalized = {}
+
+        headers.each do |key, value|
+          # Skip nil keys or values entirely
+          next if key.nil? || value.nil?
+
+          # Convert key to string, downcase, and strip in one operation
+          normalized_key = key.to_s.downcase.strip
+          next if normalized_key.empty?
+
+          # Handle different value types efficiently
+          normalized_value = case value
+                             when String
+                               value.strip
+                             when Array
+                               # Take first non-empty element for multi-value headers
+                               first_valid = value.find { |v| v && !v.to_s.strip.empty? }
+                               first_valid ? first_valid.to_s.strip : nil
+                             else
+                               value.to_s.strip
+                             end
+
+          # Only add if we have a non-empty value
+          normalized[normalized_key] = normalized_value if normalized_value && !normalized_value.empty?
+        end
+
+        normalized
+      end
+
+      # Normalize a single HTTP header name
+      #
+      # @param header [String] Header name to normalize
+      # @return [String, nil] Normalized header name (downcased and trimmed), or nil if input is nil
+      #
+      # @example Single header normalization
+      #   Normalize.header("  Content-Type  ")  # => "content-type"
+      #   Normalize.header("X-GitHub-Event")    # => "x-github-event"
+      #   Normalize.header("")                  # => ""
+      #   Normalize.header(nil)                 # => nil
+      #
+      # @raise [ArgumentError] If input is not a String or nil
+      def self.header(header)
+        return nil if header.nil?
+        if header.is_a?(String)
+          header.downcase.strip
+        else
+          raise ArgumentError, "Expected a String for header normalization"
+        end
+      end
+    end
+  end
+end

data/lib/hooks/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Hooks
+  VERSION = "0.0.2"
+end

data/lib/hooks.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "hooks/version"
+require_relative "hooks/core/builder"
+
+# Load all plugins (auth plugins, handler plugins, lifecycle hooks, etc.)
+Dir[File.join(__dir__, "hooks/plugins/**/*.rb")].sort.each do |file|
+  require file
+end
+
+# Load all utils
+Dir[File.join(__dir__, "hooks/utils/**/*.rb")].sort.each do |file|
+  require file
+end
+
+# Main module for the Hooks webhook server framework
+module Hooks
+  # Build a Rack-compatible webhook server application
+  #
+  # @param config [String, Hash] Path to config file or config hash
+  # @param log [Logger] Custom logger instance (optional)
+  # @return [Object] Rack-compatible application
+  def self.build(config: nil, log: nil)
+    Core::Builder.new(
+      config:,
+      log:,
+    ).build
+  end
+end

metadata

@@ -0,0 +1,189 @@
+--- !ruby/object:Gem::Specification
+name: hooks-ruby
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- github
+- GrantBirki
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redacting-logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: retryable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.5
+- !ruby/object:Gem::Dependency
+  name: dry-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.14.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.14.1
+- !ruby/object:Gem::Dependency
+  name: grape
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: grape-swagger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.1.2
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.6'
+description: 'A Pluggable Webhook Server Framework written in Ruby
+
+  '
+executables:
+- hooks
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/bundle
+- bin/erb
+- bin/hooks
+- bin/htmldiff
+- bin/irb
+- bin/ldiff
+- bin/puma
+- bin/pumactl
+- bin/racc
+- bin/rdoc
+- bin/ri
+- bin/rspec
+- bin/rubocop
+- bin/ruby-parse
+- bin/ruby-rewrite
+- bin/rubygems-await
+- bin/sigstore-cli
+- bin/thor
+- config.ru
+- hooks.gemspec
+- lib/hooks.rb
+- lib/hooks/app/api.rb
+- lib/hooks/app/auth/auth.rb
+- lib/hooks/app/endpoints/catchall.rb
+- lib/hooks/app/endpoints/health.rb
+- lib/hooks/app/endpoints/version.rb
+- lib/hooks/app/helpers.rb
+- lib/hooks/core/builder.rb
+- lib/hooks/core/config_loader.rb
+- lib/hooks/core/config_validator.rb
+- lib/hooks/core/log.rb
+- lib/hooks/core/logger_factory.rb
+- lib/hooks/core/plugin_loader.rb
+- lib/hooks/plugins/auth/base.rb
+- lib/hooks/plugins/auth/hmac.rb
+- lib/hooks/plugins/auth/shared_secret.rb
+- lib/hooks/plugins/handlers/base.rb
+- lib/hooks/plugins/handlers/default.rb
+- lib/hooks/plugins/lifecycle.rb
+- lib/hooks/security.rb
+- lib/hooks/utils/normalize.rb
+- lib/hooks/version.rb
+homepage: https://github.com/github/hooks
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/github/hooks/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: A Pluggable Webhook Server Framework written in Ruby
+test_files: []