cloudflare-email 0.1.0 → 0.2.0

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

@@ -0,0 +1,219 @@
+require "active_record"
+require "digest"
+require "cloudflare-email"
+require "cloudflare/email/active_record/outbound_delivery"
+require "cloudflare/email/active_record/outbound_recipient"
+require "cloudflare/email/active_record/outbound_reconciliation"
+
+module Cloudflare
+  module Email
+    module ActiveRecord
+      # Durable, single-attempt boundary. A retry job may revisit an accepted
+      # operation, but uncertainty always requires an explicit operator decision.
+      class Outbox
+        class Error < Cloudflare::Email::Error; end
+        class InvalidTransition < Error; end
+        class SnapshotConflict < Error; end
+
+        class << self
+          def acceptance_state(states)
+            aggregate(states)
+          end
+
+          def normalize_recipient(value)
+            local, separator, domain = value.to_s.rpartition("@")
+            separator.empty? ? value.to_s : "#{local}@#{domain.downcase}"
+          end
+
+          def prepare(account_id:, operation_key:, from:, recipients:, mime_message:)
+            [account_id, operation_key, from].each do |value|
+              raise ArgumentError, "account, operation key and sender must be nonempty strings" unless value.is_a?(String) && !value.strip.empty?
+            end
+            unless recipients.is_a?(Array) && recipients.any? && recipients.all? { |v| v.is_a?(String) && !v.strip.empty? }
+              raise ArgumentError, "recipients must be a nonempty array of addresses"
+            end
+            raise ArgumentError, "mime_message must be a nonempty String" unless mime_message.is_a?(String) && !mime_message.empty?
+            addresses = recipients.map { |address| normalize_recipient(address) }.uniq
+            json = JSON.generate(addresses)
+            digest = Digest::SHA256.hexdigest(JSON.generate([account_id, from, addresses]) + "\0" + mime_message.b)
+            OutboundDelivery.transaction do
+              delivery = OutboundDelivery.create_or_find_by!(account_id: account_id, operation_key: operation_key) do |row|
+                row.assign_attributes(from_address: from, recipients_json: json, mime_message: mime_message.b,
+                  snapshot_digest: digest, state: "prepared")
+              end
+              raise SnapshotConflict, "operation key already has a different immutable message" unless delivery.snapshot_digest == digest
+              addresses.each { |address| delivery.outbound_recipients.create_or_find_by!(recipient: address) }
+              delivery
+            end
+          end
+
+          def deliver(delivery, client: nil)
+            persisted!(delivery)
+            outside_transaction!
+            delivery.reload
+            return delivery if %w[accepted partial].include?(delivery.state)
+            client ||= Client.new(account_id: Credentials.account_id, api_token: Credentials.api_token)
+            unless client.account_id.to_s == delivery.account_id && client.respond_to?(:retry_ambiguous) && client.retry_ambiguous == false
+              raise ConfigurationError, "outbox client must match the account and disable ambiguous retries"
+            end
+            now = Time.now.utc
+            claimed = OutboundDelivery.where(id: delivery.id, state: "prepared").update_all(state: "sending", request_started_at: now, updated_at: now)
+            unless claimed == 1
+              delivery.reload
+              return delivery if %w[accepted partial].include?(delivery.state)
+              raise InvalidTransition, "cannot send an operation in #{delivery.state}; uncertainty requires reconciliation"
+            end
+
+            # Everything after this durable claim can leave an ambiguous outcome.
+            begin
+              response = client.send_raw(from: delivery.from_address, recipients: delivery.recipients, mime_message: delivery.mime_message)
+            rescue StandardError => error
+              record_failure(delivery, error)
+              raise
+            end
+            begin
+              outcomes, provider_message_id = response_outcomes(response, delivery.recipients)
+              delivery.with_lock do
+                raise InvalidTransition, "send claim changed during delivery" unless delivery.state == "sending"
+                outcomes.each do |address, state|
+                  delivery.outbound_recipients.find_by!(recipient: address).update!(state: state, acceptance_state: state, occurred_at: nil,
+                    terminal: %w[delivered bounced suppressed].include?(state))
+                end
+                delivery.update!(state: aggregate(outcomes.values), provider_message_id: provider_message_id,
+                  response_json: JSON.generate(response.to_h), completed_at: Time.now.utc, error_class: nil)
+              end
+            rescue StandardError => error
+              # Even a local validation/persistence error here follows provider
+              # acceptance. Never convert it into permission to resend.
+              mark_unknown(delivery.id, error)
+              raise
+            end
+            delivery.reload
+          end
+
+          def reconcile(delivery, outcome:, actor:, reason:, evidence:, provider_message_id: nil, recipients: nil, confirm_sender_stopped: false)
+            persisted!(delivery)
+            raise ArgumentError, "outcome must be accepted or not_sent" unless %w[accepted not_sent].include?(outcome.to_s)
+            [actor, reason, evidence].each do |value|
+              raise ArgumentError, "actor, reason and evidence are required strings" unless value.is_a?(String) && !value.strip.empty?
+            end
+            provider_message_id = validated_message_id(provider_message_id)
+            if outcome.to_s == "accepted" && provider_message_id.nil?
+              raise ArgumentError, "accepted reconciliation requires a provider message ID"
+            end
+            completed = false
+            delivery.with_lock(requires_new: true) do
+              allowed = %w[unknown partial].include?(delivery.state) || (delivery.state == "sending" && confirm_sender_stopped == true &&
+                delivery.request_started_at && delivery.request_started_at <= Time.now.utc - 900)
+              raise InvalidTransition, "only uncertain operations may be reconciled; a sending process must be confirmed stopped and at least 15 minutes old" unless allowed
+              rows = delivery.outbound_recipients.to_a
+              unresolved = rows.select { |row| %w[unknown prepared sending].include?(row.acceptance_state) }.map(&:recipient)
+              selected = recipients || unresolved
+              selected = selected.map { |address| normalize_recipient(address) } if selected.is_a?(Array)
+              unless selected.is_a?(Array) && selected.any? && (selected - unresolved).empty? && selected.uniq == selected
+                raise ArgumentError, "recipients must be unique unresolved snapshot recipients"
+              end
+              existing_id = validated_message_id(delivery.provider_message_id.presence)
+              if provider_message_id && existing_id && provider_message_id != existing_id
+                raise ArgumentError, "provider message ID conflicts with the existing operation"
+              end
+              delivery.outbound_reconciliations.create!(actor: actor, reason: reason, evidence: evidence,
+                outcome: outcome.to_s, provider_message_id: provider_message_id, recipients_json: JSON.generate(selected))
+              states = rows.map do |recipient|
+                unless selected.include?(recipient.recipient)
+                  recipient.update!(state: "unknown", acceptance_state: "unknown") if %w[prepared sending].include?(recipient.acceptance_state)
+                  next recipient.acceptance_state
+                end
+                state = outcome.to_s == "not_sent" ? "not_sent" : "accepted"
+                recipient.update!(state: state, acceptance_state: state, occurred_at: nil, terminal: state == "not_sent")
+                state
+              end
+              delivery.update!(state: states.all? { |state| state == "not_sent" } ? "confirmed_not_sent" : aggregate(states),
+                provider_message_id: provider_message_id || existing_id, completed_at: Time.now.utc)
+              yield delivery if block_given?
+              completed = true
+            end
+            raise InvalidTransition, "reconciliation rolled back instead of completing" unless completed
+            delivery.reload
+          end
+
+          private
+
+          def persisted!(delivery)
+            raise ArgumentError, "expected a persisted OutboundDelivery" unless delivery.is_a?(OutboundDelivery) && delivery.persisted?
+          end
+
+          def outside_transaction!
+            raise ArgumentError, "outbox network delivery must run outside an existing database transaction" if OutboundDelivery.connection.transaction_open?
+          end
+
+          def record_failure(delivery, error)
+            # Only an explicit provider 4xx rejection proves nonacceptance.
+            rejected = error.is_a?(Cloudflare::Email::Error) && [400, 401, 403, 422, 429].include?(error.status)
+            OutboundDelivery.transaction do
+              count = OutboundDelivery.where(id: delivery.id, state: "sending").update_all(state: rejected ? "rejected" : "unknown",
+                error_class: error.class.name, completed_at: Time.now.utc, updated_at: Time.now.utc)
+              OutboundRecipient.where(outbound_delivery_id: delivery.id).update_all(state: rejected ? "rejected" : "unknown", acceptance_state: rejected ? "rejected" : "unknown") if count == 1
+            end
+          rescue StandardError
+            # A database outage leaves the already committed sending claim.
+            # It is deliberately just as non-retryable as unknown.
+            nil
+          end
+
+          def mark_unknown(id, error)
+            OutboundDelivery.where(id: id, state: "sending").update_all(state: "unknown", error_class: error.class.name, updated_at: Time.now.utc)
+          rescue StandardError
+            nil
+          end
+
+          def response_outcomes(response, addresses)
+            raise ValidationError, "invalid provider response" unless response.is_a?(Response) && response.success?
+            outcomes = addresses.to_h { |address| [address, "unknown"] }
+            result = response.result
+            ids = [validated_message_id(result["message_id"])]
+            groups = { "delivered" => "delivered", "queued" => "queued", "permanent_bounces" => "bounced", "suppressed_recipients" => "suppressed" }
+            seen = {}
+            groups.each do |key, state|
+              entries = result.fetch(key, [])
+              raise ValidationError, "invalid recipient outcomes" unless entries.is_a?(Array)
+              entries.each do |entry|
+                ids << validated_message_id(entry["message_id"]) if entry.is_a?(Hash)
+                address = entry.is_a?(Hash) ? (entry["to"] || entry["email"] || entry["recipient"] || entry["address"]) : entry
+                address = normalize_recipient(address)
+                raise ValidationError, "unknown or conflicting provider recipient" unless addresses.include?(address) && !seen[address]
+                seen[address] = true
+                outcomes[address] = state
+              end
+            end
+            raise ValidationError, "multiple provider message IDs cannot be correlated to one operation" if ids.compact.uniq.size > 1
+            if seen.empty? && ids.compact.any?
+              outcomes.transform_values! { "accepted" }
+            end
+            [outcomes, ids.compact.first]
+          end
+
+          def validated_message_id(value)
+            return nil if value.nil?
+            unless value.is_a?(String)
+              raise ValidationError, "provider message ID must be a nonempty string"
+            end
+            normalized = MessageId.normalize(value)
+            if normalized.empty? || normalized.match?(/[\s<>]/)
+              raise ValidationError, "provider message ID must not contain whitespace or brackets"
+            end
+            normalized
+          end
+
+          def aggregate(states)
+            accepted = states.count { |state| %w[accepted delivered queued].include?(state) }
+            return "accepted" if accepted == states.size
+            return "partial" if accepted.positive?
+            return "rejected" if states.all? { |state| %w[bounced suppressed rejected not_sent].include?(state) }
+            "unknown"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+module Cloudflare
+  module Email
+    module ActiveRecord
+      module OutboxNotifications
+        def prepare(**options)
+          notify_outbox("prepare", account_id: options[:account_id], operation_key: options[:operation_key]) { super }
+        end
+
+        def deliver(delivery, **options)
+          notify_outbox("send", account_id: delivery.account_id, operation_key: delivery.operation_key) { super }
+        end
+
+        def reconcile(delivery, **options, &block)
+          notify_outbox("reconcile", account_id: delivery.account_id, operation_key: delivery.operation_key) { super }
+        end
+
+        private
+
+        def notify_outbox(action, **payload)
+          return yield unless defined?(::ActiveSupport::Notifications)
+
+          ::ActiveSupport::Notifications.instrument("cloudflare_email.outbox_#{action}", payload) do |details|
+            result = yield
+            details[:delivery_id] = result.id
+            details[:state] = result.state
+            result
+          end
+        end
+      end
+
+      Outbox.singleton_class.prepend(OutboxNotifications)
+    end
+  end
+end

