cloudflare-email 0.2.0 → 0.3.0

data/docs/verification/2026-09-13-durable-inbound-and-routing.md

@@ -0,0 +1,71 @@
+# Durable inbound and Routing delivery verification
+
+This change brings the verified Routing-delivery correlation from Rebulk into an
+optional gem API and adds inbound storage/recovery for Rails outages. All tests
+below use synthetic messages and disposable local storage. This report does not
+claim the new Worker configuration is deployed in Rebulk production.
+
+## Boundaries verified
+
+- Shared sending/queue HTTP requests stream bounded responses, including gzip
+  expansion, and enforce a total network deadline. Real socket tests cover
+  slow streams, socket cleanup, oversized replies and uncertain queue ACKs.
+  No ambiguous failure automatically resends an accepted email.
+- Authenticated Routing analytics validates account/zone, provider ID, sender,
+  request window and a single saved envelope recipient. Dedicated encrypted
+  receipts preserve provider evidence and support idempotent projection.
+- Inbound R2 persistence finishes before successful Email Worker return. Queue
+  messages contain only a storage pointer. Failed enqueue, Rails errors, lost
+  responses, failed deletion and exhausted retries retain the pending payload.
+  Scheduled pagination advances over poison messages and retries retained mail.
+- A real local workerd instance uses R2 and Queues against Rails with SQLite and
+  disk-backed Active Storage. With queue retries disabled, Rails 503 leaves mail
+  in R2; invoking the scheduled handler after recovery persists one message and
+  removes the pending object. Returning 503 after Rails commits also replays to
+  one record. MIME and binary attachments remain byte-identical.
+- Missing Message-ID fallback remains stable when Rails hostnames change. Valid
+  Message-IDs and raw MIME are preserved. Pre-upgrade fallback IDs require care
+  when replaying historical archive records.
+- Local workerd capacity checks pass for one 25 MiB message and two concurrent
+  25 MiB receipts, followed by concurrent handoffs. The receiver verifies exact
+  SHA256 and HMAC values, and R2 pending objects clear after acknowledgement.
+  Local workerd does not certify production memory-limit enforcement.
+
+## Reproduce
+
+Use Ruby 3.4 and Node 22 or another supported version:
+
+```sh
+BUNDLE_GEMFILE=gemfiles/local_ingress.gemfile bundle install
+npm ci --prefix templates/worker
+BUNDLE_GEMFILE=gemfiles/local_ingress.gemfile bundle exec rake test
+npm test --prefix templates/worker
+npm run check --prefix templates/worker
+node script/verify_durable_capacity.mjs
+BUNDLE_GEMFILE=gemfiles/local_ingress.gemfile bundle exec ruby script/verify_local_ingress.rb
+BUNDLE_GEMFILE=gemfiles/local_ingress.gemfile bundle exec ruby script/verify_package.rb
+```
+
+The local runtime harness invokes the real scheduled handler through a temporary
+test-only endpoint. It does not test Cloudflare's production cron scheduler or
+SMTP delivery behavior. No test endpoint is shipped in the Worker.
+
+## Before production enablement
+
+Provision a private R2 bucket, queue and schedule per environment, and keep
+pending objects free of lifecycle expiration. Deploy the updated Rails ingress
+first. Verify maximum message size and recovery throughput with expected traffic,
+then perform a staging outage drill through the actual Cloudflare email route.
+Monitor storage errors and pending object age as well as queue backlog. Keep
+Rails deduplication records throughout the recovery horizon and monitor mailbox
+routing jobs after durable ingestion.
+
+Routing tracking is separately opt-in and needs encryption keys, its migration,
+a restricted analytics read credential, and host scheduling. Cross-database
+applications must retain their durable business projection boundary and enforce
+provider-ID uniqueness across tenant databases. Missing delivery evidence stays
+unresolved; it never authorizes another send.
+
+R2 storage and retry protect mail after a successful storage commit. They cannot
+promise absolute losslessness during upstream storage failure, deletion,
+misconfiguration or account suspension. See the [operating guide](../../templates/worker/docs/durable-inbound.md).

