bouncy 0.1.0 → 0.2.1

data/lib/bouncy/importer.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Bouncy
+  # Records a block that another system recorded first, for Bouncy.import!.
+  #
+  # A bounce or a complaint becomes the same evidence that a webhook records, and a manual block
+  # becomes a manual hold. The time is the time the other system recorded the block. It is kept
+  # as given, however old: config.maximum_event_age is for webhook feedback that arrives late,
+  # and an old block that another system kept still stops mail.
+  #
+  # An import is not new evidence, so it calls no hook. It is idempotent: the same address,
+  # reason and time a second time writes nothing. It never removes or weakens a block that is
+  # in force, and a release recorded at or after its time fences it.
+  class Importer
+    REASONS = %w[hard_bounce complaint manual].freeze
+    FUTURE_SKEW = 5.minutes
+    # The attributes that an import can change. A difference in them is a change to record.
+    CHANGES = %w[manual_blocked_at manual_note event_blocked_at event_reason last_event_at blocked_at details].freeze
+
+    def call(email, reason:, at:, note:, actor:)
+      reason = reason.to_s
+      raise ArgumentError, "reason must be :hard_bounce, :complaint or :manual" unless REASONS.include?(reason)
+
+      time = time_of(at)
+      exact = email.to_s.strip
+      key = Identity.normalize(email)
+      dedupe_key = Digest::SHA256.hexdigest(JSON.generate(["import", Bouncy.scope, key, reason, time.iso8601(6)]))
+      Store.change(key) do |row|
+        next row if Bouncy.events.exists?(dedupe_key: dedupe_key)
+
+        record(row, reason, time, dedupe_key, exact: exact, note: note.to_s.strip.truncate(1000).presence,
+                                              actor: actor.to_s.truncate(200))
+      end
+    end
+
+    private
+
+    def record(row, reason, time, dedupe_key, exact:, note:, actor:)
+      was_blocked = row.blocked?
+      released_at = fence(row, reason)
+      fenced = !released_at.nil? && time <= released_at
+      unless fenced
+        before = row.attributes.slice(*CHANGES).deep_dup
+        reason == "manual" ? hold(row, time, note) : feedback(row, reason, time, exact)
+        row.blocked_at = [row.blocked_at, time].compact.min
+        return row if row.attributes.slice(*CHANGES) == before
+
+        row.summarize!
+      end
+      Store.event!("imported", email: row.email, source: "import", occurred_at: time, dedupe_key: dedupe_key, details: {
+                     "reason" => reason, "note" => note, "actor" => actor,
+                     "ignored_for_policy" => fenced, "became_blocked" => !was_blocked && row.blocked?
+                   })
+      row
+    end
+
+    # A release clears manual holds and records "soft_released_before". A provider release, or a
+    # sync that no longer finds webhook evidence, clears it and records released_before. An
+    # imported block at or before that time is older than the release, so it changes nothing.
+    def fence(row, reason)
+      return row.released_before unless reason == "manual"
+
+      Time.iso8601(row.details["soft_released_before"].to_s)
+    rescue ArgumentError
+      nil
+    end
+
+    # Keeps an earlier hold and its support note.
+    def hold(row, time, note)
+      return if row.manual_blocked_at && row.manual_blocked_at <= time
+
+      row.manual_note = note unless row.manual_blocked_at
+      row.manual_blocked_at = time
+    end
+
+    # Webhook evidence keeps the time of its newest block and the stronger reason: a complaint
+    # outranks a hard bounce, so an imported hard bounce never replaces a complaint.
+    def feedback(row, reason, time, exact)
+      previous = row.event_reason if row.event_blocked_at
+      return if previous == reason && row.event_blocked_at >= time
+      return if previous == "complaint" && row.event_blocked_at >= time
+
+      row.event_reason = previous == "complaint" ? "complaint" : reason
+      row.event_blocked_at = [row.event_blocked_at, time].compact.max
+      row.last_event_at = [row.last_event_at, time].compact.max
+      row.details = row.details.except("absence_count").reverse_merge("exact_email" => exact)
+    end
+
+    # Microsecond precision, as every supported database stores it, so a second import of the
+    # same time compares and deduplicates as equal.
+    def time_of(value)
+      raise ArgumentError, "at must be a Time" unless value.is_a?(Time) || value.is_a?(DateTime)
+
+      time = value.to_time.utc.floor(6)
+      raise ArgumentError, "at must not be in the future" if time > FUTURE_SKEW.from_now
+
+      time
+    end
+  end
+end

