bouncy 0.1.0 → 0.2.0

data/lib/bouncy/interceptor.rb

@@ -1,30 +1,83 @@
 # frozen_string_literal: true
 
 module Bouncy
+  # Checks the recipients of every mail where Mail hands it to the transport.
+  #
+  # Mail calls delivering_email before each delivery. It stamps the configuration-set header and
+  # wraps the message's delivery method in a Gate. Mail's deliver and deliver! both end in that
+  # delivery method, after every interceptor and every Action Mailer callback, so the Gate
+  # decides on the recipients the transport would really get. In :drop mode it removes blocked
+  # recipients, and when none is left it does not call the transport: deliver_now!,
+  # deliver_later! and their plain forms all send nothing.
   class Interceptor
-    def self.delivering_email(message)
-      return if Bouncy.configuration.interception == :off || ActiveSupport::IsolatedExecutionState[:bouncy_unblocked]
-      return Bouncy.unconfigured!("interception") unless Bouncy.configured?
+    CONFIGURATION_SET_HEADER = "X-SES-CONFIGURATION-SET"
+    RECIPIENT_FIELDS = %i[to cc bcc].freeze
 
-      new.call(message)
+    # The delivery method of a message that Bouncy checks. Mail builds it through
+    # Message#delivery_method(Gate, transport), its public way to set a delivery method.
+    class Gate
+      attr_reader :transport
+
+      def initialize(transport)
+        @transport = transport
+      end
+
+      def settings = transport.settings
+
+      # Bypass, scope and mode are read again at each delivery: a message delivered once keeps
+      # its gate, and can be delivered again under Bouncy.unblocked or another mode.
+      def deliver!(message)
+        return transport.deliver!(message) unless Interceptor.active?
+        return if Interceptor.new.call(message) == :undeliverable
+
+        transport.deliver!(message)
+      end
+
+      def respond_to_missing?(name, include_private = false) = transport.respond_to?(name, include_private) || super
+      def method_missing(name, ...) = transport.respond_to?(name) ? transport.public_send(name, ...) : super
     end
 
+    class << self
+      def delivering_email(message)
+        stamp_configuration_set(message)
+        return if bypassed?
+        return Bouncy.unconfigured!("interception") unless Bouncy.configured?
+
+        transport = message.delivery_method
+        message.delivery_method(Gate, transport) unless transport.is_a?(Gate)
+      end
+
+      def active? = !bypassed? && Bouncy.configured?
+
+      private
+
+      def bypassed? = Bouncy.configuration.interception == :off || ActiveSupport::IsolatedExecutionState[:bouncy_unblocked]
+
+      # SES reads the set from this header and removes it before delivery. A mail that names its
+      # own set keeps it. The header does not depend on the interception mode: turning
+      # interception off must not stop the events that SES publishes for the set.
+      def stamp_configuration_set(message)
+        name = Bouncy.configuration.ses.configuration_set.presence
+        message[CONFIGURATION_SET_HEADER] = name if name && message.header[CONFIGURATION_SET_HEADER].nil?
+      end
+    end
+
+    # Returns :undeliverable when :drop removed every recipient, else nil.
     def call(message)
       envelope = Array(message.smtp_envelope_to).dup
-      headers = %i[to cc bcc].to_h { |field| [field, Array(message.public_send(field)).dup] }
-      keys = (envelope + headers.values.flatten).filter_map { |email| normalize(email) }.uniq
-      rows = Bouncy.blocked.where(email: keys).to_a
+      fields = RECIPIENT_FIELDS.to_h { |name| [name, addresses(message[name])] }
+      keys = (envelope + fields.values.flatten.map(&:address)).filter_map { |entry| normalize(entry) }.uniq
+      rows = Bouncy.current_state(Bouncy.blocked).where(email: keys).to_a
       return if rows.empty?
 
       mode = Bouncy.configuration.interception
