cloudflare-email 0.1.0

data/lib/generators/cloudflare/email/install_generator.rb

@@ -0,0 +1,227 @@
+require "rails/generators/base"
+require "securerandom"
+
+module Cloudflare
+  module Email
+    module Generators
+      class InstallGenerator < ::Rails::Generators::Base
+        namespace "cloudflare:email:install"
+
+        source_root File.expand_path("templates", __dir__)
+
+        class_option :inbound, type: :boolean, default: true,
+                     desc: "Set up ActionMailbox ingress + Cloudflare Worker template for inbound mail"
+
+        class_option :worker_dir, type: :string, default: "cloudflare-worker",
+                     desc: "Directory to copy the Cloudflare Worker template into"
+
+        class_option :all_envs, type: :boolean, default: false,
+                     desc: "Also configure action_mailbox.ingress in development.rb and test.rb (not just production.rb)"
+
+        class_option :deploy_worker, type: :boolean, default: nil,
+                     desc: "Deploy the Worker via wrangler after setup (nil = interactive prompt)"
+
+        class_option :scaffold_mailbox, type: :boolean, default: nil,
+                     desc: "Scaffold MainMailbox + catch-all route so inbound has somewhere to land (nil = interactive prompt)"
+
+        def create_initializer
+          template "initializer.rb", "config/initializers/cloudflare_email.rb"
+        end
+
+        def ensure_action_mailbox_installed
+          return unless options[:inbound]
+          return if File.exist?("app/mailboxes/application_mailbox.rb")
+
+          say ""
+          if yes?("ActionMailbox isn't installed yet. Run `bin/rails action_mailbox:install` now? [Y/n]", :green)
+            rails_command "action_mailbox:install", inline: true
+            rails_command "db:migrate",             inline: true
+          else
+            say "  Skipping — run `bin/rails action_mailbox:install` manually before inbound will work.", :yellow
+          end
+        end
+
+        def maybe_scaffold_mailbox
+          return unless options[:inbound]
+          return unless File.exist?("app/mailboxes/application_mailbox.rb")
+
+          if File.exist?("app/mailboxes/main_mailbox.rb")
+            say "  app/mailboxes/main_mailbox.rb already exists — skipping.", :cyan
+            return
+          end
+
+          if active_route?("app/mailboxes/application_mailbox.rb")
+            say "  ApplicationMailbox already has routes — skipping MainMailbox scaffold.", :cyan
+            return
+          end
+
+          should_scaffold = options[:scaffold_mailbox]
+          if should_scaffold.nil?
+            should_scaffold = yes?(
+              "Scaffold a default MainMailbox + catch-all route so inbound has somewhere to land? [Y/n]",
+              :green,
+            )
+          end
+          return unless should_scaffold
+
+          template "main_mailbox.rb", "app/mailboxes/main_mailbox.rb"
+
+          inject_into_class "app/mailboxes/application_mailbox.rb", "ApplicationMailbox" do
+            "  routing :all => :main\n"
+          end
+        end
+
+        def configure_action_mailbox_ingress
+          return unless options[:inbound]
+
+          envs = ["production"]
+          envs += ["development", "test"] if options[:all_envs]
+
+          envs.each do |env|
+            file = "config/environments/#{env}.rb"
+            next unless File.exist?(file)
+            next if File.read(file).include?("action_mailbox.ingress = :cloudflare")
+
+            inject_into_file file,
+              "  config.action_mailbox.ingress = :cloudflare\n",
+              after: /Rails\.application\.configure do\n/
+          end
+        end
+
+        def copy_worker_template
+          return unless options[:inbound]
+
+          worker_src = File.expand_path("../../../../templates/worker", __dir__)
+          directory worker_src, options[:worker_dir]
+        end
+
+        def maybe_deploy_worker
+          return unless options[:inbound]
+
+          should_deploy = options[:deploy_worker]
+          if should_deploy.nil?
+            say ""
+            say "  The Worker can be deployed via the Cloudflare API (pure Ruby, no wrangler/Node)"
+            say "  once you've set cloudflare.account_id and cloudflare.api_token in Rails credentials."
+            say "  Run `bin/rails cloudflare:email:deploy_worker URL=https://yourapp.com#{ingress_path}`"
+            say "  after `bin/rails credentials:edit`."
+            say ""
+            say "  Alternatively, deploy now via wrangler if it's installed locally." if wrangler_installed?
+          end
+
+          if should_deploy && wrangler_installed?
+            wrangler_deploy
+          end
+        end
+
+        def wrangler_deploy
+          @ingress_secret = SecureRandom.hex(32)
+
+          inside options[:worker_dir] do
+            run "npm install --legacy-peer-deps", abort_on_failure: true
+
+            ingress_url = ask("Rails ingress URL? (e.g. https://yourapp.com#{ingress_path})")
+            if ingress_url.to_s.strip.empty?
+              say "  Skipping Worker deploy — no URL supplied. Re-run `wrangler deploy` manually when ready.", :yellow
+              return
+            end
+
+            run_with_stdin("wrangler secret put RAILS_INGRESS_URL", ingress_url.strip)
+            run_with_stdin("wrangler secret put INGRESS_SECRET",    @ingress_secret)
+            run "wrangler deploy", abort_on_failure: false
+          end
+
+          @worker_deployed = true
+        end
+
+        def print_post_install
+          @ingress_secret ||= SecureRandom.hex(32) if options[:inbound]
+
+          say ""
+          say "  cloudflare-email installed.", :green
+          say ""
+          say "  Next steps:"
+          say ""
+          say "  1. Add credentials:"
+          say "       bin/rails credentials:edit"
+          say "     cloudflare:"
+          say "       account_id: <your-account-id>"
+          say "       api_token:  <your-api-token>"
+          if options[:inbound]
+            say "       ingress_secret: #{@ingress_secret}"
+          end
+          say ""
+          say "  2. Verify your setup:"
+          say "       bin/rails cloudflare:email:doctor"
+          say ""
+          say "  3. Send a test email:"
+          say "       TO=you@example.com bin/rails cloudflare:email:send_test"
+          say ""
+
+          if options[:inbound] && !@worker_deployed
+            say "  4. Deploy the Worker (pick one):"
+            say "       # Pure Ruby (recommended — no wrangler/Node required):"
+            say "       bin/rails cloudflare:email:deploy_worker URL=https://yourapp.com#{ingress_path}"
+            say ""
+            say "       # Or via wrangler if you have it installed:"
+            say "       cd #{options[:worker_dir]}"
+            say "       npm install --legacy-peer-deps"
+            say "       wrangler secret put INGRESS_SECRET     # paste #{@ingress_secret[0, 8]}..."
+            say "       wrangler secret put RAILS_INGRESS_URL  # https://yourapp.com#{ingress_path}"
+            say "       wrangler deploy"
+            say ""
+          end
+
+          if options[:inbound]
+            say "  5. For local dev (tunnels cloudflared to your Worker):"
+            say "       bin/rails cloudflare:email:dev"
+            say ""
+            say "  6. In the Cloudflare dashboard:"
+            say "       Email Routing -> Routes -> Send to a Worker -> #{worker_name}"
+            say ""
+            say "  Dashboard deep-links:"
+            say "    API tokens:       https://dash.cloudflare.com/profile/api-tokens"
+            say "    Sending domains:  https://dash.cloudflare.com/?to=/:account/email/sending"
+            say "    Email routing:    https://dash.cloudflare.com/?to=/:account/email/routing"
+            say ""
+            say "  Rotation: to rotate the ingress secret, update cloudflare.ingress_secret"
+            say "  in Rails credentials AND re-run `wrangler secret put INGRESS_SECRET` in"
+            say "  #{options[:worker_dir]}/ with the new value, then redeploy the Worker."
+            say ""
+            say "  Dev/test: by default only production.rb is wired to :cloudflare ingress."
+            say "  Re-run with --all-envs to also configure development.rb and test.rb."
+          end
+          say ""
+        end
+
+        private
+
+        # True if ApplicationMailbox contains any uncommented `routing` call.
+        def active_route?(file)
+          return false unless File.exist?(file)
+          File.readlines(file).any? { |line| line =~ /^\s*routing\s/ }
+        end
+
+        def wrangler_installed?
+          system("command -v wrangler >/dev/null 2>&1")
+        end
+
+        def ingress_path
+          "/rails/action_mailbox/cloudflare/inbound_emails"
+        end
+
+        def worker_name
+          "cloudflare-email-ingress"
+        end
+
+        def run_with_stdin(cmd, input)
+          require "open3"
+          out, err, status = Open3.capture3(cmd, stdin_data: input + "\n")
+          unless status.success?
+            say "  #{cmd} failed: #{err.empty? ? out : err}", :red
+          end
+        end
+      end
+    end
+  end
+end

