bouncy 0.1.0

data/guides/troubleshooting.md

@@ -0,0 +1,46 @@
+# Action Mailer says sent, but the email was not received
+
+Start by separating what you know:
+
+1. A mailer job completed: your app ran the send path.
+2. SES accepted a send request: the provider accepted responsibility for processing it.
+3. A delivery event arrived: the receiving server accepted the message.
+4. The person saw the message: only the person or another appropriate signal can establish that.
+
+Bouncy records known restrictions and selected provider events. Missing evidence does not mean successful delivery. Spam placement, recipient filters, content problems and incorrect recipient selection may require investigation elsewhere.
+
+```ruby
+status = Bouncy.status(address)
+[status.knowledge, status.reasons, status.stale?, status.observed_at]
+Bouncy.events.for(address).recent.limit(20)
+```
+
+## An address is on the SES suppression list
+
+`OnAccountSuppressionList` means SES refused a send because a restriction already existed. It is not a new hard bounce. A complete `Bouncy.sync!` imports restrictions from before installation, sister apps on the same account, missed notifications and console changes.
+
+Inspect the underlying reason and the account/region. After verifying that recovery is appropriate, an authorized support action can call `Bouncy.release!(address, note: ...)`. This operates on exact-case provider identifiers and confirms removal. A lowercase console/API lookup alone may miss another case variant.
+
+Release never resends the original email. Regenerate time-sensitive links in an explicitly authorized host action if a resend is needed. See [recovery](recovery.md).
+
+## Nothing is appearing locally
+
+- Check the configured account, region, credentials and exact SNS topic allowlist.
+- Run `bouncy:doctor`, then sync. An unknown/manual publisher-policy check is not a pass. If the latest sync did not verify policy, `Bouncy.status(address).policy_unverified?` is true for listed addresses and `policy_reason` explains why. Historical restrictions remain queryable while provider-derived interception is suspended.
+- If `Bouncy.status(address).knowledge` is `:unconfigured`, `config.scope` is blank and Bouncy is inactive in that environment.
+- Confirm the SNS HTTPS subscription is active and points at the actual mounted route.
+- Confirm SES routes the needed event types to that topic, and raw SNS message delivery is disabled.
+- Inspect bounded receiver status codes: 401 authorization/signature, 400 malformed input, 413 body limit, 503 retryable infrastructure failure.
+- Run a complete sync and verify the scheduled job actually runs in production.
+
+An hourly sync cannot reconstruct every lost delivery or soft-bounce event. SNS retries and operational monitoring still matter.
+
+## The mirror is stale or unavailable
+
+Compare `Bouncy.last_sync` and `Bouncy.last_successful_sync`. A failed/partial run cannot prove absence. A provider scope mismatch blocks authoritative reconciliation. Check credentials, API permissions, configuration-set overrides and worker execution.
+
+Recognized database read outages produce an unavailable status and fail open for interception. Ordinary SQL/programming errors raise. In drop mode, provider-derived enforcement needs a recent complete sync; independent manual holds do not depend on provider freshness.
+
+## A message was locally skipped
+
+Inspect its recipient's `skipped` event and mode. `:log` observes the decision while delivering. `:drop` removes restricted recipients from both headers and envelope. Custom transports or later interceptors that rewrite recipients require host tests. Never infer a send from the absence of a skip record.

