hooksmith 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82cacda1d785736b14476d699c2d18e90d65036f2b4e291d03dd2b393a907d14
-  data.tar.gz: 65407cf717e2e3ac6edede0392ed319250b3e0c06fc61dc0d730fd82fafead3c
+  metadata.gz: 1c87efd7d2887fc38d26d7615fbb913efaa086f09b0753b84479d41f87c4a4fd
+  data.tar.gz: 395f26ad9af550a7d64596edd3f23a486db879f8fc71aa9e2997a4e468eb785e
 SHA512:
-  metadata.gz: bbd5f49b4248a597997816a03c0e9624c93ec3fe8185837398564360a16663defe758463ba2528f1af38e53e0816fadf1b61d5243591835f8b84cd9c822a7f40
-  data.tar.gz: b13ef16ba8d73c011c410ca838575f9a4eb8b3bdc58560b392cf88350f8520d0752a7081e556dc649fa5e6ad89441e975bde9e57085717b98356516a6e801f81
+  metadata.gz: b2d5953050726bec3601f37656b51a8d98f242e119058df1bca090568e9d99fd47dcde8d0788a4077dfc2dbe27f426a06d70ce85546edd36f0bbb80f91c1c237
+  data.tar.gz: 8e20347d959d17c8c03da4e969e06c5158ad9c083ae675aaaeeee86fb7cc8051ea11cdc780922d4c504b0775f2d754309aa97a6f0e587678dd8a96abe46bae89

data/CHANGELOG.md

@@ -1,5 +1,57 @@
 ## [Unreleased]
 
+## [1.0.0] - 2025-12-25
+
+### Added
+
+- **Request Verification Interface** - Built-in verifiers for HMAC and Bearer token authentication
+  - `Hooksmith::Verifiers::Hmac` for HMAC-based signature verification
+  - `Hooksmith::Verifiers::BearerToken` for Bearer token authentication
+  - `Hooksmith::Verifiers::Base` for creating custom verifiers
+  - `Hooksmith::Request` wrapper for accessing headers and body
+
+- **Error Taxonomy** - Explicit error classes for different failure modes
+  - `Hooksmith::Error` base class for all Hooksmith errors
+  - `Hooksmith::VerificationError` for signature verification failures
+
+- **Idempotency Support** - Prevent duplicate webhook processing
+  - Configurable idempotency key extraction per provider
+  - Pre-built extractors for Stripe, GitHub, and generic webhooks
+  - `Hooksmith::Idempotency.extract_key` and `already_processed?` methods
+
+- **ActiveJob Integration** - Process webhooks asynchronously
+  - `Hooksmith::Jobs::DispatcherJob` for background processing
+  - Automatic idempotency checking (can be skipped)
+
+- **Instrumentation** - ActiveSupport::Notifications hooks for observability
+  - `dispatch.hooksmith` event wrapping the entire dispatch flow
+  - `process.hooksmith` event wrapping processor execution
+  - `no_processor.hooksmith` event when no processor matches
+  - `multiple_processors.hooksmith` event when multiple processors match
+  - `error.hooksmith` event when an error occurs
+
+- **Rails Controller Concern** - Standardized webhook handling
+  - `Hooksmith::Rails::WebhooksController` concern
+  - `handle_webhook` for synchronous processing
+  - `handle_webhook_async` for background processing
+  - Automatic CSRF protection skip
+  - Optional signature verification integration
+
+### Changed
+
+- Internal storage now uses strings instead of symbols to prevent Symbol DoS attacks
+- `MultipleProcessorsError` no longer includes full payload in error message to prevent PII exposure
+
+### Security
+
+- Fixed Symbol DoS vulnerability in Dispatcher (provider/event were converted to symbols from untrusted input)
+- Fixed PII exposure in `MultipleProcessorsError` (full payload was included in error message)
+
+## [0.2.0] - 2025-03-15
+
+- Added event store for persisting webhook events
+- Added configurable mapper for event persistence
+
 ## [0.1.0] - 2025-03-12
 
 - Initial release

data/README.md