data/lib/generators/cloudflare/email/templates/initializer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Cloudflare Email configuration.
+#
+# Outbound: ActionMailer delivery method `:cloudflare` is registered automatically.
+# Set settings here or per-environment.
+#
+# Inbound: ActionMailbox ingress is mounted at
+#   /rails/action_mailbox/cloudflare/inbound_emails
+# Set `config.action_mailbox.ingress = :cloudflare` (the install generator
+# does this for production by default) and configure cloudflare.ingress_secret
+# in your Rails credentials.
+
+Rails.application.configure do
+  config.action_mailer.delivery_method = :cloudflare
+  config.action_mailer.cloudflare_settings = {
+    account_id: Rails.application.credentials.dig(:cloudflare, :account_id),
+    api_token:  Rails.application.credentials.dig(:cloudflare, :api_token),
+  }
+end

data/lib/generators/cloudflare/email/templates/main_mailbox.rb

@@ -0,0 +1,32 @@
+# Scaffolded by `bin/rails cloudflare:email:install` as the default landing
+# place for inbound Cloudflare email. Replace the `process` body with your
+# real handling — parse the subject, match the sender, hand off to a job, etc.
+#
+# See https://guides.rubyonrails.org/action_mailbox_basics.html for the full
+# ActionMailbox API (mail is a Mail::Message, inbound_email is the AR record).
+class MainMailbox < ApplicationMailbox
+  def process
+    Rails.logger.info(
+      "[cloudflare-email] inbound received: " \
+      "from=#{mail.from&.first.inspect} " \
+      "to=#{Array(mail.to).inspect} " \
+      "subject=#{mail.subject.inspect} " \
+      "message_id=#{mail.message_id.inspect}"
+    )
+
+    # Example ways to pull content out of the incoming message:
+    #
+    #   mail.from.first              # => "alice@example.com"
+    #   mail.to                      # => ["cole@in.rebulk.com"]
+    #   mail.subject                 # => "Re: agent task"
+    #   mail.body.decoded            # => "text/plain body, decoded"
+    #   mail.html_part&.body&.decoded
+    #   mail.attachments             # => [Mail::Part, ...]
+    #   inbound_email.message_id     # => "<...@mail.gmail.com>"
+    #   inbound_email.raw_email.download  # full RFC822 bytes
+    #
+    # Common next steps:
+    #   YourAgentJob.perform_later(mail.from.first, mail.body.decoded)
+    #   bounce_with BounceMailer.not_recognized(inbound_email) if ignore?
+  end
+end

