@remit/mailbox-service 0.0.1

package/src/heuristics/classifyByHeaders.ts

@@ -0,0 +1,369 @@
+import { AuthResultVerdict, MessageCategory } from "@remit/domain-enums";
+import type {
+	Attachment,
+	HeaderLines,
+	Headers,
+	ParsedMail,
+	StructuredHeader,
+} from "mailparser";
+import { SOCIAL_DOMAINS } from "./socialDomains.js";
+import { TRANSACTIONAL_DOMAINS } from "./transactionalDomains.js";
+
+type Category = (typeof MessageCategory)[keyof typeof MessageCategory];
+type AuthVerdictValue =
+	(typeof AuthResultVerdict)[keyof typeof AuthResultVerdict];
+
+export interface MessageAuthResult {
+	dmarc?: AuthVerdictValue;
+	spf?: AuthVerdictValue;
+	dkim?: AuthVerdictValue;
+}
+
+export interface MessageProviderSpam {
+	classified: boolean;
+	score?: string;
+	source?: string;
+}
+
+/**
+ * Structured sender-authenticity signal extracted from DKIM headers.
+ * Persisted alongside `category` during body-sync so the intelligence
+ * sidebar (#425) can render phishing verdicts without re-parsing.
+ *
+ * Present only when a DKIM-Signature header exists; absent otherwise
+ * (absence means "no signal" — no comparison was possible).
+ */
+export interface MessageAuthenticity {
+	/** Domain of the From header address */
+	fromDomain: string;
+	/** DKIM signing domain (d=) that was compared, when a signature is present */
+	dkimDomain?: string;
+	/** True when none of the DKIM signing domains aligns with the From domain */
+	dkimMismatch: boolean;
+}
+
+/**
+ * Header-only classification. Pure function. First match wins. Falls through
+ * to `personal` so misclassification stays in the safest bucket.
+ *
+ * Rule order matches the EDD heuristic table:
+ *
+ * 1. `Auto-Submitted: auto-generated|auto-replied` → `automated`
+ * 2. `Precedence: bulk|list|junk` → `automated`
+ * 3. `Content-Type: text/calendar` part anywhere → `transactional`
+ * 4. From-domain in TRANSACTIONAL_DOMAINS → `transactional`
+ * 5. `List-Unsubscribe` AND `List-Id` → `newsletter`
+ * 6. `List-Unsubscribe` only → `marketing`
+ * 7. DKIM `d=` differs from From domain → `automated`
+ * 8. From-domain in SOCIAL_DOMAINS → `social`
+ * 9. fallback → `personal`
+ */
+export const classifyByHeaders = (parsed: ParsedMail): Category => {
+	const headers = parsed.headers;
+	const lines = parsed.headerLines;
+
+	if (matchesAutoSubmitted(headers)) return MessageCategory.automated;
+	if (matchesPrecedence(headers)) return MessageCategory.automated;
+	if (hasCalendarPart(parsed.attachments)) return MessageCategory.transactional;
+
+	const fromDomain = getFromDomain(parsed);
+
+	if (fromDomain && domainMatches(fromDomain, TRANSACTIONAL_DOMAINS)) {
+		return MessageCategory.transactional;
+	}
+
+	const hasListUnsubscribe = hasHeaderLine(lines, "list-unsubscribe");
+	const hasListId = hasHeaderLine(lines, "list-id");
+
+	if (hasListUnsubscribe && hasListId) return MessageCategory.newsletter;
+	if (hasListUnsubscribe) return MessageCategory.marketing;
+
+	if (fromDomain && dkimMismatchResult(headers, lines, fromDomain).mismatch) {
+		return MessageCategory.automated;
+	}
+
+	if (fromDomain && domainMatches(fromDomain, SOCIAL_DOMAINS)) {
+		return MessageCategory.social;
+	}
+
+	return MessageCategory.personal;
+};
+
+/**
+ * Extract the structured authenticity signal from parsed headers.
+ *
+ * Returns a `MessageAuthenticity` when at least one DKIM-Signature header
+ * is present (a comparison was possible). Returns `null` when there are no
+ * DKIM-Signature headers so callers can omit the field entirely — absence
+ * means "no signal", not "mismatch: false".
+ *
+ * The alignment rule exactly mirrors the category heuristic (rule 7) so the
+ * structured `dkimMismatch` boolean and the `automated` category can never
+ * disagree.
+ */
+export const extractAuthenticity = (
+	parsed: ParsedMail,
+): MessageAuthenticity | null => {
+	const headers = parsed.headers;
+	const lines = parsed.headerLines;
+	const fromDomain = getFromDomain(parsed);
+
+	if (!fromDomain) return null;
+
+	const dkimDomains = extractDkimDomains(headers, lines);
+	if (dkimDomains.length === 0) return null;
+
+	const result = dkimMismatchResult(headers, lines, fromDomain);
+
+	// Pick the reported domain: first mismatching one on mismatch, first domain otherwise.
+	const reportedDomain = result.mismatchingDomain ?? dkimDomains[0];
+
+	return {
+		fromDomain,
+		dkimDomain: reportedDomain,
+		dkimMismatch: result.mismatch,
+	};
+};
+
+const extractVerdict = (
+	text: string,
+	mechanism: string,
+): AuthVerdictValue | undefined => {
+	const match = text.match(new RegExp(`${mechanism}=(\\w+)`, "i"));
+	if (!match) return undefined;
+	const raw = match[1].toLowerCase();
+	const map: Record<string, AuthVerdictValue> = {
+		pass: AuthResultVerdict.Pass,
+		fail: AuthResultVerdict.Fail,
+		none: AuthResultVerdict.None,
+		neutral: AuthResultVerdict.Neutral,
+		softfail: AuthResultVerdict.Softfail,
+	};
+	return map[raw];
+};
+
+/**
+ * Extract provider authentication-results verdict from the Authentication-Results header.
+ * Returns null when the header is absent.
+ */
+export const extractAuthResult = (
+	parsed: ParsedMail,
+): MessageAuthResult | null => {
+	const line = parsed.headerLines.find(
+		(l) => l.key.toLowerCase() === "authentication-results",
+	);
+	if (!line) return null;
+
+	const text = stripHeaderName(line.line);
+	const dmarc = extractVerdict(text, "dmarc");
+	const spf = extractVerdict(text, "spf");
+	const dkim = extractVerdict(text, "dkim");
+
+	return { dmarc, spf, dkim };
+};
+
+/**
+ * Extract provider spam-filter signal from X-SpamExperts-Class, X-Spam-Status,
+ * or X-HalOne-Spam-Probability headers. Returns null when none are present.
+ */
+export const extractProviderSpam = (
+	parsed: ParsedMail,
+): MessageProviderSpam | null => {
+	const lines = parsed.headerLines;
+
+	const spamExperts = lines.find(
+		(l) => l.key.toLowerCase() === "x-spamexperts-class",
+	);
+	if (spamExperts) {
+		const value = stripHeaderName(spamExperts.line).trim().toLowerCase();
+		return {
+			classified: value === "spam",
+			source: "x-spamexperts-class",
+		};
+	}
+
+	const spamStatus = lines.find((l) => l.key.toLowerCase() === "x-spam-status");
+	if (spamStatus) {
+		const text = stripHeaderName(spamStatus.line).trim();
+		const classified = text.toLowerCase().startsWith("yes");
+		const scoreMatch = text.match(/score=([\d.+-]+)/i);
+		return {
+			classified,
+			score: scoreMatch ? scoreMatch[1] : undefined,
+			source: "x-spam-status",
+		};
+	}
+
+	const halOne = lines.find(
+		(l) => l.key.toLowerCase() === "x-halone-spam-probability",
+	);
+	if (halOne) {
+		const value = stripHeaderName(halOne.line).trim();
+		return {
+			classified: parseFloat(value) > 0.5,
+			score: value,
+			source: "x-halone-spam-probability",
+		};
+	}
+
+	return null;
+};
+
+/**
+ * Returns true when a List-Unsubscribe header is present, indicating a
+ * bulk/mailing-list sender.
+ */
+export const extractHasListUnsubscribe = (parsed: ParsedMail): boolean =>
+	parsed.headerLines.some((l) => l.key.toLowerCase() === "list-unsubscribe");
+
+const matchesAutoSubmitted = (headers: Headers): boolean => {
+	const value = readStringHeader(headers, "auto-submitted");
+	if (!value) return false;
+	const normalized = value.split(";")[0].trim().toLowerCase();
+	return normalized === "auto-generated" || normalized === "auto-replied";
+};
+
+const matchesPrecedence = (headers: Headers): boolean => {
+	const value = readStringHeader(headers, "precedence");
+	if (!value) return false;
+	const normalized = value.trim().toLowerCase();
+	return (
+		normalized === "bulk" || normalized === "list" || normalized === "junk"
+	);
+};
+
+const hasCalendarPart = (attachments: Attachment[] | undefined): boolean => {
+	if (!attachments) return false;
+	for (const att of attachments) {
+		if ((att.contentType ?? "").toLowerCase().startsWith("text/calendar")) {
+			return true;
+		}
+	}
+	return false;
+};
+
+const getFromDomain = (parsed: ParsedMail): string | null => {
+	const from = parsed.from;
+	if (!from || !from.value || from.value.length === 0) return null;
+	const address = from.value[0]?.address;
+	if (!address) return null;
+	const at = address.lastIndexOf("@");
+	if (at < 0 || at === address.length - 1) return null;
+	return address.slice(at + 1).toLowerCase();
+};
+
+const domainMatches = (
+	domain: string,
+	allowList: readonly string[],
+): boolean => {
+	for (const entry of allowList) {
+		if (domain === entry || domain.endsWith(`.${entry}`)) return true;
+	}
+	return false;
+};
+
+/**
+ * Check whether DKIM signing domain(s) align with the From domain and
+ * return a structured result so both the category heuristic and the
+ * authenticity extractor share the exact same alignment logic.
+ *
+ * Alignment: signing domain equals From domain, or one is a subdomain of
+ * the other (parent/child). Any single aligned domain is enough to consider
+ * the message non-mismatching — a legitimate re-mailer signing under a
+ * subdomain is not suspicious.
+ *
+ * On mismatch the first non-aligned domain is reported so the UI can show
+ * "signed by relay.example.net, claims example.com".
+ */
+const dkimMismatchResult = (
+	headers: Headers,
+	lines: HeaderLines,
+	fromDomain: string,
+): { mismatch: boolean; mismatchingDomain: string | null } => {
+	const dkimDomains = extractDkimDomains(headers, lines);
+	if (dkimDomains.length === 0)
+		return { mismatch: false, mismatchingDomain: null };
+	let firstMismatching: string | null = null;
+	for (const d of dkimDomains) {
+		if (
+			d === fromDomain ||
+			fromDomain.endsWith(`.${d}`) ||
+			d.endsWith(`.${fromDomain}`)
+		) {
+			return { mismatch: false, mismatchingDomain: null };
+		}
+		if (!firstMismatching) firstMismatching = d;
+	}
+	return { mismatch: true, mismatchingDomain: firstMismatching };
+};
+
+const extractDkimDomains = (headers: Headers, lines: HeaderLines): string[] => {
+	const domains: string[] = [];
+
+	const raw = headers.get("dkim-signature");
+	const structured = collectStructured(raw);
+	for (const s of structured) {
+		const d = s.params?.d;
+		if (typeof d === "string") domains.push(d.trim().toLowerCase());
+	}
+
+	for (const line of lines) {
+		if (line.key.toLowerCase() !== "dkim-signature") continue;
+		const value = stripHeaderName(line.line);
+		const match = value.match(/(?:^|;)\s*d\s*=\s*([^;\s]+)/i);
+		if (match) {
+			const candidate = match[1].trim().toLowerCase();
+			if (!domains.includes(candidate)) domains.push(candidate);
+		}
+	}
+	return domains;
+};
+
+const collectStructured = (value: unknown): StructuredHeader[] => {
+	if (!value) return [];
+	if (Array.isArray(value)) {
+		const out: StructuredHeader[] = [];
+		for (const v of value) {
+			if (isStructuredHeader(v)) out.push(v);
+		}
+		return out;
+	}
+	if (isStructuredHeader(value)) return [value];
+	return [];
+};
+
+const isStructuredHeader = (v: unknown): v is StructuredHeader => {
+	if (!v || typeof v !== "object") return false;
+	return (
+		"value" in v &&
+		typeof (v as { value: unknown }).value === "string" &&
+		"params" in v &&
+		typeof (v as { params: unknown }).params === "object"
+	);
+};
+
+const stripHeaderName = (line: string): string => {
+	const idx = line.indexOf(":");
+	return idx >= 0 ? line.slice(idx + 1).trim() : line;
+};
+
+const hasHeaderLine = (lines: HeaderLines, name: string): boolean => {
+	const lc = name.toLowerCase();
+	for (const line of lines) {
+		if (line.key.toLowerCase() === lc) return true;
+	}
+	return false;
+};
+
+const readStringHeader = (
+	headers: Headers,
+	key: string,
+): string | undefined => {
+	const value = headers.get(key);
+	if (typeof value === "string") return value;
+	if (Array.isArray(value)) {
+		const first = value[0];
+		if (typeof first === "string") return first;
+	}
+	return undefined;
+};