-      # Provider-derived evidence is only enforced while a complete sync is fresh. Manual holds
-      # and legacy soft holds are local policy and do not depend on provider freshness. The same
-      # rule applies in :log mode so that its preview matches what :drop would do.
-      fresh = Bouncy.sync_fresh?
+      # Provider-derived evidence is only enforced while a complete sync is fresh, unless the host
+      # set require_fresh_sync to false. Manual holds and legacy soft holds are local policy and
+      # do not depend on provider freshness. The same rule applies in :log mode so that its
+      # preview matches what :drop would do.
+      fresh = !Bouncy.configuration.require_fresh_sync || Bouncy.sync_fresh?
       enforceable = rows.select { |row| fresh || row.manual_blocked_at || (row.soft_blocked_until && row.soft_blocked_until > Time.current) }
       blocked = enforceable.map(&:email)
-      remaining = envelope.reject { |email| blocked.include?(normalize(email)) }
-      changed_headers = headers.transform_values { |values| values.reject { |email| blocked.include?(normalize(email)) } }
       # Persist all skip evidence before changing the message. A DB outage must leave it intact.
       Event.transaction do
         rows.each do |row|
@@ -37,19 +90,35 @@ module Bouncy
       end
       return unless mode == :drop && blocked.any?
 
-      changed_headers.each { |field, values| message.public_send("#{field}=", values.empty? ? nil : values) }
+      # Each kept entry keeps its own text, display name included; only the lookup uses the
+      # bare address.
+      fields.each do |name, field_addresses|
+        kept = field_addresses.reject { |address| blocked.include?(normalize(address.address)) }
+        message[name] = kept.empty? ? nil : kept.map(&:format) if kept.size < field_addresses.size
+      end
+      remaining = envelope.reject { |entry| blocked.include?(normalize(entry)) }
       message.smtp_envelope_to = remaining
-      message.perform_deliveries = false if remaining.empty?
+      return if remaining.any?
+
+      message.perform_deliveries = false
+      :undeliverable
     rescue ActiveRecord::ActiveRecordError => e
       raise unless Bouncy.database_unavailable?(e)
 
       ActiveSupport::Notifications.instrument("unavailable.bouncy", operation: "interception")
+      nil
     end
 
     private
 
+    # The parsed addresses of a To, Cc or Bcc field, or none for a field Mail cannot parse.
+    def addresses(field)
+      field.respond_to?(:addrs) ? field.addrs : []
+    end
+
+    # "Ada <ADA@example.com>" and "ada@example.com" are the same lookup key.
     def normalize(value)
-      Identity.normalize(Mail::Address.new(value).address)
+      Identity.normalize(Mail::Address.new(value.to_s).address)
     rescue InvalidAddress, Mail::Field::ParseError
       nil
     end

data/lib/bouncy/notification.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Bouncy
+  # One SES notification, as config.on_notification receives it: every event type SES
+  # publishes to the topic, Send and Delivery included, after the receiver committed what it
+  # records from it.
+  #
+  #   config.on_notification = lambda do |notification|
+  #     notification.type        # => "Delivery"
+  #     notification.message_id  # => the SES message id of the mail
+  #     notification.recipients  # => ["ada@example.com"]
+  #     notification.occurred_at # => the time SES gives for this event
+  #     notification.tags        # => { "order" => ["42"] }
+  #     notification.raw         # => the SES JSON object, as a Hash
+  #   end
+  #
+  # SNS repeats and reorders notifications, so the hook must be safe to run again and in any
+  # order.
+  class Notification
+    # The SES object that holds an event's own details, where it is not the type in camelCase.
+    SECTIONS = { "Rendering Failure" => "failure", "RenderingFailure" => "failure" }.freeze
+
+    attr_reader :raw
+
+    def initialize(raw, sns_timestamp: nil)
+      @raw = raw
+      @sns_timestamp = sns_timestamp
+    end
+
+    # The SES event type as SES names it: "Send", "Delivery", "Bounce", "Complaint", ...
+    def type = raw["eventType"] || raw["notificationType"]
+
+    def message_id = mail["messageId"]
+
+    # The SES message tags of the mail: each name maps to an array of values.
+    def tags = mail["tags"].is_a?(Hash) ? mail["tags"] : {}
+
+    # The addresses this event is about, exactly as SES spells them: the bounced, complained,
+    # delivered or delayed recipients, or the mail's destination for other events.
+    def recipients
+      values = case type
+               when "Bounce" then section["bouncedRecipients"]
+               when "Complaint" then section["complainedRecipients"]
+               when "Delivery" then section["recipients"]
+               when "DeliveryDelay" then section["delayedRecipients"]
+               else mail["destination"]
+               end
+      Array(values).filter_map do |recipient|
+        address = recipient.is_a?(Hash) ? recipient["emailAddress"] : recipient
+        address if address.is_a?(String)
+      end
+    end
+
+    # The time of this event: its own timestamp, else the mail's, else the time SNS published it.
+    def occurred_at
+      [section["timestamp"], mail["timestamp"], @sns_timestamp].each do |value|
+        return Time.iso8601(value) if value.is_a?(String)
+      rescue ArgumentError
+        next
+      end
+      nil
+    end
+
+    private
+
+    def mail = object(raw["mail"])
+    def section = object(raw[SECTIONS.fetch(type.to_s) { type.to_s.sub(/\A./, &:downcase) }])
+    def object(value) = value.is_a?(Hash) ? value : {}
+  end
+end

