cloudflare-email 0.2.0 → 0.3.0

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

@@ -4,6 +4,16 @@ require "cloudflare/email/envelope"
 module Cloudflare
   module Email
     module Mailboxes
+      # A routing snapshot, not a model or an authorization token. Use it inside
+      # the yielded tenant context; later jobs must resolve/check policy again.
+      Destination = Struct.new(:tenant_key, :mailbox_id, :address_id,
+        :receiving_domain_id, :recipient, :owner_ref, :catch_all, keyword_init: true) do
+        def initialize(**attributes)
+          super(**{ catch_all: false }.merge(attributes).transform_values { |value| value.is_a?(String) ? value.dup.freeze : value })
+          freeze
+        end
+      end
+
       class << self
         # Call after host authorization. The directory is a control-plane API,
         # not a public endpoint accepting arbitrary customer domain claims.
@@ -27,16 +37,23 @@ module Cloudflare
 
         # Only call after verifying the complete ingress HMAC. Resolve before
         # ActionMailbox or ActiveStorage accesses a tenant connection.
-        def receive(recipient:)
-          raise ArgumentError, "persistence block required" unless block_given?
-          address = canonical_address(recipient)
-          directory = ReceivingDomain.find_by(domain: address.split("@", 2).last, state: "active")
-          raise Unavailable, "receiving domain unavailable" unless directory
-          for_tenant(directory.tenant_key) do |session|
-            session.receive(address, directory) { yield }
+        def receive(recipient:, &block)
+          raise ArgumentError, "persistence block required" unless block
+          in_recipient_tenant(recipient) do |session, address, directory|
+            session.receive(address, directory) do |destination|
+              # Preserve strict callbacks accepted before destinations were yielded.
+              block.lambda? && block.arity.zero? ? block.call : block.call(destination)
+            end
+          end
+        end
+
+        # Lookup only: the host owns persistence and the block's return value.
+        # Verify ingress before calling this API. No ActionMailbox is required.
+        def with_recipient(recipient:)
+          raise ArgumentError, "a block is required" unless block_given?
+          in_recipient_tenant(recipient) do |session, address, directory|
+            session.with_recipient(address, directory) { |destination| yield destination }
           end
-        rescue ::ActiveRecord::RecordNotFound
-          raise Unavailable, "mailbox address unavailable"
         end
 
         def canonical_address(value)
@@ -45,6 +62,17 @@ module Cloudflare
           end
           value.downcase
         end
+
+        private
+
+        def in_recipient_tenant(recipient)
+          address = canonical_address(recipient)
+          directory = ReceivingDomain.find_by(domain: address.split("@", 2).last, state: "active")
+          raise Unavailable, "receiving domain unavailable" unless directory
+          for_tenant(directory.tenant_key) do |session|
+            yield session, address, directory
+          end
+        end
       end
 
       class Session
@@ -100,6 +128,29 @@ module Cloudflare
           activate_address!(address.id, evidence: "Cloudflare address rule provisioned for Worker #{worker_name}")
         end
 
+        # This records the host's verified provider routing decision; it does
+        # not provision Cloudflare DNS/rules or authorize arbitrary From values.
+        def enable_catch_all(address_id, evidence:)
+          context!
+          catch_all_schema!
+          raise ArgumentError, "catch-all route verification evidence is required" if evidence.to_s.strip.empty?
+          Address.transaction do
+            address = Address.where(tenant_key: tenant_key, state: "active").find(address_id)
+            active_mailbox!(address.mailbox_id)
+            active_domain!(address)
+            address.update!(catch_all: true, catch_all_evidence: evidence)
+            address
+          end
+        end
+
+        def disable_catch_all(address_id)
+          context!
+          catch_all_schema!
+          # Disabling is permitted even after suspension; retain the previous
+          # verification evidence for operator inspection.
+          Address.where(tenant_key: tenant_key).find(address_id).tap { |address| address.update!(catch_all: false) }
+        end
+
         def suspend(mailbox_id)
           mailboxes.find(mailbox_id).tap { |mailbox| mailbox.update!(state: "suspended") }
         end
@@ -237,23 +288,56 @@ module Cloudflare
           context!
           ensure_storage_connection! if defined?(::ActionMailbox::InboundEmail)
           Mailbox.transaction do