data/lib/cloudflare/email/active_record.rb

@@ -0,0 +1,5 @@
+# Optional durable Rails/ActiveRecord integration. Jobs are a separate opt-in.
+require "cloudflare/email/active_record/outbox"
+require "cloudflare/email/active_record/mail_snapshot"
+require "cloudflare/email/active_record/delivery_events"
+require "cloudflare/email/active_record/outbox_notifications"

data/lib/cloudflare/email/client.rb

@@ -1,6 +1,8 @@
 require "net/http"
 require "json"
 require "uri"
+require "time"
+require "cloudflare/email/endpoint"
 
 module Cloudflare
   module Email
@@ -12,39 +14,50 @@ module Cloudflare
       MAX_RETRY_AFTER  = 60 # seconds; never sleep longer than this even if server says so
 
       RETRYABLE_NETWORK = [
-        Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET,
+        Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, Errno::ECONNRESET,
         Errno::ECONNREFUSED, Errno::EHOSTUNREACH, EOFError, SocketError,
         IOError
       ].freeze
+      PRE_SEND_NETWORK = [Net::OpenTimeout, Errno::ECONNREFUSED, Errno::EHOSTUNREACH, SocketError].freeze
 
-      attr_reader :account_id, :base_url, :retries, :timeout
+      attr_reader :account_id, :base_url, :retries, :timeout, :retry_ambiguous
 
       def initialize(account_id:, api_token:, base_url: DEFAULT_BASE_URL,
                      retries: DEFAULT_RETRIES, timeout: DEFAULT_TIMEOUT,
                      initial_backoff: DEFAULT_BACKOFF, max_retry_after: MAX_RETRY_AFTER,
-                     logger: nil)
-        raise ConfigurationError, "account_id is required" if account_id.nil? || account_id.to_s.empty?
-        raise ConfigurationError, "api_token is required"  if api_token.nil?  || api_token.to_s.empty?
+                     retry_ambiguous: false, logger: nil)
+        unless account_id.is_a?(String) && account_id.match?(/\A[a-zA-Z0-9_-]+\z/)
+          raise ConfigurationError, "account_id is required and must be a single account identifier"
+        end
+        unless api_token.is_a?(String) && !api_token.empty? && !api_token.match?(/\s/)
+          raise ConfigurationError, "api_token is required and must not contain whitespace"
+        end
 
         @account_id      = account_id
         @api_token       = api_token