package/src/heuristics/classifyPlacement.ts

@@ -0,0 +1,96 @@
+import type { MessageItem } from "@remit/data-ports";
+import { SenderTrust } from "@remit/domain-enums";
+
+type SenderTrustValue = (typeof SenderTrust)[keyof typeof SenderTrust];
+
+export type FolderPlacement = "inbox" | "junk" | "other";
+
+export type PlacementAction = "move-to-inbox" | "move-to-junk" | "leave";
+
+export interface PlacementVerdict {
+	action: PlacementAction;
+	confidence: "confident" | "unsure";
+	reasons: string[];
+}
+
+const isTrusted = (senderTrust: SenderTrustValue): boolean =>
+	senderTrust === SenderTrust.Vip || senderTrust === SenderTrust.Wellknown;
+
+/**
+ * Tier 0 deterministic placement verdict (RFC 031, "Confident moves").
+ *
+ * Pure: the caller resolves the message's current folder placement and the
+ * sender trust; this function does no DB lookups and produces no side effects.
+ * It generalizes `shouldRescueFromJunk` into a two-directional verdict and is
+ * recall-biased — a confident move only fires when cheap, deterministic signals
+ * agree; everything else is left in place for a later LLM tier.
+ */
+export const classifyPlacement = (
+	message: MessageItem,
+	placement: FolderPlacement,
+	senderTrust: SenderTrustValue,
+): PlacementVerdict => {
+	if (message.movedByRemit === true) {
+		return {
+			action: "leave",
+			confidence: "confident",
+			reasons: ["already-moved-by-remit"],
+		};
+	}
+
+	if (!message.providerSpam || !message.authResult) {
+		return {
+			action: "leave",
+			confidence: "unsure",
+			reasons: ["missing-signals"],
+		};
+	}
+
+	const providerSpam = message.providerSpam.classified === true;
+	const dmarc = message.authResult.dmarc;
+	const dkimMismatch = message.authenticity?.dkimMismatch === true;
+	const trusted = isTrusted(senderTrust);
+
+	// Rescue (junk → inbox), LOW bar. Mirrors shouldRescueFromJunk's gate.
+	if (placement === "junk" && providerSpam && dmarc === "Pass") {
+		if (trusted) {
+			return {
+				action: "move-to-inbox",
+				confidence: "confident",
+				reasons: ["provider=spam", "dmarc=pass", `sender=${senderTrust}`],
+			};
+		}
+		// Anti-spoof guard: an unknown sender is never auto-rescued.
+		return {
+			action: "leave",
+			confidence: "unsure",
+			reasons: ["provider=spam", "dmarc=pass", "sender=untrusted"],
+		};
+	}
+
+	// Demote (inbox → junk), HIGH bar.
+	if (placement === "inbox" && dkimMismatch) {
+		if (dmarc === "Fail" && !trusted) {
+			return {
+				action: "move-to-junk",
+				confidence: "confident",
+				reasons: ["dkim-mismatch", "dmarc=fail", "sender=untrusted"],
+			};
+		}
+		// DMARC-pass phishing: dkimMismatch but DMARC did not fail. Deferred to a
+		// later LLM tier — must never auto-demote here.
+		if (dmarc === "Pass") {
+			return {
+				action: "leave",
+				confidence: "unsure",
+				reasons: ["dkim-mismatch", "dmarc=pass", "deferred-to-llm"],
+			};
+		}
+	}
+
+	return {
+		action: "leave",
+		confidence: "unsure",
+		reasons: ["no-confident-signal"],
+	};
+};

