cloudflare-email 0.2.0 → 0.4.0

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

@@ -1,142 +1,20 @@
-require "active_record"
 require "cloudflare/email/active_record/base"
-
+require "mailbox_kit/mailboxes/configuration"
+require "mailbox_kit/mailboxes/models"
 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 { 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 }
+      Mailbox.has_many :outbound_messages, class_name: "MailboxKit::Mailboxes::OutboundMessage"
+      # A process may also serve core-only tenants without the outbound schema.
+      Mailbox.before_destroy do
+        if self.class.connection.data_source_exists?(OutboundMessage.table_name) && outbound_messages.exists?
+          raise ::ActiveRecord::DeleteRestrictionError, :outbound_messages
         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
-        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_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
-      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 :mailbox, class_name: "MailboxKit::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

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

@@ -1,93 +1,11 @@
 require "digest"
-require "cloudflare/email/envelope"
-
+require "mailbox_kit/mailboxes/service"
 module Cloudflare
   module Email
     module Mailboxes
-      class << self
-        # Call after host authorization. The directory is a control-plane API,
-        # not a public endpoint accepting arbitrary customer domain claims.
-        def register_domain(domain:, tenant_key:, account_id:)
-          Tenancy.normalize_key(tenant_key)
-          ReceivingDomain.create!(domain: domain, tenant_key: tenant_key, account_id: account_id)
-        end
-
-        def activate_domain!(id, evidence:, sending_enabled: false)
-          raise ArgumentError, "verification evidence is required" if evidence.to_s.strip.empty?
-          domain = ReceivingDomain.find(id)
-          domain.update!(state: "active", provisioning_evidence: evidence,
-            verified_at: Time.now.utc, sending_enabled: sending_enabled)
-          domain
-        end
-
-        def for_tenant(key)
-          raise ArgumentError, "a block is required" unless block_given?
-          Tenancy.with(key) { yield Session.new(key) }
-        end
-
-        # Only call after verifying the complete ingress HMAC. Resolve before
-        # ActionMailbox or ActiveStorage accesses a tenant connection.
-        def receive(recipient:)
-          raise ArgumentError, "persistence block required" unless block_given?
-          address = canonical_address(recipient)
-          directory = ReceivingDomain.find_by(domain: address.split("@", 2).last, state: "active")
-          raise Unavailable, "receiving domain unavailable" unless directory
-          for_tenant(directory.tenant_key) do |session|
-            session.receive(address, directory) { yield }
-          end
-        rescue ::ActiveRecord::RecordNotFound
-          raise Unavailable, "mailbox address unavailable"
-        end
-
-        def canonical_address(value)
-          unless Envelope.valid_address?(value)
-            raise ValidationError, "mailbox address must be an ASCII dot-atom address"
-          end
-          value.downcase
-        end
-      end
-
-      class Session
-        attr_reader :tenant_key
-
-        def initialize(tenant_key)
-          @tenant_key = tenant_key
-        end
-
-        def mailboxes
-          context!
-          Mailbox.where(tenant_key: tenant_key)
-        end
-
-        def create(name:, address:, owner_ref: nil)
-          context!
-          Mailbox.transaction do
-            mailbox = Mailbox.create!(tenant_key: tenant_key, name: name, owner_ref: owner_ref)
-            add_address(mailbox.id, address: address)
-            mailbox
-          end
-        end
-
-        def add_address(mailbox_id, address:)
-          mailbox = active_mailbox!(mailbox_id)
-          canonical = Mailboxes.canonical_address(address)
-          local, domain = canonical.split("@", 2)
-          directory = ReceivingDomain.find_by!(domain: domain, tenant_key: tenant_key, state: "active")
-          Address.create!(tenant_key: tenant_key, mailbox_id: mailbox.id,
-            receiving_domain_id: directory.id, local_part: local, domain: domain,
-            address: canonical, state: "pending")
-        end
-
-        def activate_address!(address_id, evidence:)
-          context!
-          raise ArgumentError, "route verification evidence is required" if evidence.to_s.strip.empty?
-          address = Address.where(tenant_key: tenant_key).find(address_id)
-          active_mailbox!(address.mailbox_id)
-          active_domain!(address)
-          address.update!(state: "active", provisioning_evidence: evidence)
-          address
-        end
-
+      # Provider-specific behavior is installed only when the Cloudflare
+      # integration is explicitly loaded. Core sessions remain receiving-only.
+      module CloudflareSession
         def provision_address!(address_id, provisioner:, worker_name:)
           context!
           raise ArgumentError, "provision outside a database transaction" if Address.connection.transaction_open?
