cloudflare-email 0.2.0 → 0.4.0

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

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import worker from "../src/index.js";
+import { forwardEmail, signedEmailHeaders } from "../src/index.js";
 
 // Minimal fake EmailMessage implementing the surface the Worker uses.
 function makeMessage(raw: string) {
@@ -64,7 +64,7 @@ describe("cloudflare-email Worker", () => {
     const env = { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET };
     const { message } = makeMessage(RAW);
 
-    await worker.email(message as any, env);
+    await forwardEmail(message as any, env);
 
     expect(fetchSpy).toHaveBeenCalledOnce();
     const [url, opts] = fetchSpy.mock.calls[0];
@@ -75,6 +75,7 @@ describe("cloudflare-email Worker", () => {
     const sig = opts.headers["X-CF-Email-Signature"];
     const envelope = opts.headers["X-CF-Email-Envelope"];
     expect(opts.headers["X-CF-Email-Signature-Version"]).toBe("2");
+    expect(opts.headers["X-CF-Email-Metadata"]).toBeUndefined();
     expect(JSON.parse(atob(envelope.replace(/-/g, "+").replace(/_/g, "/")))).toEqual({
       from: "sender@external.test", to: "inbox@trial.test",
     });
@@ -93,7 +94,7 @@ describe("cloudflare-email Worker", () => {
   it.each(["http://rails.test/inbound", "https://user:password@rails.test/inbound", "https://rails.test/inbound#fragment", "invalid"])(
     "rejects invalid ingress URL %j before reading mail", async (url) => {
       const { message, rejects } = makeMessage(RAW);
-      await worker.email(message as any, { RAILS_INGRESS_URL: url, INGRESS_SECRET: SECRET });
+      await forwardEmail(message as any, { RAILS_INGRESS_URL: url, INGRESS_SECRET: SECRET });
       expect(rejects).toHaveLength(1);
       expect(fetchSpy).not.toHaveBeenCalled();
       expect(message.raw.locked).toBe(false);
@@ -102,14 +103,14 @@ describe("cloudflare-email Worker", () => {
 
   it("allows loopback HTTP for local verification", async () => {
     const { message, rejects } = makeMessage(RAW);
-    await worker.email(message as any, { RAILS_INGRESS_URL: "http://127.0.0.1:3000/inbound", INGRESS_SECRET: SECRET });
+    await forwardEmail(message as any, { RAILS_INGRESS_URL: "http://127.0.0.1:3000/inbound", INGRESS_SECRET: SECRET });
     expect(rejects).toEqual([]);
     expect(fetchSpy).toHaveBeenCalledOnce();
   });
 
   it("accepts mail at the configured size boundary", async () => {
     const { message, rejects } = makeMessage(RAW);
-    await worker.email(message as any, { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET, MAX_EMAIL_BYTES: String(message.rawSize) });
+    await forwardEmail(message as any, { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET, MAX_EMAIL_BYTES: String(message.rawSize) });
     expect(rejects).toEqual([]);
     expect(fetchSpy).toHaveBeenCalledOnce();
   });
@@ -117,7 +118,7 @@ describe("cloudflare-email Worker", () => {
   it.each([true, false])("enforces size limit with accurate rawSize=%j", async (accurate) => {
     const { message, rejects } = makeMessage(RAW);
     if (!accurate) message.rawSize = 0;
-    await worker.email(message as any, { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET, MAX_EMAIL_BYTES: "16" });
+    await forwardEmail(message as any, { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET, MAX_EMAIL_BYTES: "16" });
     expect(rejects).toHaveLength(1);
     expect(rejects[0]).toMatch(/size limit/);
     expect(fetchSpy).not.toHaveBeenCalled();
@@ -125,7 +126,7 @@ describe("cloudflare-email Worker", () => {
 
   it("rejects invalid size configuration", async () => {
     const { message, rejects } = makeMessage(RAW);
-    await worker.email(message as any, { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET, MAX_EMAIL_BYTES: "0" });
+    await forwardEmail(message as any, { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET, MAX_EMAIL_BYTES: "0" });
     expect(rejects).toHaveLength(1);
     expect(fetchSpy).not.toHaveBeenCalled();
   });
@@ -135,7 +136,7 @@ describe("cloudflare-email Worker", () => {
     const env = { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET };
     const { message, rejects } = makeMessage(RAW);
 
-    await worker.email(message as any, env);
+    await forwardEmail(message as any, env);
 
     expect(rejects).toEqual(["upstream returned 503"]);
   });
@@ -143,10 +144,10 @@ describe("cloudflare-email Worker", () => {
   it("authenticates SMTP recipients independently of sender-controlled To headers", async () => {
     vi.spyOn(Date, "now").mockReturnValue(1_750_000_000_000);
     const env = { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET };
-    await worker.email(makeMessage(RAW).message as any, env);
+    await forwardEmail(makeMessage(RAW).message as any, env);
     const other = makeMessage(RAW);
     other.message.to = "bcc@trial.test";
-    await worker.email(other.message as any, env);
+    await forwardEmail(other.message as any, env);
     const first = fetchSpy.mock.calls[0][1];
     const second = fetchSpy.mock.calls[1][1];
     expect(second.body).toEqual(first.body);
@@ -158,7 +159,7 @@ describe("cloudflare-email Worker", () => {
   it("allows the empty SMTP reverse path used by bounce messages", async () => {
     const { message, rejects } = makeMessage(RAW);
     message.from = "";
-    await worker.email(message as any, { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET });
+    await forwardEmail(message as any, { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET });
     expect(rejects).toEqual([]);
     expect(fetchSpy).toHaveBeenCalledOnce();
   });
@@ -167,7 +168,7 @@ describe("cloudflare-email Worker", () => {
     "rejects invalid SMTP recipient %j before posting", async (address) => {
       const { message, rejects } = makeMessage(RAW);
       message.to = address;
-      await worker.email(message as any, { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET });
+      await forwardEmail(message as any, { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET });
       expect(rejects).toEqual(["worker received invalid SMTP envelope"]);
       expect(fetchSpy).not.toHaveBeenCalled();
     },
@@ -177,7 +178,7 @@ describe("cloudflare-email Worker", () => {
     const env = { RAILS_INGRESS_URL: "", INGRESS_SECRET: SECRET };
     const { message, rejects } = makeMessage(RAW);
 
-    await worker.email(message as any, env);
+    await forwardEmail(message as any, env);
 
     expect(rejects[0]).toMatch(/missing RAILS_INGRESS_URL/);
     expect(fetchSpy).not.toHaveBeenCalled();
@@ -187,7 +188,7 @@ describe("cloudflare-email Worker", () => {
     const env = { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: "" };
     const { message, rejects } = makeMessage(RAW);
 
-    await worker.email(message as any, env);
+    await forwardEmail(message as any, env);
 
     expect(rejects[0]).toMatch(/missing .*INGRESS_SECRET/);
     expect(fetchSpy).not.toHaveBeenCalled();
@@ -198,7 +199,7 @@ describe("cloudflare-email Worker", () => {
     const env = { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET };
     const { message, rejects } = makeMessage(RAW);
 
-    await worker.email(message as any, env);
+    await forwardEmail(message as any, env);
 
     expect(rejects).toEqual(["upstream fetch failed"]);
   });
@@ -209,7 +210,7 @@ describe("cloudflare-email Worker", () => {
       options.signal.addEventListener("abort", () => reject(new Error("aborted")));
     }));
     const { message, rejects } = makeMessage(RAW);
-    const delivery = worker.email(message as any, { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET });
+    const delivery = forwardEmail(message as any, { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET });
     // Signing uses async Web Crypto, so wait until fetch starts before advancing timers.
     await vi.waitFor(() => expect(fetchSpy).toHaveBeenCalledOnce());
     await vi.advanceTimersByTimeAsync(15_000);
@@ -220,7 +221,7 @@ describe("cloudflare-email Worker", () => {
 
   it("refuses redirects and clears the timeout after delivery", async () => {
     vi.useFakeTimers();
-    await worker.email(makeMessage(RAW).message as any, { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET });
+    await forwardEmail(makeMessage(RAW).message as any, { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET });
     const options = fetchSpy.mock.calls[0][1];
     expect(options.redirect).toBe("manual");
     await vi.advanceTimersByTimeAsync(15_000);
@@ -230,7 +231,7 @@ describe("cloudflare-email Worker", () => {
   it("rejects an ingress redirect response", async () => {
     fetchSpy.mockResolvedValueOnce(new Response(null, { status: 302, headers: { Location: "https://other.test" } }));
     const { message, rejects } = makeMessage(RAW);
-    await worker.email(message as any, { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET });
+    await forwardEmail(message as any, { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET });
     expect(rejects).toEqual(["upstream returned 302"]);
     expect(fetchSpy).toHaveBeenCalledOnce();
   });
@@ -239,13 +240,70 @@ describe("cloudflare-email Worker", () => {
     // 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);
+    await forwardEmail(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);
+    await forwardEmail(makeMessage(RAW + "tamper").message as any, env);
     const sig2 = fetchSpy.mock.calls[0][1].headers["X-CF-Email-Signature"];
 
     expect(sig1).not.toBe(sig2);
   });
+
+  const metadata = { source: "cloudflare", data: { note: "Résumé ☁", spf: "pass", score: 0.5, flags: [true, null] } };
+  const signingInput = { secret: SECRET, raw: new Uint8Array([0, 255, 13, 10, 128]), from: "sender@external.test", to: "inbox@trial.test", timestamp: "1750000000" };
+
+  it("matches the shared v3 binary body and UTF8 metadata vector", async () => {
+    const headers = await signedEmailHeaders({ ...signingInput, metadata });
+    expect(headers["X-CF-Email-Signature-Version"]).toBe("3");
+    expect(headers["X-CF-Email-Metadata"]).toBe("eyJzb3VyY2UiOiJjbG91ZGZsYXJlIiwiZGF0YSI6eyJub3RlIjoiUsOpc3Vtw6kg4piBIiwic3BmIjoicGFzcyIsInNjb3JlIjowLjUsImZsYWdzIjpbdHJ1ZSxudWxsXX19");
+    expect(headers["X-CF-Email-Signature"]).toBe("d4e5ed55306e1619b5c40f3ec5dfea44a3131ad422a22b49ffb042069f6b720f");
+    for (const changed of [{ ...metadata, source: "other" }, { ...metadata, data: { ...metadata.data, spf: "fail" } }]) {
+      expect((await signedEmailHeaders({ ...signingInput, metadata: changed }))["X-CF-Email-Signature"]).not.toBe(headers["X-CF-Email-Signature"]);
+    }
+  });
+
+  it("forwards opt-in metadata while preserving raw MIME and normal transport policy", async () => {
+    vi.spyOn(Date, "now").mockReturnValue(1750000000000);
+    const { message, rejects } = makeMessage(RAW);
+    await forwardEmail(message, { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET }, { metadata });
+    expect(rejects).toEqual([]);
+    const options = fetchSpy.mock.calls[0][1];
+    expect(options.headers).toEqual(await signedEmailHeaders({ ...signingInput, raw: new TextEncoder().encode(RAW), metadata }));
+    expect(options.redirect).toBe("manual");
+    expect(new TextDecoder().decode(options.body)).toBe(RAW);
+  });
+
+  it.each([null, {}, { source: "Cloudflare", data: {} }, { source: "a\n", data: {} },
+    { source: "a".repeat(129), data: {} }, { source: "a", data: [] },
+    { source: "a", data: {}, extra: true }, { source: "a", data: { x: undefined } },
+    { source: "a", data: { x: NaN } }, { source: "a", data: { x: new Date() } },
+    { source: "a", data: { x: "\uD800" } }, { source: "a", data: { "\uDC00": true } },
+    { source: "a", data: { x: "x".repeat(16384) } }])("rejects malformed metadata without downgrading to v2 (%j)", async (invalid) => {
+    await expect(signedEmailHeaders({ ...signingInput, metadata: invalid })).rejects.toThrow();
+    const { message, rejects } = makeMessage(RAW);
+    await forwardEmail(message, { RAILS_INGRESS_URL: URL_, INGRESS_SECRET: SECRET }, { metadata: invalid });
+    expect(rejects).toEqual(["worker could not sign envelope or provider metadata"]);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("bounds metadata nesting including cyclic data", async () => {
+    const data: any = {};
+    let node = data;
+    for (let i = 0; i < 6; i++) { node.child = {}; node = node.child; }
+    await expect(signedEmailHeaders({ ...signingInput, metadata: { source: "a", data } })).resolves.toBeDefined();
+    node.child = {};
+    await expect(signedEmailHeaders({ ...signingInput, metadata: { source: "a", data } })).rejects.toThrow();
+    data.child = data;
+    await expect(signedEmailHeaders({ ...signingInput, metadata: { source: "a", data } })).rejects.toThrow();
+  });
+
+  it("enforces the encoded metadata size boundary", async () => {
+    // The JSON wrapper occupies 33 UTF8 bytes; 12288 bytes encode to 16384 characters.
+    const atLimit = { source: "a", data: { text: "x".repeat(12288 - 33) } };
+    const headers = await signedEmailHeaders({ ...signingInput, metadata: atLimit });
+    expect(headers["X-CF-Email-Metadata"]).toHaveLength(16384);
+    atLimit.data.text += "x";
+    await expect(signedEmailHeaders({ ...signingInput, metadata: atLimit })).rejects.toThrow(/16384/);
+  });
 });

data/templates/worker/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/worker/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/wrangler.toml

@@ -17,3 +17,53 @@ name = "cloudflare-email-ingress-production"
 
 # After deploying, in the Cloudflare dashboard:
 #   Email Routing -> Routes -> "Send to a Worker" -> select the matching environment Worker
+
+# Durable delivery is the default. Create these private resources before deploy.
+# See docs/durable-inbound.md. Buckets must not expire pending objects.
+# Explicit emergency fallback: set INBOUND_DELIVERY_MODE = "direct" in the
+# chosen environment's [env.<name>.vars]. Keep recovery bindings and cron.
+
+[[env.development.r2_buckets]]
+binding = "INBOUND_EMAIL_STORE"
+bucket_name = "cloudflare-email-inbound-development"
+[[env.development.queues.producers]]
+binding = "INBOUND_EMAIL_QUEUE"
+queue = "cloudflare-email-inbound-development"
+[[env.development.queues.consumers]]
+queue = "cloudflare-email-inbound-development"
+max_batch_size = 5
+max_batch_timeout = 5
+max_retries = 10
+retry_delay = 300
+[env.development.triggers]
+crons = ["* * * * *"]
+
+[[env.staging.r2_buckets]]
+binding = "INBOUND_EMAIL_STORE"
+bucket_name = "cloudflare-email-inbound-staging"
+[[env.staging.queues.producers]]
+binding = "INBOUND_EMAIL_QUEUE"
+queue = "cloudflare-email-inbound-staging"
+[[env.staging.queues.consumers]]
+queue = "cloudflare-email-inbound-staging"
+max_batch_size = 5
+max_batch_timeout = 5
+max_retries = 10
+retry_delay = 300
+[env.staging.triggers]
+crons = ["* * * * *"]
+
+[[env.production.r2_buckets]]
+binding = "INBOUND_EMAIL_STORE"
+bucket_name = "cloudflare-email-inbound-production"
+[[env.production.queues.producers]]
+binding = "INBOUND_EMAIL_QUEUE"
+queue = "cloudflare-email-inbound-production"
+[[env.production.queues.consumers]]
+queue = "cloudflare-email-inbound-production"
+max_batch_size = 5
+max_batch_timeout = 5
+max_retries = 10
+retry_delay = 300
+[env.production.triggers]
+crons = ["* * * * *"]