data/lib/cloudflare/email/active_record/base.rb

@@ -4,13 +4,25 @@ require "cloudflare/email/tenancy"
 module Cloudflare
   module Email
     module ActiveRecord
+      # Rails may inspect every model's pool while preloading schema metadata
+      # before any request has selected a tenant. Report an unavailable
+      # connection using Rails' error hierarchy so boot can recover, while
+      # retaining the same fail-closed guard for every caller.
+      class TenantConnectionUnavailable < ::ActiveRecord::ConnectionNotEstablished; end
+
       # Uses the host's abstract tenant connection owner when explicitly configured.
       class Base < Tenancy.model_base(::ActiveRecord::Base)
         self.abstract_class = true
 
         class << self
           def connection_pool
-            Tenancy.require_context! if Tenancy.enabled?
+            if Tenancy.enabled?
+              begin
+                Tenancy.require_context!
+              rescue ConfigurationError => error
+                raise TenantConnectionUnavailable, error.message
+              end
+            end
             super
           end
         end

data/lib/cloudflare/email/active_record/routing_deliveries.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "cloudflare/email/routing_analytics"
+require "cloudflare/email/active_record/outbox"
+
+module Cloudflare
+  module Email
+    module ActiveRecord
+      class RoutingDeliveryReceipt < Base
+        self.table_name = "cloudflare_email_routing_delivery_receipts"
+        belongs_to :outbound_delivery, class_name: "Cloudflare::Email::ActiveRecord::OutboundDelivery"
+        encrypts :payload_json
+        attr_readonly :account_id, :zone_id, :event_key, :outbound_delivery_id, :payload_json, :received_at
+
+        def evidence
+          RoutingAnalytics::Evidence.new(JSON.parse(payload_json))
+        rescue JSON::ParserError, TypeError
+          raise RoutingAnalytics::Error, "Stored Routing analytics evidence is malformed", cause: nil
+        end
+      end
+
+      # An opt-in delivery projection, separate from Sending webhook receipts and
+      # acceptance reconciliation. No method here can send or authorize a resend.
+      class RoutingDeliveries
+        class InvalidEvidence < RoutingAnalytics::Error; end
+        ReplayResult = Struct.new(:after_id, :processed, :errors, :finished, keyword_init: true)
+
+        class << self
+          def record(delivery:, evidence:)
+            unless evidence.is_a?(RoutingAnalytics::Evidence) && delivery.is_a?(OutboundDelivery) && delivery.persisted?
+              raise ArgumentError, "A persisted outbound delivery and RoutingAnalytics::Evidence are required"
+            end
+            if RoutingDeliveryReceipt.connection.transaction_open?
+              raise ArgumentError, "record must commit outside an existing transaction before projection"
+            end
+            validate!(delivery.reload, evidence)
+            receipt = RoutingDeliveryReceipt.create_or_find_by!(account_id: evidence.account_id, event_key: evidence.identity) do |row|
+              row.outbound_delivery = delivery
+              row.zone_id = evidence.zone_id
+              row.payload_json = JSON.generate(evidence.payload)
+              row.received_at = Time.now.utc
+            end
+            unless receipt.outbound_delivery_id == delivery.id && receipt.evidence.same_event?(evidence)
+              raise InvalidEvidence, "Routing analytics evidence identity conflict"
+            end
+            receipt
+          end
+
+          # Returns :applied (including idempotent replay). An existing terminal
+          # fact is preserved; inspect recipient.state instead of assuming delivery.
+          # Only new recipient changes invoke the same-database callback.
+          def apply(receipt)
+            unless receipt.is_a?(RoutingDeliveryReceipt) && receipt.persisted?
+              raise ArgumentError, "A persisted RoutingDeliveryReceipt is required"
+            end
+            completed = false
+            receipt.with_lock(requires_new: true) do
+              if receipt.state == "applied"
+                completed = true
+                next
+              end
+              evidence = receipt.evidence
+              unless receipt.account_id == evidence.account_id && receipt.zone_id == evidence.zone_id && receipt.event_key == evidence.identity
+                raise InvalidEvidence, "Routing analytics receipt identity mismatch"
+              end
+              delivery = receipt.outbound_delivery
+              delivery.with_lock do
+                recipient = validate!(delivery, evidence)
+                unless recipient.terminal?
+                  recipient.update!(state: "delivered", occurred_at: evidence.occurred_at, terminal: true)
+                  yield delivery, recipient if block_given?
+                end
+                receipt.update!(state: "applied", applied_at: Time.now.utc)
+                completed = true
+              end
+              # ActiveRecord::Rollback can be swallowed by the nested lock's
+              # transaction. Fail before this outer transaction can commit.
+              raise ArgumentError, "Projection rolled back instead of completing" unless completed
+            end
+            raise ArgumentError, "Projection rolled back instead of completing" unless completed
+            :applied
+          end
+
+          # Each failed receipt advances the cursor too. Persist after_id in the
+          # host job and reset it to zero after finished; discovery gets its own budget.
+          def replay(account_id:, limit: 100, after_id: 0, &on_change)
+            unless account_id.is_a?(String) && !account_id.empty? && limit.is_a?(Integer) && (1..1000).cover?(limit) &&
+                after_id.is_a?(Integer) && after_id >= 0
+              raise ArgumentError, "An account, limit of 1..1000 and nonnegative cursor are required"
+            end
+            scope = RoutingDeliveryReceipt.where(account_id: account_id, state: "pending").where("id > ?", after_id).order(:id)
+            rows = scope.limit(limit).to_a
+            errors = []
+            rows.each do |receipt|
+              apply(receipt, &on_change)
+            rescue StandardError => error
+              errors << {receipt_id: receipt.id, error: error}
+            end
+            cursor = rows.last&.id || after_id
+            ReplayResult.new(after_id: cursor, processed: rows.length, errors: errors,
+              finished: !RoutingDeliveryReceipt.where(account_id: account_id, state: "pending").where("id > ?", cursor).exists?)
+          end
+
+          private
+
+          def validate!(delivery, evidence)
+            ids = OutboundDelivery.where(account_id: evidence.account_id,
+              provider_message_id: [evidence.message_id, "<#{evidence.message_id}>"]).limit(2).pluck(:id)
+            unless delivery.state == "accepted" && delivery.account_id == evidence.account_id && ids == [delivery.id] &&
+                MessageId.normalize(delivery.provider_message_id) == evidence.message_id &&
+                delivery.from_address.casecmp?(evidence.event.fetch("from")) && delivery.request_started_at &&
+                evidence.occurred_at >= Time.at(delivery.request_started_at.to_i).utc
+              raise InvalidEvidence, "Routing analytics requires one matching accepted outbound operation"
+            end
+            recipients = delivery.outbound_recipients.to_a
+            envelope = delivery.recipients
+            unless envelope.is_a?(Array) && envelope.one? && recipients.one? &&
+                recipients.first.recipient == Outbox.normalize_recipient(envelope.first) &&
+                recipients.first.acceptance_state == "accepted"
+              raise InvalidEvidence, "Routing analytics requires one accepted saved envelope recipient"
+            end
+            recipients.first
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cloudflare/email/check_route_task.rb