data/lib/bouncy/ingestor.rb

@@ -1,8 +1,15 @@
 # frozen_string_literal: true
 
 module Bouncy
+  # Internal: one webhook observation for Ingestor. See Ingestor.
   Observation = Data.define(:email, :kind, :provider_event_id, :message_id, :occurred_at, :details, :provider_reason, :status_code, :diagnostic)
 
+  # Internal: the receiver's step for one webhook observation. It is not a public API. Use
+  # Bouncy.import! to record a block from another system. The call shape of Ingestor#call and
+  # Observation stays the same in 0.2.x, because apps on 0.2.0 call them to carry blocks.
+  #
+  # config.maximum_event_age applies here only. It keeps a late webhook notification from
+  # blocking. Bouncy.import! and Bouncy.block! do not apply it.
   class Ingestor
     def call(observation)
       email = observation.email && Identity.normalize(observation.email)
@@ -44,9 +51,11 @@ module Bouncy
       details = attributes.fetch(:details).merge("ignored_for_policy" => [too_old, fenced, out_of_order].any?)
       if row && !details["ignored_for_policy"]
         was_blocked = row.blocked?
-        # A complaint blocks locally only when the provider named exactly one recipient (SesParser
-        # marks it "confirmed"); candidates wait for the provider's own list at the next sync.
-        if attributes[:kind] == "hard_bounce" || (attributes[:kind] == "complaint" && details["certainty"] == "confirmed")
+        # Under :cautious a complaint blocks locally only when the provider named exactly one
+        # recipient (SesParser marks it "confirmed"); candidates wait for the provider's own list
+        # at the next sync. Under :strict every named recipient blocks.
+        complaint = attributes[:kind] == "complaint" && (details["certainty"] == "confirmed" || Bouncy.configuration.webhook_blocking == :strict)
+        if attributes[:kind] == "hard_bounce" || complaint
           row.event_blocked_at = time
           row.event_reason = attributes[:kind]
           row.last_event_at = [row.last_event_at, time].compact.max

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/status.rb

@@ -29,6 +29,9 @@ module Bouncy
     def blocked? = @row ? @row.blocked? : false
     def reasons = @row ? @row.reasons : []
     def reason = (%i[complaint hard_bounce provider_list manual soft_bounces] & reasons).first
+    # The time the block in force began: when the address became blocked here, or the at: time
+    # of the Bouncy.import! that blocked it. nil when the address is not blocked.
+    def blocked_at = blocked? ? @row.blocked_at : nil
     def observed_at = @row&.provider_checked_at || @row&.last_event_at
     def provider_updated_at = @row&.provider_entries&.filter_map { |entry| Time.iso8601(entry.fetch("provider_updated_at")) }&.max
     def last_event = @row && Bouncy.events.for(@row.email).recent.first

data/lib/bouncy/store.rb

@@ -5,15 +5,23 @@ 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
-          row.with_lock { yield row }
+          row.with_lock do
+            # A soft hold that ran out leaves its start in blocked_at. The next block starts anew.
+            row.blocked_at = nil unless row.blocked?
+            yield row
+          end
         end
       rescue ActiveRecord::RecordNotUnique, ActiveRecord::StaleObjectError, ActiveRecord::Deadlocked
         attempts += 1

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.1"
 end