hooksmith 0.2.0 → 1.0.0

data/lib/hooksmith/rails/webhooks_controller.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Hooksmith
+  module Rails
+    # A concern for Rails controllers that handle webhooks.
+    #
+    # This concern provides standardized webhook handling with:
+    # - Automatic request verification (if configured)
+    # - Consistent response codes (200 for success, 400 for bad request, 500 for errors)
+    # - Error logging and instrumentation
+    # - Skip CSRF protection for webhook endpoints
+    #
+    # @example Basic usage
+    #   class WebhooksController < ApplicationController
+    #     include Hooksmith::Rails::WebhooksController
+    #
+    #     def stripe
+    #       handle_webhook(provider: 'stripe', event: params[:type], payload: params.to_unsafe_h)
+    #     end
+    #   end
+    #
+    # @example With custom error handling
+    #   class WebhooksController < ApplicationController
+    #     include Hooksmith::Rails::WebhooksController
+    #
+    #     def stripe
+    #       handle_webhook(provider: 'stripe', event: params[:type], payload: params.to_unsafe_h) do |result|
+    #         # Custom success handling
+    #         render json: { processed: true, result: result }
+    #       end
+    #     rescue Hooksmith::VerificationError => e
+    #       render json: { error: 'Invalid signature' }, status: :unauthorized
+    #     end
+    #   end
+    #
+    # @example Async processing with ActiveJob
+    #   class WebhooksController < ApplicationController
+    #     include Hooksmith::Rails::WebhooksController
+    #
+    #     def stripe
+    #       handle_webhook_async(provider: 'stripe', event: params[:type], payload: params.to_unsafe_h)
+    #     end
+    #   end
+    #
+    module WebhooksController
+      extend ActiveSupport::Concern
+
+      included do
+        skip_before_action :verify_authenticity_token, raise: false
+        before_action :verify_webhook_signature, if: :hooksmith_verification_enabled?
+      end
+
+      # Handles a webhook synchronously.
+      #
+      # @param provider [String, Symbol] the webhook provider
+      # @param event [String, Symbol] the event type
+      # @param payload [Hash] the webhook payload
+      # @yield [result] optional block for custom success handling
+      # @yieldparam result [Object] the result from the processor
+      # @return [void]
+      def handle_webhook(provider:, event:, payload:)
+        result = Hooksmith::Dispatcher.new(provider:, event:, payload:).run!
+
+        if block_given?
+          yield(result)
+        else
+          head :ok
+        end
+      rescue Hooksmith::MultipleProcessorsError => e
+        Hooksmith.logger.error("Webhook error: #{e.message}")
+        head :internal_server_error
+      rescue StandardError => e
+        Hooksmith.logger.error("Webhook processing failed: #{e.message}")
+        head :internal_server_error
+      end
+
+      # Handles a webhook asynchronously using ActiveJob.
+      #
+      # Requires Hooksmith::Jobs::DispatcherJob to be available.
+      #
+      # @param provider [String, Symbol] the webhook provider
+      # @param event [String, Symbol] the event type
+      # @param payload [Hash] the webhook payload
+      # @param queue [Symbol, String] the queue to use (default: :default)
+      # @return [void]
+      def handle_webhook_async(provider:, event:, payload:, queue: :default)
+        unless defined?(Hooksmith::Jobs::DispatcherJob)
+          raise 'Hooksmith::Jobs::DispatcherJob is not available. Ensure ActiveJob is loaded.'
+        end
+
+        Hooksmith::Jobs::DispatcherJob.set(queue:).perform_later(
+          provider: provider.to_s,
+          event: event.to_s,
+          payload: payload.as_json
+        )
+
+        head :ok
+      end
+
+      private
+
+      # Verifies the webhook signature using the provider's configured verifier.
+      #
+      # Override this method to customize verification behavior.
+      #
+      # @return [void]
+      # @raise [Hooksmith::VerificationError] if verification fails
+      def verify_webhook_signature
+        provider = hooksmith_provider_name
+        return unless provider
+
+        verifier = Hooksmith.configuration.verifier_for(provider)
+        return unless verifier&.enabled?
+
+        hooksmith_request = Hooksmith::Request.new(
+          headers: request.headers.to_h,
+          body: request.raw_post
+        )
+
+        verifier.verify!(hooksmith_request)
+      rescue Hooksmith::VerificationError => e
+        Hooksmith.logger.warn("Webhook verification failed for #{provider}: #{e.message}")
+        head :unauthorized
+      end
+
+      # Returns the provider name for the current action.
+      #
+      # Override this method to customize provider detection.
+      # By default, uses the action name.
+      #
+      # @return [String, nil] the provider name
+      def hooksmith_provider_name
+        action_name
+      end
+
+      # Checks if webhook verification is enabled for the current provider.
+      #
+      # Override this method to customize when verification runs.
+      #
+      # @return [Boolean] true if verification should run
+      def hooksmith_verification_enabled?
+        return false unless Hooksmith.configuration.respond_to?(:verifier_for)
+
+        provider = hooksmith_provider_name
+        return false unless provider
+
+        verifier = Hooksmith.configuration.verifier_for(provider)
+        verifier&.enabled? || false
+      end
+    end
+  end
+end