@@ -0,0 +1,21 @@
+require "cloudflare/email/credentials"
+require "cloudflare/email/routing_diagnostics"
+require "cloudflare/email/worker_deployer"
+
+module Cloudflare
+  module Email
+    class CheckRouteTask
+      def self.call(address:, worker_name: nil, account_id: nil, io: $stdout)
+        report = RoutingDiagnostics.new(api_token: Credentials.management_token).check(
+          address: address, worker_name: worker_name || WorkerDeployer.default_script_name,
+          account_id: account_id || Credentials.account_id)
+        report[:checks].each { |check| io.puts "#{check[:status].upcase} #{check[:name]}: #{check[:message]}" }
+        io.puts report[:limitations]
+        report[:status] == "pass" ? 0 : 1
+      rescue StandardError
+        io.puts "UNKNOWN: Unable to inspect routing. Check ADDRESS, WORKER_NAME, and Cloudflare management credentials."
+        1
+      end
+    end
+  end
+end

data/lib/cloudflare/email/client.rb

@@ -2,6 +2,8 @@ require "net/http"
 require "json"
 require "uri"
 require "time"
+require "timeout"
+require "zlib"
 require "cloudflare/email/endpoint"
 
 module Cloudflare
@@ -11,33 +13,47 @@ module Cloudflare
       DEFAULT_RETRIES  = 3
       DEFAULT_TIMEOUT  = 30
       DEFAULT_BACKOFF  = 0.5