data/lib/bouncy/providers/ses.rb

@@ -3,6 +3,24 @@
 module Bouncy
   module Providers
     class Ses < Base
+      # The SNS host domain of each AWS partition, for the certificate and SubscribeURL checks.
+      SNS_DOMAINS = { "aws" => "amazonaws.com", "aws-us-gov" => "amazonaws.com", "aws-cn" => "amazonaws.com.cn" }.freeze
+      # SNS answers a SubscribeURL visit with a short XML document.
+      CONFIRMATION_LIMIT = 64 * 1024
+
+      # The SubscribeURL as a URI when it is HTTPS on the topic's own regional SNS host, port 443,
+      # with no userinfo and no fragment; nil for any other value.
+      def self.subscribe_uri(envelope, region)
+        uri = URI.parse(envelope["SubscribeURL"].to_s)
+        domain = SNS_DOMAINS[envelope["TopicArn"].to_s.split(":")[1]]
+        return unless domain && uri.is_a?(URI::HTTPS) && uri.host == "sns.#{region}.#{domain}" && uri.port == 443
+        return if uri.userinfo || uri.fragment
+
+        uri
+      rescue URI::InvalidURIError
+        nil
+      end
+
       def initialize(configuration = Bouncy.configuration)
         super()
         @configuration = configuration
@@ -70,8 +88,12 @@ module Bouncy
       def control(envelope) # rubocop:disable Naming/PredicateMethod -- Adapter operation with side effects.
         case envelope.fetch("Type")
         when "SubscriptionConfirmation"
-          request { sns_client.confirm_subscription(topic_arn: envelope.fetch("TopicArn"), token: envelope.fetch("Token")) }
-          Store.event!("subscription_confirmed", source: "webhook")
+          if @settings.subscription_confirmation == :subscribe_url
+            visit_subscribe_url(envelope)
+          else
+            request { sns_client.confirm_subscription(topic_arn: envelope.fetch("TopicArn"), token: envelope.fetch("Token")) }
+          end
+          Store.event!("subscription_confirmed", source: "webhook", details: { "via" => @settings.subscription_confirmation.to_s })
           true
         when "UnsubscribeConfirmation"
           Store.event!("subscription_unsubscribed", source: "webhook")
@@ -85,6 +107,11 @@ module Bouncy
         SesParser.new(@configuration).call(envelope)
       end
 