data/lib/hooksmith/request.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Hooksmith
+  # Wrapper for incoming webhook request data.
+  #
+  # This class provides a consistent interface for accessing request data
+  # regardless of the underlying web framework (Rails, Rack, etc.).
+  #
+  # @example Creating a request from Rails controller
+  #   request = Hooksmith::Request.new(
+  #     headers: request.headers.to_h,
+  #     body: request.raw_post,
+  #     method: request.request_method,
+  #     path: request.path
+  #   )
+  #
+  # @example Creating a request from Rack env
+  #   request = Hooksmith::Request.from_rack_env(env)
+  #
+  class Request
+    # @return [Hash] the request headers
+    attr_reader :headers
+    # @return [String] the raw request body
+    attr_reader :body
+    # @return [String] the HTTP method (GET, POST, etc.)
+    attr_reader :method
+    # @return [String] the request path
+    attr_reader :path
+    # @return [Hash] the parsed payload (optional, for convenience)
+    attr_reader :payload
+
+    # Initializes a new Request.
+    #
+    # @param headers [Hash] the request headers
+    # @param body [String] the raw request body
+    # @param method [String] the HTTP method
+    # @param path [String] the request path
+    # @param payload [Hash] the parsed payload (optional)
+    def initialize(headers:, body:, method: 'POST', path: '/', payload: nil)
+      @headers = normalize_headers(headers)
+      @body = body.to_s
+      @method = method.to_s.upcase
+      @path = path.to_s
+      @payload = payload
+    end
+
+    # Creates a Request from a Rack environment hash.
+    #
+    # @param env [Hash] the Rack environment
+    # @return [Request] a new Request instance
+    def self.from_rack_env(env)
+      headers = extract_headers_from_rack(env)
+      body = env['rack.input']&.read || ''
+      env['rack.input']&.rewind
+
+      new(
+        headers:,
+        body:,
+        method: env['REQUEST_METHOD'],
+        path: env['PATH_INFO']
+      )
+    end
+
+    # Gets a header value by name (case-insensitive).
+    #
+    # @param name [String] the header name
+    # @return [String, nil] the header value or nil if not found
+    def header(name)
+      normalized_name = normalize_header_name(name)
+      @headers[normalized_name]
+    end
+
+    # Alias for {#header}.
+    #
+    # @param name [String] the header name
+    # @return [String, nil] the header value or nil if not found
+    def [](name)
+      header(name)
+    end
+
+    # Extracts headers from a Rack environment hash.
+    #
+    # @param env [Hash] the Rack environment
+    # @return [Hash] the extracted headers
+    def self.extract_headers_from_rack(env)
+      env.select { |k, _| k.start_with?('HTTP_') || %w[CONTENT_TYPE CONTENT_LENGTH].include?(k) }
+    end
+    private_class_method :extract_headers_from_rack
+
+    private
+
+    # Normalizes headers to use consistent key format.
+    #
+    # @param headers [Hash] the raw headers
+    # @return [Hash] normalized headers
+    def normalize_headers(headers)
+      return {} unless headers.is_a?(Hash)
+
+      headers.transform_keys { |k| normalize_header_name(k) }
+    end
+
+    # Normalizes a header name to a consistent format.
+    #
+    # @param name [String] the header name
+    # @return [String] the normalized header name
+    def normalize_header_name(name)
+      name.to_s.upcase.tr('-', '_').sub(/^HTTP_/, '')
+    end
+  end
+end

