cloudflare-email 0.1.0

data/lib/cloudflare/email/secure_message_id.rb

@@ -0,0 +1,89 @@
+require "json"
+require "cloudflare/email/signing"
+
+module Cloudflare
+  module Email
+    # Signed outbound Message-IDs for reply authentication.
+    #
+    # Sign the outbound Message-ID with HMAC-SHA256. The recipient's reply
+    # naturally carries the signed id in `In-Reply-To:`, which your mailbox
+    # verifies and decodes to recover the original thread state.
+    #
+    # See README's "Signed replies" section for a full usage example.
+    module SecureMessageId
+      InvalidToken = Class.new(Cloudflare::Email::Error)
+
+      DEFAULT_PREFIX  = "msg".freeze
+      DEFAULT_MAX_AGE = 30 * 24 * 60 * 60   # 30 days
+      EPOCH_OFFSET    = Time.utc(2026, 1, 1).to_i.freeze
+
+      class << self
+        # Build a signed Message-ID carrying `payload`. Returns the bare
+        # Message-ID without angle brackets — SMTP/Mail adds them.
+        def encode(payload:, domain:, secret:, prefix: DEFAULT_PREFIX, now: Time.now.to_i)
+          raise ArgumentError, "secret must not be empty" if secret.to_s.empty?
+          raise ArgumentError, "domain must not be empty" if domain.to_s.empty?
+
+          iat_offset = now.to_i - EPOCH_OFFSET
+          raise ArgumentError, "timestamp out of 32-bit range" if iat_offset.negative? || iat_offset >= (1 << 32)
+
+          packed = [iat_offset].pack("N") + JSON.generate(payload)
+          b64    = Signing.base64url_encode(packed)
+          mac    = Signing.hmac_hex(secret, b64)
+
+          "#{prefix}.#{b64}.#{mac}@#{domain}"
+        end
+
+        # Decode a Message-ID produced by encode. Accepts `<bracketed>` form
+        # too. Returns parsed payload or raises InvalidToken.
+        def decode(message_id, secret:, max_age: DEFAULT_MAX_AGE, now: Time.now.to_i)
+          raise InvalidToken, "message-id is empty" if message_id.to_s.empty?
+
+          id = strip_brackets(message_id.to_s).strip
+          local, domain = id.split("@", 2)
+          raise InvalidToken, "missing @ in message-id" unless local && domain
+
+          _prefix, b64, mac = local.split(".", 3)
+          raise InvalidToken, "malformed message-id" unless b64 && mac && !b64.empty? && !mac.empty?
+
+          expected = Signing.hmac_hex(secret, b64)
+          raise InvalidToken, "signature mismatch" unless Signing.secure_compare(expected, mac)
+
+          packed = begin
+            Signing.base64url_decode(b64)
+          rescue StandardError
+            raise InvalidToken, "base64 decode failed"
+          end
+          raise InvalidToken, "truncated packed bytes" if packed.bytesize < 4
+
+          iat_offset   = packed.byteslice(0, 4).unpack1("N")
+          iat          = iat_offset + EPOCH_OFFSET
+          payload_json = packed.byteslice(4..)
+
+          raise InvalidToken, "token expired"                 if now - iat > max_age
+          raise InvalidToken, "token timestamp in the future" if iat - now > 5 * 60
+
+          JSON.parse(payload_json.to_s)
+        rescue JSON::ParserError
+          raise InvalidToken, "payload not valid JSON"
+        end
+
+        # Cheap heuristic — does this look like one of our signed Message-IDs?
+        def match?(message_id, prefix: DEFAULT_PREFIX)
+          id = strip_brackets(message_id.to_s).strip
+          local, domain = id.split("@", 2)
+          return false unless local && domain
+          p, b64, mac = local.split(".", 3)
+          return false unless p && b64 && mac
+          p == prefix && !b64.empty? && mac.match?(/\A[0-9a-f]{64}\z/)
+        end
+
+        private
+
+        def strip_brackets(s)
+          s.start_with?("<") && s.end_with?(">") ? s[1..-2] : s
+        end
+      end
+    end
+  end
+end

data/lib/cloudflare/email/send_test.rb

