cloudflare-email 0.1.0 → 0.3.0

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

@@ -0,0 +1,372 @@
+require "digest"
+require "cloudflare/email/envelope"
+
+module Cloudflare
+  module Email
+    module Mailboxes
+      # A routing snapshot, not a model or an authorization token. Use it inside
+      # the yielded tenant context; later jobs must resolve/check policy again.
+      Destination = Struct.new(:tenant_key, :mailbox_id, :address_id,
+        :receiving_domain_id, :recipient, :owner_ref, :catch_all, keyword_init: true) do
+        def initialize(**attributes)
+          super(**{ catch_all: false }.merge(attributes).transform_values { |value| value.is_a?(String) ? value.dup.freeze : value })
+          freeze
+        end
+      end
+
+      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:, &block)
+          raise ArgumentError, "persistence block required" unless block
+          in_recipient_tenant(recipient) do |session, address, directory|
+            session.receive(address, directory) do |destination|
+              # Preserve strict callbacks accepted before destinations were yielded.
+              block.lambda? && block.arity.zero? ? block.call : block.call(destination)
+            end
+          end
+        end
+
+        # Lookup only: the host owns persistence and the block's return value.
+        # Verify ingress before calling this API. No ActionMailbox is required.
+        def with_recipient(recipient:)
+          raise ArgumentError, "a block is required" unless block_given?
+          in_recipient_tenant(recipient) do |session, address, directory|
+            session.with_recipient(address, directory) { |destination| yield destination }
+          end
+        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
+
+        private
+
+        def in_recipient_tenant(recipient)
+          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|
+            yield session, address, directory
+          end
+        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
+
+        def provision_address!(address_id, provisioner:, worker_name:)
+          context!
+          raise ArgumentError, "provision outside a database transaction" if Address.connection.transaction_open?
+          address = Address.where(tenant_key: tenant_key).find(address_id)
+          active_mailbox!(address.mailbox_id)
+          active_domain!(address)
+          provisioner.provision(address: address.address, worker_name: worker_name)
+          # Failed requests leave the address pending; the existing provisioner
+          # upserts a rule, making a deliberate retry safe.
+          activate_address!(address.id, evidence: "Cloudflare address rule provisioned for Worker #{worker_name}")
+        end
+
+        # This records the host's verified provider routing decision; it does
+        # not provision Cloudflare DNS/rules or authorize arbitrary From values.
+        def enable_catch_all(address_id, evidence:)
+          context!
+          catch_all_schema!
+          raise ArgumentError, "catch-all route verification evidence is required" if evidence.to_s.strip.empty?
+          Address.transaction do
+            address = Address.where(tenant_key: tenant_key, state: "active").find(address_id)
+            active_mailbox!(address.mailbox_id)
+            active_domain!(address)
+            address.update!(catch_all: true, catch_all_evidence: evidence)
+            address
+          end
+        end
+
+        def disable_catch_all(address_id)
+          context!
+          catch_all_schema!
+          # Disabling is permitted even after suspension; retain the previous
+          # verification evidence for operator inspection.
+          Address.where(tenant_key: tenant_key).find(address_id).tap { |address| address.update!(catch_all: false) }
+        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?
+          mail = mail.message if mail.respond_to?(:message) && !mail.respond_to?(:encoded)
+          raise ValidationError, "mail must be a rendered Mail message" unless mail.respond_to?(:encoded)
+          mailbox = active_mailbox!(mailbox_id)
+          from = Array(mail.from)
+          raise ValidationError, "mail must have one mailbox From address" unless from.length == 1
+          sender = Array(mail.sender)
+          address = authorized_sender!(mailbox, from.first)
+          envelope_from = mail.respond_to?(:smtp_envelope_from) ? mail.smtp_envelope_from : from.first
+          unless Mailboxes.canonical_address(envelope_from) == address.address &&
+              sender.all? { |value| Mailboxes.canonical_address(value) == address.address }
+            raise ValidationError, "MIME and envelope sender must match the mailbox address"
+          end
+          domain = active_domain!(address)
+          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
+            delivery = ActiveRecord::Outbox.prepare_mail(account_id: domain.account_id, operation_key: key, mail: mail)
+            OutboundMessage.create_or_find_by!(tenant_key: tenant_key, mailbox_id: mailbox.id,
+              outbound_delivery_id: delivery.id)
+            delivery
+          end
+        end
+
+        # Enqueue only after the outer transaction commits. No mail or model
+        # GlobalIDs are serialized into this job, just stable identities.
+        def enqueue(mailbox_id, operation_key:)
+          context!
+          raise ArgumentError, "enqueue after database commit" if Mailbox.connection.transaction_open?
+          linked_delivery!(mailbox_id, operation_key)
+          SendJob.perform_later(tenant_key, mailbox_id, operation_key)
+        end
+
+        def deliver(mailbox_id, operation_key:)
+          mailbox = active_mailbox!(mailbox_id)
+          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 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
+          delivery.with_lock { handler.call(delivery) } if handler.respond_to?(:call)
+          Events.register(delivery, tenant_key: tenant_key) if %w[accepted partial].include?(delivery.state) && delivery.provider_message_id
+          delivery
+        end
+
+        def reconcile(mailbox_id, operation_key:, **evidence, &handler)
+          delivery = linked_delivery!(mailbox_id, operation_key)
+          raise ArgumentError, "reconcile outside an outer transaction" if Mailbox.connection.transaction_open?
+          ActiveRecord::Outbox.reconcile(delivery, **evidence, &handler)
+          Events.register(delivery, tenant_key: tenant_key) if %w[accepted partial].include?(delivery.state) && delivery.provider_message_id
+          delivery
+        end
+
+        # A bounded repair pass after an enqueue gap or cross-database commit
+        # gap. Does not automatically resend sending/unknown/rejected rows.
+        def recover(limit: 100, after_id: 0)
+          context!
+          raise ArgumentError, "recover outside a database transaction" if Mailbox.connection.transaction_open?
+          raise ArgumentError, "limit must be 1..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
+          links = OutboundMessage.where(tenant_key: tenant_key).where("id > ?", after_id).order(:id).limit(limit).to_a
+          links.each do |link|
+            delivery = ActiveRecord::OutboundDelivery.find(link.outbound_delivery_id)
+            if delivery.state == "prepared"
+              enqueue(link.mailbox_id, operation_key: delivery.operation_key) if mailboxes.find(link.mailbox_id).state == "active"
+            elsif %w[accepted partial].include?(delivery.state)
+              handler = Mailboxes.delivery_handler
+              delivery.with_lock { handler.call(delivery) } if handler.respond_to?(:call)
+              Events.register(delivery, tenant_key: tenant_key) if delivery.provider_message_id
+            end
+          end
+          links.last&.id
+        end
+
+        def receive(address, directory)
+          context!
+          ensure_storage_connection! if defined?(::ActionMailbox::InboundEmail)
+          Mailbox.transaction do
+            destination = resolve_destination(address, directory)
+            inbound = yield destination
+            Message.create_or_find_by!(tenant_key: tenant_key, mailbox_id: destination.mailbox_id,
+              inbound_email_id: inbound.id) { |row| row.recipient = address } if inbound
+            inbound
+          end
+        end
+
+        def with_recipient(address, directory)
+          context!
+          yield resolve_destination(address, directory)
+        end
+
+        private
+
+        def resolve_destination(address, directory)
+          destination = Address.where(tenant_key: tenant_key, address: address,
+            receiving_domain_id: directory.id).first
+          fallback = destination.nil?
+          if fallback && catch_all_schema_available?
+            destination = Address.where(tenant_key: tenant_key, receiving_domain_id: directory.id,
+              catch_all: true, state: "active").first
+          end
+          # An exact pending/suspended address intentionally reserves its name.
+          # It must never fall through to another mailbox's catch-all.
+          raise Unavailable, "mailbox address unavailable" unless destination&.state == "active"
+          mailbox = active_mailbox!(destination.mailbox_id)
+          active_domain!(destination)
+          Destination.new(tenant_key: tenant_key, mailbox_id: mailbox.id,
+            address_id: destination.id, receiving_domain_id: directory.id,
+            recipient: address, owner_ref: mailbox.owner_ref, catch_all: fallback)
+        rescue ::ActiveRecord::RecordNotFound
+          raise Unavailable, "mailbox address unavailable"
+        end
+
+        def context!
+          raise ConfigurationError, "mailbox session used outside its tenant context" unless Tenancy.require_context! == tenant_key
+        end
+
+        def catch_all_schema_available?
+          Address.connection.column_exists?(Address.table_name, :catch_all) &&
+            Address.connection.column_exists?(Address.table_name, :catch_all_evidence)
+        end
+
+        def catch_all_schema!
+          unless catch_all_schema_available?
+            raise ConfigurationError, "run cloudflare:email:mailboxes:catch_all migrations for this tenant first"
+          end
+        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))
+        end
+
+        def linked_delivery!(mailbox_id, operation_key)
+          mailbox = mailboxes.find(mailbox_id)
+          delivery = ActiveRecord::OutboundDelivery.find_by!(operation_key: operation_key)
+          OutboundMessage.find_by!(tenant_key: tenant_key, mailbox_id: mailbox.id, outbound_delivery_id: delivery.id)
+          delivery
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+module Cloudflare
+  module Email
+    module Mailboxes
+      class SharedEventReceipt < Mailboxes.directory_base
+        self.table_name = "cloudflare_email_shared_event_receipts"
+        attr_readonly :account_id, :event_id, :message_id, :recipient, :payload_json
+
+        def event
+          DeliveryEvent.new(JSON.parse(payload_json))
+        end
+      end
+    end
+  end
+end