data/lib/hooksmith/verifiers/base.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Hooksmith
+  module Verifiers
+    # Base class for webhook request verifiers.
+    #
+    # Verifiers are responsible for authenticating incoming webhook requests
+    # before they are processed. Each provider can have its own verifier
+    # configured to handle provider-specific authentication schemes.
+    #
+    # @abstract Subclass and override {#verify!} to implement custom verification.
+    #
+    # @example Creating a custom verifier
+    #   class MyCustomVerifier < Hooksmith::Verifiers::Base
+    #     def verify!(request)
+    #       token = request.headers['X-Custom-Token']
+    #       raise Hooksmith::VerificationError, 'Invalid token' unless valid_token?(token)
+    #     end
+    #
+    #     private
+    #
+    #     def valid_token?(token)
+    #       token == @options[:expected_token]
+    #     end
+    #   end
+    #
+    class Base
+      # @return [Hash] options passed to the verifier
+      attr_reader :options
+
+      # Initializes the verifier with options.
+      #
+      # @param options [Hash] verifier-specific options
+      def initialize(**options)
+        @options = options
+      end
+
+      # Verifies the incoming webhook request.
+      #
+      # @param request [Hooksmith::Request] the incoming request to verify
+      # @raise [Hooksmith::VerificationError] if verification fails
+      # @return [void]
+      def verify!(request)
+        raise NotImplementedError, 'Subclasses must implement #verify!'
+      end
+
+      # Returns whether the verifier is configured and should be used.
+      #
+      # @return [Boolean] true if the verifier should be applied
+      def enabled?
+        true
+      end
+
+      protected
+
+      # Performs a constant-time string comparison to prevent timing attacks.
+      #
+      # @param expected [String] expected string
+      # @param actual [String] actual string
+      # @return [Boolean] true if strings are equal
+      def secure_compare(expected, actual)
+        return false if expected.nil? || actual.nil?
+        return false if expected.bytesize != actual.bytesize
+
+        # Use OpenSSL's secure comparison if available (Ruby 2.5+)
+        if OpenSSL.respond_to?(:secure_compare)
+          OpenSSL.secure_compare(expected, actual)
+        else
+          # Fallback to manual constant-time comparison
+          left = expected.unpack('C*')
+          right = actual.unpack('C*')
+          result = 0
+          left.zip(right) { |x, y| result |= x ^ y }
+          result.zero?
+        end
+      end
+    end
+  end
+end