data/lib/bouncy/configuration.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Bouncy
+  class Configuration
+    class Ses
+      # sns_message_verifier replaces ONLY the Aws::SNS::MessageVerifier that downloads and
+      # caches Amazon's signing certificate, so a host can test its mounted receiver offline.
+      # Topic authorization and certificate-URL checks still run, which is the point: a test
+      # seam that skipped them would hide exactly the hole they exist to close.
+      attr_accessor :region, :credentials, :topic_arns, :client, :sns_client, :sts_client, :sns_message_verifier,
+                    :identities, :configuration_sets, :all_sending_paths_listed
+
+      def initialize
+        @topic_arns = []
+        @identities = []
+        @configuration_sets = []
+        # Imported provider restrictions are enforced only after the policy check passes, and the
+        # check needs every sending identity and configuration set listed. This flag is the
+        # installer's statement that the lists above are complete.
+        @all_sending_paths_listed = false
+      end
+    end
+
+    # A soft bounce is a temporary refusal, so one of them says nothing. Repeated soft bounces
+    # for the same address inside a window are a different signal, and some hosts want them to
+    # stop the sending. Leave the threshold nil to keep soft bounces record-only.
+    SOFT_BOUNCE_OCCURRENCE_LIMIT = 50
+
+    attr_accessor :provider, :scope, :interception, :record_deliveries,
+                  :retention, :maximum_event_age, :stale_after, :after_block, :after_release,
+                  :after_event, :adapter, :soft_bounce_threshold, :soft_bounce_window,
+                  :soft_bounce_block_for
+    attr_reader :ses
+
+    def initialize
+      @provider = :ses
+      @interception = :log
+      @record_deliveries = false
+      @retention = 90.days
+      @maximum_event_age = 90.days
+      @stale_after = 2.hours
+      @soft_bounce_threshold = nil
+      @soft_bounce_window = 30.days
+      @soft_bounce_block_for = 30.days
+      @ses = Ses.new
+      @after_block = @after_release = @after_event = ->(_event) {}
+    end
+
+    # Occurrence times retained per address so the window can roll. Bounded either way: a
+    # configured threshold needs no more entries than the threshold itself.
+    def soft_bounce_occurrences
+      return SOFT_BOUNCE_OCCURRENCE_LIMIT unless soft_bounce_escalation?
+
+      [soft_bounce_threshold, SOFT_BOUNCE_OCCURRENCE_LIMIT].min
+    end
+
+    def soft_bounce_escalation? = soft_bounce_threshold.to_i.positive?
+
+    def configured? = !scope.to_s.strip.empty?
+
+    def validate!
+      raise ConfigurationError, "Set config.scope to the provider account and region" unless configured?
+      raise ConfigurationError, "scope must be at most 191 characters" if scope.to_s.length > 191
+      raise ConfigurationError, "Only the SES provider is supported" unless provider == :ses || adapter
+      raise ConfigurationError, "interception must be :log, :drop or :off" unless %i[log drop off].include?(interception)
+      unless maximum_event_age.positive? && retention >= maximum_event_age
+        raise ConfigurationError, "retention must cover maximum_event_age, and both must be positive"
+      end
+      if soft_bounce_threshold && !(soft_bounce_threshold.is_a?(Integer) && (1..SOFT_BOUNCE_OCCURRENCE_LIMIT).cover?(soft_bounce_threshold))
+        raise ConfigurationError, "soft_bounce_threshold must be an integer from 1 to #{SOFT_BOUNCE_OCCURRENCE_LIMIT}, or nil"
+      end
+      unless [soft_bounce_window, soft_bounce_block_for].all? { |duration| duration.is_a?(Numeric) || duration.is_a?(ActiveSupport::Duration) } &&
+             soft_bounce_window.positive? && soft_bounce_block_for.positive?
+        raise ConfigurationError, "soft_bounce_window and soft_bounce_block_for must be positive durations"
+      end
+
+      self
+    end
+  end
+end

data/lib/bouncy/engine.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Bouncy
+  class Engine < Rails::Engine
+    isolate_namespace Bouncy
+
+    initializer "bouncy.model" do
+      ActiveSupport.on_load(:active_record) { extend Bouncy::Model }
+    end
+
+    initializer "bouncy.interceptor" do
+      ActiveSupport.on_load(:action_mailer) { register_interceptor Bouncy::Interceptor }
+    end
+  end
+end

data/lib/bouncy/event.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Bouncy
+  class Event < Record
+    self.table_name = "bouncy_events"
+
+    attribute :details, default: -> { {} }
+
+    scope :for, ->(email) { where(email: Identity.normalize(email)) }
+    scope :recent, -> { order(occurred_at: :desc, id: :desc) }
+
+    after_create_commit :notify_host
+
+    private
+
+    def notify_host
+      Bouncy.notify(:after_event, self)
+      Bouncy.notify(:after_block, self) if details["became_blocked"]
+      Bouncy.notify(:after_release, self) if kind == "release"
+    end
+  end
+end

