cloudflare-email 0.2.0 → 0.3.0

data/lib/cloudflare/email/routing_diagnostics.rb

@@ -0,0 +1,206 @@
+require "net/http"
+require "json"
+require "uri"
+require "timeout"
+require "cloudflare/email/endpoint"
+
+module Cloudflare
+  module Email
+    # A bounded, GET-only snapshot of provider configuration. This deliberately
+    # does not inherit RoutingProvisioner: inspecting must never repair routing.
+    class RoutingDiagnostics
+      API_BASE = "https://api.cloudflare.com/client/v4".freeze
+      MAX_BYTES = 1_048_576
+      MAX_PAGES = 50
+      LIMITATIONS = "Configuration snapshot only: does not prove public DNS propagation, live delivery, Worker destination, or application acceptance.".freeze
+      class ReadError < StandardError; end
+
+      def initialize(api_token:, api_base: API_BASE)
+        raise ArgumentError, "api_token is required" if api_token.to_s.empty?
+        @api_token = api_token
+        @api_base = Endpoint.parse(api_base).to_s.delete_suffix("/")
+      end
+
+      # Status is pass only if every requested configuration check passes.
+      # Unknown means inspection could not establish readiness, not success.
+      def check(address:, worker_name:, account_id: nil)
+        unless address.is_a?(String) && address.bytesize <= 254 && address.match?(/\A[^\s@]+@(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9-]+\z/)
+          raise ArgumentError, "address must be a full email address with a DNS domain"
+        end
+        raise ArgumentError, "worker_name is required" if worker_name.to_s.empty?
+        domain = address.split("@", 2).last.downcase
+        address = "#{address.split('@', 2).first}@#{domain}"
+        checks = []
+        zone = inspect_check(checks, "zone") { find_zone(domain) }
+        if zone
+          if account_id
+            actual = zone["account"].is_a?(Hash) ? zone["account"]["id"] : nil
+            add(checks, "account", actual.nil? ? "unknown" : (actual == account_id ? "pass" : "fail"),
+              actual.nil? ? "Zone account was not returned." : (actual == account_id ? "Zone belongs to the expected account." : "Zone belongs to a different account."))
+          end
+          zone_id = URI.encode_www_form_component(zone.fetch("id"))
+          inspect_check(checks, "routing") { routing_check(checks, zone_id) }
+          inspect_check(checks, "dns") { dns_check(checks, zone_id, domain) }
+          inspect_check(checks, "route") { route_check(checks, zone_id, address, worker_name) }
+        else
+          %w[routing dns route].each { |name| add(checks, name, "unknown", "Cannot inspect without a unique zone.") }
+        end
+        statuses = checks.map { |item| item[:status] }
+        { status: statuses.include?("fail") ? "fail" : (statuses.include?("unknown") ? "unknown" : "pass"),
+          checks: checks, limitations: LIMITATIONS }
+      end
+
+      private
+
+      def add(checks, name, status, message)
+        checks << { name: name, status: status, message: message }
+      end
+
+      def inspect_check(checks, name)
+        value = yield
+        add(checks, name, "pass", "Found a unique containing Cloudflare zone.") if name == "zone" && value
+        add(checks, name, "fail", "No containing Cloudflare zone was found.") if name == "zone" && !value
+        value
+      rescue ReadError => e
+        add(checks, name, "unknown", e.message)
+        nil
+      rescue StandardError
+        add(checks, name, "unknown", "Provider configuration could not be interpreted safely.")
+        nil
+      end
+
+      def find_zone(domain)
+        parts = domain.split(".")
+        (0..parts.size - 2).each do |index|
+          candidate = parts[index..].join(".")
+          zones = pages("/zones?name=#{URI.encode_www_form_component(candidate)}")
+          next if zones.empty?
+          unless zones.size == 1 && zones.first["name"].to_s.downcase == candidate && zones.first["id"].is_a?(String)
+            raise ReadError, "Zone lookup was ambiguous or incomplete."
+          end
+          return zones.first
+        end
+        nil
+      end
+
+      def routing_check(checks, zone_id)
+        result = get("/zones/#{zone_id}/email/routing")["result"]
+        enabled = result.is_a?(Hash) ? result["enabled"] : nil
+        status = enabled == true ? "pass" : (enabled == false ? "fail" : "unknown")
+        add(checks, "routing", status, enabled == true ? "Zone Email Routing is enabled." : "Zone Email Routing is disabled or its enabled flag is unavailable.")
+      end
+
+      def dns_check(checks, zone_id, domain)
+        records = pages("/zones/#{zone_id}/dns_records?name=#{URI.encode_www_form_component(domain)}")
+        # Defensively enforce exact name even when the provider returns parent
+        # records. A parent's Google MX must not invalidate a receiving subdomain.
+        records = records.select { |record| record["name"].to_s.downcase.delete_suffix(".") == domain }
+        mx = records.select { |r| r["type"] == "MX" }.map { |r| r["content"].to_s.downcase.delete_suffix(".") }.uniq.sort
+        spf = records.select { |r| r["type"] == "TXT" }.map { |r| r["content"].to_s.delete('"') }.select { |v| v.match?(/\Av=spf1(?:\s|\z)/i) }
+        mx_ok = mx == (1..3).map { |n| "route#{n}.mx.cloudflare.net" }
+        # Do not declare an include useful when an earlier `all` terminates SPF.
+        terms = spf.size == 1 ? spf.first.split.drop(1) : []
+        include_index = terms.index("include:_spf.mx.cloudflare.net")
+        all_index = terms.index { |term| term.match?(/\A[+~?-]?all\z/i) }
+        spf_ok = include_index && (!all_index || include_index < all_index)
+        add(checks, "dns", mx_ok && spf_ok ? "pass" : "fail", mx_ok && spf_ok ?
+          "Exact receiving domain has Cloudflare MX records and one SPF record including Cloudflare." :
+          "Exact receiving domain needs Cloudflare MX records and a single SPF record with an effective Cloudflare include; records may be missing or conflicting.")
+      end
+
+      def route_check(checks, zone_id, address, worker_name)
+        rules = pages("/zones/#{zone_id}/email/routing/rules")
+        matching = []
+        rules.each do |rule|
+          next if rule["enabled"] == false
+          matchers = rule["matchers"]
+          unless matchers.is_a?(Array) && matchers.size == 1 && matchers.first.is_a?(Hash)
+            raise ReadError, "Unsupported rule matchers prevent establishing which rule wins."
+          end
+          matcher = matchers.first
+          unless matcher["type"] == "literal" && matcher["field"] == "to" && matcher["value"].is_a?(String)
+            raise ReadError, "Unsupported rule matchers prevent establishing which rule wins."
+          end
+          next unless matcher["value"].casecmp?(address)
+          raise ReadError, "A matching rule has an unknown enabled state." unless rule["enabled"] == true
+          matching << rule
+        end
+        if matching.size > 1
+          raise ReadError, "Multiple explicit rules match; their priority or tie ordering has not been verified."
+        end
+        if matching.one?
+          selected = matching.first
+          source = "Explicit address rule (takes precedence over catch-all)"
+        else
+          selected = get("/zones/#{zone_id}/email/routing/rules/catch_all")["result"]
+          unless selected.is_a?(Hash) && selected["matchers"] == [{ "type" => "all" }]
+            raise ReadError, "Catch-all settings are incomplete or use unsupported matchers."
+          end
+          source = "Catch-all rule"
+        end
+        unless [true, false].include?(selected["enabled"])
+          raise ReadError, "Selected rule has an unknown enabled state."
+        end
+        unless selected["enabled"]
+          return add(checks, "route", "fail", "No enabled explicit route or catch-all accepts this address.")
+        end
+        actions = selected["actions"]
+        unless actions.is_a?(Array) && actions.all? { |action| action.is_a?(Hash) }
+          raise ReadError, "Selected rule actions were not returned."
+        end
+        correct = actions.size == 1 && actions.first["type"] == "worker" && actions.first["value"] == [worker_name]
+        add(checks, "route", correct ? "pass" : "fail", correct ?
+          "#{source} targets the expected Worker." : "#{source} does not exclusively target the expected Worker (it may drop, forward, or target another Worker).")
+      end
+
+      def pages(path)
+        records = []
+        1.upto(MAX_PAGES) do |page|
+          data = get("#{path}#{path.include?('?') ? '&' : '?'}per_page=50&page=#{page}")
+          batch = data["result"]
+          raise ReadError, "Provider returned an invalid list." unless batch.is_a?(Array) && batch.all? { |item| item.is_a?(Hash) }
+          records.concat(batch)
+          total = data.dig("result_info", "total_pages")
+          if total && (!total.is_a?(Integer) || total.negative? || (total.zero? && batch.any?))
+            raise ReadError, "Provider returned invalid pagination."
+          end
+          return records if total ? page >= total : batch.size < 50
+          raise ReadError, "Provider pagination ended before all pages were available." if batch.empty?
+        end
+        raise ReadError, "Provider pagination exceeds the inspection limit."
+      end
+
+      def get(path)
+        uri = URI.parse("#{@api_base}#{path}")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = 5
+        http.read_timeout = 10
+        request = Net::HTTP::Get.new(uri.request_uri)
+        request["Authorization"] = "Bearer #{@api_token}"
+        request["Accept"] = "application/json"
+        body = +""
+        # read_timeout alone does not bound a peer streaming tiny chunks.
+        Timeout.timeout(20) do
+          http.request(request) do |response|
+            raise ReadError, "Provider request failed (HTTP #{response.code.to_i}); check token scopes and configuration." unless response.code.to_i.between?(200, 299)
+            response.read_body do |chunk|
+              raise ReadError, "Provider response exceeds the inspection size limit." if body.bytesize + chunk.bytesize > MAX_BYTES
+              body << chunk
+            end
+          end
+        end
+        data = JSON.parse(body)
+        unless data.is_a?(Hash) && data["success"] == true && data.key?("result")
+          raise ReadError, "Provider response did not contain a successful result."
+        end
+        data
+      rescue ReadError
+        raise
+      rescue StandardError
+        # Never surface raw provider bodies, URLs, credentials, or socket errors.
+        raise ReadError, "Provider request could not be read; check connectivity, token scopes, and response format."
+      end
+    end
+  end
+end