data/lib/tasks/cloudflare_email.rake

@@ -0,0 +1,45 @@
+namespace :cloudflare do
+  namespace :email do
+    desc "Run diagnostics against your Cloudflare Email setup"
+    task doctor: :environment do
+      require "cloudflare/email/doctor"
+      exit Cloudflare::Email::Doctor.call
+    end
+
+    desc "Send a test email via the current Cloudflare Email config (TO=addr FROM=addr)"
+    task send_test: :environment do
+      require "cloudflare/email/send_test"
+      exit Cloudflare::Email::SendTest.call(to: ENV["TO"], from: ENV["FROM"])
+    end
+
+    desc "Deploy the Worker via Cloudflare API (no wrangler/Node required). URL=https://... sets RAILS_INGRESS_URL"
+    task deploy_worker: :environment do
+      require "cloudflare/email/deploy_worker_task"
+      exit Cloudflare::Email::DeployWorkerTask.call(ingress_url: ENV["URL"])
+    end
+
+    desc "Create Cloudflare Email Routing rule: ADDRESS=addr@domain → env-scoped Worker (WORKER=name to override)"
+    task provision_route: :environment do
+      require "cloudflare/email/provision_route_task"
+      exit Cloudflare::Email::ProvisionRouteTask.call(
+        address:     ENV["ADDRESS"],
+        worker_name: ENV["WORKER"],
+      )
+    end
+
+    desc "Point the zone's catch-all rule at the env-scoped Worker (DOMAIN=in.example.com [WORKER=name])"
+    task provision_catchall: :environment do
+      require "cloudflare/email/provision_catchall_task"
+      exit Cloudflare::Email::ProvisionCatchallTask.call(
+        domain:      ENV["DOMAIN"],
+        worker_name: ENV["WORKER"],
+      )
+    end
+
+    desc "Run a cloudflared tunnel pointed at this Rails app, update the Worker's RAILS_INGRESS_URL, and tail logs"
+    task dev: :environment do
+      require "cloudflare/email/dev_tunnel"
+      Cloudflare::Email::DevTunnel.call(port: ENV.fetch("PORT", "3000").to_i)
+    end
+  end
+end

