cloudflare-email 0.3.0 → 0.4.0

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/version.rb

@@ -1,5 +1,5 @@
 module Cloudflare
   module Email
-    VERSION = "0.3.0"
+    VERSION = "0.4.0"
   end
 end

data/lib/cloudflare-email.rb

@@ -1,3 +1,9 @@
+require "mailbox-kit"
+module Cloudflare
+  module Email
+    Mailboxes = MailboxKit::Mailboxes
+  end
+end
 require "cloudflare/email/version"
 require "cloudflare/email/error"
 require "cloudflare/email/response"

data/lib/generators/cloudflare/email/mailboxes/templates/create_cloudflare_email_mailboxes.rb

@@ -40,6 +40,7 @@ class CreateCloudflareEmailMailboxes < ActiveRecord::Migration[7.1]
       t.timestamps
     end
     add_index :cloudflare_email_mailbox_messages, [:mailbox_id, :inbound_email_id], unique: true, name: "idx_cf_email_mailbox_inbound"
+    add_index :cloudflare_email_mailbox_messages, :inbound_email_id, name: "idx_cf_email_message_inbound"
     add_index :cloudflare_email_mailbox_messages, [:tenant_key, :mailbox_id, :archived_at, :id], name: "idx_cf_email_mailbox_inbox"
 
     create_table :cloudflare_email_mailbox_outbound_messages do |t|

data/lib/generators/cloudflare/email/mailboxes/templates/create_cloudflare_email_receiving_domains.rb

@@ -3,7 +3,7 @@ class CreateCloudflareEmailReceivingDomains < ActiveRecord::Migration[7.1]
     create_table :cloudflare_email_receiving_domains do |t|
       t.string :domain, null: false
       t.string :tenant_key, null: false
-      t.string :account_id, null: false
+      t.string :account_id # Required by the sending adapter only.
       t.string :state, null: false, default: "pending"
       t.boolean :sending_enabled, null: false, default: false
       t.text :provisioning_evidence

data/templates/deploy-to-cloudflare/README.md

@@ -38,20 +38,40 @@ cron are present. Keep the bucket private with no lifecycle rule expiring
 
 ## 3. Connect an email address
 
+**Choose your address shape:** `acme@in.example.com` on one receiving domain,
+or `invoices@acme.in.example.com` with dynamic organization subdomains.
+Use the [shared domain setup guide](docs/domain-setup.md) for the setup worksheet,
+Cloudflare DNS/routing steps, cited Rebulk example, and verification commands.
+The same Worker serves both; there is no per-organization Worker allowlist.
+
 In Cloudflare, enable Email Routing for the intended receiving domain/subdomain
 and complete its required DNS setup. Add an Email Routing rule for your receiving
-address with **Send to a Worker**, selecting the Worker you just deployed.
+address with **Send to a Worker**, selecting the Worker you just deployed. For
+many local parts, configure the intended domain's catch-all to this Worker once.
 The button does not change your MX records, provision addresses in Rails, or
 replace your existing mailbox provider. Use a receiving subdomain when your apex
 domain's email belongs to Google Workspace or Microsoft 365.
 
 If using the gem's managed mailboxes, register the receiving mailbox/address in
 Rails too. Tenant support and domain catch-all receiving remain explicit choices.
+After verifying a dynamic namespace as described in the guide, register new
+organization domains in Rails without routinely adding provider rules per org.
+Wildcard DNS behavior must be verified on your Cloudflare account; the guide
+distinguishes working Rebulk evidence from Cloudflare's explicit onboarding docs.
 Outbound Email Sending credentials and delivery-event subscriptions are separate
 from this inbound Worker setup.
 
 ## 4. Verify and operate
 
+For dynamic organization subdomains, start with the read-only DNS check:
+
+```sh
+npm run check:subdomains -- --base in.example.com --labels acme,globex
+```
+
+It checks named and fresh labels without API credentials or configuration changes.
+It reports DNS observations only; finish with the real-email checks below.
+
 Send to the configured address and verify that Rails retains and routes it.
 In staging, stop Rails, send another message, confirm it remains in R2, restore
 Rails, and confirm one inbox record and removal of the pending object. Verify a

data/templates/deploy-to-cloudflare/docs/domain-setup.md

