cloudflare-email 0.1.0 → 0.2.0

data/lib/cloudflare/email/doctor.rb

@@ -64,7 +64,7 @@ module Cloudflare
         if api_token.to_s.empty?
           record("credentials.cloudflare.api_token", FAIL, "missing — run bin/rails credentials:edit")
         else
-          record("credentials.cloudflare.api_token", OK, "#{api_token[0, 8]}...")
+          record("credentials.cloudflare.api_token", OK, "set (redacted)")
         end
       end
 
@@ -89,47 +89,20 @@ module Cloudflare
         if response[:ok]
           record("Account accessible", OK, response[:body].dig("result", "name") || account_id)
         elsif response[:status] == 403
-          # Narrowly-scoped send-only tokens don't have account read permission;
-          # that's a feature, not a bug. We already confirmed the token is valid.
-          record("Account accessible", OK, "send-scoped token (no account read — this is fine)")
+          # Send-scoped tokens may lack account read permission. A 403 cannot
+          # establish that this token can send for the configured account.
+          record("Account accessible", SKIP, "403 — account access unverified; token may lack account read permission")
         else
           record("Account accessible", FAIL, extract_error(response))
         end
       end
 
       def check_sending_domains
-        token      = credential(:api_token)
-        account_id = credential(:account_id)
-        return record("Sending domains", SKIP, "missing credentials") if token.to_s.empty? || account_id.to_s.empty?
-
-        response = request("GET", "/accounts/#{account_id}/email/sending/domains", token: token)
-        if response[:status] == 403 || response[:status] == 404
-          record("Sending domains", SKIP, "send-scoped token can't list domains (check the dashboard instead)")
-          return
-        end
-
-        unless response[:ok]
-          record("Sending domains", WARN, "could not list: #{extract_error(response)}")
-          return
-        end
-
-        domains = Array(response[:body]["result"])
-        if domains.empty?
-          record("Sending domains", WARN, "no sending domains set up — add one in the dashboard")
-          return
-        end
-
-        verified = domains.select { |d| d["verified"] == true || d["status"] == "verified" }
-        if verified.any?
-          names = verified.map { |d| d["name"] || d["domain"] }.compact.join(", ")
-          record("Sending domains", OK, "#{verified.size} verified (#{names})")
-        else
-          names = domains.map { |d| d["name"] || d["domain"] }.compact.join(", ")
-          record("Sending domains", WARN, "#{domains.size} configured but none verified (#{names})")
-        end
+        record("Sending domains", SKIP, "verify your sender domain in Email Sending in the Cloudflare dashboard")
       end
 
       def check_ingress_secret
+        return record("Ingress secret", SKIP, "Cloudflare inbound routing not selected") unless inbound_enabled?
         require "cloudflare/email/credentials"
         secret = Cloudflare::Email::Credentials.ingress_secret
 
@@ -143,6 +116,7 @@ module Cloudflare
       end
 
       def check_token_split
+        return record("Token split", SKIP, "send-only setup; management token optional") unless inbound_enabled?
         require "cloudflare/email/credentials"
         if Cloudflare::Email::Credentials.split_tokens?
           record("Token split", OK, "separate management_token set (good security posture)")
@@ -160,12 +134,16 @@ module Cloudflare
         when :cloudflare
           record("ActionMailbox ingress", OK, ":cloudflare")
         when nil
-          record("ActionMailbox ingress", WARN, "nil — inbound will 404. Set config.action_mailbox.ingress = :cloudflare")
+          record("ActionMailbox ingress", SKIP, "inbound routing not configured")
         else
-          record("ActionMailbox ingress", WARN, "#{ActionMailbox.ingress.inspect} — not :cloudflare, our controller will 404")
+          record("ActionMailbox ingress", SKIP, "#{ActionMailbox.ingress.inspect} — Cloudflare inbound routing not selected")
         end
       end
 
+      def inbound_enabled?
+        defined?(ActionMailbox) && ActionMailbox.respond_to?(:ingress) && ActionMailbox.ingress == :cloudflare
+      end
+
       def check_delivery_method_registered
         return record("Delivery method :cloudflare", SKIP, "ActionMailer not loaded") unless defined?(ActionMailer)
 
@@ -188,9 +166,9 @@ module Cloudflare
         warn_count = @results.count { |r| r[:status] == WARN }
 
         if fail_count.zero? && warn_count.zero?
-          @io.puts "  Everything looks good."
+          @io.puts "  Completed checks passed. Review skipped checks; live delivery is not verified."
         elsif fail_count.zero?
