cloudflare-email 0.1.0

data/lib/cloudflare/email/doctor.rb

@@ -0,0 +1,244 @@
+require "net/http"
+require "json"
+
+module Cloudflare
+  module Email
+    # Diagnostic runner for `bin/rails cloudflare:email:doctor`.
+    # Verifies each layer of configuration independently so a new user can
+    # see exactly which piece is misconfigured.
+    class Doctor
+      OK    = :ok
+      WARN  = :warn
+      FAIL  = :fail
+      SKIP  = :skip
+
+      def self.call(io: $stdout)
+        new(io: io).call
+      end
+
+      def initialize(io: $stdout)
+        @io      = io
+        @results = []
+      end
+
+      def call
+        header
+        check_rails_loaded
+        check_credentials
+        check_api_token
+        check_account_access
+        check_sending_domains
+        check_ingress_secret
+        check_token_split
+        check_action_mailbox_ingress
+        check_delivery_method_registered
+        summary
+        @results.any? { |r| r[:status] == FAIL } ? 1 : 0
+      end
+
+      private
+
+      def header
+        @io.puts "cloudflare-email doctor — v#{Cloudflare::Email::VERSION}"
+        @io.puts ""
+      end
+
+      def check_rails_loaded
+        if defined?(Rails) && Rails.application
+          record("Rails app", OK, "#{Rails.application.class.name} (#{Rails.env})")
+        else
+          record("Rails app", FAIL, "Rails.application not loaded — run via bin/rails")
+        end
+      end
+
+      def check_credentials
+        account_id = credential(:account_id)
+        api_token  = credential(:api_token)
+
+        if account_id.to_s.empty?
+          record("credentials.cloudflare.account_id", FAIL, "missing — run bin/rails credentials:edit")
+        else
+          record("credentials.cloudflare.account_id", OK, account_id)
+        end
+
+        if api_token.to_s.empty?
+          record("credentials.cloudflare.api_token", FAIL, "missing — run bin/rails credentials:edit")
+        else
+          record("credentials.cloudflare.api_token", OK, "#{api_token[0, 8]}...")
+        end
+      end
+
+      def check_api_token
+        token = credential(:api_token)
+        return record("API token valid", SKIP, "no token to test") if token.to_s.empty?
+
+        response = request("GET", "/user/tokens/verify", token: token)
+        if response[:ok] && response[:body].dig("result", "status") == "active"
+          record("API token valid", OK, "active (id: #{response[:body].dig('result', 'id')&.slice(0, 8)}...)")
+        else
+          record("API token valid", FAIL, extract_error(response))
+        end
+      end
+
+      def check_account_access
+        token      = credential(:api_token)
+        account_id = credential(:account_id)
+        return record("Account accessible", SKIP, "missing token or account_id") if token.to_s.empty? || account_id.to_s.empty?
+
+        response = request("GET", "/accounts/#{account_id}", token: token)
+        if response[:ok]
+          record("Account accessible", OK, response[:body].dig("result", "name") || account_id)
+        elsif response[:status] == 403
+          # Narrowly-scoped send-only tokens don't have account read permission;
+          # that's a feature, not a bug. We already confirmed the token is valid.
+          record("Account accessible", OK, "send-scoped token (no account read — this is fine)")
+        else
+          record("Account accessible", FAIL, extract_error(response))
+        end
+      end
+
+      def check_sending_domains
+        token      = credential(:api_token)
+        account_id = credential(:account_id)
+        return record("Sending domains", SKIP, "missing credentials") if token.to_s.empty? || account_id.to_s.empty?
+
+        response = request("GET", "/accounts/#{account_id}/email/sending/domains", token: token)
+        if response[:status] == 403 || response[:status] == 404
+          record("Sending domains", SKIP, "send-scoped token can't list domains (check the dashboard instead)")
+          return
+        end
+
+        unless response[:ok]
+          record("Sending domains", WARN, "could not list: #{extract_error(response)}")
+          return
+        end
+
+        domains = Array(response[:body]["result"])
+        if domains.empty?
+          record("Sending domains", WARN, "no sending domains set up — add one in the dashboard")
+          return
+        end
+
+        verified = domains.select { |d| d["verified"] == true || d["status"] == "verified" }
+        if verified.any?
+          names = verified.map { |d| d["name"] || d["domain"] }.compact.join(", ")
+          record("Sending domains", OK, "#{verified.size} verified (#{names})")
+        else
+          names = domains.map { |d| d["name"] || d["domain"] }.compact.join(", ")
+          record("Sending domains", WARN, "#{domains.size} configured but none verified (#{names})")
+        end
+      end
+
+      def check_ingress_secret
+        require "cloudflare/email/credentials"
+        secret = Cloudflare::Email::Credentials.ingress_secret
+
+        if secret.empty?
+          record("Ingress secret", WARN, "not set — inbound will 401 until you configure it")
+        elsif secret.length < 32
+          record("Ingress secret", WARN, "set but shorter than 32 chars — rotate to a strong random value")
+        else
+          record("Ingress secret", OK, "set (#{secret.length} chars)")
+        end
+      end
+
+      def check_token_split
+        require "cloudflare/email/credentials"
+        if Cloudflare::Email::Credentials.split_tokens?
+          record("Token split", OK, "separate management_token set (good security posture)")
+        else
+          record("Token split", WARN,
+            "single api_token used for runtime + management — consider splitting via CLOUDFLARE_MANAGEMENT_TOKEN " \
+            "(see README 'Tokens')")
+        end
+      end
+
+      def check_action_mailbox_ingress
+        return record("ActionMailbox ingress", SKIP, "ActionMailbox not loaded") unless defined?(ActionMailbox)
+
+        case ActionMailbox.ingress
+        when :cloudflare
+          record("ActionMailbox ingress", OK, ":cloudflare")
+        when nil
+          record("ActionMailbox ingress", WARN, "nil — inbound will 404. Set config.action_mailbox.ingress = :cloudflare")
+        else
+          record("ActionMailbox ingress", WARN, "#{ActionMailbox.ingress.inspect} — not :cloudflare, our controller will 404")
+        end
+      end
+
+      def check_delivery_method_registered
+        return record("Delivery method :cloudflare", SKIP, "ActionMailer not loaded") unless defined?(ActionMailer)
+
+        if ActionMailer::Base.delivery_methods[:cloudflare]
+          record("Delivery method :cloudflare", OK, "registered")
+        else
+          record("Delivery method :cloudflare", FAIL, "not registered — engine failed to load")
+        end
+      end
+
+      def summary
+        @io.puts ""
+        width = @results.map { |r| r[:name].length }.max
+        @results.each do |r|
+          @io.puts "  #{icon(r[:status])}  #{r[:name].ljust(width)}  #{r[:detail]}"
+        end
+        @io.puts ""
+
+        fail_count = @results.count { |r| r[:status] == FAIL }
+        warn_count = @results.count { |r| r[:status] == WARN }
+
+        if fail_count.zero? && warn_count.zero?
+          @io.puts "  Everything looks good."
+        elsif fail_count.zero?
+          @io.puts "  #{warn_count} warning(s). Setup is usable but incomplete."
+        else
+          @io.puts "  #{fail_count} failure(s), #{warn_count} warning(s). Fix failures before sending."
+        end
+        @io.puts ""
+      end
+
+      def record(name, status, detail)
+        @results << { name: name, status: status, detail: detail }
+      end
+
+      def icon(status)
+        case status
+        when OK   then "[ok]  "
+        when WARN then "[warn]"
+        when FAIL then "[fail]"
+        when SKIP then "[skip]"
+        end
+      end
+
+      def credential(key)
+        require "cloudflare/email/credentials"
+        Cloudflare::Email::Credentials.fetch(key)
+      end
+
+      def request(method, path, token:)
+        uri = URI.parse("https://api.cloudflare.com/client/v4#{path}")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.open_timeout = 10
+        http.read_timeout = 10
+
+        req = (method == "GET" ? Net::HTTP::Get : Net::HTTP::Post).new(uri.request_uri)
+        req["Authorization"] = "Bearer #{token}"
+        req["Content-Type"]  = "application/json"
+
+        response = http.request(req)
+        body = JSON.parse(response.body) rescue {}
+        { ok: response.code.to_i.between?(200, 299), status: response.code.to_i, body: body }
+      rescue StandardError => e
+        { ok: false, status: 0, body: { "errors" => [{ "message" => e.message }] } }
+      end
+
+      def extract_error(response)
+        errors = response[:body].is_a?(Hash) ? response[:body]["errors"] : nil
+        return "HTTP #{response[:status]}" unless errors.is_a?(Array) && errors.any?
+        msg = errors.map { |e| e.is_a?(Hash) ? e["message"] : e.to_s }.compact.join("; ")
+        "HTTP #{response[:status]} — #{msg}"
+      end
+    end
+  end
+end