@@ -6,16 +6,21 @@
 
 - **DSL for Registration:** Group processors by provider and event.
 - **Flexible Dispatcher:** Dynamically selects the appropriate processor based on payload conditions.
+- **Request Verification:** Built-in support for HMAC and Bearer token authentication.
+- **Idempotency Support:** Prevent duplicate webhook processing with configurable key extraction.
+- **ActiveJob Integration:** Process webhooks asynchronously with automatic idempotency checks.
+- **Instrumentation:** ActiveSupport::Notifications hooks for observability.
+- **Rails Controller Concern:** Standardized webhook handling with consistent response codes.
 - **Rails Integration:** Automatically configures with Rails using a Railtie.
 - **Lightweight Logging:** Built-in logging that can be switched to `Rails.logger` when in a Rails environment.
-- **Tested with Minitest:** 100% branch coverage for robust behavior.
+- **Tested with Minitest:** Comprehensive test coverage for robust behavior.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'hooksmith', '~> 0.1.1'
+gem 'hooksmith', '~> 1.0'
 ```
 
 Then execute:
@@ -29,30 +34,244 @@ Or install it yourself as:
 gem install hooksmith
 ```
 
-## Usage
+## Quick Start
 
-### Configuration
+### 1. Configure Providers and Processors
 
 Configure your webhook processors in an initializer (e.g., `config/initializers/hooksmith.rb`):
 
 ```ruby
 Hooksmith.configure do |config|
   config.provider(:stripe) do |stripe|
-    stripe.register(:charge_succeeded, 'Stripe::Processor::ChargeSucceeded::First')
-    stripe.register(:charge_succeeded, 'Stripe::Processor::ChargeSucceeded::Second')
+    stripe.register(:charge_succeeded, 'Stripe::ChargeSucceededProcessor')
+    stripe.register(:payment_failed, 'Stripe::PaymentFailedProcessor')
   end
 
-  config.provider(:paypal) do |paypal|
-    paypal.register(:payment_received, 'Paypal::Processor::PaymentReceived')
+  config.provider(:github) do |github|
+    github.register(:push, 'Github::PushProcessor')
+    github.register(:pull_request, 'Github::PullRequestProcessor')
   end
 end
 ```
 
-### Persisting Webhook Events (Optional)
+### 2. Create a Processor
 