-        @base_url        = base_url
+        @base_url        = Endpoint.parse(base_url).to_s.delete_suffix("/")
         @retries         = retries
         @timeout         = timeout
         @initial_backoff = initial_backoff
         @max_retry_after = max_retry_after
         @logger          = logger
+        @retry_ambiguous = retry_ambiguous
+      end
+
+      def inspect
+        "#<#{self.class.name} account_id=#{@account_id.inspect} api_token=[REDACTED]>"
       end
 
-      def send(from:, to:, subject:, text: nil, html: nil, cc: nil, bcc: nil,
+      def send(from:, subject:, to: nil, text: nil, html: nil, cc: nil, bcc: nil,
                reply_to: nil, headers: nil, attachments: nil)
         raise ValidationError, "must provide :text or :html" if text.nil? && html.nil?
+        raise ValidationError, "must provide a recipient in :to, :cc, or :bcc" if [to, cc, bcc].all? { |v| wrap(v).empty? }
 
         body = {
           from:    normalize_address(from),
-          to:      wrap(to).map  { |addr| normalize_address(addr) },
           subject: subject,
         }
+        body[:to]          = wrap(to).map { |addr| normalize_address(addr) } if to
         body[:text]        = text if text
         body[:html]        = html if html
         body[:cc]          = wrap(cc).map  { |a| normalize_address(a) } if cc
@@ -104,6 +117,10 @@ module Cloudflare
           response = request(:post, path, body)
           payload[:status]     = response.status
           payload[:message_id] = response.message_id
+          payload[:delivered] = response.delivered
+          payload[:queued] = response.queued
+          payload[:permanent_bounces] = response.permanent_bounces
+          payload[:suppressed_recipients] = response.suppressed_recipients
           response
         end
       end
@@ -125,6 +142,9 @@ module Cloudflare
           attempts += 1
           do_request(method, uri, body)
         rescue *RETRYABLE_NETWORK => e
+          unless PRE_SEND_NETWORK.any? { |type| e.is_a?(type) } || @retry_ambiguous
+            raise NetworkError.new("#{e.message}; delivery outcome is unknown; automatic retry disabled")
+          end
           raise NetworkError.new(e.message) if attempts > @retries
           log_retry(attempts, e)
           sleep(backoff); backoff *= 2
@@ -135,7 +155,7 @@ module Cloudflare
           sleep(retry_after_from(e, backoff)); backoff *= 2
           retry
         rescue ServerError => e
-          raise if attempts > @retries
+          raise unless @retry_ambiguous && attempts <= @retries
           log_retry(attempts, e)
           sleep(backoff); backoff *= 2
           retry
@@ -145,7 +165,15 @@ module Cloudflare
       def retry_after_from(error, fallback_backoff)
         header = error.response.is_a?(Hash) ? error.response["retry_after"] : nil
         value  = header || fallback_backoff
-        seconds = value.to_f
+        seconds = if value.to_s.match?(/\A\d+(?:\.\d+)?\z/)
+          value.to_f
+        else
+          begin
+            Time.httpdate(value.to_s) - Time.now
+          rescue ArgumentError
+            fallback_backoff
+          end
+        end
         return fallback_backoff if seconds <= 0
         [seconds, @max_retry_after].min
       end
@@ -155,6 +183,8 @@ module Cloudflare
         http.use_ssl     = (uri.scheme == "https")
         http.open_timeout = @timeout
         http.read_timeout = @timeout
+        http.write_timeout = @timeout
+        http.max_retries = 0
 
         req_class = { post: Net::HTTP::Post, get: Net::HTTP::Get }.fetch(method)
         req = req_class.new(uri.request_uri)
@@ -178,6 +208,15 @@ module Cloudflare
 
         case status
         when 200..299
+          if body.is_a?(Hash) && body.key?("success") && body["success"] != true
+            raise Error.new(extract_message(body), status: status, response: body)
+          end
+          unless body.is_a?(Hash) && body["result"].is_a?(Hash)
+            raise Error.new("invalid successful API response; request outcome is unknown", status: status, response: body)
+          end
+          if body["errors"].is_a?(Array) && body["errors"].any?
+            raise Error.new(extract_message(body), status: status, response: body)
+          end
           Response.new(body, status: status)
         when 400, 422
           raise ValidationError.new(extract_message(body), status: status, response: body)
@@ -209,7 +248,8 @@ module Cloudflare
 
       def log_retry(attempt, error)
         return unless @logger
-        @logger.warn("[cloudflare-email] retry #{attempt}: #{error.class}: #{error.message}")
+        # Provider messages can echo message content or other sensitive data.
+        @logger.warn("[cloudflare-email] retry #{attempt}: #{error.class}")
       end
     end
   end

data/lib/cloudflare/email/consume_events_task.rb

@@ -0,0 +1,22 @@
+require "cloudflare/email/task_base"
+require "cloudflare/email/event_consumer"
+
+module Cloudflare
+  module Email
+    class ConsumeEventsTask < TaskBase
+      def run
+        handler = opts[:handler]
+        raise ConfigurationError, "configure config.x.cloudflare_email.event_handler with a callable" unless handler.respond_to?(:call)
+
+        consumer = EventConsumer.new(
+          account_id: account_id,
+          api_token: require_value!(credential(:queues_token), "cloudflare.queues_token / CLOUDFLARE_QUEUES_TOKEN"),
+          queue_id: require_value!(credential(:event_queue_id), "cloudflare.event_queue_id / CLOUDFLARE_EVENT_QUEUE_ID"),
+          domains: opts[:domains],
+        )
+        count = consumer.poll(batch_size: opts.fetch(:batch_size, 5), &handler.method(:call))
+        say "  Processed and acknowledged #{count} delivery event(s)."
+      end
+    end
+  end
+end

data/lib/cloudflare/email/delivery_event.rb

@@ -0,0 +1,70 @@
+require "json"
+require "time"
+
+module Cloudflare
+  module Email
+    # An outbound Email Sending event, delivered through Cloudflare Queues.
+    # Treat event_id as an idempotency key; events may arrive more than once
+    # or out of order. This is distinct from inbound ActionMailbox messages.
+    class DeliveryEvent
+      TYPES = %w[delivered deferred bounced failed rejected complained].freeze
+      attr_reader :raw
+
+      def initialize(raw)
+        @raw = raw
+        unless raw.is_a?(Hash) && raw["type"].is_a?(String) &&
+               raw["type"].match?(/\Acf\.email\.sending\.message\.[a-z][a-z0-9_]*\z/) &&
+               raw["payload"].is_a?(Hash) && raw["source"].is_a?(Hash) &&
+               raw["source"]["type"] == "email.sending" && raw["metadata"].is_a?(Hash) &&
+               raw["metadata"]["eventSchemaVersion"] == 1 &&
+               [event_id, message_id, account_id, domain, recipient].all? { |value| valid_identifier?(value) } &&
+               [true, false].include?(payload["terminal"]) &&
+               %w[delivery bounce complaint rejection failure].all? { |key| !payload.key?(key) || payload[key].is_a?(Hash) }
+          raise ValidationError, "invalid Email Sending event or unsupported schema version"
+        end
+        unless occurred_at.is_a?(String) && valid_identifier?(occurred_at)
+          raise ValidationError, "delivery event timestamp must be ISO8601"
+        end
+        Time.iso8601(occurred_at)
+      rescue ArgumentError
+        raise ValidationError, "delivery event timestamp must be ISO8601"
+      end
+
+      def type = raw["type"]
+      def status = type.delete_prefix("cf.email.sending.message.")
+      def known? = TYPES.include?(status)
+      def payload = raw["payload"]
+      def event_id = payload["eventId"]
+      def message_id = payload["messageId"]
+      def recipient = payload["recipient"]
+      def sender = payload["sender"]
+      def terminal? = payload["terminal"] == true
+      def domain = raw["source"]["domain"]
+      def account_id = raw["metadata"]["accountId"]
+      def occurred_at = raw["metadata"]["eventTimestamp"]
+      def delivery = payload["delivery"] || {}
+      def bounce = payload["bounce"] || {}
+      def complaint = payload["complaint"] || {}
+      def rejection = payload["rejection"] || {}
+      def failure = payload["failure"] || {}
+
+      # Use only after matching account, provider message ID, and recipient.
+      # Equal timestamps keep the existing state; unknown future types remain
+      # available in receipts but must not replace a recognized delivery state.
+      def supersedes?(occurred_at:, terminal:)
+        return false unless known?
+        return false if terminal && !terminal?
+
+        incoming = Time.iso8601(self.occurred_at.to_s)
+        previous = occurred_at.is_a?(Time) ? occurred_at : Time.iso8601(occurred_at.to_s) unless occurred_at.nil?
+        previous.nil? || incoming > previous
+      end
+
+      private
+
+      def valid_identifier?(value)
+        value.is_a?(String) && !value.strip.empty? && !value.match?(/[[:cntrl:]]/)
+      end
+    end
+  end
+end

data/lib/cloudflare/email/delivery_method.rb

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

data/lib/cloudflare/email/deploy_worker_task.rb

@@ -20,6 +20,9 @@ module Cloudflare
         path = script_path
         raise "Worker script not found at #{path} — re-run `bin/rails g cloudflare:email:install`" unless File.exist?(path)
 
+        # Validate before uploading code or rotating any deployed secrets.
+        Endpoint.parse(url) unless url.to_s.empty?
+
         deployer = Cloudflare::Email::WorkerDeployer.new(
           account_id: account_id, api_token: management_token,
         )

data/lib/cloudflare/email/dev_ingress_guard.rb

@@ -0,0 +1,27 @@
+module Cloudflare
+  module Email
+    # cloudflared forces this origin Host. Restrict tunnel traffic before Rails
+    # routing, debug middleware and normal host authorization execute.
+    class DevIngressGuard
+      HOST = "cloudflare-email-ingress.localhost".freeze
+      PATH = "/rails/action_mailbox/cloudflare/inbound_emails".freeze
+      RESPONSE_HEADER = "x-cloudflare-email-ingress-only".freeze
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        return @app.call(env) unless env["HTTP_HOST"].to_s.downcase.split(":", 2).first == HOST
+        unless env["REQUEST_METHOD"] == "POST" && env["PATH_INFO"] == PATH
+          return [404, { "content-type" => "text/plain", "content-length" => "0", RESPONSE_HEADER => "1" }, []]
+        end
+        forwarded = env.dup
+        forwarded["HTTP_HOST"] = "localhost"
+        forwarded.delete("HTTP_X_FORWARDED_HOST")
+        forwarded.delete("HTTP_FORWARDED")
+        @app.call(forwarded)
+      end
+    end
+  end
+end

data/lib/cloudflare/email/dev_tunnel.rb

@@ -1,4 +1,6 @@
 require "cloudflare/email/worker_deployer"
+require "tempfile"
+require "cloudflare/email/dev_ingress_guard"
 
 module Cloudflare
   module Email
@@ -13,6 +15,7 @@ module Cloudflare
       end
 
       def initialize(port:, io: $stdout)
+        raise ArgumentError, "port must be between 1 and 65535" unless port.is_a?(Integer) && (1..65_535).cover?(port)
         @port       = port
         @io         = io
         @tunnel_pid = nil
@@ -51,22 +54,45 @@ module Cloudflare
       private
 
       def check_prerequisites
+        unless defined?(Rails) && Rails.respond_to?(:env) && Rails.env.development?
+          raise "cloudflare:email:dev only runs in development; use RAILS_ENV=development"
+        end
+        unless Rails.application.config.respond_to?(:action_mailbox) &&
+               Rails.application.config.action_mailbox.ingress == :cloudflare
+          raise "Set config.action_mailbox.ingress = :cloudflare in config/environments/development.rb"
+        end
+
         unless system("command -v cloudflared >/dev/null 2>&1")
           raise "cloudflared not found in PATH — install from https://developers.cloudflare.com/cloudflared/"
         end
         require "cloudflare/email/credentials"
-        if Cloudflare::Email::Credentials.account_id.empty? ||
-           Cloudflare::Email::Credentials.management_token.empty?
+        if Cloudflare::Email::Credentials.account_id.to_s.empty? ||
+           Cloudflare::Email::Credentials.management_token.to_s.empty?
           raise "Missing cloudflare.account_id or cloudflare.api_token in credentials " \
                 "(or CLOUDFLARE_ACCOUNT_ID / CLOUDFLARE_API_TOKEN env vars)"
         end
+        verify_ingress_guard!
+      end
+
+      def verify_ingress_guard!
+        http = Net::HTTP.new("127.0.0.1", @port, nil)
+        http.open_timeout = http.read_timeout = 2
+        request = Net::HTTP::Get.new("/")
+        request["Host"] = DevIngressGuard::HOST
+        response = http.request(request)
+        unless response.code == "404" && response[DevIngressGuard::RESPONSE_HEADER] == "1"
+          raise "Restart the development Rails server with the ingress-only middleware before opening a tunnel"
+        end
+      rescue SystemCallError, IOError, Timeout::Error
+        raise "Start the development Rails server with the ingress-only middleware before opening a tunnel"
       end
 
       def start_tunnel
         @io.puts "  Starting cloudflared tunnel on :#{@port}..."
-        @tunnel_log = File.open("/tmp/cloudflare-email-dev-tunnel.log", "w")
+        @tunnel_log = Tempfile.new(["cloudflare-email-dev-tunnel", ".log"])
         @tunnel_pid = spawn(
           "cloudflared", "tunnel", "--url", "http://127.0.0.1:#{@port}",
+          "--http-host-header", DevIngressGuard::HOST,
           out: @tunnel_log, err: @tunnel_log,
         )
       end
@@ -75,7 +101,7 @@ module Cloudflare
         deadline = Time.now + 30
         while Time.now < deadline
           sleep 0.5
-          log = File.read("/tmp/cloudflare-email-dev-tunnel.log") rescue ""
+          log = File.read(@tunnel_log.path) rescue ""
           if (match = log.match(%r{https://[a-z0-9\-]+\.trycloudflare\.com}))
             return match[0]
           end
@@ -89,7 +115,7 @@ module Cloudflare
           Process.wait(@tunnel_pid) rescue nil
           @tunnel_pid = nil
         end
-        @tunnel_log&.close
+        @tunnel_log&.close!
       end
 
     end