data/lib/cloudflare/email/engine.rb

@@ -0,0 +1,25 @@
+require "rails/engine"
+
+# Register the delivery method at engine load time (not inside an initializer)
+# so the `cloudflare_settings=` accessor exists before Rails' own
+# "action_mailer.set_configs" initializer applies user config.
+ActiveSupport.on_load(:action_mailer) do
+  require "cloudflare/email/delivery_method"
+  add_delivery_method :cloudflare, Cloudflare::Email::DeliveryMethod
+end
+
+module Cloudflare
+  module Email
+    class Engine < ::Rails::Engine
+      isolate_namespace Cloudflare::Email
+
+      initializer "cloudflare-email.routes" do |app|
+        app.routes.append do
+          post "/rails/action_mailbox/cloudflare/inbound_emails",
+               to: "cloudflare/email/ingress#create",
+               as: :rails_cloudflare_inbound_emails
+        end
+      end
+    end
+  end
+end

data/lib/cloudflare/email/error.rb

@@ -0,0 +1,20 @@
+module Cloudflare
+  module Email
+    class Error < StandardError
+      attr_reader :response, :status
+
+      def initialize(message = nil, status: nil, response: nil)
+        super(message)
+        @status   = status
+        @response = response
+      end
+    end
+
+    class ConfigurationError < Error; end
+    class AuthenticationError < Error; end
+    class ValidationError < Error; end
+    class RateLimitError < Error; end
+    class ServerError < Error; end
+    class NetworkError < Error; end
+  end
+end

