cloudflare-email 0.2.0 → 0.4.0

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

@@ -0,0 +1,226 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { archiveEmail, relayEmail, signedEmailHeaders } from "../src/index.js";
+
+const raw = new Uint8Array([0, 255, 13, 10, 128]);
+function message(bytes = raw, rawSize = bytes.length) {
+  return { from: "sender@example.com", to: "inbox@tenant.example.com", rawSize,
+    raw: new ReadableStream({ start(c) { c.enqueue(bytes); c.close(); } }) };
+}
+function options(overrides = {}) {
+  return { resolveBackend: async () => ({ url: "https://rails.example.com/ingest", secret: "test-secret" }),
+    headers: async ({ raw, from, to, backend }) => signedEmailHeaders({ raw, from, to, secret: backend.secret }),
+    ...overrides };
+}
+afterEach(() => { vi.unstubAllGlobals(); vi.useRealTimers(); });
+
+describe("host-controlled relay", () => {
+  it("archives once before acceptance and backend lookup, signs and sends exact binary bytes", async () => {
+    const order: string[] = [];
+    const put = vi.fn(async (key, body, metadata) => {
+      order.push("archive");
+      expect(key).toBe("mail/one.eml");
+      expect(body).toEqual(raw);
+      expect(metadata).toEqual({ httpMetadata: { contentType: "message/rfc822" },
+        customMetadata: { from: "sender@example.com", to: "inbox@tenant.example.com", size: "5" } });
+    });
+    const fetch = vi.fn(async (_url, init) => {
+      order.push("fetch");
+      expect(init.body).toEqual(raw);
+      expect(init.headers.get("X-CF-Email-Signature-Version")).toBe("2");
+      expect(init.redirect).toBe("manual");
+      expect(init.signal).toBeInstanceOf(AbortSignal);
+      return new Response(null, { status: 202 });
+    });
+    vi.stubGlobal("fetch", fetch);
+    const result = await relayEmail(message(), options({
+      archive: (args) => archiveEmail({ ...args, bucket: { put }, key: "mail/one.eml" }),
+      accepts: async () => { order.push("accepts"); return true; },
+      resolveBackend: async () => { order.push("backend"); return { url: "https://rails.example.com/ingest", secret: "test-secret" }; },
+      headers: async (args) => {
+        expect(args.archive).toEqual({ key: "mail/one.eml" });
+        order.push("headers");
+        return signedEmailHeaders({ ...args, secret: args.backend.secret });
+      },
+    }));
+    expect(order).toEqual(["archive", "accepts", "backend", "headers", "fetch"]);
+    expect(result).toEqual({ status: "delivered", reason: "delivered", httpStatus: 202, archiveFailed: false });
+    expect(fetch).toHaveBeenCalledOnce();
+    expect(put).toHaveBeenCalledOnce();
+  });
+
+  it("continues after archive failure without exposing exception content", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => new Response(null, { status: 204 })));
+    const result = await relayEmail(message(), options({ archive: async () => { throw new Error("PRIVATE EMAIL SECRET"); } }));
+    expect(result).toEqual({ status: "delivered", reason: "delivered", httpStatus: 204, archiveFailed: true });
+  });
+
+  it("archives rejected recipients without resolving a backend", async () => {
+    const archive = vi.fn(async () => ({ key: "retained.eml" }));
+    const resolveBackend = vi.fn();
+    expect(await relayEmail(message(), options({ archive, accepts: async () => false, resolveBackend })))
+      .toEqual({ status: "rejected", reason: "not_accepted", archiveFailed: false });
+    expect(archive).toHaveBeenCalledOnce();
+    expect(resolveBackend).not.toHaveBeenCalled();
+  });
+
+  it("continues when the archive deadline expires, allowing a late archive completion", async () => {
+    vi.useFakeTimers();
+    let finish;
+    const archive = vi.fn(() => new Promise(resolve => { finish = resolve; }));
+    const fetch = vi.fn(async () => new Response(null, { status: 200 }));
+    vi.stubGlobal("fetch", fetch);
+    const pending = relayEmail(message(), options({ archive, archiveTimeoutMs: 20,
+      headers: async ({ archive }) => { expect(archive).toBeUndefined(); return {}; },
+    }));
+    await vi.advanceTimersByTimeAsync(19);
+    expect(fetch).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(1);
+    expect(await pending).toEqual({ status: "delivered", reason: "delivered", httpStatus: 200, archiveFailed: true });
+    finish({ key: "late.eml" });
+    await Promise.resolve();
+    expect(fetch).toHaveBeenCalledOnce();
+    expect(archive).toHaveBeenCalledOnce();
+  });
+
+  it("uses the validated URL even when the headers callback changes the backend", async () => {
+    const fetch = vi.fn(async () => new Response(null, { status: 200 }));
+    vi.stubGlobal("fetch", fetch);
+    await relayEmail(message(), options({ headers: async ({ backend }) => {
+      backend.url = "http://untrusted.example.com/secret";
+      return { Authorization: "Basic private" };
+    } }));
+    expect(fetch.mock.calls[0][0]).toBe("https://rails.example.com/ingest");
+  });
+
+  it("bounds actual streaming bytes even when rawSize is false", async () => {
+    const cancel = vi.fn();
+    const stream = new ReadableStream({ start(c) { c.enqueue(raw); }, cancel });
+    const archive = vi.fn();
+    expect(await relayEmail({ ...message(), raw: stream, rawSize: 1 }, options({ maxEmailBytes: 4, archive })))
+      .toEqual({ status: "rejected", reason: "too_large", archiveFailed: false });
+    expect(cancel).toHaveBeenCalledOnce();
+    expect(archive).not.toHaveBeenCalled();
+  });
+
+  it("rejects declared oversize or invalid envelopes without reading", async () => {
+    const getReader = vi.fn();
+    expect((await relayEmail({ ...message(), raw: { getReader }, rawSize: 100 }, options({ maxEmailBytes: 50 }))).reason).toBe("too_large");
+    expect((await relayEmail({ ...message(), raw: { getReader }, to: "bad\r\naddress" }, options())).reason).toBe("invalid_envelope");
+    expect(getReader).not.toHaveBeenCalled();
+  });
+
+  it("reports read failures and invalid chunks without forwarding", async () => {
+    const fetch = vi.fn(); vi.stubGlobal("fetch", fetch);
+    for (const stream of [new ReadableStream({ start(c) { c.error(new Error("secret")); } }),
+      new ReadableStream({ start(c) { c.enqueue("bad chunk"); c.close(); } })]) {
+      expect(await relayEmail({ ...message(), raw: stream }, options()))
+        .toEqual({ status: "failed", reason: "unreadable", archiveFailed: false });
+    }
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it.each(["http://rails.example.com", "https://user:secret@example.com", "https://example.com/#secret", "ftp://example.com", "invalid"])
+    ("rejects unsafe backend %s", async (url) => {
+      const fetch = vi.fn(); vi.stubGlobal("fetch", fetch);
+      expect((await relayEmail(message(), options({ resolveBackend: async () => ({ url }) }))).reason).toBe("invalid_backend");
+      expect(fetch).not.toHaveBeenCalled();
+    });
+
+  it("supports a host-selected loopback backend and Basic headers", async () => {
+    const fetch = vi.fn(async (url, init) => {
+      expect(url).toBe("http://127.0.0.1:3000/ingest");
+      expect(init.headers.get("Authorization")).toBe("Basic dGVzdDp0ZXN0");
+      expect(init.body).toEqual(raw);
+      return new Response(null, { status: 200 });
+    });
+    vi.stubGlobal("fetch", fetch);
+    const result = await relayEmail(message(), options({
+      resolveBackend: async ({ to }) => ({ url: to.includes("tenant") ? "http://127.0.0.1:3000/ingest" : "https://other.example.com" }),
+      headers: async () => ({ Authorization: "Basic dGVzdDp0ZXN0", "Content-Type": "message/rfc822" }),
+    }));
+    expect(result.status).toBe("delivered");
+  });
+
+  it("leaves Unicode and legacy address shapes to host acceptance with custom headers", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => new Response(null, { status: 200 })));
+    const from = "séndér@example.com";
+    const to = '"quoted local"@TENANT.example.com';
+    const accepts = vi.fn(async (envelope) => {
+      expect(envelope).toEqual({ from, to });
+      return true;
+    });
+    expect((await relayEmail({ ...message(), from, to }, options({ accepts,
+      headers: async () => ({ Authorization: "Basic dGVzdDp0ZXN0" }),
+    }))).status).toBe("delivered");
+    expect(accepts).toHaveBeenCalledOnce();
+  });
+
+  it.each([301, 400, 401, 413, 422, 429, 500, 503])("returns HTTP %i without reading response content or retrying", async (status) => {
+    const cancel = vi.fn();
+    const response = new Response(new ReadableStream({ cancel }), { status });
+    const text = vi.spyOn(response, "text");
+    const fetch = vi.fn(async () => response); vi.stubGlobal("fetch", fetch);
+    expect(await relayEmail(message(), options())).toEqual({ status: "failed", reason: "http_status", httpStatus: status, archiveFailed: false });
+    expect(text).not.toHaveBeenCalled();
+    expect(cancel).toHaveBeenCalledOnce();
+    expect(fetch).toHaveBeenCalledOnce();
+  });
+
+  it("does not wait for an unresponsive response cancellation", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => new Response(new ReadableStream({ cancel: () => new Promise(() => {}) }), { status: 200 })));
+    expect((await relayEmail(message(), options())).status).toBe("delivered");
+  });
+
+  it("aborts fetch on the configured timeout and returns no exception text", async () => {
+    vi.useFakeTimers();
+    vi.stubGlobal("fetch", vi.fn(async (_url, { signal }) => new Promise((_resolve, reject) => {
+      signal.addEventListener("abort", () => reject(new Error("private backend")));
+    })));
+    const pending = relayEmail(message(), options({ timeoutMs: 25, headers: async () => ({}) }));
+    await vi.advanceTimersByTimeAsync(25);
+    expect(await pending).toEqual({ status: "failed", reason: "timeout", archiveFailed: false });
+  });
+
+  it.each([
+    [{ accepts: async () => { throw new Error("secret"); } }, "acceptance_failed"],
+    [{ resolveBackend: async () => { throw new Error("secret"); } }, "backend_failed"],
+    [{ resolveBackend: async () => null }, "invalid_backend"],
+    [{ headers: async () => { throw new Error("secret"); } }, "headers_failed"],
+    [{ headers: async () => ({ "Bad\nHeader": "secret" }) }, "headers_failed"],
+    [{ maxEmailBytes: 0 }, "invalid_options"],
+    [{ timeoutMs: Infinity }, "invalid_options"],
+    [{ timeoutMs: 2 ** 31 }, "invalid_options"],
+    [{ archive: true }, "invalid_options"],
+    [{ archiveTimeoutMs: 0 }, "invalid_options"],
+    [{ archiveTimeoutMs: 2 ** 31 }, "invalid_options"],
+  ])("returns safe callback/configuration failure %#", async (overrides, reason) => {
+    expect(await relayEmail(message(), options(overrides))).toEqual({ status: "failed", reason, archiveFailed: false });
+  });
+
+  it("returns fetch failures without backend secrets", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => { throw new Error("secret-url"); }));
+    expect(await relayEmail(message(), options())).toEqual({ status: "failed", reason: "fetch_failed", archiveFailed: false });
+  });
+});
+
+describe("R2 archive helper", () => {
+  it("validates archive arguments before invoking the bucket", async () => {
+    const put = vi.fn();
+    const args = { bucket: { put }, key: "mail/id.eml", raw, from: "", to: "inbox@example.com" };
+    for (const overrides of [{ key: "" }, { key: "x".repeat(1025) }, { key: "\u0000" }, { raw: "bad" },
+      { from: "sender\r\n@example.com" }, { to: "" }]) {
+      await expect(archiveEmail({ ...args, ...overrides })).rejects.toThrow("invalid email archive arguments");
+    }
+    expect(put).not.toHaveBeenCalled();
+    await expect(archiveEmail(args)).resolves.toEqual({ key: "mail/id.eml" });
+    expect(put.mock.calls[0][2].customMetadata.from).toBe("");
+  });
+
+  it("stores ASCII-safe envelope metadata while preserving raw Unicode mail bytes", async () => {
+    const put = vi.fn();
+    await archiveEmail({ bucket: { put }, key: "mail/unicode.eml", raw,
+      from: "séndér@example.com", to: "inbox@tenant.example.com" });
+    expect(put.mock.calls[0][1]).toEqual(raw);
+    expect(put.mock.calls[0][2].customMetadata.from).toBe("s?nd?r@example.com");
+  });
+});

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/deploy-to-cloudflare/vitest.config.ts

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