@@ -100,62 +18,11 @@ module Cloudflare
           activate_address!(address.id, evidence: "Cloudflare address rule provisioned for Worker #{worker_name}")
         end
 
-        def suspend(mailbox_id)
-          mailboxes.find(mailbox_id).tap { |mailbox| mailbox.update!(state: "suspended") }
-        end
-
-        def resume(mailbox_id)
-          mailboxes.find(mailbox_id).tap { |mailbox| mailbox.update!(state: "active") }
-        end
-
-        def messages(mailbox_id)
-          mailbox = mailboxes.find(mailbox_id)
-          Message.where(tenant_key: tenant_key, mailbox_id: mailbox.id)
-        end
-
-        def addresses(mailbox_id)
-          mailbox = mailboxes.find(mailbox_id)
-          Address.where(tenant_key: tenant_key, mailbox_id: mailbox.id)
-        end
-
-        def suspend_address(mailbox_id, address_id)
-          addresses(mailbox_id).find(address_id).tap { |address| address.update!(state: "suspended") }
-        end
-
         def outbound_messages(mailbox_id)
           mailbox = mailboxes.find(mailbox_id)
           OutboundMessage.where(tenant_key: tenant_key, mailbox_id: mailbox.id)
         end
 
-        def inbound_email(mailbox_id, message_id)
-          message = messages(mailbox_id).find(message_id)
-          ensure_storage_connection!
-          ::ActionMailbox::InboundEmail.find(message.inbound_email_id)
-        end
-
-        # Explicit permanent removal. Archive is the reversible default.
-        # Other mailbox memberships retain their shared raw source.
-        def purge_message(mailbox_id, message_id)
-          context!
-          ensure_storage_connection!
-          Message.transaction do
-            message = messages(mailbox_id).find(message_id)
-            inbound_id = message.inbound_email_id
-            message.destroy!
-            unless Message.where(inbound_email_id: inbound_id).exists?
-              ::ActionMailbox::InboundEmail.find_by(id: inbound_id)&.destroy!
-            end
-          end
-        end
-
-        def mark_read(mailbox_id, message_id, read: true)
-          messages(mailbox_id).find(message_id).update!(read_at: read ? Time.now.utc : nil)
-        end
-
-        def archive(mailbox_id, message_id, archived: true)
-          messages(mailbox_id).find(message_id).update!(archived_at: archived ? Time.now.utc : nil)
-        end
-
         def prepare(mailbox_id, operation_key:, mail:)
           context!
           raise ArgumentError, "operation_key is required" unless operation_key.is_a?(String) && !operation_key.strip.empty?
@@ -172,6 +39,7 @@ module Cloudflare
             raise ValidationError, "MIME and envelope sender must match the mailbox address"
           end
           domain = active_domain!(address)
+          raise Unavailable, "domain is not enabled for Cloudflare sending" if domain.account_id.to_s.strip.empty?
           raise Unavailable, "domain is not enabled for sending" unless domain.sending_enabled
           key = "mailbox:#{Digest::SHA256.hexdigest(JSON.generate([tenant_key, mailbox.id, operation_key]))}"
           Mailbox.transaction do
@@ -196,6 +64,7 @@ module Cloudflare
           delivery = linked_delivery!(mailbox.id, operation_key)
           address = authorized_sender!(mailbox, delivery.from_address)
           domain = active_domain!(address)
