cloudflare-email 0.1.0 → 0.3.0

data/lib/cloudflare/email/envelope.rb

@@ -0,0 +1,58 @@
+require "json"
+require "cloudflare/email/signing"
+
+module Cloudflare
+  module Email
+    # Authenticated SMTP routing metadata, kept separate from sender-supplied MIME.
+    # v2 encodes exact {"from": string, "to": string} JSON as unpadded base64url.
+    module Envelope
+      METADATA_KEY = "cloudflare_email_envelope".freeze
+      MAX_ENCODED_BYTES = 1024
+      LOCAL_PART = /\A[A-Za-z0-9.!#$%&'*+\/=\?^_`{|}~-]+\z/
+      DOMAIN_LABEL = /\A[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\z/
+
+      def self.valid_address?(address, allow_empty: false)
+        return false unless address.is_a?(String) && address.ascii_only?
+        return true if allow_empty && address.empty?
+        return false if address.bytesize > 254
+        parts = address.split("@", -1)
+        return false unless parts.size == 2
+        local, domain = parts
+        local.bytesize <= 64 && LOCAL_PART.match?(local) &&
+          !local.start_with?(".") && !local.end_with?(".") && !local.include?("..") &&
+          domain.split(".", -1).all? { |label| DOMAIN_LABEL.match?(label) }
+      end
+
+      def self.valid?(value)
+        value.is_a?(Hash) && value.size == 2 && value.key?("from") && value.key?("to") &&
+          valid_address?(value["from"], allow_empty: true) && valid_address?(value["to"])
+      end
+
+      def self.encode(from:, to:)
+        value = { "from" => from, "to" => to }
+        raise ArgumentError, "invalid SMTP envelope" unless valid?(value)
+        Signing.base64url_encode(JSON.generate(value))
+      end
+
+      def self.decode(encoded)
+        return nil unless encoded.is_a?(String) && encoded.bytesize.between?(1, MAX_ENCODED_BYTES)
+        return nil unless /\A[A-Za-z0-9_-]+\z/.match?(encoded)
+        decoded = Signing.base64url_decode(encoded)
+        return nil unless Signing.base64url_encode(decoded) == encoded
+        value = JSON.parse(decoded)
+        valid?(value) ? value : nil
+      rescue JSON::ParserError, ArgumentError
+        nil
+      end
+
+      # 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) && [2, 3].include?(metadata["version"])
+        value = metadata.reject { |key, _| key == "version" }
+        valid?(value) ? value : nil
+      end
+    end
+  end
+end

data/lib/cloudflare/email/event_consumer.rb

@@ -0,0 +1,95 @@
+require "base64"
+require "cloudflare/email/client"
+require "cloudflare/email/delivery_event"
+
+module Cloudflare
+  module Email
+    # Short-poll a dedicated Email Sending event queue from Ruby/Rails.
+    # Each message is acknowledged only after the caller's block succeeds.
+    # Handler/parse/ack failures propagate; unacknowledged leases expire and
+    # are redelivered according to the queue's retry/dead-letter policy.
+    class EventConsumer < Client
+      # 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, max_response_bytes: max_response_bytes))
+        @queue_id = queue_id
+        @domains = domains && Array(domains).map(&:downcase)
+      end
+
+      def poll(batch_size: 5, visibility_timeout_ms: 300_000)
+        raise ArgumentError, "a delivery event handler block is required" unless block_given?
+        unless batch_size.is_a?(Integer) && (1..100).cover?(batch_size)
+          raise ArgumentError, "batch_size must be between 1 and 100"
+        end
+        unless visibility_timeout_ms.is_a?(Integer) && (1_000..43_200_000).cover?(visibility_timeout_ms)
+          raise ArgumentError, "visibility_timeout_ms must be between 1000 and 43200000"
+        end
+
+        response = request(:post, queue_path("pull"), {
+          batch_size: batch_size, visibility_timeout_ms: visibility_timeout_ms,
+        })
+        messages = response.result["messages"]
+        raise Error, "invalid queue pull response: messages must be an array" unless messages.is_a?(Array)
+
+        messages.each do |message|
+          unless message.is_a?(Hash) && message["lease_id"].is_a?(String) && !message["lease_id"].empty?
+            raise ValidationError, "queue message is missing its lease_id"
+          end
+          event = decode_event(message)
+          unless event.account_id == account_id && (!@domains || @domains.include?(event.domain.to_s.downcase))
+            raise ValidationError, "Email Sending event does not match configured account/domain"
+          end
+          instrument("cloudflare_email.delivery_event", event_id: event.event_id,
+                     message_id: event.message_id, status: event.status) do
+            yield event
+          end
+          ack = request(:post, queue_path("ack"), { acks: [{ lease_id: message["lease_id"] }], retries: [] })
+          unless ack.result["ackCount"] == 1
+            raise Error.new("queue did not acknowledge the message; it may be redelivered", response: ack.raw, status: ack.status)
+          end
+        end
+        messages.length
+      end
+
+      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
+
+      def decode_event(message)
+        body = message["body"]
+        metadata = message["metadata"]
+        content_type = metadata.is_a?(Hash) ? metadata["CF-Content-Type"] : nil
+        case content_type
+        when "json"
+          # Email Sending subscriptions return plain JSON strings from HTTP
+          # pull. Also accept the base64 JSON transport used by other producers.
+          begin
+            body = JSON.parse(body)
+          rescue JSON::ParserError
+            body = JSON.parse(Base64.strict_decode64(body))
+          end
+        when "bytes"
+          body = JSON.parse(Base64.strict_decode64(body))
+        when "text"
+          body = JSON.parse(body)
+        else
+          raise ValidationError, "unsupported queue content type; use json, bytes, or text"
+        end
+        DeliveryEvent.new(body)
+      rescue JSON::ParserError, ArgumentError, TypeError
+        raise ValidationError, "queue body must contain a valid JSON Email Sending event", cause: nil
+      end
+    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/configuration.rb

@@ -0,0 +1,58 @@
+require "active_record"
+require "cloudflare/email/error"
+
+module Cloudflare
+  module Email
+    module Mailboxes
+      class Unavailable < Cloudflare::Email::Error; end
+
+      class << self
+        def configure(directory_base: ::ActiveRecord::Base, client_resolver: nil)
+          if const_defined?(:ReceivingDomain, false)
+            raise ConfigurationError, "configure mailboxes before loading mailbox models"
+          end
+          unless directory_base.is_a?(Class) && directory_base <= ::ActiveRecord::Base
+            raise ConfigurationError, "directory_base must be an ActiveRecord base class"
+          end
+          if client_resolver && !client_resolver.respond_to?(:call)
+            raise ConfigurationError, "client_resolver must be callable"
+          end
+          @directory_base = directory_base
+          @client_resolver = client_resolver
+        end
+
+        def directory_base = @directory_base || ::ActiveRecord::Base
+
+        def delivery_handler = rails_setting(:outbox_delivery_handler)
+        def recipient_handler = rails_setting(:outbox_recipient_handler)
+
+        def client_for(tenant_key, account_id)
+          client = if @client_resolver
+            @client_resolver.call(tenant_key, account_id)
+          else
+            require "cloudflare/email/credentials"
+            unless Credentials.account_id == account_id
+              raise ConfigurationError, "configure a tenant/account client_resolver for this sending account"
+            end
+            Client.new(account_id: account_id, api_token: Credentials.api_token, retry_ambiguous: false)
+          end
+          unless client.account_id == account_id && client.retry_ambiguous == false
+            raise ConfigurationError, "mailbox client must match account and disable ambiguous retries"
+          end
+          client
+        end
+
+        def enabled? = @enabled == true
+        def enable! = @enabled = true
+
+        private
+
+        def rails_setting(name)
+          if defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+            ::Rails.application.config.x.cloudflare_email.public_send(name)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+require "cloudflare/email/active_record/delivery_events"
+require "cloudflare/email/mailboxes/shared_event_receipt"
+require "cloudflare/email/mailboxes/provider_correlation"
+
+module Cloudflare
+  module Email
+    module Mailboxes
+      # Queue ACK follows shared intake. Projection is separately replayable:
+      # a crash between tenant commit and shared completion simply replays the
+      # tenant's idempotent receipt. No distributed transaction is assumed.
+      class Events
+        class << self
+          def record(event)
+            outside_shared_transaction!
+            event = DeliveryEvent.new(event.raw)
+            receipt = SharedEventReceipt.create_or_find_by!(account_id: event.account_id, event_id: event.event_id) do |row|
+              row.message_id = MessageId.normalize(event.message_id)
+              row.recipient = normalize_recipient(event.recipient)
+              row.payload_json = JSON.generate(event.raw)
+              row.state = "pending"
+            end
+            raise ValidationError, "event ID already recorded with a different payload" unless receipt.event.raw == event.raw
+            receipt
+          end
+
+          # Call after provider acceptance has committed in the tenant database.
+          # Duplicate registrations are harmless; collisions remain visible and
+          # deliberately prevent routing rather than selecting an arbitrary tenant.
+          def register(delivery, tenant_key: Tenancy.require_context!)
+            assert_context!(tenant_key)
+            outside_shared_transaction!
+            raise ArgumentError, "registration must follow the tenant commit" if delivery.class.connection.transaction_open?
+            delivery.reload
+            unless delivery.persisted? && %w[accepted partial].include?(delivery.state) && !delivery.provider_message_id.to_s.empty?
+              raise ArgumentError, "expected a committed accepted delivery with a provider message ID"
+            end
+            unless OutboundMessage.where(tenant_key: tenant_key, outbound_delivery_id: delivery.id).exists?
+              raise ArgumentError, "delivery does not belong to a mailbox in the current tenant"
+            end
+            delivery.outbound_recipients.map do |recipient|
+              ProviderCorrelation.create_or_find_by!(account_id: delivery.account_id,
+                message_id: MessageId.normalize(delivery.provider_message_id), recipient: normalize_recipient(recipient.recipient),
+                tenant_key: tenant_key.to_s, outbound_delivery_id: delivery.id)
+            end
+          end
+
+          def apply(receipt, &on_change)
+            outside_shared_transaction!
+            raise ArgumentError, "expected a persisted shared receipt" unless receipt.is_a?(SharedEventReceipt) && receipt.persisted?
+            receipt.reload
+            return receipt if receipt.state == "applied"
+
+            candidates = ProviderCorrelation.where(account_id: receipt.account_id,
+              message_id: receipt.message_id, recipient: receipt.recipient).limit(2).to_a
+            outcome = :unmatched
+            if candidates.length == 1
+              correlation = candidates.first
+              outcome = Tenancy.with(correlation.tenant_key) do
+                project(receipt.event, correlation, &on_change)
+              end
+            end
+            # Never overwrite another worker's completed projection.
+            SharedEventReceipt.where(id: receipt.id, state: %w[pending unmatched]).update_all(
+              state: outcome.to_s, applied_at: outcome == :applied ? Time.now.utc : nil, updated_at: Time.now.utc)
+            receipt.reload
+          end
+
+          # A bounded page, not an unbounded find_each scan. Use the last scanned
+          # ID as after_id for the next page, and restart at zero on the next pass.
+          def replay(limit: 100, after_id: 0, account_id: nil, &on_change)
+            raise ArgumentError, "limit must be between 1 and 1000" unless limit.is_a?(Integer) && (1..1000).cover?(limit)
+            raise ArgumentError, "after_id must be nonnegative" unless after_id.is_a?(Integer) && after_id >= 0
+            scope = SharedEventReceipt.where(state: %w[pending unmatched]).where("id > ?", after_id)
+            scope = scope.where(account_id: account_id) if account_id
+            scope.order(:id).limit(limit).to_a.each { |receipt| apply(receipt, &on_change) }
+          end
+
+          private
+
+          def outside_shared_transaction!
+            if SharedEventReceipt.connection.transaction_open?
+              raise ArgumentError, "shared event processing must run outside an existing database transaction"
+            end
+          end
+
+          def normalize_recipient(value)
+            ActiveRecord::Outbox.normalize_recipient(value)
+          end
+
+          def assert_context!(key)
+            raise ConfigurationError, "delivery belongs to another tenant" unless Tenancy.require_context! == key
+          end
+
+          def project(event, correlation, &on_change)
+            assert_context!(correlation.tenant_key)
+            return :unmatched unless OutboundMessage.where(tenant_key: correlation.tenant_key,
+              outbound_delivery_id: correlation.outbound_delivery_id).exists?
+            delivery = ActiveRecord::OutboundDelivery.find_by(id: correlation.outbound_delivery_id,
+              account_id: event.account_id, provider_message_id: MessageId.normalize(event.message_id), state: %w[accepted partial])
+            return :unmatched unless delivery && delivery.outbound_recipients.exists?(recipient: normalize_recipient(event.recipient))
+            return :unmatched unless ReceivingDomain.active.where(tenant_key: correlation.tenant_key,
+              account_id: event.account_id, domain: delivery.from_address.rpartition("@").last.downcase).exists?
+            # DeliveryEvents also refuses collisions within the tenant. Its
+            # transactional receipt protects callback writes against redelivery.
+            receipt = ActiveRecord::DeliveryEvents.record(event, &on_change)
+            receipt.state == "applied" ? :applied : :unmatched
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+module Cloudflare
+  module Email
+    module Mailboxes
+      # ActionMailbox normally deletes processed mail after its retention window.
+      # A mailbox membership owns the raw source until explicit application purge.
+      module InboundRetention
+        def incinerate
+          return if Mailboxes.enabled? && Message.where(inbound_email_id: id).exists?
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+require "active_job"
+
+module Cloudflare
+  module Email
+    module Mailboxes
+      class SendJob < ::ActiveJob::Base
+        queue_as :mailers
+
+        def perform(tenant_key, mailbox_id, operation_key)
+          Mailboxes.for_tenant(tenant_key) { |session| session.deliver(mailbox_id, operation_key: operation_key) }
+        end
+      end
+
+      class RecoverJob < ::ActiveJob::Base
+        queue_as :mailers
+
+        def perform(tenant_key, after_id = 0)
+          cursor = Mailboxes.for_tenant(tenant_key) { |session| session.recover(after_id: after_id) }
+          self.class.perform_later(tenant_key, cursor) if cursor
+        end
+      end
+
+      class ReplayEventsJob < ::ActiveJob::Base
+        queue_as :mailers
+
+        def perform(after_id = 0)
+          handler = Mailboxes.recipient_handler
+          page = Events.replay(after_id: after_id, &(handler.method(:call) if handler.respond_to?(:call)))
+          self.class.perform_later(page.last.id) if page.length == 100
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,165 @@
+require "active_record"
+require "cloudflare/email/active_record/base"
+
+module Cloudflare
+  module Email
+    module Mailboxes
+      # Domains are an administrator-maintained receiving directory. An active
+      # record is an assertion by the application, not DNS ownership verification.
+      class ReceivingDomain < Mailboxes.directory_base
+        self.table_name = "cloudflare_email_receiving_domains"
+        STATES = %w[pending active suspended].freeze
+        attr_readonly :domain, :tenant_key, :account_id
+        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 },
+          format: { with: /\A[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+\z/ }
+        validates :state, inclusion: { in: STATES }
+        validate do
+          errors.add(:domain, "has an oversized label") if domain.to_s.split(".").any? { |label| label.length > 63 }
+        end
+        scope :active, -> { where(state: "active") }
+      end
+
+      module TenantIdentity
+        extend ActiveSupport::Concern
+        included do
+          attr_readonly :tenant_key
+          validates :tenant_key, presence: true
+          before_validation :assign_tenant_identity
+          validate :validate_tenant_identity
+          before_destroy :assert_tenant_identity!
+        end
+
+        private
+
+        def assign_tenant_identity
+          self.tenant_key ||= Tenancy.current_key
+        end
+
+        def validate_tenant_identity
+          return unless Tenancy.enabled? || Tenancy.current_key
+          Tenancy.require_context!
+          errors.add(:tenant_key, "does not match the current tenant") unless tenant_key == Tenancy.current_key
+        end
+
+        def assert_tenant_identity!
+          return unless Tenancy.enabled? || Tenancy.current_key
+          Tenancy.require_context!
+          raise ArgumentError, "record belongs to another tenant" unless tenant_key == Tenancy.current_key
+        end
+
+        def validate_parent_tenant(parent, attribute)
+          errors.add(attribute, "belongs to another tenant") if parent && parent.tenant_key != tenant_key
+        end
+      end
+
+      class Mailbox < Cloudflare::Email::ActiveRecord::Base
+        include TenantIdentity
+        self.table_name = "cloudflare_email_mailboxes"
+        has_many :addresses, class_name: "Cloudflare::Email::Mailboxes::Address", dependent: :restrict_with_exception
+        has_many :messages, class_name: "Cloudflare::Email::Mailboxes::Message", dependent: :restrict_with_exception
+        has_many :outbound_messages, class_name: "Cloudflare::Email::Mailboxes::OutboundMessage", dependent: :restrict_with_exception
+        validates :name, presence: true, length: { maximum: 255 }
+        validates :state, inclusion: { in: %w[active suspended] }
+        scope :active, -> { where(state: "active") }
+      end
+
+      class Address < Cloudflare::Email::ActiveRecord::Base
+        include TenantIdentity
+        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, 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") }
+
+        def receiving_domain
+          ReceivingDomain.find_by(id: receiving_domain_id)
+        end
+
+        private
+
+        def normalize_address
+          self.local_part = local_part.to_s.strip.downcase
+          self.domain = domain.to_s.strip.downcase
+          self.address = "#{local_part}@#{domain}"
+        end
+
+        def validate_directory
+          registered = receiving_domain
+          unless registered && registered.domain == domain && registered.tenant_key == tenant_key
+            errors.add(:receiving_domain_id, "must match this tenant and domain")
+            return
+          end
+          if new_record? && registered.state != "active"
+            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
+        include TenantIdentity
+        self.table_name = "cloudflare_email_mailbox_messages"
+        belongs_to :mailbox, class_name: "Cloudflare::Email::Mailboxes::Mailbox"
+        attr_readonly :mailbox_id, :inbound_email_id, :recipient
+        validates :mailbox, :inbound_email_id, :recipient, presence: true
+        # The unique database index also supports create_or_find_by! retries.
+        validate { validate_parent_tenant(mailbox, :mailbox) }
+        scope :unread, -> { where(read_at: nil) }
+        scope :inbox, -> { where(archived_at: nil) }
+
+        def mark_read!
+          update!(read_at: Time.current)
+        end
+
+        def mark_unread!
+          update!(read_at: nil)
+        end
+
+        def archive!
+          update!(archived_at: Time.current)
+        end
+
+        def unarchive!
+          update!(archived_at: nil)
+        end
+      end
+
+      class OutboundMessage < Cloudflare::Email::ActiveRecord::Base
+        include TenantIdentity
+        self.table_name = "cloudflare_email_mailbox_outbound_messages"
+        belongs_to :mailbox, class_name: "Cloudflare::Email::Mailboxes::Mailbox"
+        belongs_to :outbound_delivery, class_name: "Cloudflare::Email::ActiveRecord::OutboundDelivery"
+        attr_readonly :mailbox_id, :outbound_delivery_id
+        validates :mailbox, :outbound_delivery, presence: true
+        # Enforce uniqueness in the database so idempotent link creation works.
+        validate { validate_parent_tenant(mailbox, :mailbox) }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+module Cloudflare
+  module Email
+    module Mailboxes
+      # Shared routing evidence, never inferred from a sender or event domain.
+      class ProviderCorrelation < Mailboxes.directory_base
+        self.table_name = "cloudflare_email_provider_correlations"
+        attr_readonly :account_id, :message_id, :recipient, :tenant_key, :outbound_delivery_id
+      end
+    end
+  end
+end