-          @io.puts "  #{warn_count} warning(s). Setup is usable but incomplete."
+          @io.puts "  #{warn_count} warning(s). Review warnings and skipped checks before relying on delivery."
         else
           @io.puts "  #{fail_count} failure(s), #{warn_count} warning(s). Fix failures before sending."
         end
@@ -228,7 +206,7 @@ module Cloudflare
 
         response = http.request(req)
         body = JSON.parse(response.body) rescue {}
-        { ok: response.code.to_i.between?(200, 299), status: response.code.to_i, body: body }
+        { ok: response.code.to_i.between?(200, 299) && body.is_a?(Hash) && body["success"] != false, status: response.code.to_i, body: body }
       rescue StandardError => e
         { ok: false, status: 0, body: { "errors" => [{ "message" => e.message }] } }
       end

data/lib/cloudflare/email/endpoint.rb

@@ -0,0 +1,24 @@
+require "uri"
+require "cloudflare/email/error"
+
+module Cloudflare
+  module Email
+    # Endpoints are trusted operator configuration, never message-derived URLs.
+    # Plain HTTP is only suitable for literal loopback development fixtures.
+    module Endpoint
+      LOOPBACK_HOSTS = %w[localhost 127.0.0.1 ::1].freeze
+
+      def self.parse(value, allow_loopback: true)
+        uri = URI.parse(value.to_s)
+        secure = uri.is_a?(URI::HTTPS)
+        local = allow_loopback && uri.is_a?(URI::HTTP) && LOOPBACK_HOSTS.include?(uri.hostname.to_s.downcase)
+        unless (secure || local) && !uri.hostname.to_s.empty? && !uri.userinfo && !uri.query && !uri.fragment
+          raise ConfigurationError, "endpoint must use HTTPS (HTTP only on literal loopback), without credentials, query or fragment"
+        end
+        uri
+      rescue URI::InvalidURIError
+        raise ConfigurationError, "endpoint must be a valid HTTPS URL"
+      end
+    end
+  end
+end

data/lib/cloudflare/email/engine.rb

@@ -1,4 +1,5 @@
 require "rails/engine"
+require "cloudflare/email/dev_ingress_guard"
 
 # Register the delivery method at engine load time (not inside an initializer)
 # so the `cloudflare_settings=` accessor exists before Rails' own
@@ -13,7 +14,34 @@ module Cloudflare
     class Engine < ::Rails::Engine
       isolate_namespace Cloudflare::Email
 
+      initializer "cloudflare-email.development_ingress_guard" do |app|
+        app.middleware.insert_before 0, DevIngressGuard if Rails.env.development?
+      end
+
+      config.to_prepare do
+        if (defined?(Cloudflare::Email::Tenancy) && Cloudflare::Email::Tenancy.enabled?) ||
+            (defined?(Cloudflare::Email::Mailboxes) && Cloudflare::Email::Mailboxes.enabled?)
+          require "cloudflare/email/tenant_job_context"
+          Cloudflare::Email::TenantJobContext.install_framework_jobs!
+        end
+        if defined?(Cloudflare::Email::Mailboxes) && Cloudflare::Email::Mailboxes.enabled? && defined?(::ActionMailbox::Engine)
+          require "cloudflare/email/mailboxes/inbound_retention"
+          ::ActionMailbox::InboundEmail.prepend(Cloudflare::Email::Mailboxes::InboundRetention) unless
+            ::ActionMailbox::InboundEmail.ancestors.include?(Cloudflare::Email::Mailboxes::InboundRetention)
+        end
+      end
+
+      config.before_initialize do
+        unless defined?(::ActionMailbox::Engine)
+          Rails.autoloaders.main.ignore(
+            File.expand_path("../../../app/controllers/cloudflare/email/ingress_controller.rb", __dir__),
+          )
+        end
+      end
+
       initializer "cloudflare-email.routes" do |app|
+        next unless defined?(::ActionMailbox::Engine)
+
         app.routes.append do
           post "/rails/action_mailbox/cloudflare/inbound_emails",
                to: "cloudflare/email/ingress#create",

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 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
+        value = metadata.reject { |key, _| key == "version" }
+        valid?(value) ? value : nil
+      end
+    end
+  end
+end

data/lib/cloudflare/email/event_consumer.rb

@@ -0,0 +1,86 @@
+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
+      def initialize(queue_id:, domains: nil, **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))
+        @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 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"
+      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