data/templates/worker/README.md

@@ -0,0 +1,37 @@
+# cloudflare-email-ingress
+
+A Cloudflare Email Worker that forwards inbound mail to a Rails ActionMailbox
+ingress shipped with the [`cloudflare-email`](https://github.com/cole/cloudflare-email)
+gem.
+
+## Deploy
+
+```sh
+npm install
+wrangler secret put INGRESS_SECRET     # same value as cloudflare.ingress_secret in Rails credentials
+wrangler secret put RAILS_INGRESS_URL  # e.g. https://your-app.com/rails/action_mailbox/cloudflare/inbound_emails
+wrangler deploy
+```
+
+Then in the Cloudflare dashboard:
+
+1. **Email Routing → Routes**
+2. Add a route for the address you want to receive on (e.g. `support@yourdomain.com`)
+3. Action: **Send to a Worker** → `cloudflare-email-ingress`
+
+## How it works
+
+For each inbound message, the Worker:
+
+1. Reads the raw RFC822 bytes from `message.raw`.
+2. Computes `HMAC-SHA256(INGRESS_SECRET, "{unix_timestamp}.{raw_body}")`.
+3. POSTs the raw bytes to `RAILS_INGRESS_URL` with:
+   - `Content-Type: message/rfc822`
+   - `X-CF-Email-Timestamp: <unix seconds>`
+   - `X-CF-Email-Signature: <hex digest>`
+4. If the Rails app responds non-2xx, the Worker calls `message.setReject` so
+   Cloudflare returns a delivery failure to the sender (the message is not
+   silently dropped).
+
+The Rails controller verifies the signature in constant time and rejects
+timestamps older than 5 minutes (replay protection).

data/templates/worker/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "cloudflare-email-ingress",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Cloudflare Email Worker that forwards inbound mail to a Rails ActionMailbox ingress (HMAC-signed).",
+  "scripts": {
+    "deploy": "wrangler deploy",
+    "dev": "wrangler dev",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.0",
+    "wrangler": "^4.0.0"
+  }
+}

data/templates/worker/src/index.js