data/lib/cloudflare/email/provision_catchall_task.rb

@@ -0,0 +1,36 @@
+require "cloudflare/email/task_base"
+require "cloudflare/email/routing_provisioner"
+require "cloudflare/email/worker_deployer"
+
+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.
+    class ProvisionCatchallTask < TaskBase
+      def self.call(domain:, worker_name: nil, io: $stdout)
+        new(io: io, domain: domain, worker_name: worker_name).call
+      end
+
+      protected
+
+      def run
+        require_value!(management_token, "cloudflare.api_token or cloudflare.management_token")
+        require_value!(opts[:domain],    "DOMAIN=in.example.com")
+
+        worker = opts[:worker_name] || Cloudflare::Email::WorkerDeployer.default_script_name
+
+        say "Provisioning catch-all:"
+        say "  Domain: #{opts[:domain]}"
+        say "  Worker: #{worker}"
+        say ""
+
+        provisioner = Cloudflare::Email::RoutingProvisioner.new(api_token: management_token)
+        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."
+      end
+    end
+  end
+end

data/lib/cloudflare/email/provision_route_task.rb

@@ -0,0 +1,34 @@
+require "cloudflare/email/task_base"
+require "cloudflare/email/routing_provisioner"
+require "cloudflare/email/worker_deployer"
+
+module Cloudflare
+  module Email
+    # `bin/rails cloudflare:email:provision_route` — creates a Cloudflare
+    # Email Routing rule binding ADDRESS to the env-scoped ingress Worker.
+    class ProvisionRouteTask < TaskBase
+      def self.call(address:, worker_name: nil, io: $stdout)
+        new(io: io, address: address, worker_name: worker_name).call
+      end
+
+      protected
+
+      def run
+        require_value!(management_token, "cloudflare.api_token or cloudflare.management_token")
+        require_value!(opts[:address],   "ADDRESS=address@domain")
+
+        worker = opts[:worker_name] || Cloudflare::Email::WorkerDeployer.default_script_name
+
+        say "Provisioning Email Routing:"
+        say "  Address: #{opts[:address]}"
+        say "  Worker:  #{worker}"
+        say ""
+
+        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}."
+      end
+    end
+  end
+end

data/lib/cloudflare/email/response.rb