-Hooksmith can optionally persist incoming webhook events to your database. Configure it with your own ActiveRecord model and mapping logic.
+Create a processor by inheriting from `Hooksmith::Processor::Base`:
+
+```ruby
+class Stripe::ChargeSucceededProcessor < Hooksmith::Processor::Base
+  def can_handle?(payload)
+    payload.dig('data', 'object', 'status') == 'succeeded'
+  end
+
+  def process!
+    charge_id = payload.dig('data', 'object', 'id')
+    Payment.find_by(stripe_charge_id: charge_id)&.mark_as_paid!
+  end
+end
+```
+
+### 3. Handle Webhooks in Your Controller
+
+```ruby
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def stripe
+    Hooksmith::Dispatcher.new(
+      provider: :stripe,
+      event: params[:type],
+      payload: params.to_unsafe_h
+    ).run!
+
+    head :ok
+  rescue StandardError => e
+    head :internal_server_error
+  end
+end
+```
+
+## Request Verification
+
+Hooksmith provides built-in verifiers for common authentication patterns.
+
+### HMAC Verification
+
+```ruby
+Hooksmith.configure do |config|
+  config.provider(:stripe) do |stripe|
+    stripe.verifier = Hooksmith::Verifiers::Hmac.new(
+      secret: ENV['STRIPE_WEBHOOK_SECRET'],
+      header: 'Stripe-Signature',
+      algorithm: :sha256
+    )
+  end
+end
+```
+
+### Bearer Token Verification
+
+```ruby
+Hooksmith.configure do |config|
+  config.provider(:internal) do |internal|
+    internal.verifier = Hooksmith::Verifiers::BearerToken.new(
+      token: ENV['WEBHOOK_SECRET_TOKEN'],
+      header: 'Authorization'
+    )
+  end
+end
+```
+
+### Custom Verifier
+
+Create your own verifier by inheriting from `Hooksmith::Verifiers::Base`:
+
+```ruby
+class MyCustomVerifier < Hooksmith::Verifiers::Base
+  def verify!(request)
+    signature = request.headers['X-Custom-Signature']
+    expected = compute_signature(request.body)
+
+    raise Hooksmith::VerificationError, 'Invalid signature' unless secure_compare(signature, expected)
+  end
+
+  private
 
-1) Create a model in your app (example):
+  def compute_signature(body)
+    OpenSSL::HMAC.hexdigest('SHA256', @secret, body)
+  end
+end
+```
+
+## Idempotency Support
+
+Prevent duplicate webhook processing by configuring idempotency key extraction:
+
+```ruby
+Hooksmith.configure do |config|
+  config.provider(:stripe) do |stripe|
+    stripe.idempotency_key = ->(payload) { payload.dig('id') }
+  end
+
+  config.provider(:github) do |github|
+    github.idempotency_key = Hooksmith::Idempotency::GITHUB
+  end
+end
+```
+
+### Pre-built Extractors
+
+Hooksmith includes pre-built extractors for common providers:
+
+- `Hooksmith::Idempotency::STRIPE` - Extracts from `id` field
+- `Hooksmith::Idempotency::GITHUB` - Extracts from `X-GitHub-Delivery` header
+- `Hooksmith::Idempotency::GENERIC` - Extracts from `id`, `event_id`, or `request_id`
+
+### Checking for Duplicates
+
+```ruby
+key = Hooksmith::Idempotency.extract_key(provider: 'stripe', payload: params)
+if Hooksmith::Idempotency.already_processed?(provider: 'stripe', key: key)
+  head :ok
+  return
+end
+```
+
+## ActiveJob Integration
+
+Process webhooks asynchronously with automatic idempotency checking:
+
+```ruby
+class WebhooksController < ApplicationController
+  def stripe
+    Hooksmith::Jobs::DispatcherJob.perform_later(
+      provider: 'stripe',
+      event: params[:type],
+      payload: params.to_unsafe_h
+    )
+
+    head :ok
+  end
+end
+```
+
+Skip idempotency checking if needed:
+
+```ruby
+Hooksmith::Jobs::DispatcherJob.perform_later(
+  provider: 'stripe',
+  event: params[:type],
+  payload: params.to_unsafe_h,
+  skip_idempotency_check: true
+)
+```
+
+## Rails Controller Concern
+
+Use the built-in controller concern for standardized webhook handling:
+
+```ruby
+class WebhooksController < ApplicationController
+  include Hooksmith::Rails::WebhooksController
+
+  def stripe
+    handle_webhook(
+      provider: 'stripe',
+      event: params[:type],
+      payload: params.to_unsafe_h
+    )
+  end
+
+  def github
+    handle_webhook_async(
+      provider: 'github',
+      event: request.headers['X-GitHub-Event'],
+      payload: params.to_unsafe_h
+    )
+  end
+end
+```
+
+The concern provides:
+- Automatic CSRF protection skip
+- Optional signature verification (if configured)
+- Consistent response codes (200, 401, 500)
+- `handle_webhook` for synchronous processing
+- `handle_webhook_async` for background processing
+
+## Instrumentation
+
+Hooksmith emits ActiveSupport::Notifications events for observability:
+
+```ruby
+ActiveSupport::Notifications.subscribe(/hooksmith/) do |name, start, finish, id, payload|
+  Rails.logger.info "#{name}: #{payload.inspect} (#{finish - start}s)"
+end
+```
+
+### Available Events
+
+| Event | Description |
+|-------|-------------|
+| `dispatch.hooksmith` | Wraps the entire dispatch flow |
+| `process.hooksmith` | Wraps processor execution |
+| `no_processor.hooksmith` | When no processor matches |
+| `multiple_processors.hooksmith` | When multiple processors match |
+| `error.hooksmith` | When an error occurs |
+
+### Subscribing to Specific Events
+
+```ruby
+Hooksmith::Instrumentation.subscribe('process') do |name, start, finish, id, payload|
+  StatsD.timing("webhooks.#{payload[:provider]}.#{payload[:event]}", finish - start)
+end
+```
+
+## Persisting Webhook Events
+
+Hooksmith can optionally persist incoming webhook events to your database:
+
+### 1. Create a Model
 
 ```ruby
 class WebhookEvent < ApplicationRecord
@@ -60,106 +279,118 @@ class WebhookEvent < ApplicationRecord
 end
 ```
 