data/lib/cloudflare/email/verification.rb

@@ -1,5 +1,6 @@
 require "cloudflare/email/signing"
 require "cloudflare/email/envelope"
+require "cloudflare/email/provider_metadata"
 
 module Cloudflare
   module Email
@@ -13,20 +14,22 @@ module Cloudflare
     #   X-CF-Email-Signature: <hex digest>
     #   X-CF-Email-Signature-Version: 2
     #   X-CF-Email-Envelope: <unpadded base64url JSON from/to>
-    # The version and authenticated SMTP envelope are required.
+    # Custom integrations may use v3, adding X-CF-Email-Metadata and signing
+    # "v3.{timestamp}.{encoded_envelope}.{encoded_metadata}.{raw_body}".
+    # v2 rejects metadata headers; v3 requires them. Both require the envelope.
     module Verification
       DEFAULT_WINDOW = 5 * 60 # seconds
 
       # Returns :ok, :bad_signature, or :stale.
       # Returns :bad_signature for any malformed input.
-      def self.verify(secret:, body:, timestamp:, signature:, version: nil, envelope: nil, window: DEFAULT_WINDOW, now: Time.now.to_i)
+      def self.verify(secret:, body:, timestamp:, signature:, version: nil, envelope: nil, metadata: nil, window: DEFAULT_WINDOW, now: Time.now.to_i)
         return :bad_signature if blank?(body)
         timestamp = timestamp.to_s if timestamp.is_a?(Integer)
         preflight = verify_headers(secret: secret, timestamp: timestamp, signature: signature,
-          version: version, envelope: envelope, window: window, now: now)
+          version: version, envelope: envelope, metadata: metadata, window: window, now: now)
         return preflight unless preflight == :ok
 