@@ -0,0 +1,75 @@
+require "cloudflare/email/task_base"
+require "cloudflare/email/client"
+
+module Cloudflare
+  module Email
+    # `bin/rails cloudflare:email:send_test TO=... [FROM=...]` — one-shot
+    # test send via the current Cloudflare Email config.
+    class SendTest < TaskBase
+      def self.call(to:, from: nil, io: $stdout)
+        new(io: io, to: to, from: from).call
+      end
+
+      protected
+
+      def run
+        require_value!(account_id, "cloudflare.account_id")
+        require_value!(api_token,  "cloudflare.api_token")
+        require_value!(opts[:to],  "TO=recipient@example.com")
+
+        sender = opts[:from] || infer_from
+        raise "Missing FROM= and couldn't infer from verified sending domains" if sender.to_s.empty?
+
+        say "Sending test email:"
+        say "  from: #{sender}"
+        say "  to:   #{opts[:to]}"
+        say ""
+
+        client = Cloudflare::Email::Client.new(
+          account_id: account_id, api_token: api_token, retries: 0,
+        )
+
+        response = client.send(
+          from:    sender,
+          to:      opts[:to],
+          subject: "[cloudflare-email test] #{Time.now.iso8601}",
+          text:    "This is a test send from the cloudflare-email gem doctor.",
+          html:    "<p>This is a test send from the <code>cloudflare-email</code> gem doctor.</p>" \
+                   "<p>Sent at <strong>#{Time.now.iso8601}</strong>.</p>",
+        )
+
+        say "  success:   #{response.success?}"
+        say "  delivered: #{response.delivered.inspect}"
+        say "  queued:    #{response.queued.inspect}"           if response.queued.any?
+        say "  bounces:   #{response.permanent_bounces.inspect}" if response.permanent_bounces.any?
+      end
+
+      private
+
+      def infer_from
+        require "net/http"
+        require "json"
+
+        uri  = URI.parse("https://api.cloudflare.com/client/v4/accounts/#{account_id}/email/sending/domains")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.open_timeout = 10
+        http.read_timeout = 10
+
+        req = Net::HTTP::Get.new(uri.request_uri)
+        req["Authorization"] = "Bearer #{api_token}"
+        response = http.request(req)
+        return nil unless response.code.to_i.between?(200, 299)
+
+        domains  = JSON.parse(response.body).dig("result") || []
+        verified = domains.find { |d| d["verified"] == true || d["status"] == "verified" }
+        return nil unless verified
+
+        domain = verified["name"] || verified["domain"]
+        domain.to_s.empty? ? nil : "test@#{domain}"
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/cloudflare/email/signing.rb

@@ -0,0 +1,37 @@
+require "base64"
+require "openssl"
+
+module Cloudflare
+  module Email
+    # Shared cryptographic helpers: HMAC-SHA256, constant-time compare,
+    # base64url encoding. Used by Verification (ingress HMAC) and
+    # SecureMessageId (signed Message-IDs). Keeps every crypto primitive in
+    # one place so the hash algorithm, encoding choice, and compare function
+    # can't drift between call sites.
+    module Signing
+      module_function
+
+      def hmac_hex(secret, data)
+        OpenSSL::HMAC.hexdigest("SHA256", secret, data)
+      end
+
+      def secure_compare(a, b)
+        if defined?(ActiveSupport::SecurityUtils)
+          ActiveSupport::SecurityUtils.secure_compare(a, b)
+        else
+          return false if a.bytesize != b.bytesize
+          OpenSSL.fixed_length_secure_compare(a, b)
+        end
+      end
+
+      def base64url_encode(bytes)
+        Base64.urlsafe_encode64(bytes, padding: false)
+      end
+
+      def base64url_decode(str)
+        padding = (4 - str.length % 4) % 4
+        Base64.urlsafe_decode64(str + ("=" * padding))
+      end
+    end
+  end
+end

data/lib/cloudflare/email/task_base.rb