+      # The notification for config.on_notification. parse has already checked the message.
+      def notification(envelope)
+        Notification.new(JSON.parse(envelope.fetch("Message"), max_nesting: 20), sns_timestamp: envelope["Timestamp"])
+      end
+
       def doctor
         policy = policy_check
         { "scope" => @configuration.scope, "policy_verified" => policy.verified, "policy_reason" => policy.reason,
@@ -94,6 +121,33 @@ module Bouncy
 
       private
 
+      # Confirms the subscription by visiting the SubscribeURL that SNS signed, so the credentials
+      # need no sns:ConfirmSubscription grant. Only an HTTPS URL on the topic's own regional SNS
+      # host is visited; any other URL is malformed for good. A transport failure or an answer
+      # other than 2xx is a ProviderError: the receiver answers 503, and SNS sends the
+      # confirmation again.
+      def visit_subscribe_url(envelope)
+        require "net/http"
+        uri = self.class.subscribe_uri(envelope, @settings.region)
+        raise MalformedMessage, "SubscribeURL is not on the topic's SNS host" unless uri
+
+        code = nil
+        Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 3, read_timeout: 5,
+                                            verify_mode: OpenSSL::SSL::VERIFY_PEER, max_retries: 0) do |http|
+          http.request(Net::HTTP::Get.new(uri.request_uri)) do |response|
+            code = response.code
+            size = 0
+            response.read_body do |chunk|
+              size += chunk.bytesize
+              raise ProviderError, "SNS confirmation response exceeds limit" if size > CONFIRMATION_LIMIT
+            end
+          end
+        end
+        raise ProviderError, "SNS did not confirm the subscription (HTTP #{code})" unless code.to_s.match?(/\A2\d\d\z/)
+      rescue Timeout::Error, SocketError, IOError, SystemCallError, OpenSSL::SSL::SSLError
+        raise ProviderError, "SNS confirmation transport unavailable"
+      end
+
       def require_sdk(service)
         require "aws-sdk-#{service}"
       rescue LoadError
@@ -160,6 +214,7 @@ module Bouncy
         end
 
         sets = @settings.configuration_sets.dup
+        sets << @settings.configuration_set if @settings.configuration_set.present?
         @settings.identities.each do |identity|
           response = request { ses.get_email_identity(email_identity: identity) }
           sets << response.configuration_set_name if response.configuration_set_name.present?

data/lib/bouncy/providers/ses_parser.rb

@@ -79,6 +79,8 @@ module Bouncy
       end
 
       def classify(type, data)
+        return strict_classification(type, data) if @configuration.webhook_blocking == :strict && %w[Bounce Complaint].include?(type)
+
         case type
         when "Bounce"
           case data["bounceSubType"]
@@ -107,6 +109,24 @@ module Bouncy
         else %w[ignored unsupported_type]
         end
       end
+
+      # config.webhook_blocking = :strict: nothing reads the account list, so every Permanent
+      # bounce blocks, whatever its subtype, and so does every recipient a complaint names.
+      # SES cannot say which one complained: most ISPs remove that address, and SES lists the
+      # recipients who might have sent the complaint. Undetermined and Transient bounces stay
+      # record-only, and a not-spam report says the opposite of a complaint.
+      def strict_classification(type, data)
+        if type == "Bounce"
+          return ["hard_bounce", data["bounceSubType"].presence || "unspecified"] if data["bounceType"] == "Permanent"
+
+          return ["soft_bounce", data["bounceSubType"]] if %w[Transient Undetermined].include?(data["bounceType"])
+
+          return %w[unknown unrecognized_bounce]
+        end
+        return %w[ignored not_spam] if data["complaintFeedbackType"] == "not-spam"
+
+        ["complaint", data["complaintSubType"].presence || "named"]
+      end
     end
   end
 end

data/lib/bouncy/providers/sns_verifier.rb

@@ -7,13 +7,71 @@ module Bouncy
     class SnsVerifier
       BODY_LIMIT = 2 * 1024 * 1024
 