-        expected = sign(secret: secret, body: body, timestamp: Integer(timestamp, 10), version: version, envelope: envelope)
+        expected = sign(secret: secret, body: body, timestamp: timestamp, version: version, envelope: envelope, metadata: metadata)
         return :bad_signature unless Signing.secure_compare(expected, signature)
 
         :ok
@@ -34,11 +37,12 @@ module Cloudflare
 
       # Reject malformed/stale requests before the controller reads MIME bytes.
       # This is only a preflight: authentication still requires verify(body: ...).
-      def self.verify_headers(secret:, timestamp:, signature:, version:, envelope:, window: DEFAULT_WINDOW, now: Time.now.to_i)
+      def self.verify_headers(secret:, timestamp:, signature:, version:, envelope:, metadata: nil, window: DEFAULT_WINDOW, now: Time.now.to_i)
         return :bad_signature if blank?(secret)
         return :bad_signature unless timestamp.is_a?(String) && /\A[0-9]{1,20}\z/.match?(timestamp)
         return :bad_signature unless signature.is_a?(String) && /\A[0-9a-f]{64}\z/.match?(signature)
-        return :bad_signature unless version == "2" && Envelope.decode(envelope)
+        return :bad_signature unless Envelope.decode(envelope)
+        return :bad_signature unless valid_metadata_version?(version, metadata)
 
         ts = begin
           Integer(timestamp.to_s, 10)
