@open-workspace/email 0.0.0-stage → 0.1.1

package/worker/mail/search.ts

@@ -0,0 +1,14 @@
+const SEARCH_TOKEN_PATTERN = /[\p{L}\p{N}]+/gu;
+const MAX_SEARCH_TOKENS = 24;
+
+/**
+ * User input never reaches FTS5 query syntax directly. Each Unicode word is
+ * quoted and treated as a prefix, which supports partial names and addresses.
+ */
+export function buildEmailSearchQuery(value: string) {
+  const tokens = value.normalize("NFKC").match(SEARCH_TOKEN_PATTERN) ?? [];
+  const unique = [...new Set(tokens)].slice(0, MAX_SEARCH_TOKENS);
+  return unique.length
+    ? unique.map((token) => `"${token}"*`).join(" AND ")
+    : null;
+}

package/worker/mail/security-settings.ts

@@ -0,0 +1,38 @@
+import { inArray, isNotNull } from "drizzle-orm";
+import { createDb } from "@open-workspace/core/worker/db/client.ts";
+import { domains, mailboxes, users } from "@open-workspace/core/worker/db/schema.ts";
+import { protectedNames } from "./impersonation";
+import { DQS_KEY_PATTERN } from "./spamhaus";
+
+/** Workspace-wide inputs for sender checks, read from D1 once per request or delivery. */
+export type WorkspaceIdentity = {
+  domains: string[];
+  /** Normalized internal person name → display form. */
+  names: Map<string, string>;
+};
+
+export async function workspaceIdentity(binding: D1Database): Promise<WorkspaceIdentity> {
+  const db = createDb(binding);
+  const [domainRows, userRows, mailboxRows] = await db.batch([
+    db.select({ name: domains.name }).from(domains),
+    db.select({ name: users.name }).from(users).where(inArray(users.status, ["active", "invited"])),
+    // Shared mailboxes ("Support", "Customer care") are generic names that
+    // vendors use too; only personal mailboxes name a person.
+    db.select({ name: mailboxes.displayName }).from(mailboxes).where(isNotNull(mailboxes.ownerUserId)),
+  ]);
+  return {
+    domains: domainRows.map((row) => row.name.toLocaleLowerCase()),
+    names: protectedNames([...userRows, ...mailboxRows].map((row) => row.name)),
+  };
+}
+
+/** The Spamhaus DQS key from the SPAMHAUS_DQS_KEY secret, when set and well-formed. */
+export function spamhausDqsKey(env: { SPAMHAUS_DQS_KEY?: string }) {
+  const key = env.SPAMHAUS_DQS_KEY?.trim().toLowerCase();
+  if (!key) return null;
+  if (!DQS_KEY_PATTERN.test(key)) {
+    console.error("SPAMHAUS_DQS_KEY is not a Spamhaus DQS key; blocklist checks are off");
+    return null;
+  }
+  return key;
+}

package/worker/mail/sender-intel.ts