data/lib/cloudflare/email/mailboxes.rb

@@ -0,0 +1,11 @@
+# Explicit opt-in. Configure Tenancy and Mailboxes before loading this file.
+require "cloudflare-email"
+require "cloudflare/email/tenancy"
+require "cloudflare/email/mailboxes/configuration"
+require "cloudflare/email/active_record"
+require "cloudflare/email/mailboxes/models"
+require "cloudflare/email/mailboxes/events"
+require "cloudflare/email/mailboxes/service"
+require "cloudflare/email/mailboxes/jobs"
+
+Cloudflare::Email::Mailboxes.enable!

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

@@ -0,0 +1,31 @@
+module Cloudflare
+  module Email
+    module Management
+      # A host supplies authentication, mailbox ownership and domain entitlement.
+      # Defaults deliberately grant no access. No principal comes from params.
+      class Adapter
+        attr_reader :controller
+
+        def initialize(controller = nil)
+          @controller = controller
+        end
+
+        def authenticate! = false
+        def tenant_key = nil
+        def mailboxes(session) = session.mailboxes.none
+        def allowed?(action, mailbox = nil) = false
+        def domains(session) = []
+
+        # Override these two hooks when the host keeps a linked product model or
+        # uses a deployment policy to activate/provision verified addresses.
+        def create_mailbox(session, name:, address:)
+          session.create(name: name, address: address)
+        end
+
+        def add_address(session, mailbox, address:)
+          session.add_address(mailbox.id, address: address)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+module Cloudflare
+  module Email
+    module Management
+      class Configuration
+        attr_accessor :adapter, :back_path
+      end
+
+      def self.configuration
+        @configuration ||= Configuration.new
+      end
+
+      def self.configure
+        yield configuration
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+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["config/routes.rb"] = "lib/cloudflare/email/management/routes.rb"
+      end
+    end
+  end
+end

