@open-workspace/email 0.0.0-stage → 0.1.1

package/shared/mail-authentication.ts

@@ -0,0 +1,145 @@
+/**
+ * Sender authentication as reported by Cloudflare Email Routing in the
+ * headers it prepends to every inbound message. Parsed at ingestion (or
+ * lazily from the stored original) by `worker/mail/auth-headers.ts`.
+ */
+
+export const authResults = [
+  "pass",
+  "fail",
+  "softfail",
+  "neutral",
+  "none",
+  "temperror",
+  "permerror",
+  "policy",
+] as const;
+export type AuthResult = (typeof authResults)[number];
+
+export type DmarcPolicy = "none" | "quarantine" | "reject";
+
+export type DkimResult = {
+  result: AuthResult;
+  /** Signing domain: `header.d`, or the domain of `header.i`. */
+  domain: string;
+  identity: string | null;
+  selector: string | null;
+  /** RFC 6008 `header.b` prefix used to find the matching DKIM-Signature. */
+  bPrefix: string | null;
+  /** Organizational domain equals the From organizational domain. */
+  aligned: boolean;
+  /** Lowercased `h=` list of the matching DKIM-Signature, when found. */
+  signedHeaders: string[] | null;
+};
+
+/** One sender-reported Authentication-Results header, shown but never trusted. */
+export type UpstreamAuthenticationClaim = {
+  authservId: string;
+  spf: AuthResult | null;
+  dkim: AuthResult | null;
+  dmarc: AuthResult | null;
+};
+
+export type ArcSealer = {
+  instance: number;
+  domain: string | null;
+  cv: string | null;
+};
+
+export type SenderVerdict = "verified" | "unverified" | "suspicious" | "unavailable";
+
+export type SenderVerdictReason =
+  | "dmarc_pass"
+  | "aligned_dkim"
+  | "forwarded_arc"
+  | "dmarc_fail"
+  | "no_aligned_pass"
+  | "partial"
+  | "not_cloudflare"
+  | "missing_results";
+
+export type InboundAuthentication = {
+  source: "headers";
+  version: 1;
+  /** authserv-id of the trusted Authentication-Results (mx.cloudflare.net). */
+  authservId: string | null;
+  parsedAt: number;
+  /** smtp.remote-ip, else Received-SPF client-ip, else the Cloudflare hop IP. */
+  remoteIp: string | null;
+  helo: string | null;
+  /** SMTP MAIL FROM (smtp.mailfrom / Received-SPF envelope-from). */
+  envelopeFrom: string | null;
+  /** Domain of the RFC 5322 From address the results were aligned against. */
+  fromDomain: string | null;
+  spf: { result: AuthResult; domain: string | null; aligned: boolean } | null;
+  spfHelo: { result: AuthResult; domain: string | null } | null;
+  dkim: DkimResult[];
+  dmarc: {
+    result: AuthResult;
+    headerFrom: string | null;
+    policy: DmarcPolicy | null;
+    alignedVia: Array<"spf" | "dkim">;
+  } | null;
+  arc: {
+    result: "pass" | "fail" | "none";
+    /** Instance of Cloudflare's own ARC set; i > 1 means an upstream chain exists. */
+    chainLength: number;
+    /** Earlier sealers (display only; Cloudflare validated the chain when result is pass). */
+    sealers: ArcSealer[];
+    /** Results recorded by the oldest sealer, when ARC passed. */
+    oldest: UpstreamAuthenticationClaim | null;
+  } | null;
+  /** X-CF-SpamH-Score, 0..5. Experimental and passive per Cloudflare. */
+  spamScore: number | null;
+  verdict: SenderVerdict;
+  verdictReason: SenderVerdictReason;
+  /** Authentication-Results headers below the trusted block (sender-supplied). */
+  upstream: UpstreamAuthenticationClaim[];
+  /** Headers below the trusted block that claimed to come from Cloudflare. */
+  ignoredCloudflareClaims: number;
+  /** Raw trusted Authentication-Results value, capped. */
+  trustedHeader: string | null;
+};
+
+export type ListUnsubscribeReason =
+  | "invalid-uri"
+  | "no-https"
+  | "no-post"
+  | "unsigned"
+  | "unaligned"
+  | "post-not-signed";
+
+export type ListUnsubscribe = {
+  httpsUrl: string | null;
+  mailto: string | null;
+  /** RFC 8058 one-click, and the signature covering both headers is aligned with From. */
+  oneClick: boolean;
+  /** Why one-click is not offered; null when it is. */
+  reason: ListUnsubscribeReason | null;
+};
+
+/** Compact sender summary returned with every message. */
+export type MessageSecurity = {
+  verdict: SenderVerdict;
+  verdictReason: SenderVerdictReason;
+  fromDomain: string | null;
+  /** Domain of the SMTP envelope sender (Gmail's "mailed-by"). */
+  mailedBy: string | null;
+  /** Passing DKIM domain, preferring the aligned one (Gmail's "signed-by"). */
+  signedBy: string | null;
+  /** Gmail's "via": shown when neither mailed-by nor signed-by aligns with From. */
+  via: string | null;
+  /** Organization that forwarded the message to this mailbox, when evident. */
+  forwardedVia: string | null;
+  /** The From domain is not one of this workspace's domains. */
+  external: boolean;
+  listUnsubscribe: ListUnsubscribe | null;
+  /** Most serious first; the reader merges them into one banner. */
+  warnings: import("./mail-sender-intel").SecurityWarning[];
+  /** First message from this external address, and this mailbox never wrote to it. */
+  firstTimeSender: boolean;
+  /** Reply-To points at another organization than From (and the message is not from a list). */
+  replyToMismatch: { address: string; domain: string } | null;
+  /** Someone in this mailbox marked the sender as trusted; caution hints are hidden. */
+  trusted: boolean;
+};