-2) Example migration (customize fields as needed):
+### 2. Create a Migration
 
 ```ruby
 create_table :webhook_events do |t|
   t.string   :provider
   t.string   :event
   t.jsonb    :payload
+  t.string   :idempotency_key
   t.datetime :received_at
   t.timestamps
-  t.index    :event
-  t.index    :received_at
+
+  t.index [:provider, :idempotency_key], unique: true
+  t.index :event
+  t.index :received_at
 end
 ```
 
-3) Configure Hooksmith to record events:
+### 3. Configure the Event Store
 
 ```ruby
 Hooksmith.configure do |config|
   config.event_store do |store|
     store.enabled = true
-    store.model_class_name = 'WebhookEvent' # your model class
-    store.record_timing = :before # :before, :after, or :both
+    store.model_class_name = 'WebhookEvent'
+    store.record_timing = :before
     store.mapper = ->(provider:, event:, payload:) {
       {
         provider: provider.to_s,
         event: event.to_s,
-        payload:,
-        received_at: (Time.respond_to?(:current) ? Time.current : Time.now)
+        payload: payload,
+        received_at: Time.current
       }
     }
   end
 end
 ```
 
-## Implementing a Processor
-Create a processor by inheriting from `Hooksmith::Processor::Base`:
+## Error Handling
 
-```ruby
-module Stripe
-  module Processor
-    module ChargeSucceeded
-      class Tenant < Hooksmith::Processor::Base
-        # Only handle events with a tenant_payment_id.
-        def can_handle?(payload)
-          payload.dig("metadata", "id").present?
-        end
+Hooksmith provides specific error classes for different failure modes:
 
-        def process!
-          tenant_payment_id = payload.dig("metadata", "id")
-          # Add your business logic here (e.g., update database records).
-          puts "Processed id : #{id}"
-        end
-      end
-    end
-  end
+| Error Class | Description |
+|-------------|-------------|
+| `Hooksmith::Error` | Base error class |
+| `Hooksmith::VerificationError` | Request signature verification failed |
+| `Hooksmith::MultipleProcessorsError` | Multiple processors matched the payload |
+
+```ruby
+begin
+  Hooksmith::Dispatcher.new(provider:, event:, payload:).run!
+rescue Hooksmith::VerificationError => e
+  render json: { error: 'Invalid signature' }, status: :unauthorized
+rescue Hooksmith::MultipleProcessorsError => e
+  render json: { error: 'Ambiguous processor' }, status: :unprocessable_entity
+rescue StandardError => e
+  render json: { error: 'Processing failed' }, status: :internal_server_error
 end
 ```
 
-## Dispatching a Webhook
+## Testing
 
-Use the dispatcher in your webhook controller:
+The gem includes a full test suite using Minitest. Run the tests with:
+
+```bash
+bundle exec rake test
+```
+
+### Testing Your Processors
 
 ```ruby
-class WebhooksController < ApplicationController
-  skip_before_action :verify_authenticity_token
+class ChargeSucceededProcessorTest < ActiveSupport::TestCase
+  test 'processes successful charges' do
+    payload = { 'data' => { 'object' => { 'id' => 'ch_123', 'status' => 'succeeded' } } }
+    processor = Stripe::ChargeSucceededProcessor.new(payload)
 
-  def receive
-    provider = params[:provider] || "stripe"
-    event    = params[:event]    || "charge_succeeded"
-    payload  = params[:data]     # Adjust extraction as needed
+    assert processor.can_handle?(payload)
+    processor.process!
 