-            destination = Address.where(tenant_key: tenant_key, address: address, receiving_domain_id: directory.id, state: "active").first
-            raise Unavailable, "mailbox address unavailable" unless destination
-            mailbox = active_mailbox!(destination.mailbox_id)
-            active_domain!(destination)
-            inbound = yield
-            Message.create_or_find_by!(tenant_key: tenant_key, mailbox_id: mailbox.id,
+            destination = resolve_destination(address, directory)
+            inbound = yield destination
+            Message.create_or_find_by!(tenant_key: tenant_key, mailbox_id: destination.mailbox_id,
               inbound_email_id: inbound.id) { |row| row.recipient = address } if inbound
             inbound
           end
         end
 
+        def with_recipient(address, directory)
+          context!
+          yield resolve_destination(address, directory)
+        end
+
         private
 
+        def resolve_destination(address, directory)
+          destination = Address.where(tenant_key: tenant_key, address: address,
+            receiving_domain_id: directory.id).first
+          fallback = destination.nil?
+          if fallback && catch_all_schema_available?
+            destination = Address.where(tenant_key: tenant_key, receiving_domain_id: directory.id,
+              catch_all: true, state: "active").first
+          end
+          # An exact pending/suspended address intentionally reserves its name.
+          # It must never fall through to another mailbox's catch-all.
+          raise Unavailable, "mailbox address unavailable" unless destination&.state == "active"
+          mailbox = active_mailbox!(destination.mailbox_id)
+          active_domain!(destination)
+          Destination.new(tenant_key: tenant_key, mailbox_id: mailbox.id,
+            address_id: destination.id, receiving_domain_id: directory.id,
+            recipient: address, owner_ref: mailbox.owner_ref, catch_all: fallback)
+        rescue ::ActiveRecord::RecordNotFound
+          raise Unavailable, "mailbox address unavailable"
+        end
+
         def context!
           raise ConfigurationError, "mailbox session used outside its tenant context" unless Tenancy.require_context! == tenant_key
         end
 
+        def catch_all_schema_available?
+          Address.connection.column_exists?(Address.table_name, :catch_all) &&
+            Address.connection.column_exists?(Address.table_name, :catch_all_evidence)
+        end
+
+        def catch_all_schema!
+          unless catch_all_schema_available?
+            raise ConfigurationError, "run cloudflare:email:mailboxes:catch_all migrations for this tenant first"
+          end
+        end
+
         def ensure_storage_connection!
           unless defined?(::ActionMailbox::InboundEmail) && ::ActionMailbox::InboundEmail.connection_pool == Mailbox.connection_pool &&
               ::ActiveStorage::Blob.connection_pool == Mailbox.connection_pool

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

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

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

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

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

@@ -0,0 +1,15 @@
+require "rails/engine"
+require "action_controller/railtie"
+
+module Cloudflare
+  module Email
+    module Management
+      class Engine < ::Rails::Engine
+        isolate_namespace Cloudflare::Email::Management
+        config.root = File.expand_path("../../../..", __dir__)
+
+        config.paths["config/routes.rb"] = "lib/cloudflare/email/management/routes.rb"
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,14 @@
+Cloudflare::Email::Management::Engine.routes.draw do
+  get "style.css", to: "styles#show", as: :style
+  root to: "mailboxes#index"
+  resources :mailboxes, only: [:index, :show, :create] do
+    member do
+      post :aliases, action: :add_address
+      post :suspend
+      post :resume
+      get "messages/:message_id", action: :message, as: :message
+      post :mark_read
+      post :archive
+    end
+  end
+end

data/lib/cloudflare/email/management.rb

@@ -0,0 +1,7 @@
+# Explicit opt-in: require this before Rails initializes, then configure the
+# adapter in an initializer. Loading the core gem never mounts this interface.
+require "rails/engine"
+require "cloudflare-email"
+require "cloudflare/email/management/adapter"
+require "cloudflare/email/management/configuration"
+require "cloudflare/email/management/engine"

data/lib/cloudflare/email/provider_metadata.rb

@@ -0,0 +1,77 @@
+require "json"
+require "cloudflare/email/signing"
+
+module Cloudflare
+  module Email
+    # Signed assertions supplied by the forwarding integration, not proof that
+    # the original sender passed SPF/DKIM/DMARC. Never read these from MIME.
+    module ProviderMetadata
+      METADATA_KEY = "cloudflare_email_provider_metadata".freeze
+      MAX_ENCODED_BYTES = 16 * 1024
+      MAX_DEPTH = 8
+      SOURCE = /\A[a-z][a-z0-9_.-]{0,127}\z/
+
+      def self.valid?(value)
+        value.is_a?(Hash) && value.size == 2 && value.key?("data") && value.key?("source") &&
+          value["source"].is_a?(String) && SOURCE.match?(value["source"]) &&
+          value["data"].is_a?(Hash) && json_value?(value, 0)
+      end
+
+      def self.json_value?(value, depth)
+        case value
+        when Hash
+          depth < MAX_DEPTH && value.all? { |key, item| key.is_a?(String) && utf8?(key) && json_value?(item, depth + 1) }
+        when Array
+          depth < MAX_DEPTH && value.all? { |item| json_value?(item, depth + 1) }
+        when String then utf8?(value)
+        when Integer, TrueClass, FalseClass, NilClass then true
+        when Float then value.finite?
+        else false
+        end
+      end
+
+      def self.utf8?(value)
+        value.encode(Encoding::UTF_8).valid_encoding?
+      rescue EncodingError
+        false
+      end
+
+      def self.encode(source:, data:)
+        value = {"source" => source, "data" => data}
+        raise ArgumentError, "invalid provider metadata" unless valid?(value)
+        encoded = Signing.base64url_encode(JSON.generate(value))
+        raise ArgumentError, "provider metadata exceeds size limit" if encoded.bytesize > MAX_ENCODED_BYTES
+        encoded
+      end
+
+      def self.decode(encoded)
+        return unless encoded.is_a?(String) && encoded.bytesize.between?(1, MAX_ENCODED_BYTES)
+        return unless /\A[A-Za-z0-9_-]+\z/.match?(encoded)
+        bytes = Signing.base64url_decode(encoded)
+        return unless Signing.base64url_encode(bytes) == encoded
+        text = bytes.force_encoding(Encoding::UTF_8)
+        return unless text.valid_encoding?
+        value = JSON.parse(text, max_nesting: MAX_DEPTH)
+        value if valid?(value)
+      rescue JSON::ParserError, ArgumentError
+        nil
+      end
+
+      def self.for(inbound_email)
+        metadata = inbound_email.raw_email.blob&.metadata&.fetch(METADATA_KEY, nil)
+        return unless metadata.is_a?(Hash) && metadata["signature_version"] == 3
+        value = metadata.reject { |key, _| key == "signature_version" }
+        value if valid?(value)
+      end
+
+      # Stable receipt identity if JSON object members arrive in another order.
+      def self.canonical(value)
+        case value
+        when Hash then value.keys.sort.to_h { |key| [key, canonical(value[key])] }
+        when Array then value.map { |item| canonical(item) }
+        else value
+        end
+      end
+    end
+  end
+end

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