@@ -0,0 +1,189 @@
+import type { InboundAuthentication } from "../../shared/mail-authentication";
+import { ipKind, normalizeIp } from "../../shared/mail-received";
+import type {
+  BimiResult,
+  LookupStatus,
+  SenderIntel,
+  SpamhausResult,
+} from "../../shared/mail-sender-intel";
+import { resolveBimi } from "./bimi";
+import { createDohResolver, type DnsResolver } from "./doh";
+import { heloMatchesPtr, ipIntelCacheTtl, lookupIpIntel, type IpIntel } from "./ip-intel";
+import { MAX_LINK_DOMAINS } from "./link-domains";
+import { isWorkspaceDomain } from "./message-security";
+import { organizationalDomain } from "./org-domain";
+import { checkSpamhaus } from "./spamhaus";
+
+export const SENDER_INTEL_BUDGET_MS = 1_500;
+const MEMORY_CACHE_LIMIT = 500;
+const CACHE_ORIGIN = "https://sender-intel.openworkspace.invalid";
+
+export type IntelCache = {
+  get(ip: string): Promise<IpIntel | null>;
+  put(ip: string, intel: IpIntel, ttlSeconds: number): Promise<void>;
+};
+
+const memory = new Map<string, { intel: IpIntel; expiresAt: number }>();
+
+/**
+ * Isolate memory first, then the colo-local Cache API under a synthetic URL.
+ * Both are best effort: a failing cache never fails ingestion.
+ */
+export function defaultIntelCache(): IntelCache {
+  const request = (ip: string) => new Request(`${CACHE_ORIGIN}/ip/v1/${encodeURIComponent(ip)}`);
+  const open = async () => {
+    try {
+      return await caches.open("openworkspace:sender-intel");
+    } catch {
+      return null;
+    }
+  };
+  return {
+    async get(ip) {
+      const hit = memory.get(ip);
+      if (hit && hit.expiresAt > Date.now()) return hit.intel;
+      try {
+        const response = await (await open())?.match(request(ip));
+        return response ? await response.json() as IpIntel : null;
+      } catch {
+        return null;
+      }
+    },
+    async put(ip, intel, ttlSeconds) {
+      if (memory.size >= MEMORY_CACHE_LIMIT) memory.delete(memory.keys().next().value!);
+      memory.set(ip, { intel, expiresAt: Date.now() + ttlSeconds * 1_000 });
+      try {
+        await (await open())?.put(request(ip), new Response(JSON.stringify(intel), {
+          headers: { "content-type": "application/json", "cache-control": `max-age=${ttlSeconds}` },
+        }));
+      } catch {
+        // Best effort only.
+      }
+    },
+  };
+}
+
+function skippedIpIntel(status: LookupStatus): IpIntel {
+  return {
+    ptr: { status, names: [], confirmed: null, fcrdns: null, generic: null },
+    network: { status, asn: null, asName: null, prefix: null, country: null, registry: null },
+  };
+}
+
+/** Resolves to `fallback` once the deadline passes, even if the work ignores the abort signal. */
+function withDeadline<T>(work: Promise<T>, signal: AbortSignal, fallback: () => T): Promise<T> {
+  return new Promise((resolve) => {
+    const onAbort = () => resolve(fallback());
+    if (signal.aborted) return onAbort();
+    signal.addEventListener("abort", onAbort, { once: true });
+    work.then(resolve, () => resolve(fallback())).finally(() => signal.removeEventListener("abort", onAbort));
+  });
+}
+
+/** BIMI applies only when DMARC passed under p=quarantine or p=reject. */
+export function bimiEligible(authentication: InboundAuthentication | null) {
+  const dmarc = authentication?.dmarc;
+  return Boolean(
+    authentication?.fromDomain
+      && dmarc?.result === "pass"
+      && (dmarc.policy === "quarantine" || dmarc.policy === "reject"),
+  );
+}
+
+/**
+ * Sending-server intelligence for one message: PTR + FCrDNS and Team Cymru
+ * ASN data for the trusted remote IP, Spamhaus ZEN/DBL when a DQS key is
+ * configured, and the BIMI logo. All lookups run in parallel under one
+ * budget and fail open with a per-field status.
+ */
+export async function collectSenderIntel(input: {
+  authentication: InboundAuthentication | null;
+  fromAddress: string;
+  linkDomains: string[];
+  workspaceDomains: readonly string[];
+  dqsKey: string | null;
+  bucket: R2Bucket;
+  fetch?: typeof fetch;
+  resolver?: DnsResolver;
+  cache?: IntelCache;
+  budgetMs?: number;
+  now?: number;
+}): Promise<SenderIntel> {
+  const now = input.now ?? Date.now();
+  const signal = AbortSignal.timeout(input.budgetMs ?? SENDER_INTEL_BUDGET_MS);
+  const resolve = input.resolver ?? createDohResolver({ fetch: input.fetch, signal });
+  const cache = input.cache ?? defaultIntelCache();
+  const auth = input.authentication;
+  const ip = normalizeIp(auth?.remoteIp);
+  const publicIp = ip && ipKind(ip) === "public" ? ip : null;
+
+  const ipWork = publicIp
+    ? withDeadline((async () => {
+        const cached = await cache.get(publicIp);
+        if (cached) return cached;
+        const fresh = await lookupIpIntel(resolve, publicIp);
+        const ttl = ipIntelCacheTtl(fresh);
+        if (ttl > 0) await cache.put(publicIp, fresh, ttl);
+        return fresh;
+      })(), signal, () => skippedIpIntel("timeout"))
+    : Promise.resolve(skippedIpIntel("skipped"));
+
+  const fromOrg = organizationalDomain(input.fromAddress);
+  const dblDomains = [...new Set([fromOrg, ...input.linkDomains])]
+    .filter((domain): domain is string => Boolean(domain) && !isWorkspaceDomain(domain, input.workspaceDomains))
+    .slice(0, MAX_LINK_DOMAINS);
+  const spamhausWork: Promise<SpamhausResult | null> = input.dqsKey
+    ? withDeadline(
+        checkSpamhaus({ resolve, key: input.dqsKey, ip: publicIp, domains: dblDomains }),
+        signal,
+        () => ({
+          zen: { status: "timeout", listings: [], error: null },
+          dbl: { status: "timeout", listings: [], error: null, domains: dblDomains },
+        }),
+      )
+    : Promise.resolve(null);
+
+  const fromDomain = auth?.fromDomain ?? null;
+  const bimiWork: Promise<BimiResult | null> = bimiEligible(auth) && fromDomain
+    ? withDeadline(
+        resolveBimi({
+          resolve,
+          fetch: input.fetch,
+          bucket: input.bucket,
+          fromDomain,
+          orgDomain: organizationalDomain(fromDomain),
+          signal,
+          now,
+        }),
+        signal,
+        () => ({ domain: fromDomain, status: "error", reason: "The BIMI lookup timed out" }),
+      )
+    : Promise.resolve(null);
+
+  const [ipIntel, spamhaus, bimi] = await Promise.all([ipWork, spamhausWork, bimiWork]);
+  return {
+    version: 1,
+    source: "live",
+    checkedAt: now,
+    ip,
+    ipVersion: ip ? (ip.includes(":") ? 6 : 4) : null,
+    ...ipIntel,
+    heloMatchesPtr: heloMatchesPtr(auth?.helo ?? null, ipIntel.ptr),
+    spamhaus,
+    bimi,
+  };
+}
+
+/** Lazy fills skip persisting a result where every attempted lookup failed. */
+export function senderIntelWorthStoring(intel: SenderIntel) {
+  const statuses: LookupStatus[] = [intel.ptr.status, intel.network.status];
+  if (intel.spamhaus) statuses.push(intel.spamhaus.zen.status, intel.spamhaus.dbl.status);
+  const attempted = statuses.filter((status) => status !== "skipped");
+  return !attempted.length || attempted.some((status) => status === "ok" || status === "nxdomain");
+}
+
+export function storedSenderIntel(value: unknown): SenderIntel | null {
+  return value && typeof value === "object" && (value as { version?: unknown }).version === 1
+    ? value as SenderIntel
+    : null;
+}