@@ -0,0 +1,61 @@
+require "cloudflare/email/credentials"
+
+module Cloudflare
+  module Email
+    # Shared scaffolding for `bin/rails cloudflare:email:*` tasks.
+    #
+    # Each task subclass implements `#run` (which raises on missing input or
+    # returns nil/0 on success). The base class wraps that with consistent
+    # credential exposure, error formatting, and exit codes so every task
+    # feels the same to the user.
+    #
+    # Subclasses use `credential(:name)` or the shorthand readers
+    # (`account_id`, `api_token`, `management_token`, `ingress_secret`)
+    # to pull config. Raising any exception from `#run` is converted to
+    # a non-zero exit with a uniformly-formatted error message.
+    class TaskBase
+      def self.call(**kwargs)
+        new(**kwargs).call
+      end
+
+      def initialize(io: $stdout, **opts)
+        @io   = io
+        @opts = opts
+      end
+
+      def call
+        run
+        0
+      rescue Cloudflare::Email::Error => e
+        @io.puts "  ERROR: #{e.message}"
+        @io.puts "  Status: #{e.status}" if e.status
+        1
+      rescue => e
+        @io.puts "  ERROR: #{e.message}"
+        1
+      end
+
+      protected
+
+      attr_reader :io, :opts
+
+      def say(msg = "")
+        @io.puts(msg)
+      end
+
+      def credential(key)
+        Cloudflare::Email::Credentials.fetch(key)
+      end
+
+      def account_id       = Cloudflare::Email::Credentials.account_id
+      def api_token        = Cloudflare::Email::Credentials.api_token
+      def management_token = Cloudflare::Email::Credentials.management_token
+      def ingress_secret   = Cloudflare::Email::Credentials.ingress_secret
+
+      def require_value!(value, label)
+        raise ArgumentError, "Missing #{label}" if value.to_s.empty?
+        value
+      end
+    end
+  end
+end

data/lib/cloudflare/email/verification.rb

@@ -0,0 +1,44 @@
+require "cloudflare/email/signing"
+
+module Cloudflare
+  module Email
+    # HMAC verification for inbound webhook signatures from the bundled
+    # Cloudflare Email Worker. Pure-Ruby and Rails-free so it can be
+    # unit-tested in isolation.
+    #
+    # Worker signs: HMAC-SHA256(secret, "{timestamp}.{raw_body}")
+    # Worker sends:
+    #   X-CF-Email-Timestamp: <unix seconds>
+    #   X-CF-Email-Signature: <hex digest>
+    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:, window: DEFAULT_WINDOW, now: Time.now.to_i)
+        return :bad_signature if blank?(secret) || blank?(body) || blank?(timestamp) || blank?(signature)
+
+        ts = begin
+          Integer(timestamp.to_s, 10)
+        rescue ArgumentError, TypeError
+          return :bad_signature
+        end
+
+        return :stale if (now - ts).abs > window
+
+        expected = Signing.hmac_hex(secret, "#{ts}.#{body}")
+        return :bad_signature unless Signing.secure_compare(expected, signature.to_s)
+
+        :ok
+      end
+
+      def self.sign(secret:, body:, timestamp:)
+        Signing.hmac_hex(secret, "#{timestamp}.#{body}")
+      end
+
+      def self.blank?(v)
+        v.nil? || v.to_s.empty?
+      end
+    end
+  end
+end

data/lib/cloudflare/email/version.rb

@@ -0,0 +1,5 @@
+module Cloudflare
+  module Email
+    VERSION = "0.1.0"
+  end
+end

data/lib/cloudflare/email/worker_deployer.rb