data/lib/bouncy/identity.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Bouncy
+  module Identity
+    module_function
+
+    def normalize(email)
+      raise InvalidAddress, "Email addresses cannot contain control characters" if email.to_s.match?(/[\x00-\x1f\x7f]/)
+
+      value = email.to_s.strip
+      unless value.bytesize <= 254 && value.match?(/\A[^\s@<>\x00-\x1f\x7f]+@[^\s@<>\x00-\x1f\x7f]+\z/)
+        raise InvalidAddress, "Provide a nonblank email address without control characters"
+      end
+
+      value.downcase
+    end
+  end
+end

data/lib/bouncy/ingestor.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Bouncy
+  Observation = Data.define(:email, :kind, :provider_event_id, :message_id, :occurred_at, :details, :provider_reason, :status_code, :diagnostic)
+
+  class Ingestor
+    def call(observation)
+      email = observation.email && Identity.normalize(observation.email)
+      attributes = observation.to_h.merge(email: email)
+      identity = [Bouncy.scope, Bouncy.configuration.provider, observation.provider_event_id, observation.kind, email]
+      attributes[:dedupe_key] = Digest::SHA256.hexdigest(JSON.generate(identity))
+      return :duplicate if duplicate?(attributes[:dedupe_key])
+
+      if email
+        Store.change(email) do |row|
+          # Re-check under the row lock so a concurrent retry becomes a duplicate, not a unique violation.
+          next :duplicate if duplicate?(attributes[:dedupe_key])
+
+          persist(attributes, row)
+        end
+      else
+        Event.transaction { persist(attributes, nil) }
+      end
+    rescue ActiveRecord::RecordNotUnique
+      # The unique event and its state transition committed in the same transaction.
+      raise unless duplicate?(attributes[:dedupe_key])
+
+      :duplicate
+    end
+
+    private
+
+    def duplicate?(key)
+      Bouncy.events.exists?(dedupe_key: key)
+    end
+
+    def persist(attributes, row)
+      time = attributes.fetch(:occurred_at)
+      too_old = time < Bouncy.configuration.maximum_event_age.ago || time > 5.minutes.from_now
+      fenced = row&.released_before && time <= row.released_before
+      soft_fence = row && attributes[:kind] == "soft_bounce" && parse_time(row.details["soft_released_before"])
+      fenced ||= soft_fence && time <= soft_fence
+      out_of_order = attributes[:kind] != "soft_bounce" && row&.event_blocked_at && time < row.event_blocked_at
+      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")
+          row.event_blocked_at = time
+          row.event_reason = attributes[:kind]
+          row.last_event_at = [row.last_event_at, time].compact.max
+          row.details = row.details.except("absence_count")
+          row.details["exact_email"] = details["exact_email"] if details["exact_email"]
+        elsif attributes[:kind] == "soft_bounce" && details["escalation_eligible"] == true
+          count_soft_bounce(row, time, details)
+        end
+        row.summarize!
+        details["became_blocked"] = !was_blocked && row.blocked?
+      end
+      Store.event!(attributes.fetch(:kind), **attributes.except(:kind, :details), source: "webhook",
+                                                                                  provider: Bouncy.configuration.provider.to_s, details: details)
+      :accepted
+    end
+
+    # Records this soft bounce against the address and, once config.soft_bounce_threshold of them
+    # fall inside config.soft_bounce_window, holds the address for config.soft_bounce_block_for.
+    # The occurrence times are kept so the window really rolls: a bounce that ages out stops
+    # counting, instead of a running total that only ever grows. Redelivered notifications are
+    # already filtered by the event dedupe key before this runs. With no threshold configured a
+    # soft bounce only updates the counters, which is the default.
+    def count_soft_bounce(row, time, details)
+      window = Bouncy.configuration.soft_bounce_window
+      previous = Array(row.details["soft_bounces"]).filter_map { |value| parse_time(value) }
+      occurrences = (previous + [time]).select { |occurred_at| occurred_at > Time.current - window }.sort
+      occurrences = occurrences.last(Bouncy.configuration.soft_bounce_occurrences)
+      row.details = row.details.merge("soft_bounces" => occurrences.map { |occurred_at| occurred_at.iso8601(6) })
+      row.soft_bounce_count = occurrences.size
+      row.last_soft_bounce_at = [row.last_soft_bounce_at, time].compact.max
+      row.last_event_at = [row.last_event_at, time].compact.max
+      details["soft_bounce_count"] = occurrences.size
+      return unless Bouncy.configuration.soft_bounce_escalation? && occurrences.size >= Bouncy.configuration.soft_bounce_threshold
+
+      row.soft_blocked_until = [row.soft_blocked_until, occurrences.last + Bouncy.configuration.soft_bounce_block_for].compact.max
+      details["soft_blocked_until"] = row.soft_blocked_until.iso8601(6)
+    end
+
+    def parse_time(value)
+      Time.iso8601(value.to_s)
+    rescue ArgumentError, TypeError
+      nil
+    end
+  end
+end