package/worker/mail/spamhaus.ts

@@ -0,0 +1,97 @@
+import type {
+  SpamhausCheck,
+  SpamhausListing,
+  SpamhausResult,
+} from "../../shared/mail-sender-intel";
+import type { DnsAnswer, DnsResolver } from "./doh";
+import { reversedIp } from "./ip-intel";
+
+/**
+ * Spamhaus Data Query Service: the customer key is part of the zone name, so
+ * the lists answer through any resolver, including DoH. Public-resolver
+ * queries against the legacy zones only return 127.255.255.254.
+ * https://docs.spamhaus.com/datasets/docs/source/40-real-world-usage/PublicMirrors/MTAs/020-Postfix.html
+ */
+
+export const DQS_KEY_PATTERN = /^[a-z0-9]{20,40}$/u;
+
+const zenCodes: Record<string, Pick<SpamhausListing, "list" | "severity">> = {
+  "127.0.0.2": { list: "SBL (spam source)", severity: "abuse" },
+  "127.0.0.3": { list: "SBL CSS (snowshoe spam)", severity: "abuse" },
+  "127.0.0.4": { list: "XBL (compromised host)", severity: "abuse" },
+  "127.0.0.5": { list: "XBL (compromised host)", severity: "abuse" },
+  "127.0.0.6": { list: "XBL (compromised host)", severity: "abuse" },
+  "127.0.0.7": { list: "XBL (compromised host)", severity: "abuse" },
+  "127.0.0.9": { list: "DROP (hijacked network)", severity: "abuse" },
+  "127.0.0.10": { list: "PBL (ISP end-user range)", severity: "policy" },
+  "127.0.0.11": { list: "PBL (end-user range)", severity: "policy" },
+};
+
+const dblCodes: Record<string, string> = {
+  "127.0.1.2": "spam domain",
+  "127.0.1.4": "phishing domain",
+  "127.0.1.5": "malware domain",
+  "127.0.1.6": "botnet C&C domain",
+  "127.0.1.102": "abused legitimate domain (spam)",
+  "127.0.1.103": "abused redirector or shortener",
+  "127.0.1.104": "abused legitimate domain (phishing)",
+  "127.0.1.105": "abused legitimate domain (malware)",
+  "127.0.1.106": "abused legitimate domain (botnet C&C)",
+};
+
+const errorCodes: Record<string, string> = {
+  "127.255.255.252": "The query was malformed",
+  "127.255.255.254": "Queried through a public resolver without a DQS key",
+  "127.255.255.255": "Query limit exceeded for this key",
+};
+
+/** 127.255.255.x is never a listing: it reports a problem with the query itself. */
+export function spamhausErrorCode(code: string) {
+  return code.startsWith("127.255.255.") ? errorCodes[code] ?? "Spamhaus returned an error code" : null;
+}
+
+function interpret(
+  zone: "zen" | "dbl",
+  target: string,
+  answer: DnsAnswer,
+): Omit<SpamhausCheck, "status"> & { status: SpamhausCheck["status"] } {
+  if (answer.status === "nxdomain") return { status: "ok", listings: [], error: null };
+  if (answer.status !== "ok") return { status: answer.status, listings: [], error: null };
+  const error = answer.records.map(spamhausErrorCode).find(Boolean) ?? null;
+  if (error) return { status: "error", listings: [], error };
+  const listings = answer.records.flatMap((code): SpamhausListing[] => {
+    if (zone === "zen") {
+      const known = zenCodes[code];
+      return known ? [{ zone, target, code, ...known }] : [];
+    }
+    const list = dblCodes[code];
+    return list ? [{ zone, target, code, list: `DBL ${list}`, severity: "abuse" }] : [];
+  });
+  return { status: "ok", listings, error: null };
+}
+
+function merge(checks: SpamhausCheck[]): SpamhausCheck {
+  const failed = checks.find((check) => check.status !== "ok");
+  return {
+    status: checks.length === 0 ? "skipped" : failed && checks.every((check) => check.status !== "ok") ? failed.status : "ok",
+    listings: checks.flatMap((check) => check.listings),
+    error: checks.map((check) => check.error).find(Boolean) ?? null,
+  };
+}
+
+export async function checkSpamhaus(input: {
+  resolve: DnsResolver;
+  key: string;
+  ip: string | null;
+  domains: string[];
+}): Promise<SpamhausResult> {
+  const zen = input.ip
+    ? input.resolve(`${reversedIp(input.ip)}.${input.key}.zen.dq.spamhaus.net`, "A")
+        .then((answer) => interpret("zen", input.ip!, answer))
+    : Promise.resolve<SpamhausCheck>({ status: "skipped", listings: [], error: null });
+  const dbl = Promise.all(input.domains.map(async (domain) =>
+    interpret("dbl", domain, await input.resolve(`${domain}.${input.key}.dbl.dq.spamhaus.net`, "A"))
+  ));
+  const [zenResult, dblResults] = await Promise.all([zen, dbl]);
+  return { zen: zenResult, dbl: { ...merge(dblResults), domains: input.domains } };
+}

