@remit/mailbox-service 0.0.94 → 0.0.95

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/mailbox-service",
-  "version": "0.0.94",
+  "version": "0.0.95",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/body-sync.ts

@@ -59,7 +59,7 @@ import {
 	classifyPlacement,
 	type FolderPlacement,
 	type PlacementVerdict,
-	resolveBlockedVsTrust,
+	resolveSenderPlacement,
 } from "./heuristics/classifyPlacement.js";
 import { extractSenderMismatch } from "./heuristics/senderMismatch.js";
 import { denormalizeMessageCategory } from "./message-category.js";
@@ -1176,7 +1176,7 @@ export class BodySyncService {
 	 * `deriveSenderTrust` always did — `vip → wellknown → unknown`, untouched by
 	 * `blocked` — plus `blocked`/`autoArchive` off the same row. `trustSetAt` is
 	 * the `setAt` of whichever flag produced the trust value, needed by
-	 * {@link resolveBlockedVsTrust}'s tie-break; it stays local to placement and
+	 * {@link resolveSenderPlacement}'s tie-break; it stays local to placement and
 	 * never reaches `deriveSenderTrust`'s own contract (the trust badge).
 	 */
 	private async deriveSenderPlacementSignals(
@@ -1187,11 +1187,13 @@ export class BodySyncService {
 		trustSetAt?: number;
 		blocked: boolean;
 		blockedSetAt?: number;
+		neverSpam: boolean;
 		autoArchive: boolean;
 	}> {
 		const unknown = {
 			trust: SenderTrust.Unknown,
 			blocked: false,
+			neverSpam: false,
 			autoArchive: false,
 		} as const;
 		try {
@@ -1207,6 +1209,7 @@ export class BodySyncService {
 					trustSetAt: flags.vip.setAt,
 					blocked: flags.blocked?.value === true,
 					blockedSetAt: flags.blocked?.setAt,
+					neverSpam: flags.neverSpam?.value === true,
 					autoArchive: flags.autoArchive?.value === true,
 				};
 			}
@@ -1216,6 +1219,7 @@ export class BodySyncService {
 					trustSetAt: flags.wellknown.setAt,
 					blocked: flags.blocked?.value === true,
 					blockedSetAt: flags.blocked?.setAt,
+					neverSpam: flags.neverSpam?.value === true,
 					autoArchive: flags.autoArchive?.value === true,
 				};
 			}
@@ -1223,6 +1227,7 @@ export class BodySyncService {
 				...unknown,
 				blocked: flags?.blocked?.value === true,
 				blockedSetAt: flags?.blocked?.setAt,
+				neverSpam: flags?.neverSpam?.value === true,
 				autoArchive: flags?.autoArchive?.value === true,
 			};
 		} catch (err) {
@@ -1514,12 +1519,14 @@ export class BodySyncService {
 			: {
 					trust: SenderTrust.Unknown,
 					blocked: false,
+					neverSpam: false,
 					autoArchive: false,
 				};
 
-		const { senderTrust, senderBlocked } = resolveBlockedVsTrust(
+		const { senderTrust, senderOverride } = resolveSenderPlacement(
 			{ trust: signals.trust, setAt: signals.trustSetAt },
 			{ blocked: signals.blocked, setAt: signals.blockedSetAt },
+			signals.neverSpam,
 		);
 
 		// The verdict needs the classification signals (providerSpam,
@@ -1530,7 +1537,7 @@ export class BodySyncService {
 			candidate,
 			placement,
 			senderTrust,
-			senderBlocked,
+			senderOverride,
 		);
 
 		// A `leave` verdict — including "nothing confident to say" — carries no

package/src/heuristics/classifyPlacement.test.ts

@@ -1,20 +1,21 @@
 /**
  * `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) adds `senderBlocked` as a confident demote
- * independent of every DKIM/DMARC/provider signal, plus a `setAt` tie-break
- * against `vip`/`wellknown` (Decision 3a, `resolveBlockedVsTrust`). These tests
- * cover both the new branch and the pre-existing DKIM/DMARC branches, so a
- * regression in either shows up here.
+ * #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 { SenderTrust } from "@remit/domain-enums";
+import { SenderOverride, SenderTrust } from "@remit/domain-enums";
 import {
 	classifyPlacement,
-	resolveBlockedVsTrust,
+	resolveSenderPlacement,
 } from "./classifyPlacement.js";
 
 const baseMessage = (overrides: Partial<MessageItem> = {}): MessageItem =>
@@ -28,7 +29,7 @@ const baseMessage = (overrides: Partial<MessageItem> = {}): MessageItem =>
 	}) as unknown as MessageItem;
 
 describe("classifyPlacement", () => {
-	describe("senderBlocked (RFC 039 Decision 3)", () => {
+	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,
@@ -38,7 +39,7 @@ describe("classifyPlacement", () => {
 				message,
 				"inbox",
 				SenderTrust.Unknown,
-				true,
+				SenderOverride.Blocked,
 			);
 			assert.deepEqual(verdict, {
 				action: "move-to-junk",
@@ -52,7 +53,7 @@ describe("classifyPlacement", () => {
 				baseMessage(),
 				"other",
 				SenderTrust.Unknown,
-				true,
+				SenderOverride.Blocked,
 			);
 			assert.equal(verdict.action, "move-to-junk");
 			assert.equal(verdict.confidence, "confident");
@@ -63,17 +64,17 @@ describe("classifyPlacement", () => {
 				baseMessage(),
 				"junk",
 				SenderTrust.Unknown,
-				true,
+				SenderOverride.Blocked,
 			);
 			assert.notEqual(verdict.action, "move-to-junk");
 		});
 
-		it("does not demote when the sender is not blocked, all else equal", () => {
+		it("does not demote when the sender carries no instruction, all else equal", () => {
 			const verdict = classifyPlacement(
 				baseMessage({ providerSpam: undefined, authResult: undefined }),
 				"inbox",
 				SenderTrust.Unknown,
-				false,
+				SenderOverride.None,
 			);
 			assert.deepEqual(verdict, {
 				action: "leave",
@@ -87,7 +88,7 @@ describe("classifyPlacement", () => {
 				baseMessage({ movedByRemit: true }),
 				"inbox",
 				SenderTrust.Unknown,
-				true,
+				SenderOverride.Blocked,
 			);
 			assert.deepEqual(verdict, {
 				action: "leave",
@@ -97,70 +98,221 @@ describe("classifyPlacement", () => {
 		});
 	});
 
-	describe("resolveBlockedVsTrust (Decision 3a tie-break)", () => {
+	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 = resolveBlockedVsTrust(
+			const result = resolveSenderPlacement(
 				{ trust: SenderTrust.Vip, setAt: 1_000 },
 				{ blocked: true, setAt: 5_000 },
+				false,
 			);
 			assert.deepEqual(result, {
 				senderTrust: SenderTrust.Unknown,
-				senderBlocked: true,
+				senderOverride: SenderOverride.Blocked,
 			});
 		});
 
 		it("vip wins when set after blocked", () => {
-			const result = resolveBlockedVsTrust(
+			const result = resolveSenderPlacement(
 				{ trust: SenderTrust.Vip, setAt: 5_000 },
 				{ blocked: true, setAt: 1_000 },
+				false,
 			);
 			assert.deepEqual(result, {
 				senderTrust: SenderTrust.Vip,
-				senderBlocked: false,
+				senderOverride: SenderOverride.None,
 			});
 		});
 
 		it("breaks a same-second tie in favor of blocked", () => {
-			const result = resolveBlockedVsTrust(
+			const result = resolveSenderPlacement(
 				{ trust: SenderTrust.Wellknown, setAt: 1_000 },
 				{ blocked: true, setAt: 1_400 },
+				false,
 			);
 			assert.deepEqual(result, {
 				senderTrust: SenderTrust.Unknown,
-				senderBlocked: true,
+				senderOverride: SenderOverride.Blocked,
 			});
 		});
 
 		it("blocked applies outright when there is no competing trust flag", () => {
-			const result = resolveBlockedVsTrust(
+			const result = resolveSenderPlacement(
 				{ trust: SenderTrust.Unknown },
 				{ blocked: true, setAt: 1_000 },
+				false,
 			);
 			assert.deepEqual(result, {
 				senderTrust: SenderTrust.Unknown,
-				senderBlocked: true,
+				senderOverride: SenderOverride.Blocked,
 			});
 		});
 
-		it("passes trust through unchanged when the sender isn't blocked", () => {
-			const result = resolveBlockedVsTrust(
+		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,
-				senderBlocked: false,
+				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 senderBlocked=false)", () => {
+	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,
-				false,
+				SenderOverride.None,
 			);
 			assert.equal(verdict.action, "move-to-inbox");
 			assert.equal(verdict.confidence, "confident");
@@ -171,7 +323,7 @@ describe("classifyPlacement", () => {
 				baseMessage({ providerSpam: { classified: true } }),
 				"junk",
 				SenderTrust.Unknown,
-				false,
+				SenderOverride.None,
 			);
 			assert.equal(verdict.action, "leave");
 			assert.equal(verdict.confidence, "unsure");
@@ -185,7 +337,7 @@ describe("classifyPlacement", () => {
 				}),
 				"inbox",
 				SenderTrust.Unknown,
-				false,
+				SenderOverride.None,
 			);
 			assert.deepEqual(verdict, {
 				action: "move-to-junk",
@@ -202,7 +354,7 @@ describe("classifyPlacement", () => {
 				}),
 				"inbox",
 				SenderTrust.Unknown,
-				false,
+				SenderOverride.None,
 			);
 			assert.deepEqual(verdict, {
 				action: "leave",

package/src/heuristics/classifyPlacement.ts

@@ -1,8 +1,10 @@
 import type { MessageItem } from "@remit/data-ports";
-import { SenderTrust } from "@remit/domain-enums";
+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";
@@ -39,7 +41,7 @@ export interface SenderBlockedSignal {
  * fixed, arbitrary order: `blocked` before `vip` before `wellknown` — a
  * determinism backstop, not a meaningful signal.
  */
-export const resolveBlockedVsTrust = (
+const resolveBlockedVsTrust = (
 	trust: SenderTrustSignal,
 	blocked: SenderBlockedSignal,
 ): { senderTrust: SenderTrustValue; senderBlocked: boolean } => {
@@ -60,6 +62,32 @@ export const resolveBlockedVsTrust = (
 	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").
  *
@@ -69,17 +97,32 @@ export const resolveBlockedVsTrust = (
  * recall-biased — a confident move only fires when cheap, deterministic signals
  * agree; everything else is left in place for a later LLM tier.
  *
- * `senderBlocked` (RFC 039 Decision 3) is a confident demote independent of
- * every DKIM/DMARC/provider signal below — a user's explicit block is not a
- * heuristic. Already-tie-broken against `vip`/`wellknown` by
- * {@link resolveBlockedVsTrust} in the caller; this function itself does not
+ * `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,
-	senderBlocked: boolean,
+	senderOverride: SenderOverrideValue,
 ): PlacementVerdict => {
 	if (message.movedByRemit === true) {
 		return {
@@ -89,7 +132,7 @@ export const classifyPlacement = (
 		};
 	}
 
-	if (senderBlocked && placement !== "junk") {
+	if (senderOverride === SenderOverride.Blocked && placement !== "junk") {
 		return {
 			action: "move-to-junk",
 			confidence: "confident",
@@ -97,6 +140,19 @@ export const classifyPlacement = (
 		};
 	}
 
+	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",