+      DEFAULT_MAX_RESPONSE_BYTES = 1_048_576
       MAX_RETRY_AFTER  = 60 # seconds; never sleep longer than this even if server says so
 
       RETRYABLE_NETWORK = [
         Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, Errno::ECONNRESET,
         Errno::ECONNREFUSED, Errno::EHOSTUNREACH, EOFError, SocketError,
-        IOError
+        IOError, Timeout::Error, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError,
+        OpenSSL::SSL::SSLError, Zlib::Error
       ].freeze
       PRE_SEND_NETWORK = [Net::OpenTimeout, Errno::ECONNREFUSED, Errno::EHOSTUNREACH, SocketError].freeze
 
-      attr_reader :account_id, :base_url, :retries, :timeout, :retry_ambiguous
+      attr_reader :account_id, :base_url, :retries, :timeout, :retry_ambiguous,
+                  :total_timeout, :max_response_bytes
 
       def initialize(account_id:, api_token:, base_url: DEFAULT_BASE_URL,
                      retries: DEFAULT_RETRIES, timeout: DEFAULT_TIMEOUT,
                      initial_backoff: DEFAULT_BACKOFF, max_retry_after: MAX_RETRY_AFTER,
-                     retry_ambiguous: false, logger: nil)
+                     retry_ambiguous: false, logger: nil,
+                     total_timeout: timeout, max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES)
         unless account_id.is_a?(String) && account_id.match?(/\A[a-zA-Z0-9_-]+\z/)
           raise ConfigurationError, "account_id is required and must be a single account identifier"
         end
         unless api_token.is_a?(String) && !api_token.empty? && !api_token.match?(/\s/)
           raise ConfigurationError, "api_token is required and must not contain whitespace"
         end
+        [[:timeout, timeout], [:total_timeout, total_timeout]].each do |name, value|
+          unless value.is_a?(Numeric) && value.real? && value.finite? && value.positive?
+            raise ConfigurationError, "#{name} must be a finite positive number"
+          end
+        end
+        unless max_response_bytes.is_a?(Integer) && max_response_bytes.positive?
+          raise ConfigurationError, "max_response_bytes must be a positive integer"
+        end
 
         @account_id      = account_id
         @api_token       = api_token
         @base_url        = Endpoint.parse(base_url).to_s.delete_suffix("/")
         @retries         = retries
         @timeout         = timeout
+        @total_timeout   = total_timeout
+        @max_response_bytes = max_response_bytes
         @initial_backoff = initial_backoff
         @max_retry_after = max_retry_after
         @logger          = logger
@@ -143,9 +159,9 @@ module Cloudflare
           do_request(method, uri, body)
         rescue *RETRYABLE_NETWORK => e
           unless PRE_SEND_NETWORK.any? { |type| e.is_a?(type) } || @retry_ambiguous