package/worker/mail/unsubscribe.ts

@@ -0,0 +1,118 @@
+import { normalizeListId } from "../../shared/mail-rules";
+import { organizationalDomain } from "./org-domain";
+
+export const ONE_CLICK_TIMEOUT_MS = 10_000;
+const USER_AGENT = "OpenWorkspace-Unsubscribe/1.0";
+
+export type OneClickFetcher = (request: Request) => Promise<Response>;
+
+export type OneClickResult =
+  | { ok: true; status: number; redirected: boolean }
+  | { ok: false; status: number | null; detail: string };
+
+/** One unsubscribe record per list: its List-Id, else the sender's organizational domain. */
+export function unsubscribeListKey(input: { listId: string | null; fromAddress: string | null }) {
+  const listId = normalizeListId(input.listId);
+  if (listId) return `list:${listId}`;
+  const domain = organizationalDomain(input.fromAddress);
+  return domain ? `domain:${domain}` : null;
+}
+
+function isOneClickUrl(value: string) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && !url.username && !url.password;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * RFC 8058 one-click: a single POST with the fixed form body. No cookies or
+ * credentials, no redirects followed, never a GET, bounded by a timeout.
+ * A 3xx violates the RFC but usually means the request was processed.
+ */
+export async function postOneClick(
+  url: string,
+  fetcher: OneClickFetcher = (request) => fetch(request),
+  timeoutMs = ONE_CLICK_TIMEOUT_MS,
+): Promise<OneClickResult> {
+  if (!isOneClickUrl(url)) return { ok: false, status: null, detail: "The unsubscribe address is not HTTPS" };
+  const request = new Request(url, {
+    method: "POST",
+    body: "List-Unsubscribe=One-Click",
+    headers: {
+      "content-type": "application/x-www-form-urlencoded",
+      "user-agent": USER_AGENT,
+    },
+    redirect: "manual",
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  try {
+    const response = await fetcher(request);
+    // Nothing in the body is used; release it promptly.
+    await response.body?.cancel().catch(() => undefined);
+    if (response.status >= 200 && response.status < 300) {
+      return { ok: true, status: response.status, redirected: false };
+    }
+    if (response.status >= 300 && response.status < 400) {
+      return { ok: true, status: response.status, redirected: true };
+    }
+    return { ok: false, status: response.status, detail: `The sender's server answered ${response.status}` };
+  } catch (error) {
+    const timedOut = error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
+    return {
+      ok: false,
+      status: null,
+      detail: timedOut ? "The sender's server did not answer in time" : "Could not reach the sender's server",
+    };
+  }
+}
+
+export type MailtoUnsubscribe = { to: string; subject: string; body: string };
+
+/**
+ * Recipient, subject and body of a `mailto:` unsubscribe URI. Other header
+ * fields (cc, bcc, …) are ignored so the request reaches only the list.
+ */
+export function parseMailtoUnsubscribe(uri: string): MailtoUnsubscribe | null {
+  let url: URL;
+  try {
+    url = new URL(uri);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "mailto:") return null;
+  let to: string;
+  try {
+    to = decodeURIComponent(url.pathname).trim();
+  } catch {
+    return null;
+  }
+  if (!/^[^\s@,<>]+@[^\s@,<>]+\.[^\s@,<>]+$/u.test(to) || to.length > 254) return null;
+  // RFC 6068 percent-encodes everything; "+" is a literal plus, not a space.
+  const pairs = url.search.slice(1).split("&").flatMap((pair) => {
+    const [key = "", value = ""] = pair.split("=", 2);
+    try {
+      return [[decodeURIComponent(key).toLocaleLowerCase(), decodeURIComponent(value)] as const];
+    } catch {
+      return [];
+    }
+  });
+  const field = (name: string) =>
+    pairs.find(([key]) => key === name)?.[1].replace(/[\r\n]+/gu, " ").trim() ?? "";
+  return {
+    to,
+    subject: field("subject").slice(0, 200) || "unsubscribe",
+    body: field("body").slice(0, 2_000) || "unsubscribe",
+  };
+}
+
+export function oneClickHost(url: string | null) {
+  if (!url) return null;
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return null;
+  }
+}