+          raise Unavailable, "domain is not enabled for Cloudflare sending" if domain.account_id.to_s.strip.empty?
           raise Unavailable, "domain is not enabled for sending" unless domain.sending_enabled && domain.account_id == delivery.account_id
           ActiveRecord::Outbox.deliver(delivery, client: Mailboxes.client_for(tenant_key, delivery.account_id))
           handler = Mailboxes.delivery_handler
@@ -233,44 +102,7 @@ module Cloudflare
           links.last&.id
         end
 
-        def receive(address, directory)
-          context!
-          ensure_storage_connection! if defined?(::ActionMailbox::InboundEmail)
-          Mailbox.transaction do
-            destination = Address.where(tenant_key: tenant_key, address: address, receiving_domain_id: directory.id, state: "active").first
-            raise Unavailable, "mailbox address unavailable" unless destination
-            mailbox = active_mailbox!(destination.mailbox_id)
-            active_domain!(destination)
-            inbound = yield
-            Message.create_or_find_by!(tenant_key: tenant_key, mailbox_id: mailbox.id,
-              inbound_email_id: inbound.id) { |row| row.recipient = address } if inbound
-            inbound
-          end
-        end
-
         private
-
-        def context!
-          raise ConfigurationError, "mailbox session used outside its tenant context" unless Tenancy.require_context! == tenant_key
-        end
-
-        def ensure_storage_connection!
-          unless defined?(::ActionMailbox::InboundEmail) && ::ActionMailbox::InboundEmail.connection_pool == Mailbox.connection_pool &&
-              ::ActiveStorage::Blob.connection_pool == Mailbox.connection_pool
-            raise ConfigurationError, "ActionMailbox, ActiveStorage and mailbox records must share the tenant connection"
-          end
-        end
-
-        def active_mailbox!(id)
-          context!
-          mailboxes.where(state: "active").find(id)
-        end
-
-        def active_domain!(address)
-          ReceivingDomain.find_by!(id: address.receiving_domain_id, domain: address.domain,
-            tenant_key: tenant_key, state: "active")
-        end
-
         def authorized_sender!(mailbox, address)
           Address.where(tenant_key: tenant_key, mailbox_id: mailbox.id, state: "active")
             .find_by!(address: Mailboxes.canonical_address(address))
@@ -283,6 +115,7 @@ module Cloudflare
           delivery
         end
       end
+      Session.include(CloudflareSession)
     end
   end
 end

data/lib/cloudflare/email/mailboxes.rb

@@ -9,3 +9,4 @@ require "cloudflare/email/mailboxes/service"
 require "cloudflare/email/mailboxes/jobs"
 
 Cloudflare::Email::Mailboxes.enable!
+require "mailbox_kit/railtie" if defined?(::Rails::Railtie)

data/lib/cloudflare/email/management/adapter.rb

@@ -0,0 +1,9 @@
+require "mailbox-kit"
+require "mailbox_kit/management/adapter"
+module Cloudflare
+  module Email
+    module Management
+      Adapter = MailboxKit::Management::Adapter
+    end
+  end
+end

data/lib/cloudflare/email/management/configuration.rb

@@ -0,0 +1,10 @@
+require "mailbox_kit/management/configuration"
+module Cloudflare
+  module Email
+    module Management
+      Configuration = MailboxKit::Management::Configuration
+      def self.configuration = MailboxKit::Management.configuration
+      def self.configure(&block) = MailboxKit::Management.configure(&block)
+    end
+  end
+end

data/lib/cloudflare/email/management/engine.rb

@@ -0,0 +1,17 @@
+require "rails/engine"
+require "action_controller/railtie"
+
+module Cloudflare
+  module Email
+    module Management
+      class Engine < ::Rails::Engine
+        isolate_namespace Cloudflare::Email::Management
+        config.root = File.expand_path("../../../..", __dir__)
+
+        config.paths["app/views"] << File.join(MailboxKit::ROOT, "app/views")
+
+        config.paths["config/routes.rb"] = "lib/cloudflare/email/management/routes.rb"
+      end
+    end
+  end
+end

data/lib/cloudflare/email/management/routes.rb

