bouncy 0.1.0

data/lib/bouncy/providers/ses_parser.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Bouncy
+  module Providers
+    class SesParser
+      RECIPIENT_LIMIT = 1000
+
+      def initialize(configuration)
+        @configuration = configuration
+      end
+
+      def call(envelope)
+        payload = JSON.parse(envelope.fetch("Message"), max_nesting: 20)
+        raise MalformedMessage, "Expected SES object" unless payload.is_a?(Hash)
+
+        type = payload["notificationType"] || payload["eventType"]
+        section = case type
+                  when "Bounce" then "bounce"
+                  when "Complaint" then "complaint"
+                  when "Delivery" then "delivery"
+                  when "DeliveryDelay" then "deliveryDelay"
+                  else ""
+                  end
+        data = payload.fetch(section, {})
+        raise MalformedMessage, "Invalid SES event details" unless data.is_a?(Hash)
+
+        recipients = case type
+                     when "Bounce" then data.fetch("bouncedRecipients", [])
+                     when "Complaint" then data.fetch("complainedRecipients", [])
+                     when "Delivery" then @configuration.record_deliveries ? data.fetch("recipients", []) : []
+                     when "DeliveryDelay" then data.fetch("delayedRecipients", [])
+                     else []
+                     end
+        raise MalformedMessage, "Invalid SES recipient count" unless recipients.is_a?(Array) && recipients.size <= RECIPIENT_LIMIT
+
+        mail = payload.fetch("mail", {})
+        raise MalformedMessage, "Invalid SES mail metadata" unless mail.is_a?(Hash)
+
+        time, fallback = timestamp(data["timestamp"], envelope.fetch("Timestamp"))
+        recipients = [nil] if recipients.empty?
+        recipients.map do |recipient|
+          raw_email = recipient.is_a?(Hash) ? recipient["emailAddress"] : recipient
+          email = normalize(raw_email)
+          kind, classification = classify(type, data)
+          details = { "exact_email" => raw_email.to_s.truncate(254), "timestamp_fallback" => fallback, "classification" => classification }
+          details["escalation_eligible"] = data["bounceSubType"] == "MailboxFull" if kind == "soft_bounce"
+          # SES lists every recipient of the message when the mailbox provider redacts the
+          # complainer; a single named recipient is the complainer. Only that case blocks locally.
+          details["certainty"] = recipients.size == 1 ? "confirmed" : "candidate" if kind == "complaint"
+          details["invalid_recipient"] = true if raw_email && !email
+          recipientless_kind = %w[reject rendering_failure ignored].include?(kind) && raw_email.nil?
+          Observation.new(email: email, kind: email || recipientless_kind ? kind : "ignored",
+                          provider_event_id: bounded(data["feedbackId"] || envelope.fetch("MessageId"), 255),
+                          message_id: bounded(mail["messageId"], 255), occurred_at: time, details: details,
+                          provider_reason: bounded(data["bounceSubType"] || data["complaintSubType"] || data["complaintFeedbackType"], 255),
+                          status_code: recipient.is_a?(Hash) ? bounded(recipient["status"], 255) : nil,
+                          diagnostic: recipient.is_a?(Hash) ? bounded(recipient["diagnosticCode"], 1000) : nil)
+        end
+      rescue JSON::ParserError
+        raise MalformedMessage, "Malformed SES payload"
+      end
+
+      private
+
+      def normalize(value)
+        Identity.normalize(value)
+      rescue InvalidAddress
+        nil
+      end
+
+      def bounded(value, length)
+        value&.to_s&.truncate(length)
+      end
+
+      def timestamp(value, fallback)
+        [Time.iso8601(value || fallback), value.nil?]
+      rescue ArgumentError, TypeError
+        raise MalformedMessage, "Invalid SES timestamp"
+      end
+
+      def classify(type, data)
+        case type
+        when "Bounce"
+          case data["bounceSubType"]
+          when "OnAccountSuppressionList" then %w[provider_suppressed account]
+          when "Suppressed", "OnTenantSuppressionList", "EmailValidationSuppressed" then ["unknown", data["bounceSubType"]]
+          when "UnsubscribedRecipient" then %w[unsubscribe list]
+          else
+            if data["bounceType"] == "Permanent" && %w[General NoEmail].include?(data["bounceSubType"])
+              %w[hard_bounce address]
+            elsif %w[Transient Undetermined].include?(data["bounceType"])
+              ["soft_bounce", data["bounceSubType"]]
+            else
+              %w[unknown unrecognized_bounce]
+            end
+          end
+        when "Complaint"
+          case data["complaintSubType"]
+          when "OnAccountSuppressionList" then %w[provider_suppressed account]
+          when nil then data["complaintFeedbackType"] == "not-spam" ? %w[ignored not_spam] : %w[complaint candidate]
+          else ["unknown", data["complaintSubType"]]
+          end
+        when "Delivery" then %w[delivery server_accepted]
+        when "DeliveryDelay" then %w[delay retrying]
+        when "Reject" then %w[reject message]
+        when "Rendering Failure", "RenderingFailure" then %w[rendering_failure message]
+        else %w[ignored unsupported_type]
+        end
+      end
+    end
+  end
+end

