@remit/mailbox-service 0.0.111 → 0.0.113

package/src/heuristics/classifyPlacement.test.ts

@@ -1,366 +0,0 @@
-/**
- * `classifyPlacement` had no dedicated unit test — only the DKIM/DMARC paths
- * were exercised indirectly through realistic-mail fixtures elsewhere. Issue
- * #300 (RFC 039 Decision 3/3a) added the user's placement instruction as a
- * confident move independent of every DKIM/DMARC/provider signal, plus a
- * `setAt` tie-break against `vip`/`wellknown` (Decision 3a). Issue #605 adds
- * the other direction, `neverSpam`. These tests cover both instruction
- * branches and the pre-existing DKIM/DMARC branches, so a regression in any of
- * them shows up here.
- */
-
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import type { MessageItem } from "@remit/data-ports";
-import { SenderOverride, SenderTrust } from "@remit/domain-enums";
-import {
-	classifyPlacement,
-	resolveSenderPlacement,
-} from "./classifyPlacement.js";
-
-const baseMessage = (overrides: Partial<MessageItem> = {}): MessageItem =>
-	({
-		messageId: "m-1",
-		mailboxId: "mb-1",
-		uid: 1,
-		providerSpam: { classified: false },
-		authResult: { dmarc: "Pass" },
-		...overrides,
-	}) as unknown as MessageItem;
-
-describe("classifyPlacement", () => {
-	describe("SenderOverride.Blocked (RFC 039 Decision 3)", () => {
-		it("demotes an inbox message from a blocked sender, independent of DKIM/DMARC", () => {
-			const message = baseMessage({
-				providerSpam: undefined,
-				authResult: undefined,
-			});
-			const verdict = classifyPlacement(
-				message,
-				"inbox",
-				SenderTrust.Unknown,
-				SenderOverride.Blocked,
-			);
-			assert.deepEqual(verdict, {
-				action: "move-to-junk",
-				confidence: "confident",
-				reasons: ["sender=blocked"],
-			});
-		});
-
-		it("demotes a message sitting outside junk/inbox (e.g. a custom folder) from a blocked sender", () => {
-			const verdict = classifyPlacement(
-				baseMessage(),
-				"other",
-				SenderTrust.Unknown,
-				SenderOverride.Blocked,
-			);
-			assert.equal(verdict.action, "move-to-junk");
-			assert.equal(verdict.confidence, "confident");
-		});
-
-		it("does not re-move a blocked sender's message already in junk", () => {
-			const verdict = classifyPlacement(
-				baseMessage(),
-				"junk",
-				SenderTrust.Unknown,
-				SenderOverride.Blocked,
-			);
-			assert.notEqual(verdict.action, "move-to-junk");
-		});
-
-		it("does not demote when the sender carries no instruction, all else equal", () => {
-			const verdict = classifyPlacement(
-				baseMessage({ providerSpam: undefined, authResult: undefined }),
-				"inbox",
-				SenderTrust.Unknown,
-				SenderOverride.None,
-			);
-			assert.deepEqual(verdict, {
-				action: "leave",
-				confidence: "unsure",
-				reasons: ["missing-signals"],
-			});
-		});
-
-		it("still leaves an already-Remit-moved message alone even when blocked", () => {
-			const verdict = classifyPlacement(
-				baseMessage({ movedByRemit: true }),
-				"inbox",
-				SenderTrust.Unknown,
-				SenderOverride.Blocked,
-			);
-			assert.deepEqual(verdict, {
-				action: "leave",
-				confidence: "confident",
-				reasons: ["already-moved-by-remit"],
-			});
-		});
-	});
-
-	describe("SenderOverride.NeverSpam (issue #605)", () => {
-		it("rescues mail the provider rated clean from a domain that publishes no DMARC", () => {
-			const verdict = classifyPlacement(
-				baseMessage({
-					providerSpam: { classified: false },
-					authResult: { dmarc: "None" },
-				}),
-				"junk",
-				SenderTrust.Unknown,
-				SenderOverride.NeverSpam,
-			);
-			assert.deepEqual(verdict, {
-				action: "move-to-inbox",
-				confidence: "confident",
-				reasons: ["sender=never-spam"],
-			});
-		});
-
-		it("rescues before the missing-signals return, so a message with no parsed signals still comes out of junk", () => {
-			const verdict = classifyPlacement(
-				baseMessage({ providerSpam: undefined, authResult: undefined }),
-				"junk",
-				SenderTrust.Unknown,
-				SenderOverride.NeverSpam,
-			);
-			assert.equal(verdict.action, "move-to-inbox");
-			assert.equal(verdict.confidence, "confident");
-		});
-
-		it("leaves a never-spam sender's mail filed in a user folder where it is", () => {
-			const verdict = classifyPlacement(
-				baseMessage(),
-				"other",
-				SenderTrust.Unknown,
-				SenderOverride.NeverSpam,
-			);
-			assert.equal(verdict.action, "leave");
-		});
-
-		// The demote branch is reached only from `inbox`, so a spoof already in
-		// Junk never meets it. Without the guard on the rescue, the grant would
-		// carry mail impersonating the granted address out of Junk.
-		it("refuses to rescue a dkim-mismatch + dmarc-fail spoof sitting in junk", () => {
-			const verdict = classifyPlacement(
-				baseMessage({
-					providerSpam: { classified: true },
-					authResult: { dmarc: "Fail" },
-					authenticity: { fromDomain: "example.com", dkimMismatch: true },
-				}),
-				"junk",
-				SenderTrust.Unknown,
-				SenderOverride.NeverSpam,
-			);
-			assert.notEqual(verdict.action, "move-to-inbox");
-		});
-
-		it("refuses to rescue on a hard DMARC failure even with DKIM aligned", () => {
-			const verdict = classifyPlacement(
-				baseMessage({
-					providerSpam: { classified: true },
-					authResult: { dmarc: "Fail" },
-				}),
-				"junk",
-				SenderTrust.Unknown,
-				SenderOverride.NeverSpam,
-			);
-			assert.notEqual(verdict.action, "move-to-inbox");
-		});
-
-		it("refuses to rescue on a DKIM mismatch even where DMARC did not fail", () => {
-			const verdict = classifyPlacement(
-				baseMessage({
-					providerSpam: { classified: true },
-					authResult: { dmarc: "None" },
-					authenticity: { fromDomain: "example.com", dkimMismatch: true },
-				}),
-				"junk",
-				SenderTrust.Unknown,
-				SenderOverride.NeverSpam,
-			);
-			assert.notEqual(verdict.action, "move-to-inbox");
-		});
-
-		it("still demotes a never-spam sender's inbox mail on dkim-mismatch + dmarc-fail", () => {
-			const verdict = classifyPlacement(
-				baseMessage({
-					authResult: { dmarc: "Fail" },
-					authenticity: { fromDomain: "example.com", dkimMismatch: true },
-				}),
-				"inbox",
-				SenderTrust.Unknown,
-				SenderOverride.NeverSpam,
-			);
-			assert.deepEqual(verdict, {
-				action: "move-to-junk",
-				confidence: "confident",
-				reasons: ["dkim-mismatch", "dmarc=fail", "sender=untrusted"],
-			});
-		});
-
-		it("still leaves an already-Remit-moved message alone", () => {
-			const verdict = classifyPlacement(
-				baseMessage({ movedByRemit: true }),
-				"junk",
-				SenderTrust.Unknown,
-				SenderOverride.NeverSpam,
-			);
-			assert.deepEqual(verdict, {
-				action: "leave",
-				confidence: "confident",
-				reasons: ["already-moved-by-remit"],
-			});
-		});
-	});
-
-	describe("resolveSenderPlacement (Decision 3a tie-break)", () => {
-		it("blocked wins when set after vip", () => {
-			const result = resolveSenderPlacement(
-				{ trust: SenderTrust.Vip, setAt: 1_000 },
-				{ blocked: true, setAt: 5_000 },
-				false,
-			);
-			assert.deepEqual(result, {
-				senderTrust: SenderTrust.Unknown,
-				senderOverride: SenderOverride.Blocked,
-			});
-		});
-
-		it("vip wins when set after blocked", () => {
-			const result = resolveSenderPlacement(
-				{ trust: SenderTrust.Vip, setAt: 5_000 },
-				{ blocked: true, setAt: 1_000 },
-				false,
-			);
-			assert.deepEqual(result, {
-				senderTrust: SenderTrust.Vip,
-				senderOverride: SenderOverride.None,
-			});
-		});
-
-		it("breaks a same-second tie in favor of blocked", () => {
-			const result = resolveSenderPlacement(
-				{ trust: SenderTrust.Wellknown, setAt: 1_000 },
-				{ blocked: true, setAt: 1_400 },
-				false,
-			);
-			assert.deepEqual(result, {
-				senderTrust: SenderTrust.Unknown,
-				senderOverride: SenderOverride.Blocked,
-			});
-		});
-
-		it("blocked applies outright when there is no competing trust flag", () => {
-			const result = resolveSenderPlacement(
-				{ trust: SenderTrust.Unknown },
-				{ blocked: true, setAt: 1_000 },
-				false,
-			);
-			assert.deepEqual(result, {
-				senderTrust: SenderTrust.Unknown,
-				senderOverride: SenderOverride.Blocked,
-			});
-		});
-
-		it("passes trust through unchanged when the sender carries no instruction", () => {
-			const result = resolveSenderPlacement(
-				{ trust: SenderTrust.Wellknown, setAt: 1_000 },
-				{ blocked: false },
-				false,
-			);
-			assert.deepEqual(result, {
-				senderTrust: SenderTrust.Wellknown,
-				senderOverride: SenderOverride.None,
-			});
-		});
-
-		it("reads never-spam as the instruction, leaving trust untouched", () => {
-			const result = resolveSenderPlacement(
-				{ trust: SenderTrust.Unknown },
-				{ blocked: false },
-				true,
-			);
-			assert.deepEqual(result, {
-				senderTrust: SenderTrust.Unknown,
-				senderOverride: SenderOverride.NeverSpam,
-			});
-		});
-
-		it("does not promote a never-spam sender's trust to vip or wellknown", () => {
-			const result = resolveSenderPlacement(
-				{ trust: SenderTrust.Vip, setAt: 1_000 },
-				{ blocked: false },
-				true,
-			);
-			assert.equal(result.senderTrust, SenderTrust.Vip);
-			assert.equal(result.senderOverride, SenderOverride.NeverSpam);
-		});
-
-		it("resolves a row that somehow carries both instructions to blocked", () => {
-			const result = resolveSenderPlacement(
-				{ trust: SenderTrust.Unknown },
-				{ blocked: true, setAt: 1_000 },
-				true,
-			);
-			assert.equal(result.senderOverride, SenderOverride.Blocked);
-		});
-	});
-
-	describe("existing DKIM/DMARC paths (unaffected by SenderOverride.None)", () => {
-		it("rescues a trusted sender's mail from junk on provider-spam + dmarc-pass", () => {
-			const verdict = classifyPlacement(
-				baseMessage({ providerSpam: { classified: true } }),
-				"junk",
-				SenderTrust.Vip,
-				SenderOverride.None,
-			);
-			assert.equal(verdict.action, "move-to-inbox");
-			assert.equal(verdict.confidence, "confident");
-		});
-
-		it("does not rescue an untrusted sender's mail from junk", () => {
-			const verdict = classifyPlacement(
-				baseMessage({ providerSpam: { classified: true } }),
-				"junk",
-				SenderTrust.Unknown,
-				SenderOverride.None,
-			);
-			assert.equal(verdict.action, "leave");
-			assert.equal(verdict.confidence, "unsure");
-		});
-
-		it("demotes an untrusted sender's inbox mail on dkim-mismatch + dmarc-fail", () => {
-			const verdict = classifyPlacement(
-				baseMessage({
-					authResult: { dmarc: "Fail" },
-					authenticity: { fromDomain: "example.com", dkimMismatch: true },
-				}),
-				"inbox",
-				SenderTrust.Unknown,
-				SenderOverride.None,
-			);
-			assert.deepEqual(verdict, {
-				action: "move-to-junk",
-				confidence: "confident",
-				reasons: ["dkim-mismatch", "dmarc=fail", "sender=untrusted"],
-			});
-		});
-
-		it("defers a dkim-mismatch + dmarc-pass message to a later LLM tier", () => {
-			const verdict = classifyPlacement(
-				baseMessage({
-					authResult: { dmarc: "Pass" },
-					authenticity: { fromDomain: "example.com", dkimMismatch: true },
-				}),
-				"inbox",
-				SenderTrust.Unknown,
-				SenderOverride.None,
-			);
-			assert.deepEqual(verdict, {
-				action: "leave",
-				confidence: "unsure",
-				reasons: ["dkim-mismatch", "dmarc=pass", "deferred-to-llm"],
-			});
-		});
-	});
-});

