@open-workspace/email 0.0.0-stage → 0.1.1

package/shared/mail-received.ts

@@ -0,0 +1,298 @@
+import {
+  headerFields,
+  parseMailDate,
+  splitTopLevel,
+  trailingMailDate,
+} from "./mail-headers";
+
+/** The `by` host Cloudflare Email Routing writes on the hop it adds. */
+export const CLOUDFLARE_RECEIVED_BY = "cloudflare-email.net";
+
+export type ReceivedHop = {
+  /** HELO name the sending server announced. */
+  from: string | null;
+  /** Reverse DNS name the receiving server resolved, when it differs. */
+  reverseDns: string | null;
+  /** Connecting IP, taken from the `from` clause only. */
+  ip: string | null;
+  by: string | null;
+  protocol: string | null;
+  tls: string | null;
+  id: string | null;
+  at: Date | null;
+  /** Time since the nearest earlier hop with a parsed date. */
+  delayMs: number | null;
+  /** Negative clock difference absorbed into a zero delay. */
+  skewMs: number | null;
+  /**
+   * The hop Cloudflare added at the top of the message. Every other hop was
+   * written by the sending side and is only a claim.
+   */
+  trusted: boolean;
+};
+
+type Clause = {
+  words: string[];
+  comments: string[];
+  /** Number of words seen before the first comment of the clause. */
+  wordsBeforeComment: number | null;
+};
+const CLAUSE_KEYWORDS = new Set(["from", "by", "via", "with", "id", "for"]);
+
+/** Tokenizes the route part into keyword clauses at comment depth 0. */
+function routeClauses(route: string) {
+  const clauses = new Map<string, Clause>();
+  const state: { current: Clause | null; token: string; comment: string; depth: number } = {
+    current: null,
+    token: "",
+    comment: "",
+    depth: 0,
+  };
+  const flushToken = () => {
+    if (!state.token) return;
+    const keyword = state.token.toLocaleLowerCase();
+    if (CLAUSE_KEYWORDS.has(keyword) && !clauses.has(keyword)) {
+      state.current = { words: [], comments: [], wordsBeforeComment: null };
+      clauses.set(keyword, state.current);
+    } else {
+      state.current?.words.push(state.token);
+    }
+    state.token = "";
+  };
+  for (let index = 0; index < route.length; index += 1) {
+    const char = route[index]!;
+    if (char === "\\" && state.depth > 0) {
+      state.comment += route.slice(index, index + 2);
+      index += 1;
+      continue;
+    }
+    if (char === "(") {
+      if (state.depth === 0) flushToken();
+      else state.comment += char;
+      state.depth += 1;
+      continue;
+    }
+    if (char === ")" && state.depth > 0) {
+      state.depth -= 1;
+      if (state.depth === 0) {
+        const clause = state.current;
+        if (clause) {
+          clause.comments.push(state.comment.trim());
+          clause.wordsBeforeComment ??= clause.words.length;
+        }
+        state.comment = "";
+      } else {
+        state.comment += char;
+      }
+      continue;
+    }
+    if (state.depth > 0) {
+      state.comment += char;
+      continue;
+    }
+    if (/\s/u.test(char)) flushToken();
+    else state.token += char;
+  }
+  flushToken();
+  return clauses;
+}
+
+// --- IP addresses ---------------------------------------------------------
+
+function ipv4(value: string) {
+  const octets = value.split(".");
+  if (octets.length !== 4) return null;
+  if (!octets.every((octet) => /^\d{1,3}$/u.test(octet) && Number(octet) <= 255)) return null;
+  return octets.map(Number).join(".");
+}
+
+function ipv6(value: string) {
+  let text = value.toLocaleLowerCase().replace(/^ipv6:/u, "").replace(/%.*$/u, "");
+  let tail: number[] = [];
+  const v4 = /:(\d{1,3}(?:\.\d{1,3}){3})$/u.exec(text);
+  if (v4) {
+    const embedded = ipv4(v4[1]!);
+    if (!embedded) return null;
+    const [a, b, c, d] = embedded.split(".").map(Number) as [number, number, number, number];
+    tail = [(a << 8) | b, (c << 8) | d];
+    text = `${text.slice(0, v4.index)}:`;
+    if (text.endsWith("::")) text = text.slice(0, -1);
+    else text = text.slice(0, -1);
+  }
+  const halves = text.split("::");
+  if (halves.length > 2) return null;
+  const parse = (part: string) =>
+    part ? part.split(":").map((group) => (/^[0-9a-f]{1,4}$/u.test(group) ? Number.parseInt(group, 16) : Number.NaN)) : [];
+  const head = parse(halves[0]!);
+  const rest = halves.length === 2 ? parse(halves[1]!) : [];
+  const total = 8 - tail.length;
+  if ([...head, ...rest].some(Number.isNaN)) return null;
+  let groups: number[];
+  if (halves.length === 2) {
+    const missing = total - head.length - rest.length;
+    if (missing < 1) return null;
+    groups = [...head, ...Array<number>(missing).fill(0), ...rest];
+  } else {
+    if (head.length !== total) return null;
+    groups = head;
+  }
+  groups = [...groups, ...tail];
+  // RFC 5952: compress the longest run (length >= 2) of zero groups.
+  let bestStart = -1;
+  let bestLength = 0;
+  for (let start = 0; start < 8;) {
+    if (groups[start] !== 0) {
+      start += 1;
+      continue;
+    }
+    let end = start;
+    while (end < 8 && groups[end] === 0) end += 1;
+    if (end - start > bestLength && end - start >= 2) {
+      bestStart = start;
+      bestLength = end - start;
+    }
+    start = end;
+  }
+  const hex = groups.map((group) => group.toString(16));
+  if (bestStart < 0) return hex.join(":");
+  return `${hex.slice(0, bestStart).join(":")}::${hex.slice(bestStart + bestLength).join(":")}`;
+}
+
+/** Validates an IPv4 or IPv6 literal and returns its canonical form. */
+export function normalizeIp(value: string | null | undefined) {
+  if (!value) return null;
+  const trimmed = value.trim().replace(/^\[|\]$/gu, "");
+  return trimmed.includes(":") ? ipv6(trimmed) : ipv4(trimmed);
+}
+
+function fromClauseIp(clause: Clause) {
+  const parts = [clause.words.join(" "), ...clause.comments];
+  for (const part of parts) {
+    for (const match of part.matchAll(/\[(?:IPv6:)?([0-9a-f:.]+)\]/giu)) {
+      const ip = normalizeIp(match[1]);
+      if (ip) return { ip, part, literal: match[0] };
+    }
+  }
+  // Bare literals in parentheses: Cloudflare "(192.0.2.1)", Microsoft "(2603:…::12)".
+  for (const comment of clause.comments) {
+    const ip = normalizeIp(comment);
+    if (ip) return { ip, part: comment, literal: comment };
+  }
+  return null;
+}
+
+function heloName(clause: Clause) {
+  for (const comment of clause.comments) {
+    const helo = /\bhelo[= ]\s*([^\s)\]]+)/iu.exec(comment)?.[1];
+    if (helo) return helo;
+  }
+  const value = clause.words[0];
+  return value && !/^\[.*\]$/u.test(value) ? value : null;
+}
+
+function reverseDnsName(found: { part: string; literal: string } | null) {
+  if (!found || found.part === found.literal) return null;
+  const before = found.part.slice(0, found.part.indexOf(found.literal)).trim().split(/\s+/u).at(-1);
+  if (!before) return null;
+  const name = before.replace(/\.$/u, "");
+  if (name.toLocaleLowerCase() === "unknown" || !/^[a-z0-9][a-z0-9.-]*\.[a-z]{2,}$/iu.test(name)) {
+    return null;
+  }
+  return name;
+}
+
+function tlsDetails(value: string) {
+  const version = /\bversion=(TLS1_[0-3])\b/u.exec(value)?.[1]?.replace("_", ".")
+    ?? /\busing (TLSv1\.[0-3])\b/u.exec(value)?.[1]
+    ?? /\((TLS1\.[0-3])\)/u.exec(value)?.[1];
+  if (version) return version.replace(/^TLSv?/u, "TLS ");
+  if (/\bwith\s+(?:E?SMTPS|ESMTPSA|UTF8SMTPS)\b/iu.test(value)) return "TLS";
+  if (/\(Google Transport Security\)/u.test(value)) return "TLS";
+  if (/\bcipher[= ]/iu.test(value)) return "TLS";
+  return null;
+}
+
+type ParsedHop = Omit<ReceivedHop, "delayMs" | "skewMs" | "trusted">;
+
+export function parseReceived(value: string): ParsedHop {
+  const segments = splitTopLevel(value, ";");
+  let route: string;
+  let at: Date | null = null;
+  if (segments.length > 1) {
+    route = segments.slice(0, -1).join(";");
+    at = parseMailDate(segments.at(-1));
+  } else {
+    // SendGrid and some HTTP submission hops omit the `;` before the date.
+    const trailing = trailingMailDate(value);
+    at = trailing?.date ?? null;
+    route = trailing ? value.slice(0, trailing.index) : value;
+  }
+  const clauses = routeClauses(route);
+  const fromClause = clauses.get("from");
+  const found = fromClause ? fromClauseIp(fromClause) : null;
+  const from = fromClause ? heloName(fromClause) : null;
+  const reverseDns = reverseDnsName(found);
+  const withClause = clauses.get("with");
+  return {
+    from,
+    reverseDns: reverseDns && reverseDns.toLocaleLowerCase() !== from?.toLocaleLowerCase()
+      ? reverseDns
+      : null,
+    ip: found?.ip ?? null,
+    by: clauses.get("by")?.words[0] ?? null,
+    protocol: withClause?.words.length
+      ? withClause.words.slice(0, Math.min(withClause.wordsBeforeComment ?? withClause.words.length, 4)).join(" ") || null
+      : null,
+    tls: tlsDetails(value),
+    id: clauses.get("id")?.words[0] ?? null,
+    at,
+  };
+}
+
+export function isCloudflareHop(hop: Pick<ParsedHop, "by">) {
+  return hop.by?.toLocaleLowerCase() === CLOUDFLARE_RECEIVED_BY;
+}
+
+const MAX_SKEW_MS = 10 * 60_000;
+
+/** Received headers in delivery order: the sender's first relay first. */
+export function receivedHops(raw: string): ReceivedHop[] {
+  const values = headerFields(raw).flatMap((field) => field.name === "received" ? [field.value] : []);
+  const parsed = values.map(parseReceived);
+  const hops = parsed.map((hop, index) => ({
+    ...hop,
+    trusted: index === 0 && isCloudflareHop(hop),
+  })).reverse();
+  let previous: Date | null = null;
+  return hops.map((hop) => {
+    let delayMs: number | null = null;
+    let skewMs: number | null = null;
+    if (hop.at && previous) {
+      const delta = hop.at.getTime() - previous.getTime();
+      if (delta >= 0) delayMs = delta;
+      else if (-delta < MAX_SKEW_MS) {
+        delayMs = 0;
+        skewMs = delta;
+      }
+    }
+    // A skewed hop keeps the later reference so the next delay is not inflated.
+    if (hop.at && (!previous || (delayMs !== null && skewMs === null))) previous = hop.at;
+    return { ...hop, delayMs, skewMs };
+  });
+}
+
+export type IpKind = "public" | "private" | "loopback" | "reserved";
+
+/** Rough classification; enough to tell an internal hop from the internet. */
+export function ipKind(ip: string): IpKind {
+  const lower = ip.toLowerCase();
+  if (lower === "::1" || lower.startsWith("127.")) return "loopback";
+  if (/^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|f[cd][0-9a-f]{2}:|fe80:)/u.test(lower)) {
+    return "private";
+  }
+  // Documentation, shared and link-local ranges never appear on the open internet.
+  if (/^(192\.0\.2\.|198\.51\.100\.|203\.0\.113\.|100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.|169\.254\.|2001:db8:)/u.test(lower)) {
+    return "reserved";
+  }
+  return "public";
+}