@@ -0,0 +1,73 @@
+/**
+ * Cloudflare Email Worker → Rails ActionMailbox ingress.
+ *
+ * Receives mail via Cloudflare Email Routing, signs the raw RFC822 with
+ * HMAC-SHA256 over "{timestamp}.{raw_body}", and POSTs it to the Rails
+ * ingress controller shipped with the cloudflare-email gem.
+ *
+ * Required environment variables (set via `wrangler secret put` OR the
+ * `cloudflare:email:deploy_worker` rake task shipped with this gem):
+ *
+ *   RAILS_INGRESS_URL   e.g. https://your-app.example.com/rails/action_mailbox/cloudflare/inbound_emails
+ *   INGRESS_SECRET      shared secret (same as cloudflare.ingress_secret in Rails credentials)
+ */
+
+function toHex(buf) {
+  const bytes = new Uint8Array(buf);
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    out += bytes[i].toString(16).padStart(2, "0");
+  }
+  return out;
+}
+
+async function sign(secret, data) {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, data);
+  return toHex(sig);
+}
+
+export default {
+  async email(message, env) {
+    if (!env.RAILS_INGRESS_URL || !env.INGRESS_SECRET) {
+      message.setReject("worker missing RAILS_INGRESS_URL or INGRESS_SECRET");
+      return;
+    }
+
+    const raw = new Uint8Array(await new Response(message.raw).arrayBuffer());
+    const ts = Math.floor(Date.now() / 1000).toString();
+
+    const tsBytes = new TextEncoder().encode(`${ts}.`);
+    const signedPayload = new Uint8Array(tsBytes.length + raw.length);
+    signedPayload.set(tsBytes, 0);
+    signedPayload.set(raw, tsBytes.length);
+
+    const signature = await sign(env.INGRESS_SECRET, signedPayload);
+
+    let res;
+    try {
+      res = await fetch(env.RAILS_INGRESS_URL, {
+        method: "POST",
+        headers: {
+          "Content-Type": "message/rfc822",
+          "X-CF-Email-Timestamp": ts,
+          "X-CF-Email-Signature": signature,
+        },
+        body: raw,
+      });
+    } catch (err) {
+      message.setReject(`upstream fetch failed: ${err.message}`);
+      return;
+    }
+
+    if (!res.ok) {
+      message.setReject(`upstream returned ${res.status}`);
+    }
+  },
+};