-    Hooksmith::Dispatcher.new(provider: provider, event: event, payload: payload).run!
-    head :ok
-  rescue Hooksmith::MultipleProcessorsError => e
-    render json: { error: e.message }, status: :unprocessable_entity
-  rescue StandardError => e
-    render json: { error: e.message }, status: :internal_server_error
+    assert Payment.find_by(stripe_charge_id: 'ch_123').paid?
   end
 end
 ```
 
-## Testing
-The gem includes a full test suite using Minitest with 100% branch coverage. See the test/ directory for examples. You can run the tests with:
+## Configuration Reference
 
-```
-bundle exec rake test
-```
+```ruby
+Hooksmith.configure do |config|
+  config.provider(:stripe) do |stripe|
+    stripe.register(:charge_succeeded, 'Stripe::ChargeSucceededProcessor')
 
-If you want to check test coverage, you can integrate SimpleCov by adding the following at the top of your test/test_helper.rb:
+    stripe.verifier = Hooksmith::Verifiers::Hmac.new(
+      secret: ENV['STRIPE_WEBHOOK_SECRET'],
+      header: 'Stripe-Signature',
+      algorithm: :sha256
+    )
 
-```ruby
-require "simplecov"
-SimpleCov.start
-```
+    stripe.idempotency_key = ->(payload) { payload['id'] }
+  end
 