package/src/heuristics/socialDomains.ts

@@ -0,0 +1,23 @@
+/**
+ * Hand-curated allow-list of domains whose mail is treated as `social`.
+ *
+ * Sources are notifications from social/communication platforms. Match is
+ * suffix-based on the From-domain (lowercase). `news.linkedin.com` matches
+ * an entry of `linkedin.com`. Add new entries lowercase, no leading dot.
+ *
+ * Note: GitHub deliberately does NOT appear here. It is in
+ * `transactionalDomains.ts` because the EDD prioritises receipts and
+ * security alerts. The transactional rule fires before the social rule, so
+ * placing GitHub in the transactional list ensures all GitHub mail surfaces
+ * as `transactional`.
+ */
+export const SOCIAL_DOMAINS = [
+	"linkedin.com",
+	"x.com",
+	"twitter.com",
+	"facebook.com",
+	"instagram.com",
+	"meetup.com",
+	"discord.com",
+	"slack.com",
+] as const;

package/src/heuristics/transactionalDomains.ts

@@ -0,0 +1,26 @@
+/**
+ * Hand-curated allow-list of domains whose mail is treated as `transactional`.
+ *
+ * Sources are receipts, billing, security alerts, and similar
+ * person-actionable but not promotional mail. GitHub appears here (security
+ * alerts, billing receipts) and is intentionally NOT in the social allow-list
+ * — we want a GitHub security alert to surface as `transactional`, not
+ * `social`.
+ *
+ * Match is suffix-based on the From-domain (lowercase). `news.example.com`
+ * matches an entry of `example.com`. Add new entries lowercase, no leading
+ * dot.
+ *
+ * TODO: We deliberately do NOT seed banks here — the bank landscape is too
+ * geographic, and a wrong allow-list entry causes silent mis-classification.
+ * Banks should be added per-deployment by the operator.
+ */
+export const TRANSACTIONAL_DOMAINS = [
+	"github.com",
+	"stripe.com",
+	"paypal.com",
+	"square.com",
+	"itunes.com",
+	"apple.com",
+	"google.com",
+] as const;