data/lib/bouncy/interceptor.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Bouncy
+  class Interceptor
+    def self.delivering_email(message)
+      return if Bouncy.configuration.interception == :off || ActiveSupport::IsolatedExecutionState[:bouncy_unblocked]
+      return Bouncy.unconfigured!("interception") unless Bouncy.configured?
+
+      new.call(message)
+    end
+
+    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
+      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?
+      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|
+          would_drop = enforceable.include?(row)
+          Store.event!("skipped", email: row.email, source: "interceptor", details: {
+                         "mode" => mode.to_s, "reasons" => row.reasons.map(&:to_s), "would_drop" => would_drop,
+                         "dropped" => mode == :drop && would_drop, "stale_provider_evidence" => !would_drop
+                       })
+        end
+      end
+      return unless mode == :drop && blocked.any?
+
+      changed_headers.each { |field, values| message.public_send("#{field}=", values.empty? ? nil : values) }
+      message.smtp_envelope_to = remaining
+      message.perform_deliveries = false if remaining.empty?
+    rescue ActiveRecord::ActiveRecordError => e
+      raise unless Bouncy.database_unavailable?(e)
+
+      ActiveSupport::Notifications.instrument("unavailable.bouncy", operation: "interception")
+    end
+
+    private
+
+    def normalize(value)
+      Identity.normalize(Mail::Address.new(value).address)
+    rescue InvalidAddress, Mail::Field::ParseError
+      nil
+    end
+  end
+end

data/lib/bouncy/model.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Bouncy
+  module Model
+    def bouncy(*attributes, normalized_attribute: nil)
+      raise ArgumentError, "Provide an email attribute" if attributes.empty?
+      raise ArgumentError, "normalized_attribute supports one email attribute at a time" if normalized_attribute && attributes.size != 1
+
+      attributes.each do |attribute|
+        column = normalized_attribute || attribute
+        define_method("#{attribute}_status") { Bouncy.status(public_send(column)) }
+        define_method("#{attribute}_blocked?") do
+          value = public_send(column)
+          value.present? && Bouncy.blocked?(value)
+        end
+        define_method("#{attribute}_bounced?") do
+          public_send("#{attribute}_blocked?") && public_send("#{attribute}_status").reasons.intersect?(%i[hard_bounce soft_bounces])
+        end
+        define_method("#{attribute}_complained?") { public_send("#{attribute}_blocked?") && public_send("#{attribute}_status").reasons.include?(:complaint) }
+
+        scope "#{attribute}_blocked", -> { where(column => Bouncy.blocked.select(:email)) }
+        scope "#{attribute}_bounced", lambda {
+          rows = Bouncy.blocked.where("provider_reason = ? OR event_reason = ? OR soft_blocked_until > ?", "hard_bounce", "hard_bounce", Time.current)
+          where(column => rows.select(:email))
+        }
+        scope "#{attribute}_unblocked", -> { where.not(column => [nil, ""]).where.not(column => Bouncy.blocked.select(:email)) }
+      end
+    end
+  end
+end