data/lib/cloudflare/email/management/management.css

@@ -0,0 +1,68 @@
+:root { color-scheme: light; --ink: #172c35; --muted: #536871; --line: #dce4e6; --accent: #12655c; --surface: #fff; }
+* { box-sizing: border-box; }
+body { margin: 0; background: #f5f7f7; color: var(--ink); font: 16px/1.55 system-ui, sans-serif; }
+a { color: var(--accent); text-underline-offset: 3px; }
+a:hover { text-decoration-thickness: 2px; }
+:focus-visible { outline: 3px solid #b66a17; outline-offset: 4px; }
+.shell { width: min(1160px, 100% - 48px); margin: 0 auto; }
+.site-header { background: var(--surface); border-bottom: 1px solid var(--line); }
+.header-content { display: flex; justify-content: space-between; align-items: center; gap: 16px; min-height: 76px; }
+.brand { color: var(--ink); font-weight: 750; font-size: 18px; text-decoration: none; }
+.header-caption, .muted, .field-help { color: var(--muted); }
+main.shell { padding-top: 32px; padding-bottom: 64px; }
+h1, h2, h3, p { margin: 0; }
+h1 { font-size: clamp(26px, 4vw, 36px); line-height: 1.2; letter-spacing: -.035em; overflow-wrap: anywhere; }
+h2 { font-size: 17px; line-height: 1.4; }
+h3 { font-size: 17px; }
+.small, .field-help { font-size: 13px; }
+.eyebrow { color: var(--accent); font-size: 12px; font-weight: 750; text-transform: uppercase; letter-spacing: .1em; margin-bottom: 8px; }
+.page-heading { display: flex; justify-content: space-between; align-items: center; gap: 24px; margin-bottom: 28px; }
+.page-heading .muted { margin-top: 12px; max-width: 640px; }
+.workspace-grid { display: grid; grid-template-columns: minmax(0, 1.65fr) minmax(280px, 1fr); gap: 24px; align-items: start; }
+.panel { background: var(--surface); border: 1px solid var(--line); border-radius: 12px; overflow: hidden; min-width: 0; }
+.panel-heading { padding: 20px 24px; border-bottom: 1px solid var(--line); }
+.panel-body { padding: 24px; }
+.stack { display: flex; flex-direction: column; gap: 20px; }
+.field { display: flex; flex-direction: column; gap: 8px; }
+label { font-weight: 650; font-size: 14px; }
+input[type="text"], input[type="email"] { width: 100%; border: 1px solid #a6b7be; border-radius: 7px; padding: 11px 12px; background: #fff; color: var(--ink); font: inherit; }
+.button { display: inline-flex; align-items: center; justify-content: center; min-height: 42px; padding: 9px 15px; border: 1px solid var(--accent); border-radius: 7px; background: var(--accent); color: #fff; font: inherit; font-size: 14px; font-weight: 650; text-decoration: none; cursor: pointer; text-align: center; }
+.button:hover { filter: brightness(.93); }
+.button-secondary { background: #fff; color: var(--ink); border-color: #a6b7be; }
+.record-list { list-style: none; margin: 0; padding: 0; }
+.record-row { padding: 20px 24px; display: flex; align-items: center; justify-content: space-between; gap: 16px; }
+.record-row + .record-row { border-top: 1px solid var(--line); }
+.record-content { min-width: 0; }
+.record-title { font-weight: 650; overflow-wrap: anywhere; }
+.record-content p { margin-top: 4px; }
+.badge { display: inline-block; border: 1px solid var(--line); border-radius: 5px; background: #f3f6f6; color: #364f58; padding: 3px 8px; font-size: 12px; font-weight: 650; white-space: nowrap; }
+.status-list { display: flex; flex-direction: column; align-items: flex-end; gap: 6px; }
+.address-row { align-items: flex-start; flex-direction: column; gap: 8px; }
+.empty-state { padding: 48px 24px; text-align: center; }
+.empty-state p { color: var(--muted); max-width: 340px; margin: 8px auto 0; }
+.pagination { padding: 16px 24px; border-top: 1px solid var(--line); }
+.actions { display: flex; flex-wrap: wrap; align-items: center; gap: 10px; }
+.actions form { margin: 0; }
+.breadcrumbs { display: flex; flex-wrap: wrap; gap: 10px; color: var(--muted); font-size: 14px; margin-bottom: 28px; overflow-wrap: anywhere; }
+.notice { border: 1px solid #a7ccc0; border-radius: 8px; background: #edf8f2; color: #205340; padding: 14px 18px; margin-bottom: 24px; overflow-wrap: anywhere; }
+.notice-error { border-color: #e8b9b3; background: #fff2ef; color: #8d2a21; }
+.message-metadata { display: grid; grid-template-columns: 84px minmax(0, 1fr); gap: 10px 20px; margin: 0; font-size: 14px; }
+.message-metadata dt { color: var(--muted); }
+.message-metadata dd { margin: 0; overflow-wrap: anywhere; }
+.message-body { border-top: 1px solid var(--line); padding: 28px 24px; }
+.message-body pre { white-space: pre-wrap; overflow-wrap: anywhere; font: inherit; margin: 0; }
+.attachments { border-top: 1px solid var(--line); }
+.attachments p { margin-top: 8px; }
+.attachments li { overflow-wrap: anywhere; }
+.skip-link { position: absolute; left: 16px; top: -100px; background: #fff; padding: 12px; z-index: 1; }
+.skip-link:focus { top: 12px; }
+@media (max-width: 760px) {
+  .shell { width: calc(100% - 32px); }
+  .header-content { min-height: 64px; }
+  .header-caption { display: none; }
+  .workspace-grid { grid-template-columns: minmax(0, 1fr); }
+  .page-heading { align-items: flex-start; flex-direction: column; }
+  .panel-heading, .panel-body, .record-row, .message-body { padding: 20px; }
+  .record-row { align-items: flex-start; }
+  .message-metadata { grid-template-columns: 64px minmax(0, 1fr); gap: 10px; }
+}

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/message_id.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Cloudflare
+  module Email
+    # Correlation only: a Message-ID does not authorize access to a thread.
+    module MessageId
+      def self.normalize(value)
+        value.to_s.strip.sub(/\A<([^<>]+)>\z/, '\1')
+      end
+    end
+  end
+end

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