@@ -0,0 +1,61 @@
+module Cloudflare
+  module Email
+    class Response
+      attr_reader :raw, :status
+
+      def initialize(raw, status: 200)
+        @raw    = raw.is_a?(Hash) ? raw : {}
+        @status = status
+      end
+
+      def success?
+        return !!@raw["success"] if @raw.key?("success") && !@raw["success"].nil?
+        @status >= 200 && @status < 300
+      end
+
+      def result
+        @raw["result"].is_a?(Hash) ? @raw["result"] : {}
+      end
+
+      def message_id
+        result["message_id"] ||
+          dig_message_id(result["delivered"]) ||
+          dig_message_id(result["queued"])
+      end
+
+      def delivered
+        Array(result["delivered"])
+      end
+
+      def queued
+        Array(result["queued"])
+      end
+
+      def permanent_bounces
+        Array(result["permanent_bounces"])
+      end
+
+      def errors
+        Array(@raw["errors"])
+      end
+
+      def messages
+        Array(@raw["messages"])
+      end
+
+      def to_h
+        @raw
+      end
+
+      private
+
+      # The API may return delivered/queued as an array of strings (email
+      # addresses) or an array of hashes ({message_id:, to:}).  Handle both.
+      def dig_message_id(arr)
+        return nil unless arr.is_a?(Array)
+        first = arr.first
+        first.is_a?(Hash) ? first["message_id"] : nil
+      end
+    end
+  end
+end

data/lib/cloudflare/email/routing_provisioner.rb