package/shared/mail-remote.ts

@@ -0,0 +1,17 @@
+/** Same-origin proxy path used inside sanitized HTML iframes. */
+export function mailRemoteProxyPath(mailboxId: string, remoteUrl: string) {
+  const params = new URLSearchParams({
+    mailboxId,
+    url: remoteUrl,
+  });
+  return `/api/mail/remote?${params.toString()}`;
+}
+
+export function isRemoteHttpUrl(value: string) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}

package/shared/mail-rules.ts

@@ -0,0 +1,156 @@
+/**
+ * Deterministic per-mailbox filter rules ("Filter messages like this").
+ * Pure so the worker (ingestion, "apply to existing") and the browser (rule
+ * preview) share one definition of a match.
+ */
+
+export const MAX_MAIL_RULES = 100;
+
+export type MailRuleConditions = {
+  /** An address (exact) or a domain / `@domain` (domain and its subdomains). */
+  from?: string;
+  /** Matches any To or Cc recipient, with the same address/domain semantics. */
+  to?: string;
+  /** Case-insensitive substring of the subject. */
+  subjectContains?: string;
+  /** RFC 2919 list identifier, compared without angle brackets. */
+  listId?: string;
+  hasAttachment?: boolean;
+};
+
+export type MailRuleActions = {
+  /** Custom folder to file matching conversations in. */
+  folderId?: string;
+  archive?: boolean;
+  spam?: boolean;
+  markRead?: boolean;
+  /** Overrides the AI spam verdict (blocked senders still go to Spam). */
+  neverSpam?: boolean;
+};
+
+export type MailRule = {
+  id: string;
+  name: string;
+  enabled: boolean;
+  conditions: MailRuleConditions;
+  actions: MailRuleActions;
+};
+
+/** The facts a rule can look at, normalized by `ruleSubject`. */
+export type RuleSubject = {
+  from: string;
+  recipients: string[];
+  subject: string;
+  listId: string | null;
+  hasAttachment: boolean;
+};
+
+export type RuleDestination =
+  | { kind: "folder"; folderId: string }
+  | { kind: "archive" }
+  | { kind: "spam" };
+
+export type RuleOutcome = {
+  ruleIds: string[];
+  /** Set by the first matching rule that names one. */
+  destination: RuleDestination | null;
+  markRead: boolean;
+  neverSpam: boolean;
+};
+
+function lower(value: string | null | undefined) {
+  return (value ?? "").trim().toLocaleLowerCase();
+}
+
+export function normalizeListId(value: string | null | undefined) {
+  return lower(value).replace(/^.*<([^>]*)>.*$/u, "$1").trim() || null;
+}
+
+export function ruleSubject(input: {
+  from: string | null | undefined;
+  recipients: Array<string | null | undefined>;
+  subject: string | null | undefined;
+  listId: string | null | undefined;
+  hasAttachment: boolean;
+}): RuleSubject {
+  return {
+    from: lower(input.from),
+    recipients: input.recipients.map(lower).filter(Boolean),
+    subject: lower(input.subject),
+    listId: normalizeListId(input.listId),
+    hasAttachment: input.hasAttachment,
+  };
+}
+
+/** `alex@x.com` matches exactly; `x.com` or `@x.com` matches x.com and *.x.com. */
+export function addressMatches(pattern: string, address: string) {
+  const value = lower(pattern);
+  if (!value || !address) return false;
+  if (value.includes("@") && !value.startsWith("@")) return address === value;
+  const domain = value.replace(/^@/u, "");
+  const at = address.lastIndexOf("@");
+  const host = at >= 0 ? address.slice(at + 1) : address;
+  return host === domain || host.endsWith(`.${domain}`);
+}
+
+export function hasConditions(conditions: MailRuleConditions) {
+  return Boolean(
+    lower(conditions.from)
+    || lower(conditions.to)
+    || lower(conditions.subjectContains)
+    || lower(conditions.listId)
+    || conditions.hasAttachment,
+  );
+}
+
+export function hasActions(actions: MailRuleActions) {
+  return Boolean(actions.folderId || actions.archive || actions.spam || actions.markRead || actions.neverSpam);
+}
+
+/** Every present condition must hold; a rule without conditions never matches. */
+export function ruleMatches(conditions: MailRuleConditions, subject: RuleSubject) {
+  if (!hasConditions(conditions)) return false;
+  if (lower(conditions.from) && !addressMatches(conditions.from!, subject.from)) return false;
+  if (lower(conditions.to) && !subject.recipients.some((address) => addressMatches(conditions.to!, address))) {
+    return false;
+  }
+  const needle = lower(conditions.subjectContains);
+  if (needle && !subject.subject.includes(needle)) return false;
+  const listId = normalizeListId(conditions.listId);
+  if (listId && subject.listId !== listId) return false;
+  if (conditions.hasAttachment && !subject.hasAttachment) return false;
+  return true;
+}
+
+export function ruleDestination(actions: MailRuleActions): RuleDestination | null {
+  if (actions.spam) return { kind: "spam" };
+  if (actions.archive) return { kind: "archive" };
+  if (actions.folderId) return { kind: "folder", folderId: actions.folderId };
+  return null;
+}
+
+/** Rules run in order; all matches contribute flags, the first destination wins. */
+export function evaluateRules(rules: readonly MailRule[], subject: RuleSubject): RuleOutcome {
+  const outcome: RuleOutcome = { ruleIds: [], destination: null, markRead: false, neverSpam: false };
+  for (const rule of rules) {
+    if (!rule.enabled || !ruleMatches(rule.conditions, subject)) continue;
+    outcome.ruleIds.push(rule.id);
+    outcome.destination ??= ruleDestination(rule.actions);
+    outcome.markRead ||= Boolean(rule.actions.markRead);
+    outcome.neverSpam ||= Boolean(rule.actions.neverSpam);
+  }
+  // "Never spam" from any matching rule overrides a later rule's Spam action.
+  if (outcome.neverSpam && outcome.destination?.kind === "spam") outcome.destination = null;
+  return outcome;
+}
+
+/** Short human description, e.g. "From @hireline.example · Subject contains "alert"". */
+export function describeConditions(conditions: MailRuleConditions) {
+  const parts: string[] = [];
+  if (lower(conditions.from)) parts.push(`From ${conditions.from!.trim()}`);
+  if (lower(conditions.to)) parts.push(`To ${conditions.to!.trim()}`);
+  if (lower(conditions.subjectContains)) parts.push(`Subject contains “${conditions.subjectContains!.trim()}”`);
+  if (lower(conditions.listId)) parts.push(`List ${normalizeListId(conditions.listId)}`);
+  if (conditions.hasAttachment) parts.push("Has attachment");
+  return parts.join(" · ");
+}

