hooksmith 0.1.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c80476ba099d00e9dfefb14d1b05d696a4b5cef3eb655e6f145c334e86fcf1ac
-  data.tar.gz: 4c1e6ae0d6cdfe4e1a013e2028b446912a636b295d949d499801e83ce4a640c8
+  metadata.gz: 1c87efd7d2887fc38d26d7615fbb913efaa086f09b0753b84479d41f87c4a4fd
+  data.tar.gz: 395f26ad9af550a7d64596edd3f23a486db879f8fc71aa9e2997a4e468eb785e
 SHA512:
-  metadata.gz: 0c004376be79241af2a779aa9eeafe4bd4075d09ab45da029d8c9d88ed6faa2d1248652b160ac0761a107c7e0ddddec81a41cec8ed1f5e147f1e6f43d8dd9ca0
-  data.tar.gz: c555b8226888a88774fb0fd97bd3b57a1741a35bdd615d462bbd479786ab6a1aede0875a070cb9fcbc0d76f4b3ad6ac85256ff023dd2d9e9ccd552fcd8d928fe
+  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,91 +34,363 @@ 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
 ```
 
-## Implementing a Processor
+### 2. Create a Processor
+
 Create a processor by inheriting from `Hooksmith::Processor::Base`:
 
 ```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
+class Stripe::ChargeSucceededProcessor < Hooksmith::Processor::Base
+  def can_handle?(payload)
+    payload.dig('data', 'object', 'status') == 'succeeded'
+  end
 
-        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
+  def process!
+    charge_id = payload.dig('data', 'object', 'id')
+    Payment.find_by(stripe_charge_id: charge_id)&.mark_as_paid!
   end
 end
 ```
 
-## Dispatching a Webhook
-
-Use the dispatcher in your webhook controller:
+### 3. Handle Webhooks in Your Controller
 
 ```ruby
 class WebhooksController < ApplicationController
   skip_before_action :verify_authenticity_token
 
-  def receive
-    provider = params[:provider] || "stripe"
-    event    = params[:event]    || "charge_succeeded"
-    payload  = params[:data]     # Adjust extraction as needed
+  def stripe
+    Hooksmith::Dispatcher.new(
+      provider: :stripe,
+      event: params[:type],
+      payload: params.to_unsafe_h
+    ).run!
 
-    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
+    head :internal_server_error
   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:
+## 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
+
+  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
+  self.table_name = 'webhook_events'
+end
+```
+
+### 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 [:provider, :idempotency_key], unique: true
+  t.index :event
+  t.index :received_at
+end
+```
+
+### 3. Configure the Event Store
+
+```ruby
+Hooksmith.configure do |config|
+  config.event_store do |store|
+    store.enabled = true
+    store.model_class_name = 'WebhookEvent'
+    store.record_timing = :before
+    store.mapper = ->(provider:, event:, payload:) {
+      {
+        provider: provider.to_s,
+        event: event.to_s,
+        payload: payload,
+        received_at: Time.current
+      }
+    }
+  end
+end
+```
+
+## Error Handling
+
+Hooksmith provides specific error classes for different failure modes:
+
+| 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
+```
+
+## Testing
+
+The gem includes a full test suite using Minitest. Run the tests with:
+
+```bash
 bundle exec rake test
 ```
 
-If you want to check test coverage, you can integrate SimpleCov by adding the following at the top of your test/test_helper.rb:
+### Testing Your Processors
 
 ```ruby
-require "simplecov"
-SimpleCov.start
+class ChargeSucceededProcessorTest < ActiveSupport::TestCase
+  test 'processes successful charges' do
+    payload = { 'data' => { 'object' => { 'id' => 'ch_123', 'status' => 'succeeded' } } }
+    processor = Stripe::ChargeSucceededProcessor.new(payload)
+
+    assert processor.can_handle?(payload)
+    processor.process!
+
+    assert Payment.find_by(stripe_charge_id: 'ch_123').paid?
+  end
+end
 ```
 
-Then run the tests to generate a coverage report.
+## Configuration Reference
+
+```ruby
+Hooksmith.configure do |config|
+  config.provider(:stripe) do |stripe|
+    stripe.register(:charge_succeeded, 'Stripe::ChargeSucceededProcessor')
+
+    stripe.verifier = Hooksmith::Verifiers::Hmac.new(
+      secret: ENV['STRIPE_WEBHOOK_SECRET'],
+      header: 'Stripe-Signature',
+      algorithm: :sha256
+    )
+
+    stripe.idempotency_key = ->(payload) { payload['id'] }
+  end
+
+  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/event_store.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Hooksmith
+  module Config
+    # EventStore holds settings for optional event persistence.
+    class EventStore
+      # Whether persistence is enabled.
+      attr_accessor :enabled
+      # Class name of the model used to persist events. Must respond to .create!(attrs)
+      attr_accessor :model_class_name
+      # Proc to map provider/event/payload to attributes persisted
+      attr_accessor :mapper
+      # When to record: :before, :after, or :both
+      attr_accessor :record_timing
+
+      def initialize
+        @enabled = false
+        # No default model in the gem; applications should provide their own model
+        @model_class_name = nil
+        @record_timing = :before
+        @mapper = default_mapper
+      end
+
+      def model_class
+        return nil if model_class_name.nil?
+
+        Object.const_get(model_class_name)
+      rescue NameError
+        nil
+      end
+
+      private
+
+      def default_mapper
+        lambda do |provider:, event:, payload:|
+          now = Time.respond_to?(:current) ? Time.current : Time.now
+          {
+            provider: provider.to_s,
+            event: event.to_s,
+            payload:,
+            received_at: now
+          }
+        end
+      end
+    end
+  end
+end

data/lib/hooksmith/config/provider.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Hooksmith
+  module Config
+    # 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 [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.to_s
+        @entries = []
+        @verifier = nil
+        @idempotency_key = nil
+      end
+
+      # Registers a processor for a specific event.
+      #
+      # @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_s, processor: processor_class_name }
+      end
+    end
+  end
+end