+      # Signing certificates, shared by every receiver in the process: each request builds a new
+      # adapter, and an app that subscribes to Send and Delivery events gets one SNS message per
+      # mail. At most 16 certificate URLs, each kept for an hour. Only a certificate that the
+      # allowlisted, bounded download returned is kept; a failed download keeps nothing.
+      class CertificateCache
+        Entry = Data.define(:pem, :fetched_at)
+
+        def initialize(size:, ttl:)
+          @size = size
+          @ttl = ttl
+          @entries = {}
+          @mutex = Mutex.new
+        end
+
+        # The download runs outside the lock, so one slow fetch does not stop other requests.
+        def fetch(url)
+          entry = @mutex.synchronize { @entries[url] }
+          return entry.pem if entry && Time.now - entry.fetched_at < @ttl
+
+          pem = yield
+          @mutex.synchronize do
+            @entries.delete(url)
+            @entries[url] = Entry.new(pem: pem, fetched_at: Time.now)
+            @entries.shift while @entries.size > @size
+          end
+          pem
+        end
+
+        # Drops a certificate that failed a verification, so the next one fetches it again. A
+        # certificate fetched less than `after` seconds ago stays: a stream of forged messages
+        # must not turn into a stream of downloads.
+        def forget(url, after:)
+          @mutex.synchronize do
+            entry = @entries[url]
+            next false unless entry && Time.now - entry.fetched_at >= after
+
+            @entries.delete(url)
+            true
+          end
+        end
+
+        def size = @mutex.synchronize { @entries.size }
+        def clear = @mutex.synchronize { @entries.clear }
+      end
+
+      CERTIFICATES = CertificateCache.new(size: 16, ttl: 3600)
+      # A cached certificate older than this is fetched again, once, when a signature fails.
+      REFETCH_AFTER = 60
+
       class BoundedVerifier < Aws::SNS::MessageVerifier
         private
 
-        def pem(uri)
-          @cached_pems ||= {}
-          @cached_pems.shift if @cached_pems.size >= 32 && !@cached_pems.key?(uri.to_s)
-          super
+        # The SDK's download_pem checks the URL and the PEM framing, and calls the bounded
+        # https_get below. A certificate is cached only once it parses and carries the RSA key
+        # that SNS signs with; any other body is refused and never kept, so the next request
+        # fetches again at once.
+        def pem(uri) = CERTIFICATES.fetch(uri.to_s) { usable(download_pem(uri)) }
+
+        def usable(pem)
+          key = OpenSSL::X509::Certificate.new(pem).public_key
+          raise VerificationError, "The SNS signing certificate has no RSA key" unless key.is_a?(OpenSSL::PKey::RSA)
+
+          pem
+        rescue OpenSSL::X509::CertificateError, OpenSSL::PKey::PKeyError
+          raise VerificationError, "The SNS signing certificate does not parse"
         end
 
         def https_get(uri, _failed_attempts = 0)
@@ -65,7 +123,7 @@ module Bouncy
         end
 
         authorize!(envelope)
-        @mutex.synchronize { @verifier.authenticate!(raw_body) }
+        verify(raw_body, envelope.fetch("SigningCertURL"))
         envelope
       rescue JSON::ParserError, URI::InvalidURIError
         raise MalformedMessage, "Malformed SNS envelope"
@@ -75,6 +133,16 @@ module Bouncy
 
       private
 
+      # A certificate that SNS rotated at the same URL fails once from the cache; it is fetched
+      # again, once, and the message is checked with the new one.
+      def verify(raw_body, url)
+        @mutex.synchronize { @verifier.authenticate!(raw_body) }
+      rescue Aws::SNS::MessageVerifier::VerificationError, OpenSSL::OpenSSLError
+        raise unless @verifier.is_a?(BoundedVerifier) && CERTIFICATES.forget(url, after: REFETCH_AFTER)
+
+        @mutex.synchronize { @verifier.authenticate!(raw_body) }
+      end
+
       def authorize!(envelope)
         topic = envelope.fetch("TopicArn")
         settings = @configuration.ses
@@ -84,7 +152,7 @@ module Bouncy
           raise AuthenticationError, "SNS topic is not authorized"
         end
 