data/templates/deploy-to-cloudflare/wrangler.toml

@@ -0,0 +1,22 @@
+# Generated by script/sync_deploy_template.mjs in cloudflare-email.
+name = "cloudflare-email-ingress"
+main = "src/index.js"
+compatibility_date = "2026-09-10"
+
+[observability]
+enabled = true
+
+[[r2_buckets]]
+binding = "INBOUND_EMAIL_STORE"
+bucket_name = "cloudflare-email-inbound"
+[[queues.producers]]
+binding = "INBOUND_EMAIL_QUEUE"
+queue = "cloudflare-email-inbound"
+[[queues.consumers]]
+queue = "cloudflare-email-inbound"
+max_batch_size = 5
+max_batch_timeout = 5
+max_retries = 10
+retry_delay = 300
+[triggers]
+crons = ["* * * * *"]

data/templates/worker/README.md

@@ -6,8 +6,21 @@ 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
+is for the explicitly named development/staging/production environments.
+
 ```sh
 npm ci
+npx wrangler r2 bucket create cloudflare-email-inbound-production
+npx wrangler queues create cloudflare-email-inbound-production
 npx wrangler secret put INGRESS_SECRET --env production
 npx wrangler secret put RAILS_INGRESS_URL --env production
 npm run deploy -- --env production
@@ -46,20 +59,17 @@ does not change DNS or create routing rules.
 
 For each inbound message, the Worker:
 
-1. Reads the raw RFC822 bytes from `message.raw`.
-2. Encodes `{"from": message.from, "to": message.to}` as unpadded base64url JSON,
-   then computes `HMAC-SHA256(INGRESS_SECRET, "v2.{unix_timestamp}.{encoded_envelope}.{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>`
-   - `X-CF-Email-Signature-Version: 2`
-   - `X-CF-Email-Envelope: <encoded envelope>`
-4. If Rails responds non-2xx, the network fails, or the request exceeds 15 seconds,
-   the Worker calls `message.setReject`. Redirects are refused to prevent sending
-   message content and the signature to a different endpoint. The Worker does
-   not retry delivery automatically. A timeout can occur after Rails accepted
-   the message, so consumers should handle duplicate deliveries.
+1. Validates and stores the exact RFC822 bytes and envelope in private R2.
+2. Queues a small pointer after storage succeeds.
+3. Signs and POSTs the stored message to Rails; only HTTP 2xx allows deleting it.
+4. Retries failures through the Queue and a minute-by-minute scheduled recovery
+   pass. Even exhausted queue retries leave the original message recoverable.
+
+The signed request uses HMAC-SHA256 and authenticates the original SMTP envelope
+alongside the MIME bytes. See [durable delivery setup and recovery](./docs/durable-inbound.md).
+`INBOUND_DELIVERY_MODE=direct` selects an explicit single-attempt fallback that
+calls `message.setReject` on non-2xx, timeout or network failure. Existing pending
+mail keeps draining through Queue and cron while this fallback is selected.
 
 The Rails controller verifies the signature in constant time and rejects
 timestamps outside its 5-minute acceptance window. A signature authenticates the
@@ -67,13 +77,174 @@ Worker request, not the original email sender. Captured requests remain valid
 inside that window; Rails deduplicates messages through Action Mailbox.
 
 Deploy the Rails gem and this Worker together with ingress paused during the
-transition. Rails requires v2 signatures and rejects v1/missing versions. It stores authenticated
+transition. Rails accepts v2 and v3 signatures and rejects v1/missing versions. It stores authenticated
 SMTP metadata separately from MIME; applications read it using
 `Cloudflare::Email::Envelope.for(inbound_email)`. Duplicate detection includes the
 exact SMTP recipient, preserving separate To/Cc/Bcc deliveries. The format accepts
 ASCII dot-atom addresses up to 254 bytes (local part up to 64 bytes), plus an empty
 sender for bounce messages. Other address forms are rejected before forwarding.
 
+## Reuse an existing Worker
+
+Keep your existing archiving, sender checks, and fallback policy. Copy this
+template's `src/index.js` into your Worker project and import either helper.
+`forwardEmail(message, env)` uses the same bounded reading, URL checks, timeout,
+and rejection policy as the explicit direct fallback. Optional metadata selects v3 signing:
+
+```js
+import { forwardEmail } from "./cloudflare-ingress.js";
+
+export default {
+  async email(message, env) {
+    // Supplied by your integration after validating its trusted provider context.
+    // This is your adapter function, not a Cloudflare EmailMessage API.
+    const providerData = await yourValidatedProviderContext(message, env);
+    return forwardEmail(message, env, {
+      metadata: { source: "your-provider", data: providerData },
+    });
+  },
+};
+```
+
+The bundled Worker does not collect provider authentication results. Never treat
+`Authentication-Results`, `Received-SPF`, or other sender-supplied MIME headers as
+trusted provider context. Signing metadata authenticates your Worker's assertion;
+it does not prove DMARC passed or authorize the original sender. Your application
+still owns sender policy, organization resolution, review, and document processing.
+
+If your Worker already owns transport and error handling, use the header builder:
+
+```js
+import { signedEmailHeaders } from "./cloudflare-ingress.js";
+
+const headers = await signedEmailHeaders({
+  secret: env.INGRESS_SECRET,
+  raw, // Original Uint8Array, obtained using your own bounded reader.
+  from: message.from,
+  to: message.to,
+  metadata: { source: "your-provider", data: providerData },
+});
+// Send these headers with exactly `raw`, using your existing transport.
+```
+
+The builder performs no network calls. You own destination validation, body size
+limits, timeouts, redirects, retries, and response handling. An optional `timestamp`
+in Unix seconds supports deterministic testing; production normally uses the
+default current time. Omitting `metadata` produces unchanged v2 headers. Invalid
+metadata throws from the builder; the forwarding helper rejects instead of
+silently falling back to v2.
+
+Metadata must contain exactly `source` and `data`. Source matches
+`[a-z][a-z0-9_.-]{0,127}`; data is a JSON object, with only JSON values and at most
+eight container levels including the outer metadata object. The UTF8 JSON is
+encoded as unpadded base64url, limited to 16,384 encoded characters, and sent as
+`X-CF-Email-Metadata`. Version 3 signs the exact bytes:
+
+```text
+HMAC-SHA256(secret, "v3.{timestamp}.{encoded_envelope}.{encoded_metadata}.{raw_body}")
+```
+
+Neither the MIME nor its headers are rewritten. Upgrade Rails to a version that
+supports v3 before enabling metadata in a custom Worker. Keep sensitive provider
+data out of metadata unless your application's retention and access policies
+permit storing it with email records.
+
+## Reuse the transport in an existing Worker
+
+`relayEmail` provides bounded reading, an optional archive, backend selection and
+one HTTP delivery attempt. Your Worker decides how a result maps to SMTP
+rejection, retry, fallback forwarding or logging. It does not call `setReject`
+or `forward` and does not extract or interpret sender authentication evidence.
+`forwardEmail` remains the explicit direct helper; the default export retains mail durably.
+
+```js
+import { relayEmail, archiveEmail, signedEmailHeaders } from "./cloudflare-ingress.js";
+
+export default {
+  async email(message, env) {
+    const outcome = await relayEmail(message, {
+      maxEmailBytes: 25 * 1024 * 1024,
+      timeoutMs: 15_000,
+      archiveTimeoutMs: 10_000,
+      // Omit archive when no bucket is configured. Key policy belongs to your app.
+      archive: env.EMAIL_ARCHIVE ? (args) => archiveEmail({
+        ...args, bucket: env.EMAIL_ARCHIVE,
+        key: `email/${crypto.randomUUID()}.eml`,
+      }) : undefined,
+      accepts: async ({ to }) => to.endsWith("@inbound.example.com"),
+      // Select only host-configured backends; never use a URL from an email header.
+      resolveBackend: async ({ from, to }) => ({
+        url: env.RAILS_INGRESS_URL, secret: env.INGRESS_SECRET,
+      }),
+      headers: ({ raw, from, to, backend }) => signedEmailHeaders({
+        raw, from, to, secret: backend.secret,
+      }),
+    });
+    // Example host policy: permanent rejection only for invalid/unaccepted mail;
+    // Throwing surfaces failure; do not assume Cloudflare retries SMTP delivery.
+    if (outcome.status === "rejected") message.setReject("email not accepted");
+    if (outcome.status === "failed") throw new Error("email relay unavailable");
+  },
+};
+```
+
+The relay reads the original stream once, enforcing the actual byte limit even
+when `rawSize` underreports it. It archives before checking `accepts` and before
+resolving the backend, so an archive can retain mail rejected by host policy.
+Invalid envelopes, unreadable streams and oversized messages are not archived.
+An archive exception or timeout does not prevent delivery: the result has
+`archiveFailed: true`. The archive deadline defaults to 10 seconds and can be
+changed with `archiveTimeoutMs`. It stops waiting but cannot cancel an R2 write:
+a timed-out archive may still finish later if the runtime remains alive. Monitor
+that flag if the archive is your outage recovery mechanism. Other callback
+implementations must finish within the Worker's runtime limits; the `timeoutMs`
+option applies to the HTTP request only.
+
+`accepts` must return exactly `true` to accept. `resolveBackend` returns an object
+with `url` and any additional host configuration needed by `headers`. Backend
+URLs must use HTTPS, or HTTP on localhost, `127.0.0.1` or `[::1]`; embedded
+credentials and fragments are rejected. Generic relay envelope checks enforce
+bounded strings without control characters, leaving address shape to the host.
+`signedEmailHeaders` retains the gem ingress's stricter ASCII address validation.
+
+The `headers` callback receives `{ raw, from, to, backend, archive }`, where
+`archive` is the archive callback's return value, or undefined on omission or
+failure. It can return a header object or `Headers`, including Basic credentials
+for an existing custom endpoint. The relay sends exactly `raw`, follows no
+redirects, cancels response bodies without reading them, and never includes
+backend response content or callback exception text in results. Callbacks are
+trusted host code: preserve the supplied bytes and keep secrets out of logs.
+Do not put an archive key or other per-attempt value into signed provider metadata;
+doing so changes the persisted message identity on retries.
+
+Every result has `status`, `reason` and `archiveFailed`. HTTP responses also add
+`httpStatus`:
+
+| Status | Reasons |
+| --- | --- |
+| `delivered` | `delivered` (HTTP 2xx) |
+| `rejected` | `invalid_envelope`, `too_large`, `not_accepted` |
+| `failed` | `unreadable`, `invalid_options`, `acceptance_failed`, `backend_failed`, `invalid_backend`, `headers_failed`, `timeout`, `fetch_failed`, `http_status` |
+
+All non-2xx responses, including redirects and permanent client errors, return
+`failed`/`http_status`; your host chooses which are permanent, retryable or eligible
+for fallback. The relay never retries on its own.
+
+`archiveEmail({ bucket, key, raw, from, to })` writes raw RFC822 bytes to an R2
+binding and returns `{ key }`. Keys must be nonempty, at most 1,024 UTF8 bytes and
+contain no ASCII control characters. It stores `message/rfc822` content type and
+ASCII-safe `from`, `to` and `size` custom metadata; non-ASCII envelope characters
+become `?` in this display metadata only. Retention, unique keys, archive browsing
+and recovery authorization belong to the host. Rails email persistence starts
+after delivery and does not replace this optional outage archive.
+
+## Durable inbound delivery
+
+[Durable inbound delivery](./docs/durable-inbound.md) is the default. Provision the
+configured private R2 bucket, Queue producer/consumer and cron before deploying.
+There is no rollout enable flag or automatic downgrade when bindings are missing.
+The guide covers upgrades, monitoring, recovery tests and explicit direct fallback.
+
 ## Validate changes
 
 ```sh