cloudflare-email 0.1.0 → 0.3.0

data/lib/cloudflare/email/provision_catchall_task.rb

@@ -6,7 +6,7 @@ module Cloudflare
   module Email
     # `bin/rails cloudflare:email:provision_catchall` — points a zone's
     # catch-all rule at the env-scoped ingress Worker. Useful for bounce
-    # handling, dev subdomains, and alias routing.
+    # handling and alias routing. Applies to the entire Cloudflare zone.
     class ProvisionCatchallTask < TaskBase
       def self.call(domain:, worker_name: nil, io: $stdout)
         new(io: io, domain: domain, worker_name: worker_name).call
@@ -16,11 +16,11 @@ module Cloudflare
 
       def run
         require_value!(management_token, "cloudflare.api_token or cloudflare.management_token")
-        require_value!(opts[:domain],    "DOMAIN=in.example.com")
+        require_value!(opts[:domain],    "DOMAIN=example.com (the Cloudflare zone name)")
 
         worker = opts[:worker_name] || Cloudflare::Email::WorkerDeployer.default_script_name
 
-        say "Provisioning catch-all:"
+        say "Provisioning zone-wide catch-all:"
         say "  Domain: #{opts[:domain]}"
         say "  Worker: #{worker}"
         say ""
@@ -29,7 +29,7 @@ module Cloudflare
         provisioner.provision_catch_all_for_domain(domain: opts[:domain], worker_name: worker)
 
         say "  ✓ Catch-all on #{opts[:domain]} now points at #{worker}."
-        say "  All unrouted addresses on this domain will hit your Worker."
+        say "  All unrouted addresses covered by this zone's catch-all will hit your Worker."
       end
     end
   end

data/lib/cloudflare/email/provision_route_task.rb

@@ -27,7 +27,8 @@ module Cloudflare
         provisioner = Cloudflare::Email::RoutingProvisioner.new(api_token: management_token)
         provisioner.provision(address: opts[:address], worker_name: worker)
 
-        say "  ✓ Route created/updated — mail to #{opts[:address]} will hit Worker #{worker}."
+        say "  ✓ Route created/updated for #{opts[:address]} → Worker #{worker}."
+        say "  Verify DNS propagation and send a test message to confirm delivery."
       end
     end
   end

data/lib/cloudflare/email/replay_events_job.rb

@@ -0,0 +1,18 @@
+require "active_job"
+require "cloudflare/email/active_record"
+
+module Cloudflare
+  module Email
+    class ReplayEventsJob < ::ActiveJob::Base
+      queue_as :mailers
+
+      def perform(account_id, message_id = nil)
+        handler = if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+          Rails.application.config.x.cloudflare_email.outbox_recipient_handler
+        end
+        ActiveRecord::DeliveryEvents.replay(account_id: account_id, message_id: message_id,
+          &(handler.method(:call) if handler.respond_to?(:call)))
+      end
+    end
+  end
+end

data/lib/cloudflare/email/response.rb

@@ -1,3 +1,5 @@
+require "cloudflare/email/message_id"
+
 module Cloudflare
   module Email
     class Response
@@ -9,18 +11,30 @@ module Cloudflare
       end
 
       def success?
-        return !!@raw["success"] if @raw.key?("success") && !@raw["success"].nil?
-        @status >= 200 && @status < 300
+        return false unless @status.is_a?(Integer) && @status >= 200 && @status < 300
+        return @raw["success"] == true if @raw.key?("success")
+        true
       end
 
       def result
         @raw["result"].is_a?(Hash) ? @raw["result"] : {}
       end
 
+      # Provider acceptance is not final delivery. A partial acceptance is true;
+      # inspect recipient outcomes before retrying any rejected recipients.
+      def accepted?
+        return false if %w[delivered queued permanent_bounces suppressed_recipients].any? { |key| result.key?(key) && !result[key].is_a?(Array) }
+        success? && (delivered.any? || queued.any? ||
+          (!message_id.to_s.strip.empty? && permanent_bounces.empty? && suppressed_recipients.empty?))
+      end
+
       def message_id
-        result["message_id"] ||
+        value = result["message_id"] ||
           dig_message_id(result["delivered"]) ||
           dig_message_id(result["queued"])
+        return nil unless value.is_a?(String)
+        normalized = MessageId.normalize(value)
+        value unless normalized.empty? || normalized.match?(/[\s<>[:cntrl:]]/)
       end
 
       def delivered
@@ -35,6 +49,10 @@ module Cloudflare
         Array(result["permanent_bounces"])
       end
 
+      def suppressed_recipients
+        Array(result["suppressed_recipients"])
+      end
+
       def errors
         Array(@raw["errors"])
       end