data/templates/worker/test/index.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import worker from "../src/index.js";
+
+// Minimal fake EmailMessage implementing the surface the Worker uses.
+function makeMessage(raw: string) {
+  const rawBytes = new TextEncoder().encode(raw);
+  const rejects: string[] = [];
+  return {
+    message: {
+      from: "sender@external.test",
+      to:   "inbox@trial.test",
+      raw:  new ReadableStream({
+        start(c) { c.enqueue(rawBytes); c.close(); },
+      }),
+      rawSize: rawBytes.byteLength,
+      setReject(reason: string) { rejects.push(reason); },
+    },
+    rejects,
+  };
+}
+
+async function verifyHmac(secret: string, ts: string, body: ArrayBuffer, hex: string) {
+  const enc = new TextEncoder();
+  const prefix = enc.encode(`${ts}.`);
+  const signed = new Uint8Array(prefix.length + body.byteLength);
+  signed.set(prefix, 0);
+  signed.set(new Uint8Array(body), prefix.length);
+
+  const key = await crypto.subtle.importKey(
+    "raw",
+    enc.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"],
+  );
+
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(hex.substr(i * 2, 2), 16);
+  }
+
+  return crypto.subtle.verify("HMAC", key, bytes, signed);
+}
+
+describe("cloudflare-email Worker", () => {
+  const RAW = "From: a@b.com\r\nTo: c@d.com\r\nSubject: hi\r\n\r\nBody line.\r\n";
+  const SECRET = "worker-test-secret-abc123";
+  const URL_ = "https://rails.test/rails/action_mailbox/cloudflare/inbound_emails";
+
+  let fetchSpy: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    fetchSpy = vi.fn(async () => new Response("", { status: 200 }));
+    globalThis.fetch = fetchSpy as unknown as typeof fetch;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("POSTs raw MIME with HMAC signature and timestamp", async () => {
+    const env = { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET };
+    const { message } = makeMessage(RAW);
+
+    await worker.email(message as any, env);
+
+    expect(fetchSpy).toHaveBeenCalledOnce();
+    const [url, opts] = fetchSpy.mock.calls[0];
+    expect(url).toBe(URL_);
+    expect(opts.method).toBe("POST");
+    expect(opts.headers["Content-Type"]).toBe("message/rfc822");
+    const ts = opts.headers["X-CF-Email-Timestamp"];
+    const sig = opts.headers["X-CF-Email-Signature"];
+    expect(ts).toMatch(/^\d+$/);
+    expect(sig).toMatch(/^[0-9a-f]{64}$/);
+
+    // Body bytes match the input.
+    const sentBytes = opts.body as Uint8Array;
+    expect(new TextDecoder().decode(sentBytes)).toBe(RAW);
+
+    // And the signature verifies against the input.
+    const ok = await verifyHmac(SECRET, ts, sentBytes.buffer, sig);
+    expect(ok).toBe(true);
+  });
+
+  it("rejects the message when upstream returns non-2xx", async () => {
+    fetchSpy.mockResolvedValueOnce(new Response("server error", { status: 503 }));
+    const env = { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET };
+    const { message, rejects } = makeMessage(RAW);
+
+    await worker.email(message as any, env);
+
+    expect(rejects).toEqual(["upstream returned 503"]);
+  });
+
+  it("rejects the message when RAILS_INGRESS_URL is missing", async () => {
+    const env = { RAILS_INGRESS_URL: "", INGRESS_SECRET: SECRET };
+    const { message, rejects } = makeMessage(RAW);
+
+    await worker.email(message as any, env);
+
+    expect(rejects[0]).toMatch(/missing RAILS_INGRESS_URL/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("rejects the message when INGRESS_SECRET is missing", async () => {
+    const env = { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: "" };
+    const { message, rejects } = makeMessage(RAW);
+
+    await worker.email(message as any, env);
+
+    expect(rejects[0]).toMatch(/missing .*INGRESS_SECRET/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("rejects when the upstream fetch throws", async () => {
+    fetchSpy.mockRejectedValueOnce(new Error("DNS fail"));
+    const env = { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET };
+    const { message, rejects } = makeMessage(RAW);
+
+    await worker.email(message as any, env);
+
+    expect(rejects[0]).toMatch(/upstream fetch failed: DNS fail/);
+  });
+
+  it("signature covers tampered bodies differently", async () => {
+    // Sanity check: two different bodies produce two different signatures.
+    const env = { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET };
+
+    await worker.email(makeMessage(RAW).message as any, env);
+    const sig1 = fetchSpy.mock.calls[0][1].headers["X-CF-Email-Signature"];
+
+    fetchSpy.mockClear();
+    await worker.email(makeMessage(RAW + "tamper").message as any, env);
+    const sig2 = fetchSpy.mock.calls[0][1].headers["X-CF-Email-Signature"];
+
+    expect(sig1).not.toBe(sig2);
+  });
+});

data/templates/worker/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["test/**/*.test.ts"],
+  },
+});

data/templates/worker/wrangler.toml

@@ -0,0 +1,10 @@
+name = "cloudflare-email-ingress"
+main = "src/index.js"
+compatibility_date = "2026-04-01"
+
+# Required secrets (set via `wrangler secret put`):
+#   RAILS_INGRESS_URL  - https://your-rails-app.example.com/rails/action_mailbox/cloudflare/inbound_emails
+#   INGRESS_SECRET     - shared secret matching cloudflare.ingress_secret in Rails credentials
+
+# After deploying, in the Cloudflare dashboard:
+#   Email Routing -> Routes -> "Send to a Worker" -> select cloudflare-email-ingress