data/lib/bouncy/providers/base.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Bouncy
+  module Providers
+    Entry = Data.define(:email, :reason, :updated_at) do
+      def to_h
+        { "email" => email, "reason" => reason.to_s, "provider_updated_at" => updated_at.iso8601(6) }
+      end
+    end
+
+    Snapshot = Data.define(:entries, :scope, :complete, :policy_verified, :started_at, :finished_at, :policy_reason) do
+      def initialize(policy_reason: nil, **members) = super
+    end
+
+    # Result of the sending-policy check: verified, or the plain-language reason it is not.
+    PolicyCheck = Data.define(:verified, :reason)
+
+    class Base
+      def snapshot = raise(NotImplementedError)
+      def lookup(_entry) = raise(NotImplementedError)
+      def release(_entries) = raise(NotImplementedError)
+    end
+  end
+end

data/lib/bouncy/providers/ses.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module Bouncy
+  module Providers
+    class Ses < Base
+      def initialize(configuration = Bouncy.configuration)
+        super()
+        @configuration = configuration
+        @settings = configuration.ses
+      end
+
+      def snapshot
+        started_at = Time.current
+        policy = policy_check
+        entries = []
+        tokens = []
+        token = nil
+        loop do
+          response = request { client.list_suppressed_destinations(page_size: 1000, next_token: token) }
+          response.suppressed_destination_summaries.each do |row|
+            Identity.normalize(row.email_address)
+            entries << Entry.new(email: row.email_address, reason: reason(row.reason), updated_at: row.last_update_time)
+          end
+          token = response.next_token
+          break if token.nil? || token.empty?
+          raise ProviderError, "SES repeated a pagination token" if tokens.include?(token)
+
+          tokens << token
+        end
+        Snapshot.new(entries: entries, scope: @configuration.scope, complete: true, policy_verified: policy.verified,
+                     policy_reason: policy.reason, started_at: started_at, finished_at: Time.current)
+      end
+
+      def lookup(email)
+        request { client.get_suppressed_destination(email_address: email) }
+        :present
+      rescue Aws::SESV2::Errors::NotFoundException
+        :absent
+      end
+
+      def release(entries)
+        outcomes = []
+        entries.each do |entry|
+          result = "removed"
+          begin
+            request { client.delete_suppressed_destination(email_address: entry.email) }
+          rescue Aws::SESV2::Errors::NotFoundException
+            # Only the exact provider identifier is checked; never substitute lowercase.
+            result = "already_absent"
+          end
+          raise ProviderError, "SES restriction remains after recovery" unless lookup(entry.email) == :absent
+
+          outcomes << { "email" => entry.email, "result" => result }
+        rescue ProviderError => e
+          outcomes << { "email" => entry.email, "result" => "failed", "error_class" => e.class.name }
+          remaining = entries.reject { |candidate| outcomes.any? { |outcome| outcome["email"] == candidate.email } }
+          outcomes.concat(remaining.map { |candidate| { "email" => candidate.email, "result" => "not_attempted" } })
+          raise ReleaseFailed.new("SES recovery did not finish; review the per-address outcomes", outcomes: outcomes)
+        end
+        outcomes
+      end
+
+      def authenticate(raw_body:, **)
+        require_sdk("sns")
+        require_relative "sns_verifier"
+        @authenticator ||= SnsVerifier.new(@configuration)
+        @authenticator.call(raw_body)
+      end
+
+      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")
+          true
+        when "UnsubscribeConfirmation"
+          Store.event!("subscription_unsubscribed", source: "webhook")
+          true
+        else
+          false
+        end
+      end
+
+      def parse(envelope)
+        SesParser.new(@configuration).call(envelope)
+      end
+
+      def doctor
+        policy = policy_check
+        { "scope" => @configuration.scope, "policy_verified" => policy.verified, "policy_reason" => policy.reason,
+          "topic_allowlist" => @settings.topic_arns.any?, "topics" => topic_checks,
+          "write_permissions" => "unknown; never tested by mutation" }
+      end
+
+      private
+
+      def require_sdk(service)
+        require "aws-sdk-#{service}"
+      rescue LoadError
+        raise ConfigurationError, "Install the optional adapter dependency: bundle add aws-sdk-#{service}"
+      end
+
+      def client
+        require_sdk("sesv2")
+        @client ||= @settings.client || Aws::SESV2::Client.new(**client_options)
+      end
+
+      def sns_client
+        require_sdk("sns")
+        @sns_client ||= @settings.sns_client || Aws::SNS::Client.new(**client_options)
+      end
+
+      def sts_client
+        require_sdk("sts")
+        @sts_client ||= @settings.sts_client || Aws::STS::Client.new(**client_options)
+      end
+
+      def client_options
+        { region: @settings.region, credentials: @settings.credentials, retry_limit: 2,
+          http_open_timeout: 3, http_read_timeout: 10 }.compact
+      end
+
+      def request
+        yield
+      rescue Seahorse::Client::NetworkingError => e
+        raise ProviderError, "AWS transport failed (#{e.class.name})"
+      rescue Aws::Errors::MissingCredentialsError
+        raise ProviderError, "AWS credentials are missing; set config.ses.credentials or configure the AWS credential chain"
+      rescue Aws::Errors::ServiceError => e
+        raise if defined?(Aws::SESV2::Errors::NotFoundException) && e.is_a?(Aws::SESV2::Errors::NotFoundException)
+
+        raise ProviderError, "AWS request failed (#{e.code})"
+      end
+
+      # Verifies that the configured scope matches the credentials and that every listed sending
+      # path uses account-level suppression for both bounces and complaints. Until this passes,
+      # sync runs in observation mode: entries are mirrored but nothing is enforced, and the
+      # reason is reported by the sync event and by `bouncy:doctor`.
+      def policy_check
+        region = @settings.region
+        raise ConfigurationError, "Set config.ses.region" unless region.to_s.match?(/\A[a-z]{2}(?:-[a-z]+)+-\d\z/)
+
+        # Resolve clients before request's typed AWS rescue clauses are needed.
+        sts = sts_client
+        account = request { sts.get_caller_identity }.account
+        expected = "ses:#{account}:#{region}:account"
+        raise UnsafeSnapshot, "Configured scope does not match AWS credentials and region" unless @configuration.scope == expected
+
+        ses = client
+        raise UnsafeSnapshot, "SES client region differs from configured scope" unless ses.config.region == region
+
+        reasons = request { ses.get_account }.suppression_attributes&.suppressed_reasons || []
+        unless reasons.sort == %w[BOUNCE COMPLAINT]
+          return PolicyCheck.new(verified: false, reason: "the SES account-level suppression list covers #{reasons.inspect}; " \
+                                                          "Bouncy needs both BOUNCE and COMPLAINT enabled for the account")
+        end
+        unless @settings.all_sending_paths_listed
+          return PolicyCheck.new(verified: false, reason: "config.ses.all_sending_paths_listed is false: list every identity and " \
+                                                          "configuration set you send through, then set it to true")
+        end
+
+        sets = @settings.configuration_sets.dup
+        @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?
+        end
+        sets.uniq.each do |name|
+          suppression = request { ses.get_configuration_set(configuration_set_name: name) }.suppression_options
+          next if suppression.nil? || suppression.suppressed_reasons.nil? || suppression.suppressed_reasons.sort == %w[BOUNCE COMPLAINT]
+
+          return PolicyCheck.new(verified: false, reason: "configuration set #{name} overrides suppression with " \
+                                                          "#{suppression.suppressed_reasons.inspect}; Bouncy needs BOUNCE and COMPLAINT")
+        end
+        PolicyCheck.new(verified: true, reason: nil)
+      end
+
+      def topic_checks
+        sns = sns_client
+        @settings.topic_arns.to_h do |arn|
+          response = request { sns.get_topic_attributes(topic_arn: arn) }
+          # Expose an explicit manual check; do not pretend a generic IAM evaluator.
+          policy = JSON.parse(response.attributes.fetch("Policy", "{}"))
+          [arn, { "readable" => true, "publisher_policy_review_required" => true,
+                  "statements" => Array(policy["Statement"]).size }]
+        end
+      end
+
+      def reason(value)
+        case value
+        when "BOUNCE" then :hard_bounce
+        when "COMPLAINT" then :complaint
+        else raise ProviderError, "Unknown SES suppression reason"
+        end
+      end
+    end
+  end
+end