@@ -51,13 +55,17 @@ module Cloudflare
         :ok
       end
 
-      def self.sign(secret:, body:, timestamp:, envelope:, version: "2")
-        raise ArgumentError, "unsupported signature version" unless version == "2"
+      def self.sign(secret:, body:, timestamp:, envelope:, version: "2", metadata: nil)
+        raise ArgumentError, "invalid signature version or metadata" unless valid_metadata_version?(version, metadata)
         raise ArgumentError, "invalid SMTP envelope" unless Envelope.decode(envelope)
-        prefix = "v2.#{timestamp}.#{envelope}."
+        prefix = version == "3" ? "v3.#{timestamp}.#{envelope}.#{metadata}." : "v2.#{timestamp}.#{envelope}."
         Signing.hmac_hex(secret, prefix.b + body.b)
       end
 
+      def self.valid_metadata_version?(version, metadata)
+        (version == "2" && metadata.nil?) || (version == "3" && ProviderMetadata.decode(metadata))
+      end
+
       def self.blank?(v)
         v.nil? || v.to_s.empty?
       end

data/lib/cloudflare/email/version.rb

@@ -1,5 +1,5 @@
 module Cloudflare
   module Email
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/cloudflare/email/worker_deployer.rb

@@ -55,12 +55,20 @@ module Cloudflare
 
       # Uploads/updates the Worker script. Accepts either `script_path:` (a
       # path to a .js file) or `source:` (the JS source string directly).
-      def deploy(script_path: nil, source: nil)
+      # The Rails deploy task passes delivery_mode: "durable" and validates
+      # existing infrastructure. Low-level callers managing custom Workers may
+      # omit it to preserve their configured transport without changing it.
+      def deploy(script_path: nil, source: nil, delivery_mode: nil)
         source ||= File.read(script_path) if script_path
         raise ArgumentError, "must pass script_path: or source:" if source.nil?
 
+        if delivery_mode
+          raise ArgumentError, "delivery_mode must be durable or direct" unless %w[durable direct].include?(delivery_mode)
+          verify_durable_infrastructure! if delivery_mode == "durable"
+        end
+
         boundary = "----cf-email-#{SecureRandom.hex(16)}"
