hooksmith 0.1.2 → 1.0.0

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.1.2'
+  VERSION = '1.0.0'
 end

data/lib/hooksmith.rb

@@ -1,11 +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.
 #
@@ -18,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.
@@ -36,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

metadata

@@ -1,14 +1,34 @@
 --- !ruby/object:Gem::Specification
 name: hooksmith
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 1.0.0
 platform: ruby
 authors:
 - gregoryrivage
 bindir: exe
 cert_chain: []
-date: 2025-03-13 00:00:00.000000000 Z
-dependencies: []
+date: 2025-12-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
 description: Hooksmith is a gem that allows you to handle webhooks in your Rails application.
   It provides a simple and flexible way to receive, validate, and process webhooks
   from various services. With Hooksmith, you can easily configure webhook endpoints,
@@ -27,13 +47,24 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- hooksmith-0.1.0.gem
 - lib/hooksmith.rb
+- lib/hooksmith/config/event_store.rb
+- lib/hooksmith/config/provider.rb
 - lib/hooksmith/configuration.rb
 - lib/hooksmith/dispatcher.rb
+- lib/hooksmith/errors.rb
+- lib/hooksmith/event_recorder.rb
+- lib/hooksmith/idempotency.rb
+- lib/hooksmith/instrumentation.rb
+- lib/hooksmith/jobs/dispatcher_job.rb
 - lib/hooksmith/logger.rb
 - lib/hooksmith/processor/base.rb
+- lib/hooksmith/rails/webhooks_controller.rb
 - lib/hooksmith/railtie.rb
+- lib/hooksmith/request.rb
+- lib/hooksmith/verifiers/base.rb
+- lib/hooksmith/verifiers/bearer_token.rb
+- lib/hooksmith/verifiers/hmac.rb
 - lib/hooksmith/version.rb
 - sig/hooksmith.rbs
 homepage: https://github.com/gregoryrivage/hooksmith