package/src/heuristics/classifyPlacement.ts

@@ -1,211 +0,0 @@
-import type { MessageItem } from "@remit/data-ports";
-import { SenderOverride, SenderTrust } from "@remit/domain-enums";
-
-type SenderTrustValue = (typeof SenderTrust)[keyof typeof SenderTrust];
-
-type SenderOverrideValue = (typeof SenderOverride)[keyof typeof SenderOverride];
-
-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;
-
-/** The trust signal plus the `setAt` of whichever flag (`vip`/`wellknown`) produced it, `undefined` when the sender is `Unknown`. */
-export interface SenderTrustSignal {
-	trust: SenderTrustValue;
-	setAt?: number;
-}
-
-/** The sender's `blocked` flag value plus its `setAt`. */
-export interface SenderBlockedSignal {
-	blocked: boolean;
-	setAt?: number;
-}
-
-/**
- * RFC 039 Decision 3a: when a sender's `blocked` flag and their `vip`/
- * `wellknown` flag disagree on placement, the one set most recently wins.
- * Scoped to {@link classifyPlacement}'s own verdict only — it never touches
- * `deriveSenderTrust` or the trust badge, which stay a plain `vip → wellknown
- * → unknown` read with no `blocked` case.
- *
- * A same-second tie (both `setAt` floor to the same second) breaks in a
- * fixed, arbitrary order: `blocked` before `vip` before `wellknown` — a
- * determinism backstop, not a meaningful signal.
- */
-const resolveBlockedVsTrust = (
-	trust: SenderTrustSignal,
-	blocked: SenderBlockedSignal,
-): { senderTrust: SenderTrustValue; senderBlocked: boolean } => {
-	if (!blocked.blocked) {
-		return { senderTrust: trust.trust, senderBlocked: false };
-	}
-	if (trust.trust === SenderTrust.Unknown || trust.setAt === undefined) {
-		return { senderTrust: SenderTrust.Unknown, senderBlocked: true };
-	}
-
-	const blockedSecond = Math.floor((blocked.setAt ?? 0) / 1000);
-	const trustSecond = Math.floor(trust.setAt / 1000);
-
-	// Newer (or a same-second tie, which `blocked` wins) — blocked wins.
-	if (blockedSecond >= trustSecond) {
-		return { senderTrust: SenderTrust.Unknown, senderBlocked: true };
-	}
-	return { senderTrust: trust.trust, senderBlocked: false };
-};
-
-/**
- * Resolve the two axes {@link classifyPlacement} takes: the trust signal, and
- * the user's standing instruction about placement.
- *
- * `blocked` and `neverSpam` are two directly contradictory instructions and
- * cannot both stand — `AddressRepository.mergeFlags` drops the loser at write
- * time. Reading a row that carries both anyway (written before that invariant)
- * resolves to `Blocked`, the same direction the `blocked`/`vip` same-second tie
- * already breaks in: the demote is the recoverable mistake.
- */
-export const resolveSenderPlacement = (
-	trust: SenderTrustSignal,
-	blocked: SenderBlockedSignal,
-	neverSpam: boolean,
-): {
-	senderTrust: SenderTrustValue;
-	senderOverride: SenderOverrideValue;
-} => {
-	const { senderTrust, senderBlocked } = resolveBlockedVsTrust(trust, blocked);
-	if (senderBlocked)
-		return { senderTrust, senderOverride: SenderOverride.Blocked };
-	if (neverSpam)
-		return { senderTrust, senderOverride: SenderOverride.NeverSpam };
-	return { senderTrust, senderOverride: SenderOverride.None };
-};
-
-/**
- * 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.
- *
- * `senderOverride` (RFC 039 Decision 3, issue #605) is the user's standing
- * instruction about this sender's placement, and it outranks every
- * DKIM/DMARC/provider signal below — an explicit block or never-spam grant is
- * not a heuristic. Already-tie-broken against `vip`/`wellknown` by
- * {@link resolveSenderPlacement} in the caller; this function itself does not
- * compare `setAt`.
- *
- * `NeverSpam` is checked above the `missing-signals` return and above the
- * `providerSpam.classified` gate on purpose: the senders who need the grant are
- * the ones the provider rated clean and whose domain publishes no DMARC record,
- * so a check inside the rescue branch below would never fire for them. It
- * rescues only from `junk` — a message a standing filter put in a user folder
- * is not a spam question.
- *
- * It refuses outright on a `dmarc === "Fail"` or a DKIM mismatch. The demote
- * branch below is reached only from `inbox`, so a spoof already sitting in Junk
- * would never meet it: without this guard the grant would launder mail out of
- * Junk on exactly the two signals that identify someone impersonating the
- * address the user granted. A domain that publishes no DMARC record never
- * scores `Fail`, so the case the grant exists for is untouched.
- */
-export const classifyPlacement = (
-	message: MessageItem,
-	placement: FolderPlacement,
-	senderTrust: SenderTrustValue,
-	senderOverride: SenderOverrideValue,
-): PlacementVerdict => {
-	if (message.movedByRemit === true) {
-		return {
-			action: "leave",
-			confidence: "confident",
-			reasons: ["already-moved-by-remit"],
-		};
-	}
-
-	if (senderOverride === SenderOverride.Blocked && placement !== "junk") {
-		return {
-			action: "move-to-junk",
-			confidence: "confident",
-			reasons: ["sender=blocked"],
-		};
-	}
-
-	if (
-		senderOverride === SenderOverride.NeverSpam &&
-		placement === "junk" &&
-		message.authResult?.dmarc !== "Fail" &&
-		message.authenticity?.dkimMismatch !== true
-	) {
-		return {
-			action: "move-to-inbox",
-			confidence: "confident",
-			reasons: ["sender=never-spam"],
-		};
-	}
-
-	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"],
-	};
-};