-        suffix = { "aws" => "amazonaws.com", "aws-us-gov" => "amazonaws.com", "aws-cn" => "amazonaws.com.cn" }[parts[1]]
+        suffix = Ses::SNS_DOMAINS[parts[1]]
         uri = URI.parse(envelope.fetch("SigningCertURL"))
         unless suffix && uri.scheme == "https" && uri.host == "sns.#{settings.region}.#{suffix}" &&
                uri.port == 443 && !uri.userinfo && !uri.query && !uri.fragment &&

data/lib/bouncy/prune_job.rb

@@ -4,7 +4,10 @@ module Bouncy
   class PruneJob < ActiveJob::Base
     queue_as :default
 
+    # Like SyncJob, a no-op until config.scope is set.
     def perform
+      return Rails.logger&.info("[bouncy] Bouncy::PruneJob skipped: config.scope is not set") unless Bouncy.configured?
+
       Bouncy.configuration.validate!
       # Keep state rows, including inactive release fences, indefinitely.
       Bouncy.events.where("created_at < ?", Bouncy.configuration.retention.ago).in_batches.delete_all

data/lib/bouncy/scope_lock.rb

@@ -13,7 +13,8 @@ module Bouncy
         key = Digest::SHA256.hexdigest(Bouncy.scope)[0, 15].to_i(16)
         case connection.adapter_name
         when "PostgreSQL"
-          acquired = connection.select_value("SELECT pg_try_advisory_lock(#{key})")
+          # Uncached: a cached answer would report the lock without taking it.
+          acquired = connection.uncached { connection.select_value("SELECT pg_try_advisory_lock(#{key})") }
           raise ProviderError, "Another sync holds this scope lock" unless [true, "t"].include?(acquired)
 
           begin
@@ -23,7 +24,7 @@ module Bouncy
           end
         when /Mysql|Trilogy/i
           name = Digest::SHA256.hexdigest("bouncy:#{connection.pool.db_config.database}:#{Bouncy.scope}")
-          acquired = connection.select_value("SELECT GET_LOCK('#{name}', 0)")
+          acquired = connection.uncached { connection.select_value("SELECT GET_LOCK('#{name}', 0)") }
           raise ProviderError, "Another sync holds this scope lock" unless acquired == 1
 
           begin

data/lib/bouncy/store.rb

@@ -5,11 +5,15 @@ module Bouncy
     module_function
 
     # Retry outside the transaction: PostgreSQL aborts a transaction on a unique violation.
+    # The address lock comes first, before any row lock: a sender inside Bouncy.hold sees this
+    # change either committed or not started.
     def change(email)
       key = Identity.normalize(email)
+      Record.connection_pool.with_connection { |connection| AddressLock.settle(connection) }
       attempts = 0
       begin
         Suppression.transaction(requires_new: true) do
+          AddressLock.claim!(key)
           row = Suppression.find_or_create_by!(scope: Bouncy.scope, email: key) do |record|
             record.provider = Bouncy.configuration.provider.to_s
           end

data/lib/bouncy/sync_job.rb

@@ -6,7 +6,11 @@ module Bouncy
   class SyncJob < ActiveJob::Base
     queue_as :default
 
+    # A recurring job in an app that has not set config.scope does nothing, instead of failing
+    # every run. Bouncy.sync! itself still raises.
     def perform
+      return Rails.logger&.info("[bouncy] Bouncy::SyncJob skipped: config.scope is not set") unless Bouncy.configured?
+
       Bouncy.sync!
     end
   end

data/lib/bouncy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bouncy
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/bouncy/webhook.rb

@@ -3,17 +3,24 @@
 module Bouncy
   class Webhook
     BODY_LIMIT = 2 * 1024 * 1024
+    METHODS = %w[GET HEAD PUT PATCH DELETE OPTIONS TRACE CONNECT].freeze
+    INVALID = "<invalid>"
+    TOPIC_ARN = /\Aarn:aws[a-z-]*:sns:[a-z]{2}(?:-[a-z]+)+-\d+:\d{12}:[A-Za-z0-9_-]{1,256}\z/
 
     def call(environment)