data/lib/cloudflare/email/routing_analytics.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "timeout"
+require "time"
+require "digest"
+require "cloudflare/email/message_id"
+
+module Cloudflare
+  module Email
+    # Optional, authenticated, delivered-only evidence. This is not a webhook.
+    module RoutingAnalytics
+      class Error < StandardError; end
+
+      class Evidence
+        attr_reader :payload
+
+        def initialize(payload)
+          @payload = JSON.parse(JSON.generate(payload))
+          validate!
+          freeze_value(@payload)
+          freeze
+        rescue JSON::ParserError, JSON::GeneratorError, KeyError, ArgumentError, TypeError
+          raise Error, "Routing analytics evidence is malformed", cause: nil
+        end
+
+        def event = payload.fetch("event")
+        def account_id = payload.fetch("account_id")
+        def zone_id = payload.fetch("zone_id")
+        def message_id = MessageId.normalize(event.fetch("messageId"))
+        def occurred_at = Time.iso8601(event.fetch("datetime"))
+
+        def identity
+          Digest::SHA256.hexdigest(JSON.generate([account_id, zone_id, event.fetch("sessionId"),
+            message_id, occurred_at.iso8601(9), event.fetch("status")]))
+        end
+
+        # Query windows change between polls; the authentic row must not change.
+        def same_event?(other)
+          account_id == other.account_id && zone_id == other.zone_id && event == other.event
+        end
+
+        private
+
+        def validate!
+          unless payload.is_a?(Hash) && payload["source"] == "cloudflare_routing_analytics" &&
+              payload["account_id"].is_a?(String) && !payload["account_id"].empty? &&
+              payload["zone_id"].is_a?(String) && payload["zone_id"].match?(/\A[a-f0-9]{32}\z/) &&
+              event.is_a?(Hash) && event["eventType"] == "newEmail" && event["status"] == "delivered" &&
+              event["isNDR"] == 0 && event["isLastEvent"] == 1 && event["sampleInterval"] == 1 &&
+              event["sessionId"].is_a?(String) && !event["sessionId"].strip.empty? &&
+              event["from"].is_a?(String) && !event["from"].strip.empty? &&
+              event["messageId"].is_a?(String) && !message_id.empty?
+            raise Error, "Routing analytics evidence is not an unsampled final delivery"
+          end
+          start = Time.iso8601(payload.fetch("query_started_at"))
+          finish = Time.iso8601(payload.fetch("query_finished_at"))
+          unless start <= occurred_at && occurred_at <= finish && finish <= Time.now.utc
+            raise Error, "Routing analytics evidence is outside its query window"
+          end
+          response = payload.fetch("response")
+          viewer = response["data"] if response.is_a?(Hash)
+          viewer = viewer["viewer"] if viewer.is_a?(Hash)
+          zones = viewer["zones"] if viewer.is_a?(Hash)
+          unless response.is_a?(Hash) && response["success"] != false &&
+              (response["errors"].nil? || response["errors"] == []) && zones.is_a?(Array) && zones.one? &&
+              zones.first.is_a?(Hash) && zones.first["zoneTag"] == zone_id
+            raise Error, "Routing analytics evidence response has unexpected zone"
+          end
+          rows = zones.first["emailRoutingAdaptive"]
+          unless rows.is_a?(Array) && rows.length < 100 && rows.all? { |row| row.is_a?(Hash) } && rows.include?(event)
+            raise Error, "Routing analytics evidence response is malformed or truncated"
+          end
+        end
+
+        def freeze_value(value)
+          value.each { |key, item| freeze_value(key); freeze_value(item) } if value.is_a?(Hash)
+          value.each { |item| freeze_value(item) } if value.is_a?(Array)
+          value.freeze
+        end
+      end
+
+      class Client
+        REQUEST_TIMEOUT = 5
+        MAX_RESPONSE_BYTES = 1_000_000
+        QUERY = <<~GRAPHQL.freeze
+          query($zone: string!, $ids: [string!], $start: Time!, $finish: Time!) {
+            viewer { zones(filter: {zoneTag: $zone}) {
+              zoneTag
+              emailRoutingAdaptive(limit: 100, orderBy: [datetime_ASC], filter: {
+                messageId_in: $ids, datetime_geq: $start, datetime_leq: $finish
+              }) { messageId sessionId datetime eventType status isNDR isLastEvent sampleInterval from to action }
+            } }
+          }
+        GRAPHQL
+
+        def initialize(account_id:, zone_id:, api_token:)
+          unless account_id.is_a?(String) && !account_id.empty? && zone_id.is_a?(String) &&
+              zone_id.match?(/\A[a-f0-9]{32}\z/) && api_token.is_a?(String) && !api_token.strip.empty? &&
+              !api_token.match?(/[\r\n]/)
+            raise ArgumentError, "Routing analytics requires an account, zone ID and API token"
+          end
+          @account, @zone, @token = account_id.dup.freeze, zone_id.dup.freeze, api_token.dup.freeze
+        end
+
+        def inspect = "#<#{self.class} credentials=[FILTERED]>"
+
+        def verify_account!
+          @verified = false
+          result = request("/zones/#{@zone}")["result"]
+          unless result.is_a?(Hash) && result["id"] == @zone && result["account"].is_a?(Hash) &&
+              result["account"]["id"] == @account
+            raise Error, "Routing analytics zone/account mismatch"
+          end
+          @verified = true
+        end
+
+        def delivery_evidence(message_id:, since:, until_time:)
+          raise Error, "Verify routing analytics zone/account first" unless @verified
+          id = MessageId.normalize(message_id)
+          unless !id.empty? && since.is_a?(Time) && until_time.is_a?(Time) && since <= until_time && until_time <= Time.now.utc
+            raise ArgumentError, "A message ID and valid historical Time window are required"
+          end
+          # Analytics timestamps have second precision, unlike saved attempts.
+          start, finish = Time.at(since.to_i).utc.iso8601, until_time.getutc.iso8601
+          data = request("/graphql", query: QUERY, variables: {
+            zone: @zone, ids: [id, "<#{id}>"], start: start, finish: finish
+          })
+          viewer = data["data"]
+          viewer = viewer["viewer"] if viewer.is_a?(Hash)
+          zones = viewer["zones"] if viewer.is_a?(Hash)
+          unless zones.is_a?(Array) && zones.one? && zones.first.is_a?(Hash) && zones.first["zoneTag"] == @zone
+            raise Error, "Routing analytics response has unexpected zone"
+          end
+          rows = zones.first["emailRoutingAdaptive"]
+          unless rows.is_a?(Array) && rows.length < 100 && rows.all? { |row| row.is_a?(Hash) }
+            raise Error, "Routing analytics response is malformed or truncated"
+          end
+          final_rows = rows.select { |row| row["eventType"] == "newEmail" && row["isNDR"] == 0 &&
+            row["isLastEvent"] == 1 && row["sampleInterval"] == 1 }
+          final_rows.group_by { |row| [MessageId.normalize(row["messageId"]), row["sessionId"]] }.each_value do |events|
+            if events.uniq.length > 1
+              raise Error, "Routing analytics response contains contradictory final events"
+            end
+          end
+          rows.filter_map do |row|
+            next unless row["eventType"] == "newEmail" && row["status"] == "delivered" &&
+              row["isNDR"] == 0 && row["isLastEvent"] == 1 && row["sampleInterval"] == 1
+            evidence = Evidence.new("source" => "cloudflare_routing_analytics", "account_id" => @account,
+              "zone_id" => @zone, "query_started_at" => start, "query_finished_at" => finish,
+              "response" => data, "event" => row)
+            raise Error, "Routing analytics response has unexpected Message-ID" unless evidence.message_id == id
+            evidence
+          end
+        end
+
+        private
+
+        def request(path, body = nil)
+          uri = URI("https://api.cloudflare.com/client/v4#{path}")
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+          http.open_timeout = http.read_timeout = http.write_timeout = REQUEST_TIMEOUT
+          http.max_retries = 0
+          request = body ? Net::HTTP::Post.new(uri) : Net::HTTP::Get.new(uri)
+          request["Authorization"] = "Bearer #{@token}"
+          request["Content-Type"] = "application/json"
+          request.body = JSON.generate(body) if body
+          payload = +""
+          Timeout.timeout(REQUEST_TIMEOUT) do
+            http.request(request) do |response|
+              raise Error, "Routing analytics HTTP request failed" unless response.is_a?(Net::HTTPSuccess)
+              response.read_body do |chunk|
+                raise Error, "Routing analytics response is too large" if payload.bytesize + chunk.bytesize > MAX_RESPONSE_BYTES
+                payload << chunk
+              end
+            end
+          end
+          data = JSON.parse(payload)
+          unless data.is_a?(Hash) && data["success"] != false && (data["errors"].nil? || data["errors"] == [])
+            raise Error, "Routing analytics API rejected query"
+          end
+          data
+        rescue JSON::ParserError, KeyError, TypeError
+          raise Error, "Routing analytics API response is invalid", cause: nil
+        rescue Timeout::Error
+          raise Error, "Routing analytics HTTP deadline exceeded", cause: nil
+        rescue IOError, SystemCallError, SocketError, OpenSSL::SSL::SSLError,
+            Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError, Net::ProtocolError
+          raise Error, "Routing analytics HTTP request failed", cause: nil
+        end
+      end
+    end
+  end
+end

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