-        body     = build_multipart(boundary, source)
+        body     = build_multipart(boundary, source, delivery_mode)
 
         request(
           method: :put,
@@ -108,11 +116,34 @@ module Cloudflare
 
       private
 
-      def build_multipart(boundary, source)
-        metadata = JSON.generate({
+      def verify_durable_infrastructure!
+        settings = request(method: :get, path: "/accounts/#{@account_id}/workers/scripts/#{@script_name}/settings")
+        bindings = Array(settings.dig("result", "bindings"))
+        configured = bindings.any? { |b| b["name"] == "INBOUND_EMAIL_STORE" && b["type"] == "r2_bucket" } &&
+          bindings.any? { |b| b["name"] == "INBOUND_EMAIL_QUEUE" && b["type"] == "queue" }
+        schedules = request(method: :get, path: "/accounts/#{@account_id}/workers/scripts/#{@script_name}/schedules")
+        configured &&= Array(schedules.dig("result", "schedules")).any? { |s| s["cron"] == "* * * * *" }
+        return if configured
+
+        raise ConfigurationError, "Provision durable R2, Queue producer/consumer and minute schedule using the generated Worker docs/durable-inbound.md before deploying; use INBOUND_DELIVERY_MODE=direct only for explicit direct fallback"
+      rescue Error => error
+        raise unless error.status == 404
+
+        raise ConfigurationError, "Provision the durable Worker with Wrangler first (see Worker docs/durable-inbound.md); use INBOUND_DELIVERY_MODE=direct only for explicit direct fallback"
+      end
+
+      def build_multipart(boundary, source, delivery_mode)
+        settings = {
           main_module:        "index.js",
           compatibility_date: @compatibility_date,
-        })
+          # API script uploads must not remove provisioned storage, queue or
+          # secrets. In particular a direct rollback still drains pending mail.
+          keep_bindings: %w[secret_text plain_text r2_bucket queue],
+        }
+        if delivery_mode
+          settings[:bindings] = [{ type: "plain_text", name: "INBOUND_DELIVERY_MODE", text: delivery_mode }]
+        end
+        metadata = JSON.generate(settings)
 
         parts = []
         parts << "--#{boundary}"

data/lib/generators/cloudflare/email/install_generator.rb

@@ -102,8 +102,8 @@ module Cloudflare
           should_deploy = options[:deploy_worker]
           if should_deploy.nil?
             say ""
-            say "  The Worker can be deployed via the Cloudflare API (pure Ruby, no wrangler/Node)"
-            say "  once you've set cloudflare.account_id and cloudflare.api_token in Rails credentials."
+            say "  First provision durable storage, Queue and cron using the generated Worker docs/durable-inbound.md."
+            say "  After the initial Wrangler deploy, Ruby uploads preserve those infrastructure bindings."
             say "  Run `RAILS_ENV=production bin/rails cloudflare:email:deploy_worker SCRIPT=#{worker_script_argument} URL=https://yourapp.com#{ingress_path}`"
             say "  after `bin/rails credentials:edit`."
             say ""
@@ -121,6 +121,7 @@ module Cloudflare
             @ingress_secret = SecureRandom.hex(32)
 
             inside options[:worker_dir] do
+              say "Create the R2 bucket and Queue in docs/durable-inbound.md before deploying. Customize wrangler.toml names if needed."
               run "npm ci", abort_on_failure: true
 
               ingress_url = ask("Rails ingress URL? (e.g. https://yourapp.com#{ingress_path})")
@@ -168,10 +169,10 @@ module Cloudflare
 
           if options[:inbound] && !@worker_deployed
             say "  4. Deploy the Worker (pick one):"
-            say "       # Pure Ruby (recommended — no wrangler/Node required):"
+            say "       # First follow Worker docs/durable-inbound.md to provision R2, Queue and cron."
             say "       RAILS_ENV=production bin/rails cloudflare:email:deploy_worker SCRIPT=#{worker_script_argument} URL=https://yourapp.com#{ingress_path}"
             say ""
-            say "       # Or via wrangler if you have it installed:"
+            say "       # Initial infrastructure deploy (after provisioning resources):"
             say "       cd #{options[:worker_dir]}"
             say "       npm ci"
             say "       npm run deploy -- --env production"
@@ -182,7 +183,7 @@ module Cloudflare
 
           if options[:inbound]
             say "  5. For local dev (tunnels cloudflared to your Worker):"
-            say "       RAILS_ENV=development bin/rails cloudflare:email:deploy_worker SCRIPT=#{worker_script_argument}"
+            say "       INBOUND_DELIVERY_MODE=direct RAILS_ENV=development bin/rails cloudflare:email:deploy_worker SCRIPT=#{worker_script_argument}"
             say "       RAILS_ENV=development bin/rails cloudflare:email:dev"
             say "     Route a separate test address to cloudflare-email-ingress-development."
             say ""

data/lib/generators/cloudflare/email/mailboxes/catch_all/catch_all_generator.rb

@@ -0,0 +1,21 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Cloudflare
+  module Email
+    module Generators
+      class CatchAllGenerator < ::Rails::Generators::Base
+        include ::ActiveRecord::Generators::Migration
+        namespace "cloudflare:email:mailboxes:catch_all"
+        source_root File.expand_path("templates", __dir__)
+        class_option :tenant_migrations_path, type: :string, default: "db/migrate",
+          desc: "Migration directory applied to every tenant database"
+
+        def copy_migration
+          migration_template "add_cloudflare_email_catch_all.rb",
+            File.join(options[:tenant_migrations_path], "add_cloudflare_email_catch_all.rb")
+        end
+      end
+    end
+  end
+end

data/lib/generators/cloudflare/email/mailboxes/catch_all/templates/add_cloudflare_email_catch_all.rb

@@ -0,0 +1,18 @@
+class AddCloudflareEmailCatchAll < ActiveRecord::Migration[7.1]
+  def up
+    unless column_exists?(:cloudflare_email_addresses, :catch_all)
+      add_column :cloudflare_email_addresses, :catch_all, :boolean, null: false, default: false
+    end
+    unless column_exists?(:cloudflare_email_addresses, :catch_all_evidence)
+      add_column :cloudflare_email_addresses, :catch_all_evidence, :text
+    end
+    unless index_exists?(:cloudflare_email_addresses, :receiving_domain_id, name: "idx_cf_email_domain_catch_all")
+      add_index :cloudflare_email_addresses, :receiving_domain_id, unique: true,
+        where: "catch_all = TRUE AND state = 'active'", name: "idx_cf_email_domain_catch_all"
+    end
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration, "Disable catch-all receiving before an explicit forward schema change"
+  end
+end

data/lib/generators/cloudflare/email/mailboxes/templates/create_cloudflare_email_mailboxes.rb

@@ -19,10 +19,14 @@ class CreateCloudflareEmailMailboxes < ActiveRecord::Migration[7.1]
       t.string :address, null: false
       t.string :state, null: false, default: "pending"
       t.text :provisioning_evidence
+      t.boolean :catch_all, null: false, default: false
+      t.text :catch_all_evidence
       t.timestamps
     end
     add_index :cloudflare_email_addresses, :address, unique: true, name: "idx_cf_email_mailbox_address"
     add_index :cloudflare_email_addresses, :mailbox_id, name: "idx_cf_email_address_mailbox"
+    add_index :cloudflare_email_addresses, :receiving_domain_id, unique: true,
+      where: "catch_all = TRUE AND state = 'active'", name: "idx_cf_email_domain_catch_all"
 
     create_table :cloudflare_email_mailbox_messages do |t|
       t.string :tenant_key, null: false

data/lib/generators/cloudflare/email/routing_tracking/routing_tracking_generator.rb

@@ -0,0 +1,28 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Cloudflare
+  module Email
+    module Generators
+      class RoutingTrackingGenerator < ::Rails::Generators::Base
+        include ::ActiveRecord::Generators::Migration
+        namespace "cloudflare:email:routing_tracking"
+        source_root File.expand_path("templates", __dir__)
+        class_option :migrations_path, type: :string, default: "db/migrate"
+
+        def copy_tracking_migration
+          migration_template "create_cloudflare_email_routing_delivery_receipts.rb",
+            File.join(options[:migrations_path], "create_cloudflare_email_routing_delivery_receipts.rb")
+        end
+
+        def create_initializer
+          create_file "config/initializers/cloudflare_email_routing_tracking.rb", <<~RUBY
+            # Requires the outbox migration and Rails Active Record encryption keys.
+            # This loads the API only; your application schedules analytics polling.
+            require "cloudflare/email/active_record/routing_deliveries"
+          RUBY
+        end
+      end
+    end
+  end
+end

data/lib/generators/cloudflare/email/routing_tracking/templates/create_cloudflare_email_routing_delivery_receipts.rb

@@ -0,0 +1,22 @@
+class CreateCloudflareEmailRoutingDeliveryReceipts < ActiveRecord::Migration[7.1]
+  def up
+    create_table :cloudflare_email_routing_delivery_receipts do |t|
+      t.references :outbound_delivery, null: false, index: {name: "idx_cf_routing_delivery"},
+        foreign_key: {to_table: :cloudflare_email_outbound_deliveries}
+      t.string :account_id, null: false
+      t.string :zone_id, null: false
+      t.string :event_key, null: false
+      t.text :payload_json, null: false
+      t.string :state, null: false, default: "pending"
+      t.datetime :received_at, null: false
+      t.datetime :applied_at
+      t.timestamps
+    end
+    add_index :cloudflare_email_routing_delivery_receipts, [:account_id, :event_key], unique: true, name: "idx_cf_routing_identity"
+    add_index :cloudflare_email_routing_delivery_receipts, [:account_id, :state, :id], name: "idx_cf_routing_replay"
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration, "Preserve authentic delivery evidence; use a forward fix or a reconciled backup"
+  end
+end

data/lib/tasks/cloudflare_email.rake

@@ -15,7 +15,8 @@ namespace :cloudflare do
     desc "Deploy the Worker via Cloudflare API. URL=https://... sets RAILS_INGRESS_URL; SCRIPT=path overrides the Worker source"
     task deploy_worker: :environment do
       require "cloudflare/email/deploy_worker_task"
-      exit Cloudflare::Email::DeployWorkerTask.call(ingress_url: ENV["URL"], script_path: ENV["SCRIPT"])
+      exit Cloudflare::Email::DeployWorkerTask.call(ingress_url: ENV["URL"], script_path: ENV["SCRIPT"],
+        delivery_mode: ENV.fetch("INBOUND_DELIVERY_MODE", "durable"))
     end
 
     desc "Create Cloudflare Email Routing rule: ADDRESS=addr@domain → env-scoped Worker (WORKER=name to override)"

data/lib/tasks/cloudflare_email_diagnostics.rake

@@ -0,0 +1,11 @@
+namespace :cloudflare do
+  namespace :email do
+    desc "Inspect routing without changes (ADDRESS=addr [WORKER_NAME=name] [ACCOUNT_ID=id]); nonzero if failed or unverified"
+    task check_route: :environment do
+      require "cloudflare/email/check_route_task"
+      exit Cloudflare::Email::CheckRouteTask.call(
+        address: ENV["ADDRESS"], worker_name: ENV["WORKER_NAME"] || ENV["WORKER"], account_id: ENV["ACCOUNT_ID"],
+      )
+    end
+  end
+end

data/templates/deploy-to-cloudflare/.dev.vars.example

@@ -0,0 +1,3 @@
+# Supply these in the Cloudflare deployment form. Never commit real values.
+RAILS_INGRESS_URL=
+INGRESS_SECRET=

data/templates/deploy-to-cloudflare/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+.wrangler/
+.dev.vars*
+!.dev.vars.example
+.env*
+!.env.example

data/templates/deploy-to-cloudflare/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cole
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/templates/deploy-to-cloudflare/README.md

@@ -0,0 +1,84 @@
+# Cloudflare Email for Rails
+
+Receive email in Rails with the [cloudflare-email gem](https://github.com/cole-robertson/cloudflare-email).
+This template stores inbound mail in private R2, delivers it through a Queue,
+and retries from storage when Rails is unavailable. It includes scheduled
+recovery and Worker logs. No React app or extra server is needed.
+
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cole-robertson/cloudflare-email/tree/main/templates/deploy-to-cloudflare)
+
+## 1. Prepare Rails
+
+Install `gem "cloudflare-email", "~> 0.3.0"` and follow the
+[Rails setup guide](https://github.com/cole-robertson/cloudflare-email/blob/main/docs/getting-started.md).
+Deploy Rails with Action Mailbox storage and routing configured before connecting
+real email. Generate a secret with `openssl rand -hex 32` and configure it as
+`cloudflare.ingress_secret` in Rails credentials or `CLOUDFLARE_INGRESS_SECRET`.
+Keep the same value for the deployment form.
+
+## 2. Deploy the Worker
+
+Click the button and sign in to Cloudflare and GitHub/GitLab as prompted.
+Cloudflare copies this directory into your own repository, provisions the R2
+bucket and Queue, and builds the Worker. Enter:
+
+- **RAILS_INGRESS_URL:** your public HTTPS endpoint, normally
+  `https://your-app.com/rails/action_mailbox/cloudflare/inbound_emails`.
+- **INGRESS_SECRET:** the exact secret you configured in Rails.
+
+Choose distinct Worker, bucket, and Queue names for each app/environment. This
+template has one environment per deployment; deploy separate copies for staging
+and production. R2 and Queues must be available on your account and their usage
+can incur charges. Review Cloudflare's resource and billing prompts.
+
+The form uses `npm run deploy`; no `--env` argument is required for this template.
+After deployment, confirm both bindings, the Queue consumer, and the once-per-minute
+cron are present. Keep the bucket private with no lifecycle rule expiring
+`cloudflare-email/pending/` objects. The Worker has no public email-submit HTTP API.
+
+## 3. Connect an email address
+
+In Cloudflare, enable Email Routing for the intended receiving domain/subdomain
+and complete its required DNS setup. Add an Email Routing rule for your receiving
+address with **Send to a Worker**, selecting the Worker you just deployed.
+The button does not change your MX records, provision addresses in Rails, or
+replace your existing mailbox provider. Use a receiving subdomain when your apex
+domain's email belongs to Google Workspace or Microsoft 365.
+
+If using the gem's managed mailboxes, register the receiving mailbox/address in
+Rails too. Tenant support and domain catch-all receiving remain explicit choices.
+Outbound Email Sending credentials and delivery-event subscriptions are separate
+from this inbound Worker setup.
+
+## 4. Verify and operate
+
+Send to the configured address and verify that Rails retains and routes it.
+In staging, stop Rails, send another message, confirm it remains in R2, restore
+Rails, and confirm one inbox record and removal of the pending object. Verify a
+retry does not duplicate application work. Monitor Worker errors and pending R2
+count/age; Queue depth alone misses mail whose queue retries are exhausted.
+
+Read the [durable delivery and recovery guide](https://github.com/cole-robertson/cloudflare-email/blob/main/templates/worker/docs/durable-inbound.md)
+for recovery limits, retention, failure drills, and the explicit direct fallback.
+In this standalone template, configure bindings at the top level and run
+`npm run deploy` without `--env`. Do not remove storage or cron while mail is pending.
+Delivery is at least once, with Rails deduplication; application handlers must
+also tolerate retries. Configure operational alerts in your monitoring service.
+
+## Updates and local development
+
+Your copied repository belongs to you; gem updates do not update its Worker
+automatically. Review upstream release notes, deploy Rails first, then port Worker
+changes into your copy while preserving your resource names, secrets, and pending
+storage. Keep production resources separate from test resources.
+
+Use Node 22.12+ (or a supported newer version): `npm ci`, `npm test`, and
+`npm run check`. For local development, copy `.dev.vars.example` to `.dev.vars`,
+set local values, and run `npm run dev`. Never commit secrets.
+
+Upstream maintainers: `templates/worker` is the canonical runtime. Run
+`node script/sync_deploy_template.mjs` from the gem repository after modifying its
+runtime, tests, dependencies, or production bindings. CI rejects drift and tests
+this directory after copying it outside the repository, matching Cloudflare's
+subdirectory deployment model. Edit this README directly; generated files are
+marked by the sync script's file list.