@@ -0,0 +1,14 @@
+Cloudflare::Email::Management::Engine.routes.draw do
+  get "style.css", to: "styles#show", as: :style
+  root to: "mailboxes#index"
+  resources :mailboxes, only: [:index, :show, :create] do
+    member do
+      post :aliases, action: :add_address
+      post :suspend
+      post :resume
+      get "messages/:message_id", action: :message, as: :message
+      post :mark_read
+      post :archive
+    end
+  end
+end

data/lib/cloudflare/email/management.rb

@@ -0,0 +1,7 @@
+# Explicit opt-in: require this before Rails initializes, then configure the
+# adapter in an initializer. Loading the core gem never mounts this interface.
+require "rails/engine"
+require "cloudflare-email"
+require "cloudflare/email/management/adapter"
+require "cloudflare/email/management/configuration"
+require "cloudflare/email/management/engine"

data/lib/cloudflare/email/provider_metadata.rb

@@ -0,0 +1,77 @@
+require "json"
+require "cloudflare/email/signing"
+
+module Cloudflare
+  module Email
+    # Signed assertions supplied by the forwarding integration, not proof that
+    # the original sender passed SPF/DKIM/DMARC. Never read these from MIME.
+    module ProviderMetadata
+      METADATA_KEY = "cloudflare_email_provider_metadata".freeze
+      MAX_ENCODED_BYTES = 16 * 1024
+      MAX_DEPTH = 8
+      SOURCE = /\A[a-z][a-z0-9_.-]{0,127}\z/
+
+      def self.valid?(value)
+        value.is_a?(Hash) && value.size == 2 && value.key?("data") && value.key?("source") &&
+          value["source"].is_a?(String) && SOURCE.match?(value["source"]) &&
+          value["data"].is_a?(Hash) && json_value?(value, 0)
+      end
+
+      def self.json_value?(value, depth)
+        case value
+        when Hash
+          depth < MAX_DEPTH && value.all? { |key, item| key.is_a?(String) && utf8?(key) && json_value?(item, depth + 1) }
+        when Array
+          depth < MAX_DEPTH && value.all? { |item| json_value?(item, depth + 1) }
+        when String then utf8?(value)
+        when Integer, TrueClass, FalseClass, NilClass then true
+        when Float then value.finite?
+        else false
+        end
+      end
+
+      def self.utf8?(value)
+        value.encode(Encoding::UTF_8).valid_encoding?
+      rescue EncodingError
+        false
+      end
+
+      def self.encode(source:, data:)
+        value = {"source" => source, "data" => data}
+        raise ArgumentError, "invalid provider metadata" unless valid?(value)
+        encoded = Signing.base64url_encode(JSON.generate(value))
+        raise ArgumentError, "provider metadata exceeds size limit" if encoded.bytesize > MAX_ENCODED_BYTES
+        encoded
+      end
+
+      def self.decode(encoded)
+        return unless encoded.is_a?(String) && encoded.bytesize.between?(1, MAX_ENCODED_BYTES)
+        return unless /\A[A-Za-z0-9_-]+\z/.match?(encoded)
+        bytes = Signing.base64url_decode(encoded)
+        return unless Signing.base64url_encode(bytes) == encoded
+        text = bytes.force_encoding(Encoding::UTF_8)
+        return unless text.valid_encoding?
+        value = JSON.parse(text, max_nesting: MAX_DEPTH)
+        value if valid?(value)
+      rescue JSON::ParserError, ArgumentError
+        nil
+      end
+
+      def self.for(inbound_email)
+        metadata = inbound_email.raw_email.blob&.metadata&.fetch(METADATA_KEY, nil)
+        return unless metadata.is_a?(Hash) && metadata["signature_version"] == 3
+        value = metadata.reject { |key, _| key == "signature_version" }
+        value if valid?(value)
+      end
+
+      # Stable receipt identity if JSON object members arrive in another order.
+      def self.canonical(value)
+        case value
+        when Hash then value.keys.sort.to_h { |key| [key, canonical(value[key])] }
+        when Array then value.map { |item| canonical(item) }
+        else value
+        end
+      end
+    end
+  end
+end