-            raise NetworkError.new("#{e.message}; delivery outcome is unknown; automatic retry disabled")
+            raise NetworkError.new("provider response could not be read; delivery outcome is unknown; automatic retry disabled"), cause: nil
           end
-          raise NetworkError.new(e.message) if attempts > @retries
+          raise NetworkError.new("provider request could not be completed; request outcome is unknown"), cause: nil if attempts > @retries
           log_retry(attempts, e)
           sleep(backoff); backoff *= 2
           retry
@@ -194,13 +210,32 @@ module Cloudflare
         req["User-Agent"]    = "cloudflare-email-ruby/#{Cloudflare::Email::VERSION}"
         req.body = JSON.generate(body) if body
 
-        response = http.request(req)
-        handle_response(response)
+        raw = +"".b
+        response = nil
+        byte_limit = response_byte_limit(uri)
+        # Bound each network attempt, including trickling headers/body. Parsing,
+        # queue handlers, and database transactions are outside this deadline.
+        Timeout.timeout(@total_timeout) do
+          http.request(req) do |incoming|
+            response = incoming
+            incoming.read_body do |chunk|
+              # Net::HTTP yields decompressed bytes, so compressed expansion is
+              # subject to the same budget. Check before extending the buffer.
+              raise IOError, "provider response exceeds byte limit" if raw.bytesize + chunk.bytesize > byte_limit
+              raw << chunk
+            end
+          end
+        end
+        handle_response(response, raw)
+      end
+
+      def response_byte_limit(_uri)
+        @max_response_bytes
       end
 
-      def handle_response(response)
+      def handle_response(response, raw = response.body)
         status  = response.code.to_i
-        body    = parse_body(response.body)
+        body    = parse_body(raw)
         retry_after = response["Retry-After"]
 
         # Stash Retry-After on the error response so retry logic can use it.
@@ -236,7 +271,7 @@ module Cloudflare
         return {} if raw.nil? || raw.empty?
         JSON.parse(raw)
       rescue JSON::ParserError
-        { "errors" => [{ "message" => raw.to_s[0, 200] }] }
+        { "errors" => [{ "message" => "invalid JSON API response; request outcome is unknown" }] }
       end
 
       def extract_message(body)

data/lib/cloudflare/email/delivery_method.rb

@@ -25,6 +25,8 @@ module Cloudflare
           base_url:    settings[:base_url] || Cloudflare::Email::Client::DEFAULT_BASE_URL,
           retries:     settings.fetch(:retries,  Cloudflare::Email::Client::DEFAULT_RETRIES),
           timeout:     settings.fetch(:timeout,  Cloudflare::Email::Client::DEFAULT_TIMEOUT),
+          total_timeout: settings.fetch(:total_timeout, settings.fetch(:timeout, Cloudflare::Email::Client::DEFAULT_TIMEOUT)),
+          max_response_bytes: settings.fetch(:max_response_bytes, Cloudflare::Email::Client::DEFAULT_MAX_RESPONSE_BYTES),
           initial_backoff: settings.fetch(:initial_backoff, Cloudflare::Email::Client::DEFAULT_BACKOFF),
           max_retry_after: settings.fetch(:max_retry_after, Cloudflare::Email::Client::MAX_RETRY_AFTER),
           retry_ambiguous: settings.fetch(:retry_ambiguous, false),

data/lib/cloudflare/email/deploy_worker_task.rb

@@ -6,8 +6,8 @@ module Cloudflare
     # `bin/rails cloudflare:email:deploy_worker` — uploads the Worker
     # script + both secrets via the Cloudflare API. No wrangler required.
     class DeployWorkerTask < TaskBase
-      def self.call(script_path: nil, ingress_url: nil, io: $stdout)
-        new(io: io, script_path: script_path, ingress_url: ingress_url).call
+      def self.call(script_path: nil, ingress_url: nil, delivery_mode: "durable", io: $stdout)
+        new(io: io, script_path: script_path, ingress_url: ingress_url, delivery_mode: delivery_mode).call
       end
 
       protected