package/shared/mail-sender-intel.ts

@@ -0,0 +1,125 @@
+/**
+ * Point-in-time facts about the server that delivered an inbound message,
+ * gathered over DNS-over-HTTPS at ingestion (or lazily on first view) by
+ * `worker/mail/sender-intel.ts`. Every lookup fails open with its own status.
+ */
+
+export type LookupStatus = "ok" | "nxdomain" | "timeout" | "error" | "skipped";
+
+export type SpamhausZone = "zen" | "dbl";
+
+export type SpamhausListing = {
+  zone: SpamhausZone;
+  /** The IP (ZEN) or registrable domain (DBL) that is listed. */
+  target: string;
+  /** Return code, e.g. 127.0.0.2 or 127.0.1.4. */
+  code: string;
+  /** Human-readable list name, e.g. "SBL" or "DBL phishing domain". */
+  list: string;
+  /** "policy" listings (PBL) describe address space, not abuse. */
+  severity: "abuse" | "policy";
+};
+
+export type SpamhausCheck = {
+  status: LookupStatus;
+  listings: SpamhausListing[];
+  /** Set when Spamhaus answered with a 127.255.255.x error code. */
+  error: string | null;
+};
+
+export type SpamhausResult = {
+  zen: SpamhausCheck;
+  dbl: SpamhausCheck & { domains: string[] };
+};
+
+export type BimiStatus = "ok" | "none" | "invalid" | "error";
+
+export type BimiResult = {
+  /** Domain whose BIMI record was used (From domain or its organizational domain). */
+  domain: string;
+  status: BimiStatus;
+  /** Why no logo is shown, for "Show original". */
+  reason: string | null;
+};
+
+export type SenderIntel = {
+  version: 1;
+  /** "demo" rows carry pre-computed values instead of live lookups. */
+  source: "live" | "demo";
+  checkedAt: number;
+  ip: string | null;
+  ipVersion: 4 | 6 | null;
+  ptr: {
+    status: LookupStatus;
+    names: string[];
+    /** The PTR name whose A/AAAA records contain the IP. */
+    confirmed: string | null;
+    /** Forward-confirmed reverse DNS. */
+    fcrdns: boolean | null;
+    /** The name looks like an auto-generated access-network name. */
+    generic: boolean | null;
+  };
+  /** HELO equals a PTR name or shares its organizational domain. */
+  heloMatchesPtr: boolean | null;
+  network: {
+    status: LookupStatus;
+    asn: number | null;
+    asName: string | null;
+    prefix: string | null;
+    /** ISO 3166-1 alpha-2, uppercase. */
+    country: string | null;
+    registry: string | null;
+  };
+  /** Present only when an administrator configured a Spamhaus DQS key. */
+  spamhaus: SpamhausResult | null;
+  /** Present only when DMARC passed with an enforcing policy. */
+  bimi: BimiResult | null;
+};
+
+export type SecurityWarning =
+  | {
+      kind: "dbl_listed";
+      severity: "danger";
+      domains: string[];
+      lists: string[];
+      /** The From domain itself is listed, not only a link domain. */
+      senderDomain: boolean;
+    }
+  | { kind: "zen_listed"; severity: "danger" | "caution"; ip: string; lists: string[] }
+  | { kind: "lookalike_domain"; severity: "danger"; domain: string; resembles: string }
+  | { kind: "display_name_impersonation"; severity: "danger"; name: string }
+  | { kind: "embedded_address"; severity: "caution"; claimed: string }
+  | { kind: "unverified_sender"; severity: "caution"; domain: string | null }
+  /** Replies go to another organization than the one in From. */
+  | { kind: "reply_to_mismatch"; severity: "caution"; address: string; domain: string }
+  /**
+   * Written for another address and forwarded here. Danger when it is an
+   * account notice from a large provider about someone else's account.
+   */
+  | {
+      kind: "addressed_elsewhere";
+      severity: "danger" | "caution";
+      addressedTo: string;
+      forwardedVia: string | null;
+      accountNotice: boolean;
+    };
+
+/** Who a message was written for and how it reached this mailbox, recorded at ingestion. */
+export type DeliveryFacts = {
+  /** The RCPT TO this mailbox received the message at. */
+  deliveredTo: string | null;
+  /** First To/Cc address when none of them is this mailbox or a workspace address. */
+  addressedTo: string | null;
+  /** Mail to that address reached this mailbox from several senders before (the person's own forwarding). */
+  knownAddressee: boolean;
+  /** Organization that relayed the message after the author's server, when forwarding is evident. */
+  forwardedVia: string | null;
+};
+
+export type SecurityWarningKind = SecurityWarning["kind"];
+
+/** Country flag emoji from an ISO 3166-1 alpha-2 code. */
+export function countryFlag(code: string | null | undefined) {
+  if (!code || !/^[A-Z]{2}$/u.test(code)) return null;
+  return String.fromCodePoint(...[...code].map((char) => 0x1f1e6 + char.charCodeAt(0) - 65));
+}

package/shared/mail-translation.ts

@@ -0,0 +1,2 @@
+export const MAX_TRANSLATION_CHARACTERS = 100_000;
+export const MAX_TRANSLATION_SEGMENTS = 500;