@@ -0,0 +1,220 @@
+require "net/http"
+require "json"
+require "uri"
+
+module Cloudflare
+  module Email
+    # Provision Cloudflare Email Routing rules via API — no dashboard clicks.
+    #
+    # Looks up the zone ID for a domain, enables Email Routing on the zone
+    # (publishing the MX + SPF records Cloudflare needs), and creates/updates
+    # a rule sending mail for a specific address to a given Worker.
+    #
+    # Required API token scopes:
+    #   Zone → Zone → Read          (to look up zone by name)
+    #   Zone → Email Routing → Edit (to enable routing and add rules)
+    #
+    # Usage:
+    #   provisioner = Cloudflare::Email::RoutingProvisioner.new(
+    #     api_token: ENV["CLOUDFLARE_API_TOKEN"],
+    #   )
+    #   provisioner.provision(
+    #     address: "cole@in.example.com",
+    #     worker_name: "cloudflare-email-ingress-production",
+    #   )
+    class RoutingProvisioner
+      API_BASE = "https://api.cloudflare.com/client/v4".freeze
+
+      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  = api_base
+      end
+
+      # High-level: given an address + Worker name, do everything needed to
+      # make that address route to that Worker. Idempotent — running twice
+      # is safe and will update the existing rule rather than duplicate it.
+      def provision(address:, worker_name:)
+        domain   = extract_domain(address)
+        zone_id  = find_zone_id_for(domain)
+        raise Error.new("No Cloudflare zone found for #{domain} — add the domain to your account first") unless zone_id
+
+        enable_routing_if_needed(zone_id)
+        upsert_route(zone_id: zone_id, address: address, worker_name: worker_name)
+      end
+
+      def find_zone_id_for(domain)
+        # Try the exact domain, then walk up parent domains until we find a
+        # Cloudflare zone. Supports subdomains like "in.example.com" routing
+        # to the "example.com" zone.
+        candidates = expand_parent_domains(domain)
+
+        candidates.each do |candidate|
+          result = api_request(:get, "/zones?name=#{URI.encode_www_form_component(candidate)}")
+          zones = Array(result["result"])
+          return zones.first["id"] if zones.any?
+        end
+
+        nil
+      end
+
+      def enable_routing_if_needed(zone_id)
+        # This endpoint requires the "Email Routing Settings" permission group,
+        # which most scoped tokens don't carry. If we can read the setting,
+        # enable when off. If we can't (403), assume the user enabled routing
+        # via the dashboard when they added the subdomain — the subsequent
+        # rule create will fail with a clear error if not.
+        current = raw_api_request(:get, "/zones/#{zone_id}/email/routing")
+        status  = current.code.to_i
+
+        case status
+        when 200
+          body    = parse(current.body)
+          enabled = body.dig("result", "enabled")
+          api_request(:post, "/zones/#{zone_id}/email/routing/enable") unless enabled
+        when 403, 404
+          # Either the token can't read settings or routing isn't set up.
+          # Try to enable optimistically; ignore failure (rule create will
+          # surface a precise error if routing is actually off).
+          attempt = raw_api_request(:post, "/zones/#{zone_id}/email/routing/enable")
+          # Don't fail here even if this also 403s — move on to rule creation.
+        else
+          handle!(current, "GET /zones/#{zone_id}/email/routing")
+        end
+      end
+
+      def upsert_route(zone_id:, address:, worker_name:)
+        existing = find_rule_for(zone_id: zone_id, address: address)
+
+        rule = {
+          name:     "cloudflare-email gem — #{address}",
+          enabled:  true,
+          priority: 0,
+          matchers: [{ field: "to", type: "literal", value: address }],
+          actions:  [{ type: "worker", value: [worker_name] }],
+        }
+
+        if existing
+          api_request(
+            :put,
+            "/zones/#{zone_id}/email/routing/rules/#{existing['id']}",
+            body: rule,
+          )
+        else
+          api_request(
+            :post,
+            "/zones/#{zone_id}/email/routing/rules",
+            body: rule,
+          )
+        end
+      end
+
+      def find_rule_for(zone_id:, address:)
+        result = api_request(:get, "/zones/#{zone_id}/email/routing/rules?per_page=50")
+        rules  = Array(result["result"])
+
+        rules.find do |r|
+          matchers = Array(r["matchers"])
+          matchers.any? { |m| m["field"] == "to" && m["value"] == address }
+        end
+      end
+
+      def list_rules(zone_id)
+        result = api_request(:get, "/zones/#{zone_id}/email/routing/rules?per_page=50")
+        Array(result["result"])
+      end
+
+      # Point the zone's catch-all rule at our Worker. Catch-all matches any
+      # address on the zone that isn't covered by a more specific rule.
+      # Useful for bounce handling, dev subdomains, alias routing.
+      def provision_catch_all(zone_id:, worker_name:)
+        api_request(
+          :put,
+          "/zones/#{zone_id}/email/routing/rules/catch_all",
+          body: {
+            name:     "cloudflare-email gem — catch-all",
+            enabled:  true,
+            matchers: [{ type: "all" }],
+            actions:  [{ type: "worker", value: [worker_name] }],
+          },
+        )
+      end
+
+      def provision_catch_all_for_domain(domain:, worker_name:)
+        zone_id = find_zone_id_for(domain)
+        raise Error.new("No Cloudflare zone found for #{domain}") unless zone_id
+
+        enable_routing_if_needed(zone_id)
+        provision_catch_all(zone_id: zone_id, worker_name: worker_name)
+      end
+
+      private
+
+      def extract_domain(address)
+        if address.include?("@")
+          address.split("@", 2).last
+        else
+          address
+        end
+      end
+
+      # "a.b.c.example.com" → ["a.b.c.example.com", "b.c.example.com", "c.example.com", "example.com"]
+      def expand_parent_domains(domain)
+        parts = domain.split(".")
+        return [domain] if parts.size < 2
+        (0..(parts.size - 2)).map { |i| parts[i..].join(".") }
+      end
+
+      def api_request(method, path, body: nil)
+        response = raw_api_request(method, path, body: body)
+        handle!(response, "#{method.upcase} #{path}")
+        parse(response.body)
+      end
+
+      def raw_api_request(method, path, body: nil)
+        uri  = URI.parse("#{@api_base}#{path}")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = 30
+        http.read_timeout = 60
+
+        klass = {
+          get:    Net::HTTP::Get,
+          post:   Net::HTTP::Post,
+          put:    Net::HTTP::Put,
+          delete: Net::HTTP::Delete,
+        }.fetch(method)
+
+        req = klass.new(uri.request_uri)
+        req["Authorization"] = "Bearer #{@api_token}"
+        req["Accept"]        = "application/json"
+        req["Content-Type"]  = "application/json" if body
+        req.body             = JSON.generate(body) if body
+
+        http.request(req)
+      end
+
+      def handle!(response, context)
+        status = response.code.to_i
+        return if status.between?(200, 299)
+
+        body    = parse(response.body)
+        errors  = body.is_a?(Hash) ? Array(body["errors"]) : []
+        message = errors.map { |e| e.is_a?(Hash) ? e["message"] : e.to_s }.compact.join("; ")
+        message = "HTTP #{status}" if message.empty?
+
+        raise Error.new(
+          "[routing_provisioner] #{context} failed: #{message}",
+          status: status, response: body,
+        )
+      end
+
+      def parse(body)
+        return {} if body.nil? || body.empty?
+        JSON.parse(body)
+      rescue JSON::ParserError
+        { "errors" => [{ "message" => body.to_s[0, 200] }] }
+      end
+    end
+  end
+end