data/lib/bouncy/providers/sns_verifier.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "aws-sdk-sns"
+
+module Bouncy
+  module Providers
+    class SnsVerifier
+      BODY_LIMIT = 2 * 1024 * 1024
+
+      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
+        end
+
+        def https_get(uri, _failed_attempts = 0)
+          body = +""
+          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|
+              raise ProviderError, "SNS certificate fetch failed" unless response.code == "200"
+
+              response.read_body do |chunk|
+                body << chunk
+                raise AuthenticationError, "SNS certificate exceeds limit" if body.bytesize > 64 * 1024
+              end
+            end
+          end
+          body
+        rescue Timeout::Error, SocketError, IOError, SystemCallError, OpenSSL::SSL::SSLError
+          raise ProviderError, "SNS certificate transport unavailable"
+        end
+      end
+
+      # The bounded verifier overrides two private SDK methods. Refuse to run against an SDK that
+      # no longer has them rather than silently fetching certificates without limits.
+      HOOKS = %i[pem https_get].freeze
+
+      def initialize(configuration)
+        @configuration = configuration
+        unless HOOKS.all? { |hook| Aws::SNS::MessageVerifier.private_method_defined?(hook) }
+          raise ConfigurationError, "aws-sdk-sns #{Aws::SNS::GEM_VERSION} changed its certificate download internals; " \
+                                    "pin aws-sdk-sns to a release tested with this version of bouncy"
+        end
+
+        @verifier = configuration.ses.sns_message_verifier || BoundedVerifier.new
+        @mutex = Mutex.new
+      end
+
+      def call(raw_body)
+        envelope = JSON.parse(raw_body, max_nesting: 30)
+        raise MalformedMessage, "Expected an SNS object" unless envelope.is_a?(Hash)
+        # The SDK supports Lambda aliases by rewriting them. This HTTP receiver
+        # must not allow an unvalidated alias to replace the checked certificate URL.
+        raise MalformedMessage, "Lambda SNS aliases are not supported" if envelope.key?("SigningCertUrl")
+
+        fields = %w[Type Message MessageId Timestamp TopicArn Signature SignatureVersion SigningCertURL]
+        fields += %w[Token SubscribeURL] if %w[SubscriptionConfirmation UnsubscribeConfirmation].include?(envelope["Type"])
+        raise MalformedMessage, "Missing SNS fields" unless fields.all? { |key| envelope[key].is_a?(String) && !envelope[key].empty? }
+        unless (Aws::SNS::MessageVerifier::SIGNABLE_KEYS & envelope.keys).all? { |key| envelope[key].is_a?(String) }
+          raise MalformedMessage, "SNS signable fields must be strings"
+        end
+
+        authorize!(envelope)
+        @mutex.synchronize { @verifier.authenticate!(raw_body) }
+        envelope
+      rescue JSON::ParserError, URI::InvalidURIError
+        raise MalformedMessage, "Malformed SNS envelope"
+      rescue Aws::SNS::MessageVerifier::VerificationError, OpenSSL::OpenSSLError
+        raise AuthenticationError, "SNS signature could not be verified"
+      end
+
+      private
+
+      def authorize!(envelope)
+        topic = envelope.fetch("TopicArn")
+        settings = @configuration.ses
+        parts = topic.split(":")
+        unless settings.topic_arns.is_a?(Array) && settings.topic_arns.include?(topic) && parts.size == 6 && parts[0] == "arn" && parts[2] == "sns" &&
+               parts[3] == settings.region && @configuration.scope == "ses:#{parts[4]}:#{parts[3]}:account"
+          raise AuthenticationError, "SNS topic is not authorized"
+        end
+
+        suffix = { "aws" => "amazonaws.com", "aws-us-gov" => "amazonaws.com", "aws-cn" => "amazonaws.com.cn" }[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 &&
+               uri.path.match?(%r{\A/SimpleNotificationService-[A-Za-z0-9_-]+\.pem\z})
+          raise AuthenticationError, "SNS certificate URL is not authorized"
+        end
+      end
+    end
+  end
+end

data/lib/bouncy/prune_job.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Bouncy
+  class PruneJob < ActiveJob::Base
+    queue_as :default
+
+    def perform
+      Bouncy.configuration.validate!
+      # Keep state rows, including inactive release fences, indefinitely.
+      Bouncy.events.where("created_at < ?", Bouncy.configuration.retention.ago).in_batches.delete_all
+    end
+  end
+end

data/lib/bouncy/reconciler.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Bouncy
+  # Reconciles the provider's suppression list with local state under the scope lock.
+  #
+  # Idempotency contract: a snapshot that changes nothing about an address writes no
+  # event, fires no hook and does not bump the row's lock version. Only the observation
+  # time (provider_checked_at) is refreshed. Changed provider metadata advances the
+  # version to fence concurrent recovery, without a restriction event. Rows with neither
+  # provider evidence nor a webhook-derived block are never looked up at the provider.
+  class Reconciler
+    def initialize(adapter)
+      @adapter = adapter
+    end
+
+    def call
+      ScopeLock.synchronize { reconcile }
+    end
+
+    private
+
+    def reconcile
+      started_at = Time.current
+      versions = Suppression.where(scope: Bouncy.scope).pluck(:email, :lock_version).to_h
+      snapshot = @adapter.snapshot
+      raise UnsafeSnapshot, "Provider returned a different scope" unless snapshot.scope == Bouncy.scope
+
+      counts = Hash.new(0)
+      grouped = snapshot.entries.group_by { |entry| Identity.normalize(entry.email) }
+      grouped.each { |email, entries| counts[apply_listed(email, entries, snapshot, versions, started_at)] += 1 }
+      if snapshot.complete && snapshot.policy_verified
+        Suppression.where(scope: Bouncy.scope).find_each do |row|
+          next if grouped.key?(row.email) || !unchanged?(row, versions, started_at)
+
+          counts[check_absence(row, snapshot)] += 1
+        end
+      end
+      Store.event!("sync", source: "sync", details: {
+                     "complete" => snapshot.complete && snapshot.policy_verified, "enumerated" => snapshot.complete,
+                     "policy_verified" => snapshot.policy_verified, "policy_reason" => snapshot.policy_reason,
+                     "entries" => snapshot.entries.size, "added" => counts[:added], "updated" => counts[:updated],
+                     "released" => counts[:released], "unchanged" => counts[:unchanged],
+                     "started_at" => started_at.iso8601(6), "finished_at" => Time.current.iso8601(6)
+                   })
+    rescue ProviderError => e
+      Store.event!("sync", source: "sync", details: { "complete" => false, "error_class" => e.class.name })
+      raise
+    end
+
+    # Applies the listed entries for one normalized address.
+    # Returns :added, :updated, :unchanged or :skipped.
+    def apply_listed(email, entries, snapshot, versions, started_at)
+      previous = Suppression.find_by(scope: Bouncy.scope, email: email)
+      retained = []
+      if snapshot.complete && previous
+        listed = entries.map(&:email)
+        retained = previous.provider_entries.reject { |entry| listed.include?(entry["email"]) }.reject do |entry|
+          @adapter.lookup(entry.fetch("email")) == :absent
+        end
+      end
+      Store.change(email) do |row|
+        next :skipped unless unchanged?(row, versions, started_at)
+
+        current = entries.reject { |entry| row.released_before && entry.updated_at <= row.released_before }
+        next :skipped if current.empty?
+
+        merged = (snapshot.complete ? retained + current.map(&:to_h) : row.provider_entries + current.map(&:to_h))
+        merged = merged.group_by { |entry| entry["email"] }.values.map do |variants|
+          variants.max_by { |entry| Time.iso8601(entry.fetch("provider_updated_at")) }
+        end
+        was_blocked = row.blocked?
+        before = restriction_of(row)
+        row.provider_entries = merged
+        row.provider_checked_at = snapshot.finished_at
+        if snapshot.policy_verified
+          row.provider_blocked_at ||= current.map(&:updated_at).min
+          row.provider_reason = merged.any? { |entry| entry["reason"] == "complaint" } ? "complaint" : "hard_bounce"
+        end
+        row.details = row.details.except("absence_count")
+        if before == restriction_of(row)
+          # New evidence must fence a concurrent recovery even when the restriction is unchanged.
+          if row.provider_entries_was.sort_by { |entry| entry["email"] } == merged.sort_by { |entry| entry["email"] }
+            row.update_columns(provider_checked_at: snapshot.finished_at)
+          else
+            row.save!
+          end
+          next :unchanged
+        end
+
+        row.summarize!
+        became_blocked = !was_blocked && row.blocked?
+        kind = before.first.empty? || became_blocked ? "sync_added" : "sync_updated"
+        Store.event!(kind, email: email, source: "sync", details: { "became_blocked" => became_blocked })
+        kind == "sync_added" ? :added : :updated
+      end
+    end
+
+    def restriction_of(row)
+      [row.provider_entries.map { |entry| [entry["email"], entry["reason"]] }.sort,
+       row.provider_blocked_at.present?, row.provider_reason, row.details.key?("absence_count")]
+    end
+
+    def unchanged?(row, versions, started_at)
+      versions.key?(row.email) ? row.lock_version == versions[row.email] : row.created_at >= started_at && row.lock_version.zero? && row.released_before.nil?
+    end
+
+    # Handles a local row the complete, policy-verified snapshot did not list.
+    # Returns :released, :unchanged or :skipped.
+    def check_absence(row, snapshot)
+      return :skipped if row.provider_entries.empty? && row.event_blocked_at.nil?
+
+      version = row.lock_version
+      identifiers = row.provider_entries.map { |entry| entry.fetch("email") }
+      identifiers << row.details.fetch("exact_email", row.email) if identifiers.empty?
+      return :skipped unless identifiers.all? { |email| @adapter.lookup(email) == :absent }
+
+      Store.change(row.email) do |current|
+        next :skipped unless current.lock_version == version
+
+        was_blocked = current.blocked?
+        released = current.provider_entries.any?
+        counted = false
+        current.provider_entries = []
+        current.provider_blocked_at = current.provider_reason = nil
+        current.provider_checked_at = snapshot.finished_at
+        if current.event_blocked_at && current.event_blocked_at < 1.hour.ago
+          count = current.details.fetch("absence_count", 0) + 1
+          current.details = current.details.merge("absence_count" => count)
+          counted = true
+          if count >= 2
+            current.released_before = [current.released_before, current.event_blocked_at].compact.max
+            current.event_blocked_at = current.event_reason = nil
+            released = true
+          end
+        end
+        unless released || counted
+          current.update_columns(provider_checked_at: snapshot.finished_at)
+          next :unchanged
+        end
+
+        current.summarize!
+        next :unchanged unless released
+
+        Store.event!("sync_released", email: current.email, source: "sync",
+                                      details: { "became_unblocked" => was_blocked && !current.blocked? })
+        :released
+      end
+    end
+  end
+end

data/lib/bouncy/record.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Bouncy
+  class Record < ActiveRecord::Base
+    self.abstract_class = true
+    self.implicit_order_column = "created_at"
+
+    before_create :assign_string_primary_key
+
+    private
+
+    def assign_string_primary_key
+      self.id ||= SecureRandom.uuid if self.class.type_for_attribute(self.class.primary_key).type == :string
+    end
+  end
+end

data/lib/bouncy/recovery.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Bouncy
+  class Recovery
+    def initialize(adapter)
+      @adapter = adapter
+    end
+
+    def call(email, note:, actor:, at:)
+      raise ArgumentError, "at must be :local or :provider" unless %i[local provider].include?(at)
+      raise ArgumentError, "A recovery note is required" if at == :provider && note.to_s.strip.empty?
+
+      key = Identity.normalize(email)
+      row = Store.change(key) { |record| record }
+      version = row.lock_version
+      started_at = Time.current
+      if at == :provider
+        snapshot = @adapter.snapshot
+        unless snapshot.complete && snapshot.policy_verified && snapshot.scope == Bouncy.scope
+          raise UnsafeSnapshot, "Release requires a complete snapshot of the configured sending scope"
+        end
+
+        entries = snapshot.entries.select { |entry| Identity.normalize(entry.email) == key }
+        # Historical exact identifiers still need checking if a list page raced a write.
+        entries += row.provider_entries.map do |entry|
+          Providers::Entry.new(email: entry.fetch("email"), reason: entry.fetch("reason"), updated_at: Time.iso8601(entry.fetch("provider_updated_at")))
+        end
+        outcomes = @adapter.release(entries.uniq(&:email))
+      end
+      Store.change(key) do |current|
+        raise ReleaseConflict, "Address changed during recovery; review its latest state and retry" if current.lock_version != version
+
+        current.manual_blocked_at = current.manual_note = current.soft_blocked_until = nil
+        # Recovery clears the soft-bounce history too. Without this, one soft bounce after a
+        # release would meet the threshold again immediately and re-hold the address.
+        current.soft_bounce_count = 0
+        current.last_soft_bounce_at = nil
+        current.details = current.details.except("soft_bounces").merge("soft_released_before" => started_at.iso8601(6))
+        if at == :provider
+          current.provider_entries = []
+          current.provider_blocked_at = current.provider_reason = current.event_blocked_at = current.event_reason = nil
+          current.provider_checked_at = Time.current
+          current.released_before = started_at
+        end
+        current.summarize!
+        Store.event!("release", email: key, details: { "at" => at.to_s, "note" => note.to_s.truncate(1000),
+                                                       "actor" => actor.to_s.truncate(200), "outcomes" => outcomes })
+        current
+      end
+    rescue ProviderError, ReleaseConflict => e
+      Store.event!("release_failed", email: key, details: { "error_class" => e.class.name,
+                                                            "outcomes" => e.is_a?(ReleaseFailed) ? e.outcomes : [] })
+      raise
+    end
+  end
+end

data/lib/bouncy/scope_lock.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+
+module Bouncy
+  # One reconciliation per scope at a time. Every adapter fails fast: a second caller gets
+  # ProviderError immediately instead of queueing behind a run that may be waiting on AWS.
+  module ScopeLock
+    module_function
+
+    def synchronize
+      Record.connection_pool.with_connection do |connection|
+        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})")
+          raise ProviderError, "Another sync holds this scope lock" unless [true, "t"].include?(acquired)
+
+          begin
+            yield
+          ensure
+            connection.execute("SELECT pg_advisory_unlock(#{key})")
+          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)")
+          raise ProviderError, "Another sync holds this scope lock" unless acquired == 1
+
+          begin
+            yield
+          ensure
+            connection.execute("SELECT RELEASE_LOCK('#{name}')")
+          end
+        when "SQLite"
+          database = connection.pool.db_config.database
+          path = database == ":memory:" ? File.join(Dir.tmpdir, "bouncy-#{Process.pid}-#{key}.lock") : "#{File.expand_path(database)}.bouncy-#{key}.lock"
+          File.open(path, File::RDWR | File::CREAT, 0o600) do |file|
+            raise ProviderError, "Another sync holds this scope lock" unless file.flock(File::LOCK_EX | File::LOCK_NB)
+
+            begin
+              yield
+            ensure
+              file.flock(File::LOCK_UN)
+            end
+          end
+        else
+          raise ConfigurationError, "Bouncy supports PostgreSQL, MySQL and SQLite"
+        end
+      end
+    end
+  end
+end

