cloudflare-email 0.2.0 → 0.4.0

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

data/lib/cloudflare/email/tenancy.rb

@@ -1,78 +1,7 @@
 require "cloudflare/email/error"
-
+require "mailbox_kit/tenancy"
 module Cloudflare
   module Email
-    # An adapter boundary: the host owns tenant discovery and connection switching.
-    # Configure once, before requiring any optional Active Record models.
-    module Tenancy
-      CONTEXT_KEY = :cloudflare_email_tenant_key
-
-      class << self
-        def configure(base_class:, switch:, current:)
-          raise ConfigurationError, "configure tenancy before loading Cloudflare Email models" if @models_loaded
-          raise ConfigurationError, "tenancy is already configured" if enabled?
-          unless base_class.is_a?(Class) && base_class.respond_to?(:abstract_class?) && base_class.abstract_class?
-            raise ConfigurationError, "base_class must be an abstract Active Record class"
-          end
-          unless switch.respond_to?(:call) && current.respond_to?(:call)
-            raise ConfigurationError, "switch and current must be callable"
-          end
-
-          @base_class, @switch, @current = base_class, switch, current
-          self
-        end
-
-        def enabled?
-          !@switch.nil?
-        end
-
-        def model_base(default)
-          @models_loaded = true
-          @base_class || default
-        end
-
-        def current_key
-          Thread.current[CONTEXT_KEY]
-        end
-
-        # Only trusted host integration code should use this to capture new work.
-        # Model access and persisted job deserialization still require explicit
-        # gem context; the adapter must not invent a default tenant here.
-        def host_current_key
-          return unless enabled?
-          key = @current.call
-          normalize_key(key) unless key.nil?
-        end
-
-        def normalize_key(key)
-          unless key.is_a?(String) && !key.empty? && key == key.strip && !key.match?(/[[:cntrl:]]/)
-            raise ConfigurationError, "tenant key must be a nonempty string without surrounding whitespace or control characters"
-          end
-          key.dup.freeze
-        end
-
-        def require_context!
-          key = current_key
-          raise ConfigurationError, "an explicit Cloudflare Email tenant context is required" unless key
-          if enabled? && @current.call != key
-            raise ConfigurationError, "host database tenant does not match Cloudflare Email tenant context"
-          end
-          key
-        end
-
-        def with(key)
-          key = normalize_key(key)
-          previous = current_key
-          run = proc do
-            Thread.current[CONTEXT_KEY] = key
-            require_context!
-            yield
-          ensure
-            Thread.current[CONTEXT_KEY] = previous
-          end
-          enabled? ? @switch.call(key, &run) : run.call
-        end
-      end
-    end
+    Tenancy = MailboxKit::Tenancy
   end
 end

data/lib/cloudflare/email/tenant_job_context.rb

@@ -1,90 +1,7 @@
 require "cloudflare/email/tenancy"
-
+require "mailbox_kit/tenant_job_context"
 module Cloudflare
   module Email
-    # Opt in with `prepend Cloudflare::Email::TenantJobContext` on jobs whose
-    # arguments or work reference tenant records. Queue payloads must be trusted.
-    module TenantJobContext
-      PAYLOAD_KEY = "cloudflare_email_tenant_key".freeze
-
-      def serialize
-        key = cloudflare_email_job_tenant_key
-        return super unless key
-        Tenancy.with(key) do
-          payload = super
-          verify_cloudflare_email_host_tenant!(key, payload["tenant"])
-          payload.merge(PAYLOAD_KEY => key)
-        end
-      end
-
-      def deserialize(job_data)
-        # Bind before super: host job integrations may deserialize model arguments
-        # eagerly. Never infer a missing tenant from the worker's ambient context.
-        if !job_data.key?(PAYLOAD_KEY) && cloudflare_email_optional_job_context?
-          @cloudflare_email_job_tenant_key = nil
-          return super
-        end
-        @cloudflare_email_job_tenant_key = Tenancy.normalize_key(job_data[PAYLOAD_KEY])
-        verify_cloudflare_email_host_tenant!(@cloudflare_email_job_tenant_key, job_data["tenant"])
-        Tenancy.with(@cloudflare_email_job_tenant_key) { super }
-      end
-
-      def perform_now
-        # Active Job resolves GlobalIDs before around_perform, so that callback
-        # cannot safely implement database tenant selection.
-        key = cloudflare_email_job_tenant_key
-        return super unless key
-        if defined?(::ActiveRecord::Tenanted::Job) && respond_to?(:tenant)
-          verify_cloudflare_email_host_tenant!(key, tenant)
-        end
-        Tenancy.with(key) { super }
-      end
-
-      def self.install_framework_jobs!
-        if defined?(::ActionMailbox)
-          %i[RoutingJob IncinerationJob].each do |name|
-            next unless ::ActionMailbox.const_defined?(name)
-            klass = ::ActionMailbox.const_get(name)
-            klass.define_singleton_method(:cloudflare_email_optional_job_context?) { !Tenancy.enabled? }
-            klass.prepend(self) unless klass.ancestors.include?(self)
-          end
-        end
-        if defined?(::ActiveStorage)
-          %i[BaseJob AnalyzeJob PurgeJob MirrorJob TransformJob PreviewImageJob].each do |name|
-            next unless ::ActiveStorage.const_defined?(name)
-            klass = ::ActiveStorage.const_get(name)
-            klass.define_singleton_method(:cloudflare_email_optional_job_context?) { !Tenancy.enabled? }
-            klass.prepend(self) unless klass.ancestors.include?(self)
-          end
-        end
-      end
-
-      private
-
-      def cloudflare_email_job_tenant_key
-        # Once serialized/deserialized, retries retain their original tenant even
-        # if re-enqueued from a different tenant or outside a tenant context.
-        return @cloudflare_email_job_tenant_key if instance_variable_defined?(:@cloudflare_email_job_tenant_key)
-        return nil if cloudflare_email_optional_job_context? && !Tenancy.current_key
-        # Native uploads/mailbox work may originate in the host's own with_tenant
-        # block. Framework jobs can capture that trusted context on first use.
-        # deserialize never takes this path for missing persisted metadata.
-        if !Tenancy.current_key && self.class.respond_to?(:cloudflare_email_optional_job_context?)
-          key = Tenancy.host_current_key
-          return @cloudflare_email_job_tenant_key = key if key
-        end
-        @cloudflare_email_job_tenant_key = Tenancy.require_context!
-      end
-
-      def cloudflare_email_optional_job_context?
-        self.class.respond_to?(:cloudflare_email_optional_job_context?) && self.class.cloudflare_email_optional_job_context?
-      end
-
-      def verify_cloudflare_email_host_tenant!(key, host_key)
-        if host_key && host_key != key
-          raise ConfigurationError, "job host tenant conflicts with Cloudflare Email tenant context"
-        end
-      end
-    end
+    TenantJobContext = MailboxKit::TenantJobContext
   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.4.0"
   end
 end