-Then run the tests to generate a coverage report.
+  config.event_store do |store|
+    store.enabled = true
+    store.model_class_name = 'WebhookEvent'
+    store.record_timing = :before
+    store.mapper = ->(provider:, event:, payload:) { ... }
+  end
+end
+```
 
 ## Contributing
-Bug reports and pull requests are welcome on GitHub at https://github.com/gregorypreve/hooksmith.
 
+Bug reports and pull requests are welcome on GitHub at https://github.com/RivageImmo/Hooksmith.
 
 ## License
+
 The gem is available as open source under the terms of the MIT License.

data/lib/hooksmith/config/provider.rb

@@ -2,16 +2,37 @@
 
 module Hooksmith
   module Config
-    # Provider is used internally by the DSL to collect processor registrations.
+    # Provider is used internally by the DSL to collect processor registrations,
+    # optional verifier configuration, and idempotency settings.
+    #
+    # Uses string keys internally to prevent Symbol DoS attacks when processing
+    # untrusted webhook input.
     class Provider
-      # @return [Symbol, String] the provider name.
+      # @return [String] the provider name.
       attr_reader :provider
       # @return [Array<Hash>] list of entries registered.
       attr_reader :entries
+      # @return [Hooksmith::Verifiers::Base, nil] the verifier for this provider.
+      # @example
+      #   config.provider(:stripe) do |stripe|
+      #     stripe.verifier = Hooksmith::Verifiers::Hmac.new(
+      #       secret: ENV['STRIPE_WEBHOOK_SECRET'],
+      #       header: 'Stripe-Signature'
+      #     )
+      #   end
+      attr_accessor :verifier
+      # @return [Proc, nil] the idempotency key extractor for this provider.
+      # @example
+      #   config.provider(:stripe) do |stripe|
+      #     stripe.idempotency_key = ->(payload) { payload['id'] }
+      #   end
+      attr_accessor :idempotency_key
 
       def initialize(provider)
-        @provider = provider
+        @provider = provider.to_s
         @entries = []
+        @verifier = nil
+        @idempotency_key = nil
       end
 
       # Registers a processor for a specific event.
@@ -19,7 +40,7 @@ module Hooksmith
       # @param event [Symbol, String] the event name.
       # @param processor_class_name [String] the processor class name.
       def register(event, processor_class_name)
-        entries << { event: event.to_sym, processor: processor_class_name }
+        entries << { event: event.to_s, processor: processor_class_name }
       end
     end
   end

data/lib/hooksmith/configuration.rb

@@ -3,16 +3,27 @@
 # Provides a DSL for registering webhook processors by provider and event.
 #
 module Hooksmith
-  # Configuration holds the registry of all processors.
+  # Configuration holds the registry of all processors, verifiers, and idempotency settings.
+  #
+  # The registry uses string keys internally to prevent Symbol DoS attacks
+  # when processing untrusted webhook input. Provider and event names from
+  # external sources are converted to strings, not symbols.
   class Configuration
-    # @return [Hash] a registry mapping provider symbols to arrays of processor entries.
+    # @return [Hash] a registry mapping provider strings to arrays of processor entries.
     attr_reader :registry
+    # @return [Hash] a registry mapping provider strings to verifier instances.
+    attr_reader :verifiers
+    # @return [Hash] a registry mapping provider strings to idempotency key extractors.
+    attr_reader :idempotency_keys
     # @return [Hooksmith::Config::EventStore] configuration for event persistence
     attr_reader :event_store_config
 
     def initialize
-      # Registry structure: { provider_symbol => [{ event: event_symbol, processor: ProcessorClass }, ...] }
+      # Registry structure: { "provider" => [{ event: "event", processor: "ProcessorClass" }, ...] }
+      # Uses strings to prevent Symbol DoS from untrusted webhook input
       @registry = Hash.new { |hash, key| hash[key] = [] }
+      @verifiers = {}
+      @idempotency_keys = {}
       @event_store_config = Hooksmith::Config::EventStore.new
     end
 
@@ -23,7 +34,10 @@ module Hooksmith
     def provider(provider_name)
       provider_config = Hooksmith::Config::Provider.new(provider_name)
       yield(provider_config)
-      registry[provider_name.to_sym].concat(provider_config.entries)
+      provider_key = provider_name.to_s
+      registry[provider_key].concat(provider_config.entries)
+      @verifiers[provider_key] = provider_config.verifier if provider_config.verifier
+      @idempotency_keys[provider_key] = provider_config.idempotency_key if provider_config.idempotency_key
     end
 
     # Direct registration of a processor.
@@ -32,7 +46,7 @@ module Hooksmith
     # @param event [Symbol, String] the event name
     # @param processor_class_name [String] the processor class name
     def register_processor(provider, event, processor_class_name)
-      registry[provider.to_sym] << { event: event.to_sym, processor: processor_class_name }
+      registry[provider.to_s] << { event: event.to_s, processor: processor_class_name }
     end
 
     # Returns all processor entries for a given provider and event.
@@ -41,7 +55,31 @@ module Hooksmith
     # @param event [Symbol, String] the event name
     # @return [Array<Hash>] the array of matching entries.
     def processors_for(provider, event)
-      registry[provider.to_sym].select { |entry| entry[:event] == event.to_sym }
+      registry[provider.to_s].select { |entry| entry[:event] == event.to_s }
+    end
+
+    # Returns the verifier for a given provider.
+    #
+    # @param provider [Symbol, String] the provider name
+    # @return [Hooksmith::Verifiers::Base, nil] the verifier or nil if not configured
+    def verifier_for(provider)
+      @verifiers[provider.to_s]
+    end
+
+    # Registers a verifier for a provider directly.
+    #
+    # @param provider [Symbol, String] the provider name
+    # @param verifier [Hooksmith::Verifiers::Base] the verifier instance
+    def register_verifier(provider, verifier)
+      @verifiers[provider.to_s] = verifier
+    end
+
+    # Returns the idempotency key extractor for a given provider.
+    #
+    # @param provider [Symbol, String] the provider name
+    # @return [Proc, nil] the idempotency key extractor or nil if not configured
+    def idempotency_key_for(provider)
+      @idempotency_keys[provider.to_s]
     end
 
     # Configure event store persistence.
@@ -54,7 +92,8 @@ module Hooksmith
     #       store.model_class_name = 'MyApp::WebhookEvent'
     #       store.record_timing = :before # or :after, or :both
     #       store.mapper = ->(provider:, event:, payload:) {
-    #         { provider:, event: event.to_s, payload:, received_at: (Time.respond_to?(:current) ? Time.current : Time.now) }
+    #         now = Time.respond_to?(:current) ? Time.current : Time.now
+    #         { provider:, event: event.to_s, payload:, received_at: now }
     #       }
     #     end
     #   end