data/lib/bouncy/status.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Bouncy
+  class Status
+    attr_reader :scope, :provider, :knowledge
+
+    # The underlying Bouncy::Suppression row, or nil. Hosts use it to link an address to
+    # their own admin page for it; it is not needed for any policy decision.
+    attr_reader :record
+
+    # knowledge: :observed, :no_known_block, :unavailable (recognized database outage)
+    # or :unconfigured (config.scope is not set; Bouncy is inactive).
+    def initialize(row, knowledge: nil, unavailable: false)
+      @row = row
+      @record = row
+      @scope = Bouncy.configuration.scope
+      @provider = Bouncy.configuration.provider
+      @knowledge = knowledge
+      @knowledge ||= if unavailable
+                       :unavailable
+                     elsif row
+                       :observed
+                     else
+                       :no_known_block
+                     end
+    end
+
+    def email = @row&.email
+    def blocked? = @row ? @row.blocked? : false
+    def reasons = @row ? @row.reasons : []
+    def reason = (%i[complaint hard_bounce provider_list manual soft_bounces] & reasons).first
+    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
+    def release_supported? = %i[unavailable unconfigured].exclude?(knowledge) && provider.to_sym == :ses
+
+    # The provider lists this address in the configured scope.
+    def provider_listed? = @row ? @row.provider_entries.any? : false
+
+    # Current scoped verification is separate from retained restriction evidence.
+    def policy_unverified? = provider_listed? && policy_details["policy_verified"] != true
+    def policy_reason = policy_unverified? ? (policy_details["policy_reason"] || "Sending policy could not be verified") : nil
+
+    def stale?
+      %i[unavailable unconfigured].include?(knowledge) || observed_at.nil? || observed_at < Bouncy.configuration.stale_after.ago
+    end
+
+    private
+
+    def policy_details
+      @policy_details ||= Event.where(scope: scope, kind: "sync").order(created_at: :desc, id: :desc).pick(:details) ||
+                          { "policy_reason" => "Sending policy has not been checked" }
+    rescue ActiveRecord::ActiveRecordError => e
+      raise unless Bouncy.database_unavailable?(e)
+
+      @policy_details = { "policy_reason" => "Sending policy is unavailable because the database could not be reached" }
+    end
+  end
+end