@@ -0,0 +1,198 @@
+# Set up once, create mailboxes in Rails
+
+Use the same Worker for either address shape:
+
+| Pattern | Example | What changes when a customer joins |
+| --- | --- | --- |
+| One receiving domain | `acme@in.example.com` | Create a mailbox/address in Rails |
+| Organization subdomains | `invoices@acme.in.example.com` | Register the exact organization domain and its mailboxes in Rails, within your verified receiving namespace |
+
+Neither pattern needs a recipient allowlist in the Worker. Rails owns accepted
+addresses and organization membership. Database multi-tenancy remains optional.
+The [Rails hello-world template](https://github.com/cole-robertson/cloudflare-email-rails-starter)
+demonstrates the first pattern with a normal SQLite database and generated login.
+
+## What is verified, and what Cloudflare documents
+
+**Rebulk's existing deployment uses the second pattern:**
+`<site>@<organization>.rebulk.com`, wildcard MX, a catch-all Worker rule, and Rails
+organization/mailbox lookup. New organizations do not need a Worker enrollment
+list or a routine per-organization Cloudflare approval. Its September 2026
+rehearsal checked exact-domain public MX answers and archived SMTP-envelope
+delivery evidence, alongside the global catch-all rule. The apex keeps its
+separate mail provider. Sources (Rebulk repository access required):
+
+- [Worker architecture and organization setup](https://github.com/Rebulk/rebulk-system/blob/1cc26e0076ba0e9157e89f5879604df8c94430bc/cloudflare/README.md).
+- [Wildcard MX observations and limits of zone-level API evidence](https://github.com/Rebulk/rebulk-system/blob/1cc26e0076ba0e9157e89f5879604df8c94430bc/docs/cloudflare-mailbox-onboarding-rehearsal-2026-09-12.md).
+
+This is deployment evidence, not a Cloudflare-wide service guarantee. Cloudflare's
+[subdomain onboarding guide](https://developers.cloudflare.com/email-service/configuration/subdomains/)
+describes adding subdomains explicitly and currently lists a 30-domain combined
+Routing/Sending limit. It does not document arbitrary wildcard Email Routing as
+a way to bypass that limit. Cloudflare separately documents
+[wildcard DNS and exact-record precedence](https://developers.cloudflare.com/dns/manage-dns-records/reference/wildcard-dns-records/).
+Working wildcard DNS alone does not establish Email Routing acceptance. If your
+account does not accept unlisted subdomains, use documented explicit onboarding
+within its limits, or the single-domain pattern. Do not assume that an existing
+Rebulk setup proves a fresh account's behavior.
+
+A fresh [public DNS observation](https://github.com/cole-robertson/cloudflare-email/blob/main/docs/verification/2026-09-13-wildcard-dns.json)
+also records Cloudflare MX answers for `test.rebulk.com` and two random subdomains
+without creating DNS records or adding those labels in Cloudflare. That report
+is public and deliberately marks `delivery_verified: false`; no email was sent
+by this DNS-only check.
+
+## 1. Fill in your setup worksheet
+
+Use a dedicated receiving namespace when the apex already serves Workspace or
+Microsoft 365. Example values:
+
+| Setting | Your example value |
+| --- | --- |
+| Cloudflare zone | `example.com` |
+| Receiving base | `in.example.com` |
+| Organization domain | `acme.in.example.com` |
+| Worker | `cloudflare-email-ingress` |
+| Rails ingress URL | `https://app.example.com/rails/action_mailbox/cloudflare/inbound_emails` |
+| Shared ingress secret | Generate with `openssl rand -hex 32`; save privately in Rails and the Worker |
+
+Keep staging and production Workers, buckets, queues, secrets, and receiving
+namespaces separate. The standalone deploy-button template takes one environment
+per copy; the regular CLI template uses `--env production` or another explicit env.
+
+## 2. Deploy the shared infrastructure
+
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cole-robertson/cloudflare-email/tree/main/templates/deploy-to-cloudflare)
+
+Deploy Rails with gem 0.3+ first. The button copies the standalone Worker and
+prompts for `RAILS_INGRESS_URL` and `INGRESS_SECRET`. Its configuration includes
+private R2 storage, a Queue producer/consumer, once-per-minute recovery, and logs.
+Cloudflare documents [automatic R2/Queue provisioning and secret prompts](https://developers.cloudflare.com/workers/platform/deploy-buttons/).
+The button does not create email DNS, claim a domain, or register Rails mailboxes.
+
+## 3. Connect DNS and the Worker once
+
+For **one domain**, follow Cloudflare's documented
+[Email Routing onboarding](https://developers.cloudflare.com/email-service/get-started/route-emails/)
+and configure its [catch-all action](https://developers.cloudflare.com/email-service/configuration/email-routing-addresses/#catch-all-rule)
+as **Send to a Worker**, selecting your deployed Worker. This avoids one provider
+rule per local part. Review the actual zone/domain scope and any explicit rules
+that take precedence before saving.
+
+For a **Rebulk-style dynamic namespace**, first establish receiving on your account
+and retain the exact MX targets/priorities assigned by Cloudflare. Then, when
+reproducing and verifying wildcard receiving, the DNS template is:
+
+| DNS type | Name in zone `example.com` | Value |
+| --- | --- | --- |
+| MX | `*.in` | Each Cloudflare-assigned receiving MX target, with its assigned priority |
+
+Create one record per assigned target. Do not invent MX targets, point MX at a
+Worker URL, or replace the apex's existing MX records. Complete the service's
+other required DNS records through its onboarding instructions; do not blindly
+duplicate SPF records. Inspect the account's catch-all **Send to a Worker** rule
+and verify that it actually handles your intended namespace. A Cloudflare Worker
+HTTP route such as `*.example.com/*` is unrelated to email routing.
+
+An explicit DNS name can stop wildcard inheritance **even if its record is TXT
+or A rather than MX**. For example, an existing `acme.in.example.com` record may
+require its own receiving MX records. Test exact customer names as well as fresh
+ones. A wildcard also does not supply MX for the receiving base itself.
+
+## 4. Check without modifying infrastructure
+
+From either current Worker template, run:
+
+```sh
+npm run check:subdomains -- --base in.example.com --labels acme,globex
+```
+
+This requires only Node and DNS access, not a Cloudflare API key. It resolves MX
+for your chosen labels plus two fresh random labels. DNS lookups have bounded
+timeouts. JSON output distinguishes observed Cloudflare MX, other/missing MX, and
+lookup uncertainty. Exit zero means only that all queried names resolved to
+Cloudflare MX; `delivery_verified` remains false. Compare returned targets with
+your account's assigned targets. Existing explicit records can explain differences.
+The command ships in the repository templates; gem 0.3.0's already-published
+template predates it, so refresh your template copy to use it.
+
+For provider rule inspection, the gem also offers:
+
+```sh
+bin/rails cloudflare:email:check_route \
+  ADDRESS=invoices@acme.in.example.com \
+  WORKER_NAME=cloudflare-email-ingress \
+  ACCOUNT_ID=your-cloudflare-account-id
+```
+
+See [diagnostic credentials and limits](https://github.com/cole-robertson/cloudflare-email/blob/main/docs/routing-diagnostics.md).
+That diagnostic inspects exact-domain configured records; it does not resolve
+wildcard DNS inheritance. A working inherited-MX setup can therefore report
+missing exact records. Keep public DNS, provider rule inspection, and actual
+delivery evidence separate; do not force every organization through Cloudflare
+onboarding merely to make that diagnostic green.
+
+## 5. Prove the dynamic path before adopting it
+
+Use two new organization labels that have not been added individually in the
+Cloudflare dashboard:
+
+1. Check their public MX answers with the command above.
+2. Through trusted provisioning code, register both **exact** domains in Rails,
+   each against the correct stable organization key. Create a test mailbox for
+   each. Record your independently checked configuration evidence and activate
+   those test addresses so the gem can receive the verification messages.
+3. Send real email to both addresses from an external mailbox. Confirm the
+   Worker receives each, Rails retains the original message, and each appears
+   only in the correct organization's inbox. Record the message IDs and result.
+4. Repeat with a newly generated label without changing Cloudflare. If delivery
+   fails before the Worker, resolve the Cloudflare acceptance/onboarding issue;
+   changing Rails cannot fix a provider SMTP rejection.
+5. Rehearse Rails being unavailable, then verify retained R2 mail drains after
+   recovery without duplicate app records. Follow the
+   [durable recovery guide](https://github.com/cole-robertson/cloudflare-email/blob/main/templates/worker/docs/durable-inbound.md).
+
+These are deliberate test addresses; no real-email test is sent by the DNS checker.
+Successful tests establish evidence for your receiving namespace, not a guarantee
+that every future DNS change or provider policy will preserve it.
+
+## 6. Create organizations in Rails
+
+Once your namespace policy is verified, use the same gem APIs on organization
+creation. For example, from trusted app code after authorizing the organization:
+
+```ruby
+registry = Cloudflare::Email::Mailboxes
+organization_key = "organization-123" # Trusted stable app identity, not request input.
+domain = registry.register_domain(
+  domain: "acme.in.example.com",
+  tenant_key: organization_key,
+  account_id: Cloudflare::Email::Credentials.account_id
+)
+registry.activate_domain!(domain.id, evidence: verified_namespace_evidence)
+registry.for_tenant(organization_key) do |inboxes|
+  mailbox = inboxes.create(name: "Invoices", address: "invoices@acme.in.example.com",
+    owner_ref: "Organization:123")
+  inboxes.activate_address!(inboxes.addresses(mailbox.id).first.id,
+    evidence: verified_namespace_evidence)
+end
+```
+
+`verified_namespace_evidence` is your stored operator evidence from the setup and
+delivery checks, not a hard-coded claim of success. Make provisioning idempotent
+in your app, validate/reserve slugs, and resolve organization identity from trusted
+records. The gem stores exact domain registrations; it does not accept a `*`
+domain registration or silently authorize an arbitrary recipient from a web form.
+The management engine must obtain allowed domains from your host adapter. The
+hello-world starter intentionally stays single-domain; this recipe is the next
+step for an organization-aware app.
+
+A **Cloudflare routing catch-all** gets mail to the Worker. The gem's optional
+**mailbox catch-all** decides whether unknown local parts enter a mailbox. They
+are separate. Without the latter, unknown/suspended recipients return non-2xx and
+remain in durable pending storage until resolved. Monitor that backlog.
+
+Receiving on dynamic domains does not authorize sending from them. Cloudflare
+[Email Sending onboarding](https://developers.cloudflare.com/email-service/configuration/subdomains/#add-a-subdomain-to-email-sending)
+is separate; keep a verified shared sending domain unless you have explicitly
+onboarded the customer sending domain.

data/templates/deploy-to-cloudflare/package.json

@@ -11,6 +11,7 @@
     "deploy": "wrangler deploy",
     "dev": "wrangler dev",
     "check": "wrangler deploy --dry-run",
+    "check:subdomains": "node scripts/check-subdomains.mjs",
     "test": "vitest run"
   },
   "devDependencies": {

data/templates/deploy-to-cloudflare/scripts/check-subdomains.mjs

@@ -0,0 +1,54 @@
+// Read-only public DNS check. No Cloudflare credentials or configuration writes.
+import { Resolver } from "node:dns/promises";
+import { randomBytes } from "node:crypto";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+
+const labelPattern = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+
+export async function checkSubdomains({ base, labels = [] }, lookup, randomLabel = () => `cf-probe-${randomBytes(8).toString("hex")}`) {
+  base = String(base || "").trim().toLowerCase();
+  if (base.length > 220 || base.split(".").length < 2 || !base.split(".").every(label => labelPattern.test(label))) {
+    throw new Error("Provide a DNS base such as in.example.com, without @, a scheme, or *.");
+  }
+  if (labels.length > 10 || !labels.every(label => labelPattern.test(label) && `${label}.${base}`.length <= 253)) {
+    throw new Error("Provide at most 10 comma-separated single-label subdomains, such as acme,globex.");
+  }
+  const probes = [randomLabel(), randomLabel()];
+  const names = [...new Set([...labels, ...probes])];
+  const checks = await Promise.all(names.map(async label => {
+    const domain = `${label}.${base}`;
+    try {
+      const mx = (await lookup(domain)).map(record => ({ priority: record.priority, exchange: record.exchange.toLowerCase().replace(/\.$/, "") }));
+      const cloudflare = mx.length > 0 && mx.every(record => record.exchange.endsWith(".mx.cloudflare.net"));
+      return { domain, fresh_probe: probes.includes(label), status: cloudflare ? "cloudflare_mx_observed" : "other_or_missing_mx", mx };
+    } catch (error) {
+      return { domain, fresh_probe: probes.includes(label), status: "unknown", reason: error.code || "DNS_LOOKUP_FAILED" };
+    }
+  }));
+  return {
+    checked_at: new Date().toISOString(),
+    base, dns_observation: checks.every(check => check.status === "cloudflare_mx_observed") ? "cloudflare_mx_observed_for_all_names" : "needs_attention",
+    delivery_verified: false, checks,
+    next_step: "Inspect the catch-all Worker rule, register two exact domains/mailboxes in Rails, and send real test emails. MX answers do not verify account ownership, Email Routing acceptance, Worker delivery, or Rails persistence."
+  };
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  try {
+    const { values } = parseArgs({ options: { base: { type: "string" }, labels: { type: "string" }, help: { type: "boolean" } } });
+    if (values.help) {
+      console.log("npm run check:subdomains -- --base in.example.com [--labels acme,globex]\nRead-only DNS observations, including two fresh labels. This does not verify email delivery.");
+    } else {
+      const resolver = new Resolver({ timeout: 2000, tries: 1 });
+      const labels = values.labels ? values.labels.split(",").map(label => label.trim().toLowerCase()) : [];
+      const report = await checkSubdomains({ base: values.base, labels }, domain => resolver.resolveMx(domain));
+      console.log(JSON.stringify(report, null, 2));
+      if (report.dns_observation === "needs_attention") process.exitCode = 1;
+    }
+  } catch (error) {
+    console.error(error.message);
+    console.error("Usage: npm run check:subdomains -- --base in.example.com [--labels acme,globex]");
+    process.exitCode = 1;
+  }
+}

data/templates/deploy-to-cloudflare/test/subdomains.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect, vi } from "vitest";
+import { checkSubdomains } from "../scripts/check-subdomains.mjs";
+
+function probes() {
+  let id = 0;
+  return () => `fresh-${++id}`;
+}
+const cloudflare = [{ priority: 10, exchange: "route1.mx.cloudflare.net" }];
+
+describe("subdomain setup DNS observations", () => {
+  it("checks chosen exact names plus fresh labels without claiming delivery", async () => {
+    const lookup = vi.fn(async () => cloudflare);
+    const report = await checkSubdomains({ base: "in.example.com", labels: ["acme"] }, lookup, probes());
+    expect(lookup.mock.calls.map(call => call[0])).toEqual(["acme.in.example.com", "fresh-1.in.example.com", "fresh-2.in.example.com"]);
+    expect(report.dns_observation).toBe("cloudflare_mx_observed_for_all_names");
+    expect(report.delivery_verified).toBe(false);
+  });
+
+  it("reports an exact-name exception even when fresh probes resolve", async () => {
+    const report = await checkSubdomains({ base: "in.example.com", labels: ["acme"] }, async domain => {
+      if (domain.startsWith("acme.")) throw Object.assign(new Error("no answer"), { code: "ENODATA" });
+      return cloudflare;
+    }, probes());
+    expect(report.dns_observation).toBe("needs_attention");
+    expect(report.checks[0].status).toBe("unknown");
+  });
+
+  it.each([
+    { mx: [] }, { mx: [{ priority: 0, exchange: "." }] },
+    { mx: [{ priority: 10, exchange: "mx.example.com" }] },
+    { mx: [...cloudflare, { priority: 5, exchange: "mx.other.test" }] }
+  ])("does not accept absent, null, foreign or mixed MX: $mx", async ({ mx }) => {
+    const report = await checkSubdomains({ base: "in.example.com" }, async () => mx, probes());
+    expect(report.dns_observation).toBe("needs_attention");
+  });
+
+  it("preserves DNS timeout uncertainty", async () => {
+    const report = await checkSubdomains({ base: "in.example.com" }, async () => { throw Object.assign(new Error("timeout"), { code: "ETIMEOUT" }); }, probes());
+    expect(report.checks.every(check => check.status === "unknown")).toBe(true);
+    expect(report.delivery_verified).toBe(false);
+  });
+
+  it("rejects malformed domains and nested labels before DNS", async () => {
+    const lookup = vi.fn();
+    for (const base of ["*.example.com", "https://example.com", "a@b.com", "localhost", "a..com"]) {
+      await expect(checkSubdomains({ base }, lookup)).rejects.toThrow();
+    }
+    await expect(checkSubdomains({ base: "example.com", labels: ["nested.acme"] }, lookup)).rejects.toThrow();
+    expect(lookup).not.toHaveBeenCalled();
+  });
+});

data/templates/worker/README.md

@@ -6,6 +6,12 @@ gem.
 
 ## Deploy
 
+Choose a single receiving domain or dynamic organization subdomains using the
+[domain setup worksheet and cited examples](docs/domain-setup.md). Once your
+receiving namespace is verified, new mailboxes can be created in Rails without
+editing a Worker recipient list. `npm run check:subdomains -- --base in.example.com`
+checks public MX for fresh names; it does not claim live delivery verification.
+
 For a guided dashboard deployment that provisions resources and prompts for
 secrets, use the [Deploy to Cloudflare template](../deploy-to-cloudflare/README.md).
 It uses this same Worker with a standalone configuration. The CLI setup below