package/shared/mail-feedback.ts

@@ -0,0 +1,90 @@
+/**
+ * Per-mailbox sender decisions (block, trust, reports) and unsubscribe
+ * records, as returned with every incoming message.
+ */
+
+export type ReportKind = "spam" | "phishing";
+
+export type FeedbackLabel = ReportKind | "not_spam";
+
+export type SenderBlock = {
+  /** The stored pattern: an address, or `@domain` for the whole domain. */
+  pattern: string;
+  scope: "address" | "domain";
+  /** Workspace-wide blocks are set by an administrator. */
+  workspace: boolean;
+  at: number;
+};
+
+export type SenderStatus = {
+  block: SenderBlock | null;
+  trustedAt: number | null;
+  reportedAt: number | null;
+};
+
+export type UnsubscribeMethod = "one_click" | "mailto" | "link";
+
+export type UnsubscribeStatus =
+  /** The sender's server accepted the one-click request. */
+  | "done"
+  /** An unsubscribe email was sent; the list processes it on its own schedule. */
+  | "requested"
+  /** The person opened the sender's unsubscribe page. */
+  | "opened"
+  | "failed";
+
+export type Unsubscription = {
+  listKey: string;
+  method: UnsubscribeMethod;
+  status: UnsubscribeStatus;
+  /** Host of the https endpoint or the mailto address. */
+  target: string | null;
+  at: number;
+};
+
+export type ReportedMessageStatus = "open" | "resolved" | "dismissed";
+
+/** Point-in-time copy of what the reporter saw, kept with an admin report. */
+export type ReportSnapshot = {
+  fromName: string | null;
+  replyTo: string[];
+  to: string[];
+  verdict: string;
+  verdictReason: string;
+  warnings: string[];
+  spamScore: number | null;
+  ip: string | null;
+  network: string | null;
+  country: string | null;
+  ai: { spam: boolean; spamConfidence: number; reason: string } | null;
+  linkDomains: string[];
+  preview: string;
+};
+
+const DOMAIN_PATTERN = /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9-]{2,63}$/u;
+
+/**
+ * Normalizes a block entry: `alex@x.com` stays an address, `x.com` and
+ * `@x.com` become `@x.com` (the domain and its subdomains). Null if invalid.
+ */
+export function normalizeBlockPattern(value: string) {
+  const input = value.trim().toLocaleLowerCase();
+  if (input.length > 320) return null;
+  const at = input.lastIndexOf("@");
+  if (at > 0) {
+    const domain = input.slice(at + 1);
+    return DOMAIN_PATTERN.test(domain) && !/[\s<>,;"]/u.test(input.slice(0, at)) ? input : null;
+  }
+  const domain = at === 0 ? input.slice(1) : input;
+  return DOMAIN_PATTERN.test(domain) ? `@${domain}` : null;
+}
+
+/** The block entries that cover an address: the address itself and each parent domain. */
+export function blockPatternsFor(address: string) {
+  const value = address.trim().toLocaleLowerCase();
+  const at = value.lastIndexOf("@");
+  if (at <= 0) return [];
+  const labels = value.slice(at + 1).split(".");
+  const domains = labels.slice(0, -1).map((_, index) => `@${labels.slice(index).join(".")}`);
+  return [value, ...domains];
+}

package/shared/mail-headers.ts

@@ -0,0 +1,250 @@
+/**
+ * Low-level RFC 5322 header helpers shared by ingestion (worker) and the
+ * "Show original" panel (browser). Everything here is pure and works on the
+ * raw message text, so header order is preserved exactly as received.
+ */
+
+const MAX_HEADER_BYTES = 256 * 1024;
+
+export type HeaderField = {
+  /** Lowercased field name. */
+  name: string;
+  /** Unfolded value with surrounding whitespace removed. */
+  value: string;
+};
+
+export function headerBlock(raw: string) {
+  const separator = /\r?\n\r?\n/u.exec(raw);
+  const end = separator?.index ?? raw.length;
+  return raw.slice(0, Math.min(end, MAX_HEADER_BYTES));
+}
+
+/** Header fields of the top-level entity, in their original (topmost first) order. */
+export function headerFields(raw: string): HeaderField[] {
+  const unfolded = headerBlock(raw).replace(/\r?\n[\t ]+/gu, " ");
+  return unfolded.split(/\r?\n/gu).flatMap((line) => {
+    const colon = line.indexOf(":");
+    if (colon < 1) return [];
+    const name = line.slice(0, colon).trim().toLocaleLowerCase();
+    if (!/^[\x21-\x39\x3b-\x7e]+$/u.test(name)) return [];
+    return [{ name, value: line.slice(colon + 1).trim() }];
+  });
+}
+
+export function headerValues(raw: string, name: string) {
+  const expected = name.toLocaleLowerCase();
+  return headerFields(raw).flatMap((field) =>
+    field.name === expected && field.value ? [field.value] : []
+  );
+}
+
+export type CommentScan = {
+  /** The value with every top-level comment replaced by a single space. */
+  text: string;
+  /** Text of each outermost comment, without its parentheses. */
+  comments: string[];
+};
+
+/**
+ * Removes RFC 5322 comments (which may nest and contain quoted pairs) while
+ * leaving quoted strings intact.
+ */
+export function scanComments(value: string): CommentScan {
+  let text = "";
+  let comment = "";
+  const comments: string[] = [];
+  let depth = 0;
+  let quoted = false;
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index]!;
+    if (char === "\\" && (quoted || depth > 0) && index + 1 < value.length) {
+      const pair = value.slice(index, index + 2);
+      if (depth > 0) comment += pair;
+      else text += pair;
+      index += 1;
+      continue;
+    }
+    if (depth === 0 && char === "\"") quoted = !quoted;
+    if (!quoted && char === "(") {
+      if (depth > 0) comment += char;
+      depth += 1;
+      continue;
+    }
+    if (!quoted && char === ")" && depth > 0) {
+      depth -= 1;
+      if (depth === 0) {
+        comments.push(comment.trim());
+        comment = "";
+        text += " ";
+      } else {
+        comment += char;
+      }
+      continue;
+    }
+    if (depth > 0) comment += char;
+    else text += char;
+  }
+  if (depth > 0 && comment) comments.push(comment.trim());
+  return { text, comments };
+}
+
+/**
+ * Splits on a delimiter that appears outside comments and quoted strings.
+ * Each part keeps its comments so callers can still read them.
+ */
+export function splitTopLevel(value: string, delimiter: string) {
+  const parts: string[] = [];
+  let current = "";
+  let depth = 0;
+  let quoted = false;
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index]!;
+    if (char === "\\" && (quoted || depth > 0) && index + 1 < value.length) {
+      current += value.slice(index, index + 2);
+      index += 1;
+      continue;
+    }
+    if (depth === 0 && char === "\"") quoted = !quoted;
+    else if (!quoted && char === "(") depth += 1;
+    else if (!quoted && char === ")" && depth > 0) depth -= 1;
+    if (char === delimiter && depth === 0 && !quoted) {
+      parts.push(current);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  parts.push(current);
+  return parts;
+}
+
+export function unquote(value: string) {
+  const trimmed = value.trim();
+  if (trimmed.length >= 2 && trimmed.startsWith("\"") && trimmed.endsWith("\"")) {
+    return trimmed.slice(1, -1).replace(/\\(.)/gu, "$1");
+  }
+  return trimmed;
+}
+
+/** Domain part of an address or a bare domain, lowercased without a trailing dot. */
+export function addressDomain(value: string | null | undefined) {
+  if (!value) return null;
+  const trimmed = value.trim().replace(/^<|>$/gu, "");
+  const at = trimmed.lastIndexOf("@");
+  const domain = (at >= 0 ? trimmed.slice(at + 1) : trimmed)
+    .replace(/\.$/u, "")
+    .toLocaleLowerCase();
+  return /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/u.test(domain)
+    ? domain
+    : null;
+}
+
+// --- Dates ---------------------------------------------------------------
+
+const MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+
+/** RFC 5322 §4.3 obsolete zones; military zones are treated as unknown (-0000). */
+const OBSOLETE_ZONES: Record<string, number> = {
+  ut: 0, gmt: 0, z: 0, utc: 0,
+  est: -5 * 60, edt: -4 * 60,
+  cst: -6 * 60, cdt: -5 * 60,
+  mst: -7 * 60, mdt: -6 * 60,
+  pst: -8 * 60, pdt: -7 * 60,
+};
+
+export const RFC5322_DATE_PATTERN =
+  /(?:(?:mon|tue|wed|thu|fri|sat|sun)[a-z]*,?\s*)?(\d{1,2})\s+([a-z]{3})[a-z]*\s+(\d{2,4})\s+(\d{1,2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?\s*([+-]\d{4}|[a-z]{1,3}\b)?/iu;
+
+export const ISO_DATE_PATTERN =
+  /(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})(?:\.\d+)?\s*([+-]\d{2}:?\d{2}|Z)?/iu;
+
+function zoneOffsetMinutes(zone: string | undefined) {
+  if (!zone) return 0;
+  const numeric = /^([+-])(\d{2}):?(\d{2})$/u.exec(zone);
+  if (numeric) {
+    const minutes = Number(numeric[2]) * 60 + Number(numeric[3]);
+    return numeric[1] === "-" ? -minutes : minutes;
+  }
+  return OBSOLETE_ZONES[zone.toLocaleLowerCase()] ?? 0;
+}
+
+function utcDate(
+  year: number,
+  month: number,
+  day: number,
+  hour: number,
+  minute: number,
+  second: number,
+  offsetMinutes: number,
+) {
+  if (
+    month < 0 || month > 11 || day < 1 || day > 31
+    || hour > 23 || minute > 59 || second > 60
+  ) {
+    return null;
+  }
+  const time = Date.UTC(year, month, day, hour, minute, Math.min(second, 59))
+    - offsetMinutes * 60_000;
+  return Number.isFinite(time) ? new Date(time) : null;
+}
+
+function rfc5322Match(match: RegExpExecArray) {
+  const month = MONTHS.indexOf(match[2]!.toLocaleLowerCase());
+  let year = Number(match[3]);
+  // RFC 5322 §4.3: two-digit years are 19xx when >= 50, 20xx otherwise.
+  if (match[3]!.length <= 2) year += year >= 50 ? 1900 : 2000;
+  else if (match[3]!.length === 3) year += 1900;
+  return utcDate(
+    year,
+    month,
+    Number(match[1]),
+    Number(match[4]),
+    Number(match[5]),
+    Number(match[6] ?? 0),
+    zoneOffsetMinutes(match[7]),
+  );
+}
+
+function isoMatch(match: RegExpExecArray) {
+  return utcDate(
+    Number(match[1]),
+    Number(match[2]) - 1,
+    Number(match[3]),
+    Number(match[4]),
+    Number(match[5]),
+    Number(match[6]),
+    zoneOffsetMinutes(match[7]),
+  );
+}
+
+/**
+ * Strict date parser for header dates. Accepts RFC 5322 dates (day name
+ * optional, fractional seconds, obsolete zones) and ISO / Go timestamps such
+ * as SendGrid's `2026-10-29 15:24:22.353912098 +0000 UTC m=+…`. Never falls
+ * back to `new Date(string)`, whose non-ISO parsing is implementation-defined.
+ */
+export function parseMailDate(value: string | null | undefined) {
+  if (!value) return null;
+  const text = scanComments(value).text.trim();
+  const rfc = RFC5322_DATE_PATTERN.exec(text);
+  if (rfc && rfc.index <= 12) return rfc5322Match(rfc);
+  const iso = ISO_DATE_PATTERN.exec(text);
+  if (iso && iso.index <= 12) return isoMatch(iso);
+  return null;
+}
+
+/** Finds a date at the end of a header that has no `;` before it. */
+export function trailingMailDate(value: string) {
+  const rfc = new RegExp(RFC5322_DATE_PATTERN.source, "giu");
+  const iso = new RegExp(ISO_DATE_PATTERN.source, "giu");
+  let best: { index: number; date: Date } | null = null;
+  for (const [pattern, parse] of [[rfc, rfc5322Match], [iso, isoMatch]] as const) {
+    for (const match of value.matchAll(pattern)) {
+      const date = parse(match as RegExpExecArray);
+      if (date && (!best || match.index > best.index)) {
+        best = { index: match.index, date };
+      }
+    }
+  }
+  return best;
+}