data/lib/bouncy/status_set.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Bouncy
+  # Statuses for many addresses, loaded with one query by Bouncy.statuses. Look an address
+  # up by any spelling; an address that was not asked for, or that is not a valid address,
+  # answers with a plain no-known-block status. When Bouncy is unconfigured or the database
+  # is unavailable every lookup answers with that knowledge instead.
+  class StatusSet
+    include Enumerable
+
+    def initialize(statuses, knowledge: nil)
+      @statuses = statuses
+      @knowledge = knowledge
+    end
+
+    def [](email)
+      key = begin
+        Identity.normalize(email)
+      rescue InvalidAddress
+        nil
+      end
+      (key && @statuses[key]) || Status.new(nil, knowledge: @knowledge)
+    end
+
+    # Yields [normalized_email, status] pairs for the addresses that were asked for.
+    def each(&) = @statuses.each(&)
+    def size = @statuses.size
+    def blocked = @statuses.select { |_email, status| status.blocked? }
+    def to_h = @statuses.dup
+  end
+end

data/lib/bouncy/store.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Bouncy
+  module Store
+    module_function
+
+    # Retry outside the transaction: PostgreSQL aborts a transaction on a unique violation.
+    def change(email)
+      key = Identity.normalize(email)
+      attempts = 0
+      begin
+        Suppression.transaction(requires_new: true) do
+          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 }
+        end
+      rescue ActiveRecord::RecordNotUnique, ActiveRecord::StaleObjectError, ActiveRecord::Deadlocked
+        attempts += 1
+        retry if attempts < 3
+        raise
+      end
+    end
+
+    def event!(kind, email: nil, source: "admin", occurred_at: Time.current, **attributes)
+      Event.create!({ scope: Bouncy.scope, email: email, kind: kind, source: source,
+                      received_at: Time.current, occurred_at: occurred_at }.merge(attributes))
+    end
+  end
+end