package/src/imapflow-connect-retry.test.ts

@@ -0,0 +1,108 @@
+/**
+ * Unit tests for ImapFlowConnection.connect() retry semantics.
+ *
+ * Verifies the retry policy without touching a real IMAP server:
+ * - Network errors (e.g. ECONNREFUSED) are retried with backoff before the
+ *   classified MailConnectionError("network") is finally thrown.
+ * - Auth errors are thrown immediately and NEVER retried.
+ *
+ * The private `attemptConnect` and `sleep` instance methods are stubbed so the
+ * test exercises the loop logic directly and runs instantly.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it, mock } from "node:test";
+import { ImapFlowConnection } from "./imapflow-connection.js";
+import { MailConnectionError } from "./types.js";
+
+const baseConfig = {
+	host: "localhost",
+	port: 143,
+	user: "alice@example.com",
+	credentials: { kind: "password" as const, password: "s3cr3t" },
+	tls: false,
+};
+
+type WithPrivates = {
+	attemptConnect: () => Promise<void>;
+	sleep: (ms: number) => Promise<void>;
+};
+
+const makeErrnoError = (code: string): Error => {
+	const err = new Error(`connect ${code}`);
+	return Object.assign(err, { code });
+};
+
+describe("ImapFlowConnection.connect() retry policy", () => {
+	it("retries network errors (ECONNREFUSED) 3x with backoff, then throws classified network error", async () => {
+		const connection = new ImapFlowConnection(baseConfig);
+		const priv = connection as unknown as WithPrivates;
+
+		// Always fail with a network-level error.
+		const attempt = mock.method(priv, "attemptConnect", async () => {
+			throw makeErrnoError("ECONNREFUSED");
+		});
+		// Stub sleep so the backoff does not actually delay the test.
+		mock.method(priv, "sleep", async () => {});
+
+		await assert.rejects(
+			() => connection.connect(),
+			(error: unknown) => {
+				assert.ok(
+					error instanceof MailConnectionError,
+					"final error should be a MailConnectionError",
+				);
+				assert.equal(error.kind, "network");
+				// The host:port endpoint must appear in the message so a DNS /
+				// connect failure is self-describing in the logs (issue #835).
+				assert.match(error.message, /localhost:143/);
+				return true;
+			},
+		);
+
+		// 3 attempts total (the retry loop runs maxRetries times).
+		assert.equal(attempt.mock.callCount(), 3);
+	});
+
+	it("succeeds on a later attempt when a transient network error clears", async () => {
+		const connection = new ImapFlowConnection(baseConfig);
+		const priv = connection as unknown as WithPrivates;
+
+		let calls = 0;
+		const attempt = mock.method(priv, "attemptConnect", async () => {
+			calls += 1;
+			if (calls < 2) {
+				throw makeErrnoError("ECONNRESET");
+			}
+			// Second attempt succeeds.
+		});
+		mock.method(priv, "sleep", async () => {});
+
+		await connection.connect();
+
+		assert.equal(attempt.mock.callCount(), 2);
+	});
+
+	it("does NOT retry auth errors — throws immediately on attempt 1", async () => {
+		const connection = new ImapFlowConnection(baseConfig);
+		const priv = connection as unknown as WithPrivates;
+
+		const attempt = mock.method(priv, "attemptConnect", async () => {
+			throw new Error("Invalid credentials");
+		});
+		const sleep = mock.method(priv, "sleep", async () => {});
+
+		await assert.rejects(
+			() => connection.connect(),
+			(error: unknown) => {
+				assert.ok(error instanceof MailConnectionError);
+				assert.equal(error.kind, "auth");
+				return true;
+			},
+		);
+
+		// Only one attempt, no backoff sleep.
+		assert.equal(attempt.mock.callCount(), 1);
+		assert.equal(sleep.mock.callCount(), 0);
+	});
+});