Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Harden webhook payload handling (#14335)
Damian Legawiecc91c92bfc10b
diff --git a/packages/admin-sdk/src/types/generated/WebhookDelivery.ts b/packages/admin-sdk/src/types/generated/WebhookDelivery.tsindex 88bf75a8cb..f758fd6ef9 100644--- a/packages/admin-sdk/src/types/generated/WebhookDelivery.ts+++ b/packages/admin-sdk/src/types/generated/WebhookDelivery.ts@@ -1,4 +1,4 @@-// Typelizer digest 520a8371e25fe869ad529fcd906a9aec+// Typelizer digest cbd21ce71269a0c670b712f661ab159a//// DO NOT MODIFY: This file was automatically generated by Typelizer.@@ -12,10 +12,10 @@ interface WebhookDelivery {request_errors: string | null;response_body: string | null;success: boolean | null;- payload: Record<string, unknown>;created_at: string;updated_at: string;delivered_at: string | null;+ payload: Record<string, unknown>;webhook_endpoint_id: string;webhook_endpoint_url: string;}diff --git a/spree/api/app/jobs/spree/webhook_delivery_job.rb b/spree/api/app/jobs/spree/webhook_delivery_job.rbindex 0e69b8fe93..5034273caf 100644--- a/spree/api/app/jobs/spree/webhook_delivery_job.rb+++ b/spree/api/app/jobs/spree/webhook_delivery_job.rb@@ -13,10 +13,15 @@ module Spree# Accept optional second argument for backward compatibility with jobs# enqueued before this change was deployed.- def perform(delivery_id, _deprecated_secret_key = nil)+ #+ # `payload_secrets` carries credentials withheld from the persisted payload+ # so the outgoing request body stays complete. See+ # {Spree::WebhookPayloadRedaction}.+ def perform(delivery_id, _deprecated_secret_key = nil, payload_secrets: nil)delivery = Spree::WebhookDelivery.find_by(id: delivery_id)return if delivery.nil?+ delivery.payload_secrets = payload_secretssecret_key = delivery.webhook_endpoint.secret_keySpree::Webhooks::DeliverWebhook.call(delivery: delivery, secret_key: secret_key)enddiff --git a/spree/api/app/serializers/spree/api/v3/admin/webhook_delivery_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/webhook_delivery_serializer.rbindex b13b264785..9906f469bc 100644--- a/spree/api/app/serializers/spree/api/v3/admin/webhook_delivery_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/admin/webhook_delivery_serializer.rb@@ -25,10 +25,15 @@ module Spreeattributes :event_name, :event_id, :response_code, :execution_time,:error_type, :request_errors, :response_body, :success,- :payload,created_at: :iso8601, updated_at: :iso8601,delivered_at: :iso8601+ # Redacted again on read: deliveries written before payload redaction+ # shipped still hold live credentials in the column.+ attribute :payload do |delivery|+ Spree::WebhookPayloadRedaction.split(delivery.payload).first+ end+attribute :webhook_endpoint_id do |delivery|delivery.webhook_endpoint&.prefixed_idenddiff --git a/spree/api/app/services/spree/webhooks/deliver_webhook.rb b/spree/api/app/services/spree/webhooks/deliver_webhook.rbindex 1c606891cd..1ed8e4cd00 100644--- a/spree/api/app/services/spree/webhooks/deliver_webhook.rb+++ b/spree/api/app/services/spree/webhooks/deliver_webhook.rb@@ -56,7 +56,7 @@ module Spree'X-Spree-Webhook-Timestamp' => webhook_timestamp.to_s,'X-Spree-Webhook-Event' => @delivery.event_name}- body = @delivery.payload.to_json+ body = payload_jsonhttp_options = { open_timeout: TIMEOUT, read_timeout: TIMEOUT, verify_mode: ssl_verify_mode }# SSRF protection is disabled in development so webhooks can reach@@ -77,10 +77,14 @@ module Spreeenddef generate_signature- payload_json = @delivery.payload.to_jsonOpenSSL::HMAC.hexdigest('SHA256', @secret_key, "#{webhook_timestamp}.#{payload_json}")end+ # Memoized so the signature is computed over exactly the bytes sent.+ def payload_json+ @payload_json ||= @delivery.deliverable_payload.to_json+ end+def webhook_timestamp@webhook_timestamp ||= Time.current.to_ienddiff --git a/spree/api/app/subscribers/spree/webhook_event_subscriber.rb b/spree/api/app/subscribers/spree/webhook_event_subscriber.rbindex 790e1f1493..7d4a080ca6 100644--- a/spree/api/app/subscribers/spree/webhook_event_subscriber.rb+++ b/spree/api/app/subscribers/spree/webhook_event_subscriber.rb@@ -56,13 +56,16 @@ module Spree)end+ # Live credentials go over the wire but never into the delivery log.+ persisted_payload, secrets = Spree::WebhookPayloadRedaction.split(payload)+delivery = endpoint.webhook_deliveries.create!(event_name: event.name,event_id: event.id,- payload: payload+ payload: persisted_payload)- Spree::WebhookDeliveryJob.perform_later(delivery.id)+ Spree::WebhookDeliveryJob.perform_later(delivery.id, payload_secrets: secrets)rescue ActiveRecord::RecordNotUnique# Race condition: another thread already created this delivery — safe to ignorerescue StandardError => ediff --git a/spree/api/spec/services/spree/webhooks/deliver_webhook_spec.rb b/spree/api/spec/services/spree/webhooks/deliver_webhook_spec.rbindex 4c51997c67..cb18a6fa9a 100644--- a/spree/api/spec/services/spree/webhooks/deliver_webhook_spec.rb+++ b/spree/api/spec/services/spree/webhooks/deliver_webhook_spec.rb@@ -11,6 +11,50 @@ module Spreelet(:secret_key) { webhook_endpoint.secret_key }describe '.call' do+ context 'when the payload had credentials withheld from the log' do+ let(:delivery) do+ create(+ :webhook_delivery, :pending,+ webhook_endpoint: webhook_endpoint,+ event_name: 'customer.password_reset_requested',+ payload: { 'name' => 'customer.password_reset_requested',+ 'data' => { 'email' => '[email protected]',+ 'reset_token' => Spree::WebhookPayloadRedaction::REDACTION_PLACEHOLDER } }+ )+ end++ before do+ delivery.payload_secrets = { 'reset_token' => 'live-token' }+ stub_request(:post, delivery.url).to_return(status: 200, body: '{}')+ end++ it 'sends the live token to the endpoint' do+ described_class.call(delivery: delivery, secret_key: secret_key)++ expect(WebMock).to have_requested(:post, delivery.url).with { |req|+ JSON.parse(req.body)['data']['reset_token'] == 'live-token'+ }+ end++ it 'signs the body that was actually sent' do+ Timecop.freeze do+ described_class.call(delivery: delivery, secret_key: secret_key)++ expect(WebMock).to have_requested(:post, delivery.url).with { |req|+ expected = OpenSSL::HMAC.hexdigest('SHA256', secret_key, "#{Time.current.to_i}.#{req.body}")+ req.headers['X-Spree-Webhook-Signature'] == expected+ }+ end+ end++ it 'leaves the persisted payload redacted after delivery' do+ described_class.call(delivery: delivery, secret_key: secret_key)++ expect(delivery.reload.payload['data']['reset_token']).+ to eq(Spree::WebhookPayloadRedaction::REDACTION_PLACEHOLDER)+ end+ end+context 'with successful response' dobefore dostub_request(:post, delivery.url)diff --git a/spree/api/spec/subscribers/spree/webhook_event_subscriber_spec.rb b/spree/api/spec/subscribers/spree/webhook_event_subscriber_spec.rbindex 0ab02df053..03a1b1be27 100644--- a/spree/api/spec/subscribers/spree/webhook_event_subscriber_spec.rb+++ b/spree/api/spec/subscribers/spree/webhook_event_subscriber_spec.rb@@ -30,6 +30,32 @@ module Spreeendend+ context 'with an event carrying a live credential' do+ let!(:webhook_endpoint) { create(:webhook_endpoint, store: store, subscriptions: ['*']) }+ let(:event_name) { 'customer.password_reset_requested' }+ let(:event_payload) { { reset_token: 'live-token', email: '[email protected]' } }++ it 'keeps the token out of the persisted delivery log' do+ described_class.new.handle(event)++ payload = Spree::WebhookDelivery.last.reload.payload+ expect(payload['data']['reset_token']).to eq(Spree::WebhookPayloadRedaction::REDACTION_PLACEHOLDER)+ expect(payload['data']['email']).to eq('[email protected]')+ end++ it 'still hands the live token to the delivery job' do+ described_class.new.handle(event)++ delivery = Spree::WebhookDelivery.last+ expect(Spree::WebhookDeliveryJob).to have_been_enqueued.with(delivery.id, payload_secrets: anything)++ # The secrets handed to the job must restore the payload the endpoint expects.+ secrets = enqueued_jobs.last['arguments'].last.symbolize_keys[:payload_secrets]+ delivery.payload_secrets = secrets+ expect(delivery.deliverable_payload['data']['reset_token']).to eq('live-token')+ end+ end+context 'when webhooks are enabled' doit 'creates a webhook delivery record' doexpect {diff --git a/spree/core/app/models/concerns/spree/webhook_payload_redaction.rb b/spree/core/app/models/concerns/spree/webhook_payload_redaction.rbnew file mode 100644index 0000000000..1b2456ac2d--- /dev/null+++ b/spree/core/app/models/concerns/spree/webhook_payload_redaction.rb@@ -0,0 +1,88 @@+# frozen_string_literal: true++module Spree+ # Keeps single-use credentials out of the persisted webhook delivery log.+ #+ # Some events must carry a live credential to their subscriber — a storefront+ # that owns its transactional emails needs the real password reset token to+ # build the email. Delivering it over TLS to a merchant-configured endpoint is+ # intended; keeping a readable copy in `spree_webhook_deliveries.payload` is+ # not, because that column is queryable and is served back through the Admin+ # API delivery log.+ #+ # Sensitive values are therefore replaced with {REDACTION_PLACEHOLDER} before+ # the record is written, and re-attached in memory at send time so the+ # outgoing request body is unchanged.+ module WebhookPayloadRedaction+ extend ActiveSupport::Concern++ # Payload keys under `data` whose values are live credentials.+ SENSITIVE_PAYLOAD_KEYS = %w[reset_token unsubscribe_token].freeze++ REDACTION_PLACEHOLDER = '[REDACTED]'++ # Splits a payload into the version safe to persist and the secrets held+ # back from it.+ #+ # @param payload [Hash] the full event payload+ # @return [Array(Hash, Hash)] redacted payload, and the extracted secrets+ # keyed as they appeared under `data`+ def self.split(payload)+ secrets = {}++ redacted = transform_data_hashes(payload) do |data|+ data.to_h do |key, value|+ if SENSITIVE_PAYLOAD_KEYS.include?(key.to_s) && value.present?+ secrets[secret_key_for(key)] = value+ [key, REDACTION_PLACEHOLDER]+ else+ [key, value]+ end+ end+ end++ secrets.empty? ? [payload, {}] : [redacted, secrets]+ end++ # Re-attaches previously extracted secrets to a redacted payload.+ #+ # @param payload [Hash] the redacted payload+ # @param secrets [Hash] secrets returned by {split}+ # @return [Hash] the payload as it should go over the wire+ def self.merge(payload, secrets)+ return payload if secrets.blank?++ transform_data_hashes(payload) do |data|+ data.to_h do |key, value|+ secret = secrets[secret_key_for(key)]+ [key, secret.presence || value]+ end+ end+ end++ # Applies +block+ to every `data` hash on the payload.+ #+ # Both key forms are visited rather than only the first match: a payload+ # carrying `:data` *and* `'data'` would otherwise leave one of them+ # unredacted.+ def self.transform_data_hashes(payload)+ return payload unless payload.is_a?(Hash)++ [:data, 'data'].reduce(payload) do |result, data_key|+ data = result[data_key]+ next result unless data.is_a?(Hash)++ result.merge(data_key => yield(data))+ end+ end+ private_class_method :transform_data_hashes++ # Secrets are keyed by name alone. They cross an ActiveJob serialization+ # boundary, which coerces symbol keys to strings, so the key form at split+ # time cannot be relied on to still match at merge time.+ def self.secret_key_for(key)+ key.to_s+ end+ private_class_method :secret_key_for+ end+enddiff --git a/spree/core/app/models/spree/webhook_delivery.rb b/spree/core/app/models/spree/webhook_delivery.rbindex dbe10ea898..fd1cd1bbc4 100644--- a/spree/core/app/models/spree/webhook_delivery.rb+++ b/spree/core/app/models/spree/webhook_delivery.rb@@ -7,6 +7,11 @@ module Spreebelongs_to :webhook_endpoint, class_name: 'Spree::WebhookEndpoint'delegate :url, to: :webhook_endpoint+ # Credentials stripped from the persisted payload. Never written to the+ # database — held in memory on a single delivery instance, assigned by+ # WebhookDeliveryJob when it runs. See {Spree::WebhookPayloadRedaction}.+ attr_accessor :payload_secrets+validates :event_name, presence: truevalidates :payload, presence: true@@ -64,6 +69,23 @@ module Spreewebhook_endpoint.check_auto_disable! unless is_successend+ # Payload as it should be sent over the wire.+ #+ # Re-attaches any credentials withheld from the persisted column. Once this+ # record has been reloaded from the database those secrets are gone for+ # good, so a redelivery sends the redacted placeholder — single-use tokens+ # are not replayable anyway.+ #+ # This is deliberate: keeping a recoverable copy would put the credential+ # back at rest, which is what redaction exists to prevent. If a delivery is+ # lost (worker crash between creation and delivery), the customer requests+ # a new reset, which mints a fresh token.+ #+ # @return [Hash]+ def deliverable_payload+ Spree::WebhookPayloadRedaction.merge(payload, payload_secrets)+ end+# Create a new delivery with the same payload and queue it.# Used to retry failed deliveries manually.#diff --git a/spree/core/spec/models/concerns/spree/webhook_payload_redaction_spec.rb b/spree/core/spec/models/concerns/spree/webhook_payload_redaction_spec.rbnew file mode 100644index 0000000000..55f5626d80--- /dev/null+++ b/spree/core/spec/models/concerns/spree/webhook_payload_redaction_spec.rb@@ -0,0 +1,91 @@+# frozen_string_literal: true++require 'spec_helper'++describe Spree::WebhookPayloadRedaction do+ let(:placeholder) { described_class::REDACTION_PLACEHOLDER }++ describe '.split' do+ it 'extracts sensitive keys and replaces them with the placeholder' do+ payload, secrets = described_class.split(+ 'name' => 'customer.password_reset_requested',+ 'data' => { 'email' => '[email protected]', 'reset_token' => 'live-token' }+ )++ expect(payload['data']['reset_token']).to eq(placeholder)+ expect(payload['data']['email']).to eq('[email protected]')+ expect(secrets).to eq('reset_token' => 'live-token')+ end++ it 'handles symbol keys' do+ original = { data: { unsubscribe_token: 'tok' } }++ payload, secrets = described_class.split(original)++ expect(payload[:data][:unsubscribe_token]).to eq(placeholder)+ expect(described_class.merge(payload, secrets)).to eq(original)+ end++ it 'returns the payload untouched when nothing is sensitive' do+ original = { 'data' => { 'number' => 'R123' } }++ expect(described_class.split(original)).to eq([original, {}])+ end++ it 'ignores payloads without a data hash' do+ expect(described_class.split('data' => nil)).to eq([{ 'data' => nil }, {}])+ end++ it 'redacts both data hashes when the payload carries :data and "data"' do+ payload, _secrets = described_class.split(+ :data => { 'reset_token' => 'sym-side' },+ 'data' => { 'reset_token' => 'str-side' }+ )++ expect(payload[:data]['reset_token']).to eq(placeholder)+ expect(payload['data']['reset_token']).to eq(placeholder)+ end++ it 'redacts every form of a sensitive key present in the same data hash' do+ payload, secrets = described_class.split(+ 'data' => { :reset_token => 'sym-tok', 'reset_token' => 'str-tok' }+ )++ expect(payload['data'].values).to all(eq(placeholder))+ expect(secrets.keys).to eq(['reset_token'])+ end++ # Secrets survive an ActiveJob round trip, which stringifies symbol keys.+ it 'restores a payload whose keys were stringified in transit' do+ _payload, secrets = described_class.split(data: { reset_token: 'live-token' })+ persisted = { 'data' => { 'reset_token' => placeholder } }++ restored = described_class.merge(persisted, JSON.parse(secrets.to_json))++ expect(restored['data']['reset_token']).to eq('live-token')+ end+ end++ describe '.merge' do+ it 'restores extracted secrets' do+ redacted = { 'data' => { 'email' => '[email protected]', 'reset_token' => placeholder } }++ restored = described_class.merge(redacted, 'reset_token' => 'live-token')++ expect(restored['data']['reset_token']).to eq('live-token')+ expect(restored['data']['email']).to eq('[email protected]')+ end++ it 'leaves the payload redacted when no secrets are held' do+ redacted = { 'data' => { 'reset_token' => placeholder } }++ expect(described_class.merge(redacted, nil)).to eq(redacted)+ end+ end++ it 'round-trips to the original payload' do+ original = { 'data' => { 'email' => '[email protected]', 'reset_token' => 'live-token' } }++ expect(described_class.merge(*described_class.split(original))).to eq(original)+ end+end