data/lib/hooksmith/verifiers/bearer_token.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module Hooksmith
+  module Verifiers
+    # Bearer token webhook verifier.
+    #
+    # This verifier validates webhook requests using a simple bearer token
+    # in the Authorization header or a custom header.
+    #
+    # @example Basic bearer token verification
+    #   verifier = Hooksmith::Verifiers::BearerToken.new(
+    #     token: ENV['WEBHOOK_TOKEN']
+    #   )
+    #
+    # @example Custom header
+    #   verifier = Hooksmith::Verifiers::BearerToken.new(
+    #     token: ENV['WEBHOOK_TOKEN'],
+    #     header: 'X-Webhook-Token'
+    #   )
+    #
+    class BearerToken < Base
+      # Default header for bearer tokens
+      DEFAULT_HEADER = 'Authorization'
+
+      # Initializes the bearer token verifier.
+      #
+      # @param token [String] the expected token value
+      # @param header [String] the header containing the token (default: Authorization)
+      # @param strip_bearer_prefix [Boolean] whether to strip 'Bearer ' prefix (default: true)
+      def initialize(token:, header: DEFAULT_HEADER, strip_bearer_prefix: true, **options)
+        super(**options)
+        @token = token
+        @header = header
+        @strip_bearer_prefix = strip_bearer_prefix
+      end
+
+      # Verifies the bearer token in the request.
+      #
+      # @param request [Hooksmith::Request] the incoming request
+      # @raise [Hooksmith::VerificationError] if verification fails
+      # @return [void]
+      def verify!(request)
+        provided_token = extract_token(request)
+
+        if provided_token.nil? || provided_token.empty?
+          raise VerificationError.new('Missing authentication token', reason: 'missing_token')
+        end
+
+        return if secure_compare(@token, provided_token)
+
+        raise VerificationError.new('Invalid authentication token', reason: 'invalid_token')
+      end
+
+      # Returns whether the verifier is properly configured.
+      #
+      # @return [Boolean] true if token is present
+      def enabled?
+        !@token.nil? && !@token.empty?
+      end
+
+      private
+
+      # Extracts the token from the request headers.
+      #
+      # @param request [Hooksmith::Request] the incoming request
+      # @return [String, nil] the extracted token
+      def extract_token(request)
+        raw_token = request.header(@header)
+        return nil if raw_token.nil?
+
+        token = raw_token.to_s.strip
+        token = token.sub(/\ABearer\s+/i, '') if @strip_bearer_prefix
+        token.empty? ? nil : token
+      end
+    end
+  end
+end

