@open-workspace/email 0.0.0-stage → 0.1.1

package/worker/mail/bimi.ts

@@ -0,0 +1,172 @@
+import type { BimiResult, BimiStatus } from "../../shared/mail-sender-intel";
+import { isAbortError, type DnsResolver } from "./doh";
+import { assertProxyableRemoteUrl } from "./remote-proxy";
+
+/**
+ * BIMI logo lookup without VMC/CMC validation: we show the domain's own logo
+ * only after DMARC passed under an enforcing policy, but never a checkmark.
+ * https://datatracker.ietf.org/doc/draft-brand-indicators-for-message-identification/
+ */
+
+export const MAX_BIMI_SVG_BYTES = 32 * 1024;
+const BIMI_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const BIMI_ERROR_TTL_MS = 60 * 60 * 1000;
+
+export function bimiObjectKey(domain: string) {
+  return `bimi/v1/${domain}.svg`;
+}
+
+export function bimiLogoPath(domain: string) {
+  return `/api/mail/bimi/${encodeURIComponent(domain)}`;
+}
+
+/** Strict CSP for serving stored logos: no scripts, no external loads. */
+export const BIMI_LOGO_HEADERS = {
+  "content-type": "image/svg+xml",
+  "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; sandbox",
+  "x-content-type-options": "nosniff",
+  "cross-origin-resource-policy": "same-origin",
+  "cache-control": "private, max-age=86400",
+} as const;
+
+/** `v=BIMI1; l=https://…/logo.svg; a=…` → the logo location, or null when declined. */
+export function parseBimiRecord(value: string) {
+  const tags = new Map<string, string>();
+  for (const part of value.split(";")) {
+    const index = part.indexOf("=");
+    if (index < 0) continue;
+    tags.set(part.slice(0, index).trim().toLocaleLowerCase(), part.slice(index + 1).trim());
+  }
+  if (tags.get("v") !== "BIMI1") return null;
+  const location = tags.get("l")?.split(",")[0]?.trim() ?? "";
+  return { location: location || null };
+}
+
+const FORBIDDEN_ELEMENTS =
+  /<\s*(?:script|foreignobject|iframe|object|embed|image|a|animate\w*|set|audio|video|canvas|handler|listener|discard)\b/iu;
+
+/**
+ * Conservative SVG Tiny PS check. Rejects anything that could run code or load
+ * another resource; returns the trimmed document, or a reason it was refused.
+ */
+export function validateBimiSvg(source: string): { svg: string } | { error: string } {
+  if (new TextEncoder().encode(source).byteLength > MAX_BIMI_SVG_BYTES) return { error: "The logo is larger than 32 KB" };
+  const svg = source.replace(/^/u, "").trim();
+  const body = svg.replace(/^<\?xml[^>]*\?>\s*/iu, "").replace(/<!--[\s\S]*?-->/gu, "").trim();
+  if (/<!DOCTYPE|<!ENTITY|<!\[CDATA\[/iu.test(body)) return { error: "The logo declares a DTD, entity or CDATA section" };
+  if (!/^<svg[\s>]/iu.test(body) || !/<\/svg>\s*$/iu.test(body)) return { error: "The file is not an SVG document" };
+  if (!/xmlns\s*=\s*["']http:\/\/www\.w3\.org\/2000\/svg["']/u.test(body)) return { error: "The SVG namespace is missing" };
+  if (FORBIDDEN_ELEMENTS.test(body)) return { error: "The logo contains scripts, links, images or animation" };
+  if (/\son[a-z]+\s*=/iu.test(body)) return { error: "The logo contains event handlers" };
+  if (/javascript:|data:|@import/iu.test(body)) return { error: "The logo references executable or embedded content" };
+  for (const match of body.matchAll(/\b(?:xlink:)?href\s*=\s*["']([^"']*)["']/giu)) {
+    if (!match[1]!.trim().startsWith("#")) return { error: "The logo references an external resource" };
+  }
+  for (const match of body.matchAll(/url\(\s*['"]?([^'")]*)/giu)) {
+    if (!match[1]!.trim().startsWith("#")) return { error: "The logo references an external resource" };
+  }
+  return { svg };
+}
+
+async function readCapped(response: Response, limit: number) {
+  const reader = response.body?.getReader();
+  if (!reader) return null;
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > limit) {
+      await reader.cancel();
+      return null;
+    }
+    chunks.push(value);
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(bytes);
+}
+
+type Lookup = { status: BimiStatus; reason: string | null; svg?: string };
+
+async function lookup(input: {
+  resolve: DnsResolver;
+  fetch: typeof fetch;
+  domain: string;
+  signal?: AbortSignal;
+}): Promise<Lookup> {
+  const answer = await input.resolve(`default._bimi.${input.domain}`, "TXT");
+  if (answer.status === "timeout" || answer.status === "error") {
+    return { status: "error", reason: "The BIMI record could not be looked up" };
+  }
+  const record = answer.records.map(parseBimiRecord).find(Boolean);
+  if (!record) return { status: "none", reason: "The domain publishes no BIMI record" };
+  if (!record.location) return { status: "none", reason: "The domain declined to show a logo" };
+  let url: URL;
+  try {
+    url = assertProxyableRemoteUrl(record.location);
+  } catch {
+    return { status: "invalid", reason: "The BIMI logo location is not a valid public URL" };
+  }
+  if (url.protocol !== "https:") return { status: "invalid", reason: "The BIMI logo is not served over HTTPS" };
+  try {
+    const response = await input.fetch(url, {
+      redirect: "manual",
+      headers: { accept: "image/svg+xml" },
+      signal: input.signal,
+    });
+    if (!response.ok) return { status: "error", reason: `The logo server answered ${response.status}` };
+    const declared = Number(response.headers.get("content-length") ?? 0);
+    if (declared > MAX_BIMI_SVG_BYTES) return { status: "invalid", reason: "The logo is larger than 32 KB" };
+    const text = await readCapped(response, MAX_BIMI_SVG_BYTES);
+    if (text === null) return { status: "invalid", reason: "The logo is larger than 32 KB" };
+    const checked = validateBimiSvg(text);
+    if ("error" in checked) return { status: "invalid", reason: checked.error };
+    return { status: "ok", reason: null, svg: checked.svg };
+  } catch (error) {
+    return { status: "error", reason: isAbortError(error) ? "The logo download timed out" : "The logo could not be downloaded" };
+  }
+}
+
+/**
+ * Per-domain logo, cached in R2 for a day (an hour after a failure). The
+ * From domain's record wins; the organizational domain is the fallback.
+ */
+export async function resolveBimi(input: {
+  resolve: DnsResolver;
+  fetch?: typeof fetch;
+  bucket: R2Bucket;
+  fromDomain: string;
+  orgDomain: string | null;
+  signal?: AbortSignal;
+  now?: number;
+}): Promise<BimiResult> {
+  const now = input.now ?? Date.now();
+  const domains = [...new Set([input.fromDomain, input.orgDomain].filter((value): value is string => Boolean(value)))];
+  let last: BimiResult | null = null;
+  for (const domain of domains) {
+    const key = bimiObjectKey(domain);
+    const cached = await input.bucket.head(key).catch(() => null);
+    const checkedAt = Number(cached?.customMetadata?.checkedAt ?? 0);
+    const cachedStatus = cached?.customMetadata?.status as BimiStatus | undefined;
+    const ttl = cachedStatus === "error" ? BIMI_ERROR_TTL_MS : BIMI_CACHE_TTL_MS;
+    let result: Lookup;
+    if (cached && cachedStatus && now - checkedAt < ttl) {
+      result = { status: cachedStatus, reason: cached.customMetadata?.reason || null };
+    } else {
+      result = await lookup({ resolve: input.resolve, fetch: input.fetch ?? fetch, domain, signal: input.signal });
+      await input.bucket.put(key, result.svg ?? "", {
+        httpMetadata: { contentType: "image/svg+xml" },
+        customMetadata: { status: result.status, checkedAt: String(now), reason: result.reason ?? "" },
+      }).catch(() => undefined);
+    }
+    last = { domain, status: result.status, reason: result.reason };
+    if (result.status !== "none") return last;
+  }
+  return last ?? { domain: input.fromDomain, status: "none", reason: "The domain publishes no BIMI record" };
+}

package/worker/mail/classification-signals.ts

@@ -0,0 +1,116 @@
+import type { InboundAuthentication } from "../../shared/mail-authentication";
+import type { DeliveryFacts, SecurityWarning, SenderIntel } from "../../shared/mail-sender-intel";
+
+/** Compact, model-facing summary of what the receiver measured for a message. */
+export type ClassificationSignals = {
+  authentication: {
+    verdict: InboundAuthentication["verdict"];
+    spf: string | null;
+    dkimAlignedPass: boolean;
+    dmarc: string | null;
+    dmarcPolicy: string | null;
+  } | null;
+  cloudflareSpamScore: number | null;
+  sendingServer: {
+    ip: string;
+    ptr: string | null;
+    forwardConfirmed: boolean | null;
+    genericPtr: boolean | null;
+    heloMatchesPtr: boolean | null;
+    asn: number | null;
+    asOrganization: string | null;
+    country: string | null;
+  } | null;
+  blocklists: {
+    zen: string[];
+    dbl: Array<{ domain: string; list: string }>;
+  } | null;
+  firstTimeSender: boolean | null;
+  warnings: Array<SecurityWarning["kind"]>;
+  /** What people in this mailbox reported about the sender before (counts). */
+  userFeedback: {
+    spamReports: number;
+    phishingReports: number;
+    notSpam: number;
+    /** Spam or phishing reports about other addresses at the same domain. */
+    domainReports: number;
+  } | null;
+  /** Who the message was written for, the address it reached, and who forwarded it. */
+  delivery: {
+    deliveredTo: string | null;
+    addressedToThisMailbox: boolean;
+    addressedTo: string | null;
+    knownAddressee: boolean;
+    forwardedVia: string | null;
+  } | null;
+  /** The same counts from every other mailbox in the workspace. */
+  workspaceFeedback: {
+    spamReports: number;
+    phishingReports: number;
+    notSpam: number;
+    domainReports: number;
+    reportingMailboxes: number;
+  } | null;
+};
+
+export function classificationSignals(input: {
+  authentication: InboundAuthentication | null;
+  intel: SenderIntel | null;
+  firstTimeSender: boolean | null;
+  warnings: SecurityWarning[];
+  feedback?: ClassificationSignals["userFeedback"];
+  workspaceFeedback?: ClassificationSignals["workspaceFeedback"];
+  delivery?: DeliveryFacts | null;
+}): ClassificationSignals {
+  const auth = input.authentication;
+  const intel = input.intel;
+  return {
+    authentication: auth && auth.verdict !== "unavailable"
+      ? {
+          verdict: auth.verdict,
+          spf: auth.spf?.result ?? null,
+          dkimAlignedPass: auth.dkim.some((dkim) => dkim.result === "pass" && dkim.aligned),
+          dmarc: auth.dmarc?.result ?? null,
+          dmarcPolicy: auth.dmarc?.policy ?? null,
+        }
+      : null,
+    cloudflareSpamScore: auth?.spamScore ?? null,
+    sendingServer: intel?.ip
+      ? {
+          ip: intel.ip,
+          ptr: intel.ptr.confirmed ?? intel.ptr.names[0] ?? null,
+          forwardConfirmed: intel.ptr.fcrdns,
+          genericPtr: intel.ptr.generic,
+          heloMatchesPtr: intel.heloMatchesPtr,
+          asn: intel.network.asn,
+          asOrganization: intel.network.asName,
+          country: intel.network.country,
+        }
+      : null,
+    blocklists: intel?.spamhaus
+      ? {
+          zen: intel.spamhaus.zen.listings.map((listing) => listing.list),
+          dbl: intel.spamhaus.dbl.listings.map((listing) => ({ domain: listing.target, list: listing.list })),
+        }
+      : null,
+    firstTimeSender: input.firstTimeSender,
+    warnings: input.warnings.map((warning) => warning.kind),
+    userFeedback: input.feedback
+      && Object.values(input.feedback).some((count) => count > 0)
+      ? input.feedback
+      : null,
+    delivery: input.delivery
+      ? {
+          deliveredTo: input.delivery.deliveredTo,
+          addressedToThisMailbox: !input.delivery.addressedTo,
+          addressedTo: input.delivery.addressedTo,
+          knownAddressee: input.delivery.knownAddressee,
+          forwardedVia: input.delivery.forwardedVia,
+        }
+      : null,
+    workspaceFeedback: input.workspaceFeedback
+      && Object.values(input.workspaceFeedback).some((count) => count > 0)
+      ? input.workspaceFeedback
+      : null,
+  };
+}

package/worker/mail/conversation-cursor.ts

@@ -0,0 +1,43 @@
+import type { ConversationCursorPosition } from "../mailbox";
+
+const CURSOR_VERSION = 1;
+
+function toBase64Url(value: string) {
+  const bytes = new TextEncoder().encode(value);
+  const binary = String.fromCharCode(...bytes);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
+}
+
+function fromBase64Url(value: string) {
+  const base64 = value.replaceAll("-", "+").replaceAll("_", "/");
+  const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=");
+  const bytes = Uint8Array.from(atob(padded), (character) => character.charCodeAt(0));
+  return new TextDecoder().decode(bytes);
+}
+
+export function encodeConversationCursor(position: ConversationCursorPosition) {
+  return toBase64Url(JSON.stringify([
+    CURSOR_VERSION,
+    position.timelineAt,
+    position.emailId,
+  ]));
+}
+
+export function decodeConversationCursor(value: string) {
+  try {
+    const decoded: unknown = JSON.parse(fromBase64Url(value));
+    if (
+      !Array.isArray(decoded)
+      || decoded.length !== 3
+      || decoded[0] !== CURSOR_VERSION
+      || !Number.isSafeInteger(decoded[1])
+      || typeof decoded[2] !== "string"
+      || decoded[2].length === 0
+    ) {
+      return null;
+    }
+    return { timelineAt: decoded[1], emailId: decoded[2] };
+  } catch {
+    return null;
+  }
+}

package/worker/mail/delivery-events.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { createDb } from "@open-workspace/core/worker/db/client.ts";
+import { domains, mailboxes } from "@open-workspace/core/worker/db/schema.ts";
+import { mailboxAddressPredicate } from "@open-workspace/core/worker/db/mailboxes.ts";
+import { normalizeMailboxAddress } from "@open-workspace/core/worker/lib/ids.ts";
+import { mailboxStub } from "../mailbox";
+import {
+  deliveryStatuses,
+  type RecipientDeliveryStatus,
+} from "../mailbox/model";
+
+const deliveryEventSchema = z.object({
+  type: z.string().startsWith("cf.email.sending.message."),
+  source: z.object({
+    type: z.literal("email.sending"),
+  }).passthrough(),
+  payload: z.object({
+    eventId: z.string().min(1),
+    messageId: z.string().min(1),
+    sender: z.string().min(1),
+    recipient: z.string().min(1),
+    delivery: z.object({
+      status: z.enum(deliveryStatuses),
+      smtpStatusCode: z.string().optional(),
+    }).passthrough(),
+    bounce: z.object({ reason: z.string().optional() }).optional(),
+    failure: z.object({ reason: z.string().optional() }).optional(),
+    rejection: z.object({
+      reason: z.string().optional(),
+      detail: z.string().optional(),
+    }).optional(),
+    complaint: z.object({ type: z.string().optional() }).optional(),
+  }).passthrough(),
+  metadata: z.object({
+    eventTimestamp: z.string().datetime(),
+  }).passthrough(),
+}).passthrough();
+
+type DeliveryEvent = z.infer<typeof deliveryEventSchema>;
+
+function deliveryDetail(event: DeliveryEvent) {
+  return event.payload.bounce?.reason
+    ?? event.payload.failure?.reason
+    ?? event.payload.rejection?.detail
+    ?? event.payload.rejection?.reason
+    ?? event.payload.complaint?.type
+    ?? null;
+}
+
+function recipientStatus(event: DeliveryEvent): RecipientDeliveryStatus {
+  return {
+    recipient: normalizeMailboxAddress(event.payload.recipient),
+    status: event.payload.delivery.status,
+    eventId: event.payload.eventId,
+    eventAt: new Date(event.metadata.eventTimestamp).getTime(),
+    smtpCode: event.payload.delivery.smtpStatusCode ?? null,
+    detail: deliveryDetail(event),
+  };
+}
+
+async function processDeliveryEvent(env: Env, event: DeliveryEvent) {
+  const sender = normalizeMailboxAddress(event.payload.sender);
+  const [mailbox] = await createDb(env.DB)
+    .select({ id: mailboxes.id })
+    .from(mailboxes)
+    .innerJoin(domains, mailboxAddressPredicate(sender))
+    .limit(1);
+  if (!mailbox) return "ignored" as const;
+  return mailboxStub(env, mailbox.id).recordDeliveryStatus(
+    event.payload.messageId,
+    recipientStatus(event),
+  );
+}
+
+export async function consumeDeliveryEvents(
+  batch: MessageBatch<unknown>,
+  env: Env,
+) {
+  await Promise.all(batch.messages.map(async (message) => {
+    const parsed = deliveryEventSchema.safeParse(message.body);
+    if (!parsed.success) {
+      console.error("Ignoring invalid Email Service event", parsed.error);
+      message.ack();
+      return;
+    }
+    try {
+      const result = await processDeliveryEvent(env, parsed.data);
+      if (result === "not_found") {
+        // Delivery events can beat the write that stores EmailSendResult.messageId.
+        message.retry({ delaySeconds: 10 });
+        return;
+      }
+      message.ack();
+    } catch (error) {
+      console.error("Could not persist Email Service event", error);
+      message.retry({ delaySeconds: 10 });
+    }
+  }));
+}

package/worker/mail/delivery-facts.ts

@@ -0,0 +1,122 @@
+import type { InboundAuthentication } from "../../shared/mail-authentication";
+import { addressDomain } from "../../shared/mail-headers";
+import type { DeliveryFacts } from "../../shared/mail-sender-intel";
+import { isWorkspaceDomain } from "./message-security";
+import { organizationalDomain } from "./org-domain";
+
+/**
+ * Providers whose account and security notices are worth forging or
+ * replaying: their alerts are trusted on sight and can carry text a user
+ * typed into an app, device, or invoice name.
+ */
+const ACCOUNT_NOTICE_DOMAINS = new Set([
+  "google.com",
+  "apple.com",
+  "icloud.com",
+  "microsoft.com",
+  "microsoftonline.com",
+  "live.com",
+  "outlook.com",
+  "paypal.com",
+  "amazon.com",
+  "facebookmail.com",
+  "instagram.com",
+  "github.com",
+  "docusign.net",
+  "dropbox.com",
+  "linkedin.com",
+  "x.com",
+  "coinbase.com",
+  "binance.com",
+]);
+
+export function isAccountNoticeSender(fromDomain: string | null | undefined) {
+  const org = organizationalDomain(fromDomain);
+  return Boolean(org && ACCOUNT_NOTICE_DOMAINS.has(org));
+}
+
+/**
+ * The organization that forwarded a message, when the envelope or ARC chain
+ * shows a hop after the author's own servers: an SRS-rewritten envelope
+ * sender, an upstream ARC chain with another organization's envelope (Gmail
+ * forwarding rewrites it to `name+caf_=…@gmail.com`), or an upstream ARC set
+ * sealed by someone other than the author.
+ */
+export function forwardingRelay(auth: InboundAuthentication | null) {
+  if (!auth) return null;
+  const fromOrg = organizationalDomain(auth.fromDomain);
+  const envelope = auth.envelopeFrom?.toLocaleLowerCase() ?? "";
+  const envelopeOrg = organizationalDomain(addressDomain(envelope));
+  const foreignEnvelope = envelopeOrg && envelopeOrg !== fromOrg ? envelopeOrg : null;
+  if (/^srs[01][=+-]/u.test(envelope) && foreignEnvelope) return foreignEnvelope;
+  if (auth.arc && auth.arc.chainLength > 1) {
+    if (foreignEnvelope) return foreignEnvelope;
+    const sealer = auth.arc.sealers
+      .map((item) => organizationalDomain(item.domain))
+      .find((domain) => domain && domain !== fromOrg);
+    if (sealer) return sealer;
+  }
+  return null;
+}
+
+/**
+ * The first To/Cc address when the message names neither the address it was
+ * delivered to nor any workspace address. Lists and undisclosed recipients
+ * are left alone: they never name the reader.
+ */
+export function addressedElsewhere(input: {
+  deliveredTo: string | null;
+  to: readonly string[];
+  cc: readonly string[];
+  listId: string | null;
+  workspaceDomains: readonly string[];
+}) {
+  if (input.listId) return null;
+  const recipients = [...input.to, ...input.cc].map((address) => address.toLocaleLowerCase()).filter((address) => address.includes("@"));
+  if (!recipients.length) return null;
+  const deliveredTo = input.deliveredTo?.toLocaleLowerCase();
+  if (deliveredTo && recipients.includes(deliveredTo)) return null;
+  if (recipients.some((address) => isWorkspaceDomain(addressDomain(address), input.workspaceDomains))) return null;
+  return recipients[0]!;
+}
+
+export function deliveryFacts(input: {
+  authentication: InboundAuthentication | null;
+  deliveredTo: string | null;
+  to: readonly string[];
+  cc: readonly string[];
+  listId: string | null;
+  workspaceDomains: readonly string[];
+  /** Whether earlier mail to the addressee already reached this mailbox from several senders. */
+  isKnownAddressee: (address: string) => boolean;
+}): DeliveryFacts {
+  const addressedTo = addressedElsewhere(input);
+  return {
+    deliveredTo: input.deliveredTo?.toLocaleLowerCase() ?? null,
+    addressedTo,
+    knownAddressee: addressedTo ? input.isKnownAddressee(addressedTo) : false,
+    forwardedVia: forwardingRelay(input.authentication),
+  };
+}
+
+/**
+ * The warning for mail written for someone else. Plain Bcc and newsletters
+ * are not forwarded and stay quiet; a provider's account notice is suspicious
+ * even without visible forwarding, because those are never Bcc'd.
+ */
+export function addressedElsewhereWarning(delivery: DeliveryFacts | null, fromDomain: string | null) {
+  if (!delivery?.addressedTo || delivery.knownAddressee) return null;
+  const accountNotice = isAccountNoticeSender(fromDomain);
+  if (!delivery.forwardedVia && !accountNotice) return null;
+  // A provider forwarding its own user's mail (Gmail auto-forwarding needs the
+  // target to confirm) is likely the person's own setup.
+  const ownForwarding = delivery.forwardedVia !== null
+    && delivery.forwardedVia === organizationalDomain(delivery.addressedTo);
+  return {
+    kind: "addressed_elsewhere" as const,
+    severity: accountNotice && !ownForwarding ? "danger" as const : "caution" as const,
+    addressedTo: delivery.addressedTo,
+    forwardedVia: delivery.forwardedVia,
+    accountNotice,
+  };
+}

package/worker/mail/demo-routes.ts

@@ -0,0 +1,33 @@
+import { Hono } from "hono";
+import type { AppEnv } from "@open-workspace/core/worker/env.ts";
+import { apiError } from "@open-workspace/core/worker/lib/http.ts";
+import type { OneClickFetcher } from "./unsubscribe";
+
+/**
+ * Demo newsletters point their RFC 8058 endpoint at this reserved host. The
+ * unsubscribe route answers it in-process (never over the network), and
+ * only while mock authentication is enabled.
+ */
+export const DEMO_UNSUBSCRIBE_HOST = "unsubscribe.openworkspace-demo.invalid";
+
+export const demoRoutes = new Hono<AppEnv>()
+  .post("/list-unsubscribe/:token", async (c) => {
+    if (c.env.ALLOW_MOCK_AUTH !== "true") return apiError(c, 404, "NOT_FOUND", "Not found");
+    const body = new TextDecoder().decode(await c.req.arrayBuffer());
+    if (body.trim() !== "List-Unsubscribe=One-Click") {
+      return apiError(c, 400, "BAD_REQUEST", "Expected an RFC 8058 one-click body");
+    }
+    return c.text("You have been unsubscribed.");
+  });
+
+/** Real endpoints go to the network; the demo host is served by `demoRoutes`. */
+export function oneClickFetcher(env: Env): OneClickFetcher {
+  return (request) => {
+    const url = new URL(request.url);
+    if (env.ALLOW_MOCK_AUTH === "true" && url.hostname === DEMO_UNSUBSCRIBE_HOST) {
+      const local = new URL(`/list-unsubscribe${url.pathname.replace(/^\/[^/]*/u, "")}`, "http://demo.local");
+      return Promise.resolve(demoRoutes.fetch(new Request(local, request), env));
+    }
+    return fetch(request);
+  };
+}

package/worker/mail/doh.ts

@@ -0,0 +1,74 @@
+import type { LookupStatus } from "../../shared/mail-sender-intel";
+
+/**
+ * DNS-over-HTTPS (JSON API) client. Workers have no raw UDP, so every DNS
+ * lookup in sender intelligence goes through this one mockable function.
+ * https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-https/make-api-requests/dns-json/
+ */
+
+export const DOH_ENDPOINT = "https://cloudflare-dns.com/dns-query";
+
+export type DnsRecordType = "A" | "AAAA" | "PTR" | "TXT";
+
+const recordTypeCodes: Record<DnsRecordType, number> = { A: 1, AAAA: 28, PTR: 12, TXT: 16 };
+
+export type DnsAnswer = {
+  status: Exclude<LookupStatus, "skipped">;
+  /** Answer data of the requested type; TXT strings are unquoted and joined. */
+  records: string[];
+};
+
+export type DnsResolver = (name: string, type: DnsRecordType) => Promise<DnsAnswer>;
+
+type DohJson = {
+  Status?: number;
+  Answer?: Array<{ type?: number; data?: string }>;
+};
+
+/** `"v=BIMI1; " "l=https://…"` → `v=BIMI1; l=https://…` (RFC 7208 §3.3 joining). */
+export function txtData(value: string) {
+  const chunks = [...value.matchAll(/"((?:[^"\\]|\\.)*)"/gu)].map((match) =>
+    match[1]!.replace(/\\(.)/gu, "$1")
+  );
+  return chunks.length ? chunks.join("") : value;
+}
+
+export function isAbortError(error: unknown) {
+  return error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError");
+}
+
+export function createDohResolver(options: {
+  fetch?: typeof fetch;
+  signal?: AbortSignal;
+  endpoint?: string;
+} = {}): DnsResolver {
+  const fetcher = options.fetch ?? fetch;
+  const endpoint = options.endpoint ?? DOH_ENDPOINT;
+  return async (name, type) => {
+    if (options.signal?.aborted) return { status: "timeout", records: [] };
+    const url = new URL(endpoint);
+    url.searchParams.set("name", name);
+    url.searchParams.set("type", type);
+    try {
+      const response = await fetcher(url, {
+        headers: { accept: "application/dns-json" },
+        signal: options.signal,
+      });
+      if (!response.ok) return { status: "error", records: [] };
+      const body = await response.json() as DohJson;
+      if (body.Status === 3) return { status: "nxdomain", records: [] };
+      if (body.Status !== 0) return { status: "error", records: [] };
+      const code = recordTypeCodes[type];
+      const records = (body.Answer ?? [])
+        .filter((answer) => answer.type === code && typeof answer.data === "string")
+        .map((answer) => {
+          const data = answer.data!.trim();
+          if (type === "TXT") return txtData(data);
+          return data.replace(/\.$/u, "").toLocaleLowerCase();
+        });
+      return { status: "ok", records };
+    } catch (error) {
+      return { status: isAbortError(error) || options.signal?.aborted ? "timeout" : "error", records: [] };
+    }
+  };
+}