@@ -0,0 +1,183 @@
+require "net/http"
+require "json"
+require "securerandom"
+
+module Cloudflare
+  module Email
+    # Deploys and manages the shipped Cloudflare Email Worker via the
+    # Cloudflare API directly — no wrangler, no Node, no npm required.
+    #
+    # Required API token scopes:
+    #   Account → Workers Scripts → Edit
+    #
+    # Usage:
+    #   deployer = Cloudflare::Email::WorkerDeployer.new(
+    #     account_id: ..., api_token: ...,
+    #   )
+    #   deployer.deploy(script_path: "cloudflare-worker/src/index.js")
+    #   deployer.put_secret("INGRESS_SECRET", "...")
+    #   deployer.put_secret("RAILS_INGRESS_URL", "https://...")
+    class WorkerDeployer
+      SCRIPT_NAME_PREFIX         = "cloudflare-email-ingress".freeze
+      DEFAULT_COMPATIBILITY_DATE = "2026-04-01".freeze
+      API_BASE                   = "https://api.cloudflare.com/client/v4".freeze
+
+      attr_reader :script_name
+
+      # Default Worker name includes the current Rails environment so a dev
+      # tunnel never stomps on the production Worker's RAILS_INGRESS_URL.
+      # Override via `script_name:` for tests or explicit control.
+      def self.default_script_name
+        env = defined?(Rails) && Rails.respond_to?(:env) ? Rails.env.to_s : ENV["RAILS_ENV"].to_s
+        default_script_name_with_env(env)
+      end
+
+      def self.default_script_name_with_env(env)
+        env = "production" if env.to_s.empty?
+        "#{SCRIPT_NAME_PREFIX}-#{env}"
+      end
+
+      def initialize(account_id:, api_token:,
+                     script_name: nil,
+                     compatibility_date: DEFAULT_COMPATIBILITY_DATE,
+                     api_base: API_BASE)
+        script_name ||= self.class.default_script_name
+        raise ArgumentError, "account_id is required" if account_id.to_s.empty?
+        raise ArgumentError, "api_token is required"  if api_token.to_s.empty?
+
+        @account_id         = account_id
+        @api_token          = api_token
+        @script_name        = script_name
+        @compatibility_date = compatibility_date
+        @api_base           = api_base
+      end
+
+      # Uploads/updates the Worker script. Accepts either `script_path:` (a
+      # path to a .js file) or `source:` (the JS source string directly).
+      def deploy(script_path: nil, source: nil)
+        source ||= File.read(script_path) if script_path
+        raise ArgumentError, "must pass script_path: or source:" if source.nil?
+
+        boundary = "----cf-email-#{SecureRandom.hex(16)}"
+        body     = build_multipart(boundary, source)
+
+        request(
+          method: :put,
+          path:   "/accounts/#{@account_id}/workers/scripts/#{@script_name}",
+          body:   body,
+          content_type: "multipart/form-data; boundary=#{boundary}",
+        )
+      end
+
+      # Set/update a Worker secret.
+      def put_secret(name, value)
+        request(
+          method: :put,
+          path:   "/accounts/#{@account_id}/workers/scripts/#{@script_name}/secrets",
+          body:   JSON.generate({ name: name.to_s, text: value.to_s, type: "secret_text" }),
+          content_type: "application/json",
+        )
+      end
+
+      # Delete a Worker secret by name.
+      def delete_secret(name)
+        request(
+          method: :delete,
+          path:   "/accounts/#{@account_id}/workers/scripts/#{@script_name}/secrets/#{name}",
+        )
+      end
+
+      # True if the Worker script already exists.
+      def exists?
+        response = raw_request(
+          method: :get,
+          path:   "/accounts/#{@account_id}/workers/scripts/#{@script_name}",
+        )
+        response.code.to_i == 200
+      end
+
+      # Delete the Worker. Useful for teardown in tests.
+      def delete_script
+        request(
+          method: :delete,
+          path:   "/accounts/#{@account_id}/workers/scripts/#{@script_name}",
+        )
+      end
+
+      private
+
+      def build_multipart(boundary, source)
+        metadata = JSON.generate({
+          main_module:        "index.js",
+          compatibility_date: @compatibility_date,
+        })
+
+        parts = []
+        parts << "--#{boundary}"
+        parts << 'Content-Disposition: form-data; name="metadata"'
+        parts << "Content-Type: application/json"
+        parts << ""
+        parts << metadata
+        parts << "--#{boundary}"
+        parts << 'Content-Disposition: form-data; name="index.js"; filename="index.js"'
+        parts << "Content-Type: application/javascript+module"
+        parts << ""
+        parts << source
+        parts << "--#{boundary}--"
+        # Force binary to avoid encoding-driven header injection by Net::HTTP.
+        (parts.join("\r\n") + "\r\n").force_encoding(Encoding::ASCII_8BIT)
+      end
+
+      def request(method:, path:, body: nil, content_type: "application/json")
+        response = raw_request(method: method, path: path, body: body, content_type: content_type)
+        handle(response, "#{method.upcase} #{path}")
+      end
+
+      def raw_request(method:, path:, body: nil, content_type: "application/json")
+        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 = {
+          put:    Net::HTTP::Put,
+          post:   Net::HTTP::Post,
+          get:    Net::HTTP::Get,
+          delete: Net::HTTP::Delete,
+        }.fetch(method)
+
+        req = klass.new(uri.request_uri)
+        req["Authorization"] = "Bearer #{@api_token}"
+        req["Accept"]        = "application/json"
+        req["Content-Type"]  = content_type if body
+        req.body             = body if body
+
+        http.request(req)
+      end
+
+      def handle(response, context)
+        status = response.code.to_i
+        body   = parse(response.body)
+
+        return body if status.between?(200, 299)
+
+        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(
+          "[worker_deployer] #{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

data/lib/cloudflare-email.rb

@@ -0,0 +1,9 @@
+require "cloudflare/email/version"
+require "cloudflare/email/error"
+require "cloudflare/email/response"
+require "cloudflare/email/signing"
+require "cloudflare/email/credentials"
+require "cloudflare/email/client"
+require "cloudflare/email/secure_message_id"
+
+require "cloudflare/email/engine" if defined?(::Rails::Engine)