data/lib/hooksmith/verifiers/hmac.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'base64'
+
+module Hooksmith
+  module Verifiers
+    # HMAC-based webhook signature verifier.
+    #
+    # This verifier validates webhook requests using HMAC signatures,
+    # which is a common authentication method used by providers like
+    # Stripe, GitHub, Shopify, and many others.
+    #
+    # @example Basic HMAC verification
+    #   verifier = Hooksmith::Verifiers::Hmac.new(
+    #     secret: ENV['WEBHOOK_SECRET'],
+    #     header: 'X-Signature'
+    #   )
+    #
+    # @example HMAC with timestamp validation (like Stripe)
+    #   verifier = Hooksmith::Verifiers::Hmac.new(
+    #     secret: ENV['STRIPE_WEBHOOK_SECRET'],
+    #     header: 'Stripe-Signature',
+    #     timestamp_options: { header: 'Stripe-Signature', tolerance: 300 }
+    #   )
+    #
+    # @example HMAC with custom signature format
+    #   verifier = Hooksmith::Verifiers::Hmac.new(
+    #     secret: ENV['WEBHOOK_SECRET'],
+    #     header: 'X-Hub-Signature-256',
+    #     algorithm: 'sha256',
+    #     signature_prefix: 'sha256='
+    #   )
+    #
+    class Hmac < Base
+      # Supported HMAC algorithms
+      ALGORITHMS = %w[sha1 sha256 sha384 sha512].freeze
+
+      # Default signature encoding
+      DEFAULT_ENCODING = :hex
+
+      # Initializes the HMAC verifier.
+      #
+      # @param secret [String] the shared secret key
+      # @param header [String] the header containing the signature
+      # @param algorithm [String] the HMAC algorithm (sha1, sha256, sha384, sha512)
+      # @param encoding [Symbol] the signature encoding (:hex or :base64)
+      # @param signature_prefix [String, nil] prefix to strip from signature (e.g., 'sha256=')
+      # @param timestamp_options [Hash] timestamp validation options
+      # @option timestamp_options [String] :header header containing the timestamp
+      # @option timestamp_options [Integer] :tolerance max age of request in seconds (default: 300)
+      # @option timestamp_options [Symbol] :format timestamp format (:unix or :iso8601)
+      def initialize(secret:, header:, **options)
+        # Extract known options and pass remaining to parent (avoids ActiveSupport dependency)
+        known_keys = %i[algorithm encoding signature_prefix timestamp_options]
+        # rubocop:disable Style/HashExcept -- intentionally avoiding ActiveSupport's Hash#except
+        parent_options = options.reject { |k, _| known_keys.include?(k) }
+        # rubocop:enable Style/HashExcept
+        super(**parent_options)
+        @secret = secret
+        @header = header
+        @algorithm = validate_algorithm(options.fetch(:algorithm, 'sha256'))
+        @encoding = options.fetch(:encoding, DEFAULT_ENCODING)
+        @signature_prefix = options[:signature_prefix]
+        configure_timestamp_options(options[:timestamp_options])
+      end
+
+      # Verifies the HMAC signature of the request.
+      #
+      # @param request [Hooksmith::Request] the incoming request
+      # @raise [Hooksmith::VerificationError] if verification fails
+      # @return [void]
+      def verify!(request)
+        signature = extract_signature(request)
+        raise VerificationError.new('Missing signature header', reason: 'missing_signature') if signature.nil?
+
+        verify_timestamp!(request) if @timestamp_header
+
+        expected = compute_signature(request.body)
+
+        return if secure_compare(expected, signature)
+
+        raise VerificationError.new('Invalid signature', reason: 'signature_mismatch')
+      end
+
+      # Returns whether the verifier is properly configured.
+      #
+      # @return [Boolean] true if secret and header are present
+      def enabled?
+        !@secret.nil? && !@secret.empty? && !@header.nil? && !@header.empty?
+      end
+
+      private
+
+      # Configures timestamp validation options.
+      #
+      # @param timestamp_options [Hash, nil] timestamp options hash
+      def configure_timestamp_options(timestamp_options)
+        return unless timestamp_options
+
+        @timestamp_header = timestamp_options[:header]
+        @timestamp_tolerance = timestamp_options.fetch(:tolerance, 300)
+        @timestamp_format = timestamp_options.fetch(:format, :unix)
+      end
+
+      # Validates the HMAC algorithm.
+      #
+      # @param algorithm [String] the algorithm name
+      # @return [String] the validated algorithm
+      # @raise [ArgumentError] if the algorithm is not supported
+      def validate_algorithm(algorithm)
+        algo = algorithm.to_s.downcase
+        unless ALGORITHMS.include?(algo)
+          raise ArgumentError, "Unsupported algorithm: #{algorithm}. Supported: #{ALGORITHMS.join(', ')}"
+        end
+
+        algo
+      end
+
+      # Extracts the signature from the request headers.
+      #
+      # @param request [Hooksmith::Request] the incoming request
+      # @return [String, nil] the extracted signature
+      def extract_signature(request)
+        raw_signature = request.header(@header)
+        return nil if raw_signature.nil? || raw_signature.empty?
+
+        signature = raw_signature.to_s
+        signature = signature.sub(/\A#{Regexp.escape(@signature_prefix)}/, '') if @signature_prefix
+        signature.strip
+      end
+
+      # Computes the expected HMAC signature for the body.
+      #
+      # @param body [String] the request body
+      # @return [String] the computed signature
+      def compute_signature(body)
+        digest = OpenSSL::HMAC.digest(@algorithm, @secret, body)
+
+        case @encoding
+        when :base64
+          Base64.strict_encode64(digest)
+        else
+          digest.unpack1('H*')
+        end
+      end
+
+      # Verifies the timestamp is within tolerance.
+      #
+      # @param request [Hooksmith::Request] the incoming request
+      # @raise [Hooksmith::VerificationError] if timestamp is invalid or expired
+      def verify_timestamp!(request)
+        timestamp_value = request.header(@timestamp_header)
+        raise VerificationError.new('Missing timestamp header', reason: 'missing_timestamp') if timestamp_value.nil?
+
+        timestamp = parse_timestamp(timestamp_value)
+        raise VerificationError.new('Invalid timestamp format', reason: 'invalid_timestamp') if timestamp.nil?
+
+        age = (Time.now - timestamp).abs
+        return unless age > @timestamp_tolerance
+
+        raise VerificationError.new(
+          "Request timestamp too old (#{age.to_i}s > #{@timestamp_tolerance}s)",
+          reason: 'timestamp_expired'
+        )
+      end
+
+      # Parses a timestamp value.
+      #
+      # @param value [String] the timestamp value
+      # @return [Time, nil] the parsed time or nil if invalid
+      def parse_timestamp(value)
+        case @timestamp_format
+        when :iso8601
+          Time.iso8601(value)
+        else
+          Time.at(value.to_i)
+        end
+      rescue ArgumentError, TypeError
+        nil
+      end
+    end
+  end
+end

data/lib/hooksmith/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hooksmith
-  VERSION = '0.2.0'
+  VERSION = '1.0.0'
 end

data/lib/hooksmith.rb

@@ -1,14 +1,26 @@
 # frozen_string_literal: true
 
 require 'hooksmith/version'
+require 'hooksmith/errors'
 require 'hooksmith/configuration'
 require 'hooksmith/config/provider'
 require 'hooksmith/config/event_store'
+require 'hooksmith/request'
+require 'hooksmith/instrumentation'
 require 'hooksmith/dispatcher'
 require 'hooksmith/logger'
 require 'hooksmith/event_recorder'
+require 'hooksmith/idempotency'
 require 'hooksmith/processor/base'
-require 'hooksmith/railtie' if defined?(Rails)
+require 'hooksmith/jobs/dispatcher_job' if defined?(ActiveJob)
+require 'hooksmith/verifiers/base'
+require 'hooksmith/verifiers/hmac'
+require 'hooksmith/verifiers/bearer_token'
+
+if defined?(Rails)
+  require 'hooksmith/railtie'
+  require 'hooksmith/rails/webhooks_controller'
+end
 
 # Main entry point for the Hooksmith gem.
 #
@@ -21,6 +33,22 @@ require 'hooksmith/railtie' if defined?(Rails)
 #
 #   Hooksmith::Dispatcher.new(provider: :stripe, event: :charge_succeeded, payload: payload).run!
 #
+# @example With request verification:
+#   Hooksmith.configure do |config|
+#     config.provider(:stripe) do |stripe|
+#       stripe.verifier = Hooksmith::Verifiers::Hmac.new(
+#         secret: ENV['STRIPE_WEBHOOK_SECRET'],
+#         header: 'Stripe-Signature'
+#       )
+#       stripe.register(:charge_succeeded, MyStripeProcessor)
+#     end
+#   end
+#
+#   # In your controller:
+#   request = Hooksmith::Request.new(headers: request.headers, body: request.raw_post)
+#   Hooksmith.verify!(provider: :stripe, request: request)
+#   Hooksmith::Dispatcher.new(provider: :stripe, event: event, payload: payload).run!
+#
 module Hooksmith
   # Returns the configuration instance.
   # @return [Configuration] the configuration instance.
@@ -39,4 +67,26 @@ module Hooksmith
   def self.logger
     Logger.instance
   end
+
+  # Verifies an incoming webhook request for a provider.
+  #
+  # @param provider [Symbol, String] the provider name
+  # @param request [Hooksmith::Request] the incoming request
+  # @raise [Hooksmith::VerificationError] if verification fails
+  # @return [void]
+  def self.verify!(provider:, request:)
+    verifier = configuration.verifier_for(provider)
+    return unless verifier&.enabled?
+
+    verifier.verify!(request)
+  end
+
+  # Checks if a provider has a verifier configured.
+  #
+  # @param provider [Symbol, String] the provider name
+  # @return [Boolean] true if a verifier is configured
+  def self.verifier_configured?(provider)
+    verifier = configuration.verifier_for(provider)
+    verifier&.enabled? || false
+  end
 end