data/lib/bouncy/suppression.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Bouncy
+  class Suppression < Record
+    self.table_name = "bouncy_suppressions"
+
+    attribute :provider_entries, default: -> { [] }
+    attribute :details, default: -> { {} }
+
+    scope :blocked, lambda {
+      where("manual_blocked_at IS NOT NULL OR provider_blocked_at IS NOT NULL OR event_blocked_at IS NOT NULL OR soft_blocked_until > ?", Time.current)
+    }
+
+    def reasons
+      values = []
+      values << :manual if manual_blocked_at
+      values << provider_reason.to_sym if provider_blocked_at && provider_reason
+      values << event_reason.to_sym if event_blocked_at && event_reason
+      values << :soft_bounces if soft_blocked_until && soft_blocked_until > Time.current
+      values.uniq
+    end
+
+    def blocked?
+      reasons.any?
+    end
+
+    def summarize!
+      self.reason = (%i[complaint hard_bounce provider_list manual soft_bounces] & reasons).first
+      self.blocked_at = blocked? ? (blocked_at || Time.current) : nil
+      save!
+    end
+  end
+end

data/lib/bouncy/sync_job.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module Bouncy
+  class SyncJob < ActiveJob::Base
+    queue_as :default
+
+    def perform
+      Bouncy.sync!
+    end
+  end
+end