@@ -28,7 +28,7 @@ module Cloudflare
         )
 
         say "  Deploying Worker '#{deployer.script_name}'..."
-        deployer.deploy(script_path: path)
+        deployer.deploy(script_path: path, delivery_mode: opts[:delivery_mode])
         say "  ✓ Worker script deployed"
 
         deployer.put_secret("INGRESS_SECRET", ingress_secret)

data/lib/cloudflare/email/engine.rb

@@ -32,6 +32,11 @@ module Cloudflare
       end
 
       config.before_initialize do
+        unless defined?(Cloudflare::Email::Management::Engine)
+          Rails.autoloaders.main.ignore(
+            File.expand_path("../../../app/controllers/cloudflare/email/management", __dir__),
+          )
+        end
         unless defined?(::ActionMailbox::Engine)
           Rails.autoloaders.main.ignore(
             File.expand_path("../../../app/controllers/cloudflare/email/ingress_controller.rb", __dir__),

data/lib/cloudflare/email/envelope.rb

@@ -45,11 +45,11 @@ module Cloudflare
         nil
       end
 
-      # Only metadata written after v2 verification is trusted. MIME headers
+      # Only metadata written after v2/v3 verification is trusted. MIME headers
       # (including X-CF-* headers) never participate in this lookup.
       def self.for(inbound_email)
         metadata = inbound_email.raw_email.blob&.metadata&.fetch(METADATA_KEY, nil)
-        return nil unless metadata.is_a?(Hash) && metadata["version"] == 2
+        return nil unless metadata.is_a?(Hash) && [2, 3].include?(metadata["version"])
         value = metadata.reject { |key, _| key == "version" }
         valid?(value) ? value : nil
       end

data/lib/cloudflare/email/event_consumer.rb

@@ -9,9 +9,12 @@ module Cloudflare
     # Handler/parse/ack failures propagate; unacknowledged leases expire and
     # are redelivered according to the queue's retry/dead-letter policy.
     class EventConsumer < Client
-      def initialize(queue_id:, domains: nil, **options)
+      # Up to 100 queue messages, including encoded payloads and metadata.
+      DEFAULT_MAX_RESPONSE_BYTES = 32 * 1_048_576
+
+      def initialize(queue_id:, domains: nil, max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES, **options)
         raise ConfigurationError, "queue_id is required" unless queue_id.to_s.match?(/\A[a-zA-Z0-9_-]+\z/)
-        super(**options.merge(retries: 0, retry_ambiguous: false))
+        super(**options.merge(retries: 0, retry_ambiguous: false, max_response_bytes: max_response_bytes))
         @queue_id = queue_id
         @domains = domains && Array(domains).map(&:downcase)
       end
@@ -53,6 +56,12 @@ module Cloudflare
 
       private
 
+      def response_byte_limit(uri)
+        # ACKs contain counts, never a queue batch. Keep their smaller budget
+        # even when a pull needs room for 100 encoded event payloads.
+        uri.path.end_with?("/messages/ack") ? [@max_response_bytes, Client::DEFAULT_MAX_RESPONSE_BYTES].min : @max_response_bytes
+      end
+
       def queue_path(action)
         "/accounts/#{account_id}/queues/#{@queue_id}/messages/#{action}"
       end
@@ -79,7 +88,7 @@ module Cloudflare
         end
         DeliveryEvent.new(body)
       rescue JSON::ParserError, ArgumentError, TypeError
-        raise ValidationError, "queue body must contain a valid JSON Email Sending event"
+        raise ValidationError, "queue body must contain a valid JSON Email Sending event", cause: nil
       end
     end
   end

data/lib/cloudflare/email/ingress.rb

@@ -0,0 +1,115 @@
+require "digest"
+require "cloudflare/email/verification"
+
+module Cloudflare
+  module Email
+    # Shared bounded verification for custom Rack/Rails ingestion endpoints.
+    # This API deliberately performs no domain lookup or business processing.
+    module Ingress
+      DEFAULT_MAX_EMAIL_BYTES = 25 * 1024 * 1024
+      Result = Struct.new(:status, :message, :bytes, keyword_init: true)
+
+      class VerifiedMessage
+        attr_reader :body, :envelope, :provider_metadata, :storage_metadata, :message_checksum
+
+        def initialize(body:, envelope:, provider_metadata:, version:)
+          @body = body.b.freeze
+          @envelope = Ingress.deep_freeze(envelope)
+          @provider_metadata = Ingress.deep_freeze(provider_metadata)
+          @storage_metadata = {Envelope::METADATA_KEY => envelope.merge("version" => version.to_i)}
+          if provider_metadata
+            @storage_metadata[ProviderMetadata::METADATA_KEY] = provider_metadata.merge("signature_version" => 3)
+          end
+          Ingress.deep_freeze(@storage_metadata)
+          identity = if version == "3"
+            "v3\0#{JSON.generate([envelope.fetch('from'), envelope.fetch('to'), ProviderMetadata.canonical(provider_metadata)])}\0".b
+          else
+            "v2\0#{envelope.fetch('to')}\0".b
+          end
+          @message_checksum = Digest::SHA256.hexdigest(identity + @body).freeze
+          freeze
+        end
+        private_class_method :new
+
+        # Call within Mailboxes.receive when using the optional registry so the
+        # framework records and memberships share the resolved tenant context.
+        # Custom endpoints may instead persist body/metadata in their own store.
+        def persist_action_mailbox!
+          ::ActionMailbox::InboundEmail.transaction do
+            inbound = ::ActionMailbox::InboundEmail.create_and_extract_message_id!(body,
+              message_checksum: message_checksum, message_id: stable_message_id)
+            if inbound
+              blob = inbound.raw_email.blob
+              blob.update!(metadata: blob.metadata.merge(storage_metadata))
+            end
+            inbound
+          end
+        end
+
+        private
+
+        # ActionMailbox's fallback includes Socket.gethostname. A replay on a
+        # different Rails host must use the same database identity, while the
+        # original MIME stays untouched. Preserve parseable provider IDs.
+        def stable_message_id
+          parsed = begin
+            ::Mail.from_source(body).message_id
+          rescue StandardError
+            nil
+          end
+          parsed || "#{message_checksum}@cloudflare-email.invalid"
+        end
+      end
+
+      def self.verify(secret:, headers:, body:, content_length: nil,
+        max_email_bytes: DEFAULT_MAX_EMAIL_BYTES, now: Time.now.to_i, window: Verification::DEFAULT_WINDOW)
+        unless max_email_bytes.is_a?(Integer) && max_email_bytes.positive?
+          raise ArgumentError, "max_email_bytes must be a positive integer"
+        end
+        values = %w[Timestamp Signature Signature-Version Envelope Metadata].to_h do |name|
+          key = "X-CF-Email-#{name}"
+          value = headers[key] || headers["HTTP_#{key.upcase.tr('-', '_')}"]
+          [name, value.is_a?(String) ? value.dup.freeze : value]
+        end
+        options = {secret: secret, timestamp: values["Timestamp"], signature: values["Signature"],
+          version: values["Signature-Version"], envelope: values["Envelope"], metadata: values["Metadata"],
+          now: now, window: window}
+        status = Verification.verify_headers(**options)
+        return Result.new(status: status).freeze unless status == :ok
+        if content_length
+          length = Integer(content_length.to_s, exception: false)
+          return Result.new(status: :bad_signature).freeze unless length && length >= 0
+          return Result.new(status: :too_large).freeze if length > max_email_bytes
+        end
+        raw = if body.is_a?(String)
+          return Result.new(status: :too_large).freeze if body.bytesize > max_email_bytes
+          body.dup.b
+        elsif body.respond_to?(:read)
+          buffer = +"".b
+          while buffer.bytesize <= max_email_bytes
+            chunk = body.read(max_email_bytes + 1 - buffer.bytesize)
+            break if chunk.nil? || chunk.empty?
+            buffer << chunk.b
+          end
+          buffer
+        else
+          raise ArgumentError, "body must be a String or readable IO"
+        end
+        return Result.new(status: :too_large).freeze if raw.bytesize > max_email_bytes
+        status = Verification.verify(body: raw, **options)
+        return Result.new(status: status, bytes: raw.bytesize).freeze unless status == :ok
+        message = VerifiedMessage.send(:new, body: raw, version: values["Signature-Version"],
+          envelope: Envelope.decode(values["Envelope"]), provider_metadata: ProviderMetadata.decode(values["Metadata"]))
+        Result.new(status: :ok, message: message, bytes: raw.bytesize).freeze
+      end
+
+      def self.deep_freeze(value)
+        case value
+        when Hash then value.each { |key, item| deep_freeze(key); deep_freeze(item) }
+        when Array then value.each { |item| deep_freeze(item) }
+        end
+        value.freeze
+      end
+    end
+  end
+end

data/lib/cloudflare/email/mailboxes/models.rb

@@ -10,7 +10,7 @@ module Cloudflare
         self.table_name = "cloudflare_email_receiving_domains"
         STATES = %w[pending active suspended].freeze
         attr_readonly :domain, :tenant_key, :account_id
-        before_validation { self.domain = domain.to_s.strip.downcase }
+        before_validation(on: :create) { self.domain = domain.to_s.strip.downcase }
         validates :tenant_key, :account_id, presence: true
         validates :domain, presence: true, uniqueness: true,
           length: { maximum: 253 },
@@ -71,13 +71,14 @@ module Cloudflare
         self.table_name = "cloudflare_email_addresses"
         belongs_to :mailbox, class_name: "Cloudflare::Email::Mailboxes::Mailbox"
         attr_readonly :mailbox_id, :receiving_domain_id, :local_part, :domain, :address
-        before_validation :normalize_address
+        before_validation :normalize_address, on: :create
         validates :mailbox, :receiving_domain_id, presence: true
         validates :local_part, length: { in: 1..64 },
           format: { with: /\A[a-z0-9!\#$%&'*+\/=\?^_`{|}~-]+(?:\.[a-z0-9!\#$%&'*+\/=\?^_`{|}~-]+)*\z/ }
         validates :address, uniqueness: true, length: { maximum: 254 }
         validates :state, inclusion: { in: %w[pending active suspended] }
         validate :validate_directory
+        validate :validate_catch_all
         validate { validate_parent_tenant(mailbox, :mailbox) }
         scope :active, -> { where(state: "active") }
 
@@ -103,6 +104,22 @@ module Cloudflare
             errors.add(:receiving_domain_id, "must be active before creating addresses")
           end
         end
+
+        def validate_catch_all
+          # Existing exact-address installations need not migrate until they
+          # opt into catch-all receiving.
+          return unless has_attribute?(:catch_all) && self[:catch_all]
+          errors.add(:catch_all_evidence, "is required") if self[:catch_all_evidence].to_s.strip.empty?
+          if will_save_change_to_catch_all? && state != "active"
+            errors.add(:catch_all, "requires an active address")
+          end
+          return unless state == "active"
+          errors.add(:catch_all, "requires an active mailbox") unless mailbox&.state == "active"
+          errors.add(:catch_all, "requires an active receiving domain") unless receiving_domain&.state == "active"
+          if self.class.where(receiving_domain_id: receiving_domain_id, catch_all: true, state: "active").where.not(id: id).exists?
+            errors.add(:catch_all, "already exists for this receiving domain")
+          end
+        end
       end
 
       class Message < Cloudflare::Email::ActiveRecord::Base