-      return response(405) unless environment["REQUEST_METHOD"] == "POST"
+      method = environment["REQUEST_METHOD"]
+      unless method == "POST"
+        shown = METHODS.include?(method) ? method : INVALID
+        return refuse(405, "method #{shown} is not POST")
+      end
 
       # An unconfigured receiver answers 503 so the provider retries later instead of
       # treating the endpoint as broken or, worse, as having accepted the notification.
       Bouncy.configuration.validate!
       body = environment.fetch("rack.input").read(BODY_LIMIT + 1).to_s
-      return response(400) if body.empty?
+      return refuse(400, "empty body") if body.empty?
 
-      return response(413) if body.bytesize > BODY_LIMIT
+      return refuse(413, "body over #{BODY_LIMIT} bytes") if body.bytesize > BODY_LIMIT
 
       adapter = Bouncy.adapter
       envelope = adapter.authenticate(raw_body: body, headers: environment)
@@ -21,18 +28,62 @@ module Bouncy
         raise MalformedMessage, "Unsupported SNS control type" unless envelope["Type"] == "Notification"
 
         adapter.parse(envelope).each { |event| Ingestor.new.call(event) }
+        return response(503) unless notified?(adapter, envelope)
       end
       response(200)
-    rescue AuthenticationError
-      response(401)
-    rescue MalformedMessage
-      response(400)
-    rescue ProviderError, ConfigurationError, ActiveRecord::ActiveRecordError
-      response(503)
+    rescue AuthenticationError => e
+      refuse(401, e.message, body)
+    rescue MalformedMessage => e
+      refuse(400, e.message, body)
+    rescue ProviderError, ConfigurationError => e
+      refuse(503, e.message, body)
+    rescue ActiveRecord::ActiveRecordError => e
+      # A database message can quote a statement and its values, so only the class is logged.
+      refuse(503, e.class.name, body)
     end
 
     private
 
+    # One warning per refused message: how a dead subscription is found in production. It names
+    # the reason and where the message claims to come from. The message is not authenticated, so
+    # a topic is logged only when it has the strict SNS ARN syntax and a SubscribeURL host only
+    # when it passes the SNS host check; anything else is written as <invalid>. No raw field of
+    # the body is ever copied into the log.
+    def refuse(status, reason, body = nil)
+      Rails.logger&.warn("[bouncy] refused an SNS message (#{status}): #{reason}#{origin(body)}")
+      response(status)
+    end
+
+    def origin(body)
+      envelope = JSON.parse(body.to_s, max_nesting: 30)
+      return "" unless envelope.is_a?(Hash)
+
+      parts = []
+      topic = envelope["TopicArn"] if envelope["TopicArn"].is_a?(String) && envelope["TopicArn"].match?(TOPIC_ARN)
+      parts << "topic #{topic || INVALID}" if envelope.key?("TopicArn")
+      if envelope["Type"] == "SubscriptionConfirmation" && envelope.key?("SubscribeURL")
+        uri = Providers::Ses.subscribe_uri(envelope, Bouncy.configuration.ses.region) if topic
+        parts << "SubscribeURL host #{uri&.host || INVALID}"
+      end
+      parts.map { |part| "; #{part}" }.join
+    rescue JSON::ParserError
+      ""
+    end
+
+    # config.on_notification runs after the state committed, outside Bouncy's locks, and before
+    # the answer. A failure answers 503, so SNS delivers the notification again; the repeat
+    # deduplicates and calls the hook again.
+    def notified?(adapter, envelope)
+      return true unless adapter.respond_to?(:notification)
+
+      Bouncy.configuration.on_notification.call(adapter.notification(envelope))
+      true
+    rescue StandardError => e
+      ActiveSupport::Notifications.instrument("hook_error.bouncy", hook: :on_notification, error_class: e.class.name)
+      Rails.logger&.error("[bouncy] config.on_notification raised #{e.class.name}; answering 503 so SNS retries")
+      false
+    end
+
     def response(status)
       [status, { "content-type" => "text/plain", "cache-control" => "no-store" }, [Rack::Utils::HTTP_STATUS_CODES.fetch(status)]]
     end