@remit/mailbox-service 0.0.46 → 0.0.48

package/package.json

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

package/src/heuristics/classifyByHeaders.ts

@@ -95,7 +95,11 @@ export const classifyByHeaders = (parsed: ParsedMail): Category => {
 	if (matchesPrecedence(headers)) return MessageCategory.automated;
 	if (isMachineSender(parsed, lines)) return MessageCategory.automated;
 
-	if (fromDomain && dkimMismatchResult(headers, lines, fromDomain).mismatch) {
+	if (
+		fromDomain &&
+		pickAlignedOrFirstMismatch(extractDkimDomains(headers, lines), fromDomain)
+			.mismatch
+	) {
 		return MessageCategory.automated;
 	}
 
@@ -126,15 +130,12 @@ export const extractAuthenticity = (
 	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];
+	const picked = pickAlignedOrFirstMismatch(dkimDomains, fromDomain);
 
 	return {
 		fromDomain,
-		dkimDomain: reportedDomain,
-		dkimMismatch: result.mismatch,
+		dkimDomain: picked.domain ?? undefined,
+		dkimMismatch: picked.mismatch,
 	};
 };
 
@@ -296,38 +297,34 @@ const domainMatches = (
 };
 
 /**
- * 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".
+ * Whether a signing domain aligns with the From domain: equal, or one is a
+ * subdomain of the other (parent/child). A legitimate re-mailer signing under
+ * a subdomain is not suspicious, so either direction counts as aligned.
  */
-const dkimMismatchResult = (
-	headers: Headers,
-	lines: HeaderLines,
+const domainsAligned = (signingDomain: string, fromDomain: string): boolean =>
+	signingDomain === fromDomain ||
+	fromDomain.endsWith(`.${signingDomain}`) ||
+	signingDomain.endsWith(`.${fromDomain}`);
+
+/**
+ * Pick the domain to report out of a list of candidate signing domains: the
+ * first one aligned with the From domain, so a legitimate signature is never
+ * shadowed by an earlier unrelated one. When none align, the first is
+ * reported as the mismatching evidence — the UI can then show "signed by
+ * relay.example.net, claims example.com". Shared by the category heuristic
+ * (rule 9, which reads only `.mismatch`) and the authenticity extractor
+ * (which also reads `.domain`), so the two can never disagree.
+ */
+const pickAlignedOrFirstMismatch = (
+	domains: string[],
 	fromDomain: string,
-): { mismatch: boolean; mismatchingDomain: string | null } => {
-	const dkimDomains = extractDkimDomains(headers, lines);
-	if (dkimDomains.length === 0)
-		return { mismatch: false, mismatchingDomain: null };
+): { mismatch: boolean; domain: string | 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 };
-		}
+	for (const d of domains) {
+		if (domainsAligned(d, fromDomain)) return { mismatch: false, domain: d };
 		if (!firstMismatching) firstMismatching = d;
 	}
-	return { mismatch: true, mismatchingDomain: firstMismatching };
+	return { mismatch: firstMismatching !== null, domain: firstMismatching };
 };
 
 const extractDkimDomains = (headers: Headers, lines: HeaderLines): string[] => {

package/src/heuristics/senderMismatch.test.ts

@@ -87,6 +87,28 @@ describe("classifyDisplayNameCorrespondence", () => {
 			DisplayNameCorrespondence.Unrelated,
 		);
 	});
+
+	// Live phishing shape: a short, valuable brand name embedded as a
+	// coincidental substring of a longer, attacker-chosen domain. "ing" sits
+	// inside "secureingverify" the same way "irs"/"dhl"/"ups"/"kpn" sit inside
+	// countless lookalike domains — none of that is the domain naming the
+	// brand.
+	it("does not match a short brand name that is merely embedded in a longer domain label (ING)", () => {
+		assert.equal(
+			classifyDisplayNameCorrespondence(
+				"ING Fraudedesk",
+				"secure-ing-verify.tk",
+			),
+			DisplayNameCorrespondence.Unrelated,
+		);
+	});
+
+	it("still matches a short brand name against its own real domain", () => {
+		assert.equal(
+			classifyDisplayNameCorrespondence("ING", "ing.nl"),
+			DisplayNameCorrespondence.Corresponds,
+		);
+	});
 });
 
 describe("extractOffDomainLinkDomains", () => {

package/src/heuristics/senderMismatch.ts

@@ -90,11 +90,22 @@ const lookalikeThreshold = (length: number): number => {
 /**
  * Whether the From display name corresponds to the From domain.
  *
- * Containment decides: the normalised name, or any word of it, appearing inside
- * the registrable domain or one of the domain's labels. `GitHub` sits inside
- * `notifications.github.com`; `InfoMedics` sits nowhere inside
+ * Containment decides: the normalised name, or any word of it, containing an
+ * entire domain candidate. `GitHub` contains the label `github` from
+ * `notifications.github.com`; `InfoMedics` contains no label of
  * `serviceupdatebank.atlassian.net`.
  *
+ * Only that direction counts — a domain candidate containing the (shorter)
+ * name does not. `ING Fraudedesk` is not a match for `secure-ing-verify.tk`
+ * just because the three-letter word "ing" sits inside "secureingverify":
+ * that is a coincidental substring of a longer label the domain owner chose,
+ * not a domain that names the brand. The direction this drops is exactly the
+ * one a short, valuable brand name is deliberately embedded into a longer,
+ * unrelated-looking domain to exploit — the live Dutch-bank shape this was
+ * fixed against (`ING`). A real short brand over its own domain (`ING` /
+ * `ing.nl`) still matches: name and label are then equal, and equality
+ * satisfies containment in either direction.
+ *
  * A bounded edit distance is the secondary test, and only reaches names that
  * nearly match a label — `InfoMedics` against `1nfomedics.nl`. It cannot promote
  * an unrelated name on its own.
@@ -117,7 +128,7 @@ export const classifyDisplayNameCorrespondence = (
 	const terms = [name, ...words(raw)];
 	for (const term of terms) {
 		for (const candidate of candidates) {
-			if (candidate.includes(term) || term.includes(candidate)) {
+			if (term.includes(candidate)) {
 				return DisplayNameCorrespondence.Corresponds;
 			}
 		}

package/src/index.ts

@@ -233,6 +233,13 @@ export {
 	normalizeSubject,
 	removeQuotedContent,
 } from "./snippet.js";
+export {
+	MoveNotSettledError,
+	type SpamReportConfig,
+	type SpamReportLogger,
+	type SpamReportParams,
+	SpamReportService,
+} from "./spam-report.js";
 export {
 	reconcileStaleMessage,
 	type StaleMessageReconcileDeps,

package/src/spam-report.test.ts

@@ -0,0 +1,606 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type {
+	AddressFlags,
+	IAccountRepository,
+	IAddressRepository,
+	IMailboxRepository,
+	IMailboxSpecialUseRepository,
+	IMessageFlagPushRepository,
+	IMessageRepository,
+	IThreadMessageRepository,
+} from "@remit/data-ports";
+import { AddressRole } from "@remit/domain-enums";
+import { FlagPushService } from "./flag-push.js";
+import { MessageMoveService } from "./message-move.js";
+import { MoveNotSettledError, SpamReportService } from "./spam-report.js";
+
+const ACCOUNT = "acc-1";
+const ACCOUNT_CONFIG = "cfg-1";
+const ACCOUNT_EMAIL = "me@example.com";
+const INBOX_MAILBOX = "mbx-inbox";
+const JUNK_MAILBOX = "mbx-junk";
+const MESSAGE_ID = "msg-1";
+const ADDRESS_ID = "addr-1";
+const THREAD_ID = "thread-1";
+
+interface ThreadRow {
+	accountConfigId: string;
+	threadMessageId: string;
+	threadId: string;
+	messageId: string;
+	mailboxId: string;
+	messageIdHeader: string;
+	isRead?: boolean;
+	hasStars?: boolean;
+	hasAttachment?: boolean;
+	isDeleted?: boolean;
+}
+
+interface World {
+	service: SpamReportService;
+	messages: Map<string, Record<string, unknown>>;
+	addresses: Map<string, { flags: AddressFlags }>;
+	threadRows: ThreadRow[];
+	sent: unknown[];
+	sqsImpl: { send: (command: unknown) => Promise<unknown> };
+	markerPuts: Array<Record<string, unknown>>;
+}
+
+const settleMove = (messages: Map<string, Record<string, unknown>>) => {
+	const m = messages.get(MESSAGE_ID);
+	assert.ok(m !== undefined);
+	m.status = "active";
+	m.syncStatus = "synced";
+};
+
+const buildWorld = (
+	opts: {
+		startMailbox?: string;
+		fromEmail?: string;
+		originalMailboxId?: string;
+	} = {},
+): World => {
+	const startMailbox = opts.startMailbox ?? INBOX_MAILBOX;
+	const fromEmail = opts.fromEmail ?? "sender@example.com";
+
+	const messages = new Map<string, Record<string, unknown>>([
+		[
+			MESSAGE_ID,
+			{
+				messageId: MESSAGE_ID,
+				mailboxId: startMailbox,
+				uid: 42,
+				rfc822Size: 100,
+				internalDate: 1_700_000_000_000,
+				envelopeId: "env-1",
+				rootBodyPartId: "body-1",
+				category: "primary",
+				hasListUnsubscribe: false,
+				syncStatus: "synced",
+				...(opts.originalMailboxId
+					? { originalMailboxId: opts.originalMailboxId }
+					: {}),
+			},
+		],
+	]);
+
+	const addresses = new Map<string, { flags: AddressFlags }>([
+		[ADDRESS_ID, { flags: {} }],
+	]);
+
+	const threadRows: ThreadRow[] = [
+		{
+			accountConfigId: ACCOUNT_CONFIG,
+			threadMessageId: `tm:${THREAD_ID}::${MESSAGE_ID}`,
+			threadId: THREAD_ID,
+			messageId: MESSAGE_ID,
+			mailboxId: INBOX_MAILBOX,
+			messageIdHeader: "<abc@example.com>",
+			isRead: false,
+			hasStars: false,
+		},
+	];
+
+	const mailboxes = new Map<string, Record<string, unknown>>([
+		[
+			INBOX_MAILBOX,
+			{ mailboxId: INBOX_MAILBOX, fullPath: "INBOX", accountId: ACCOUNT },
+		],
+		[
+			JUNK_MAILBOX,
+			{ mailboxId: JUNK_MAILBOX, fullPath: "Junk", accountId: ACCOUNT },
+		],
+	]);
+
+	const messageService = {
+		get: async (id: string | string[]) => {
+			if (Array.isArray(id)) {
+				return id.map((i) => messages.get(i)).filter(Boolean);
+			}
+			const m = messages.get(id);
+			if (!m) throw new Error(`no message ${id}`);
+			return m;
+		},
+		describe: async (id: string) => {
+			const m = messages.get(id);
+			if (!m) throw new Error(`no message ${id}`);
+			return {
+				message: [m],
+				messageFlag: [],
+				envelope: [],
+				messageReference: [],
+				envelopeAddress: [
+					{
+						envelopeAddressId: "ea-1",
+						messageId: id,
+						addressId: ADDRESS_ID,
+						normalizedEmail: fromEmail,
+						addressRole: AddressRole.From,
+						addressOrder: 0,
+					},
+				],
+				bodyPart: [],
+				bodyPartParameter: [],
+				rawMessageStorage: [],
+				bodyPartStorage: [],
+				bodyPartContent: [],
+			};
+		},
+		update: async (id: string, patch: Record<string, unknown>) => {
+			const m = messages.get(id);
+			if (m) Object.assign(m, patch);
+			return m;
+		},
+		updateForMove: async (id: string, patch: Record<string, unknown>) => {
+			const m = messages.get(id);
+			if (m) Object.assign(m, patch);
+			return m;
+		},
+		clearSpamReport: async (id: string) => {
+			const m = messages.get(id);
+			if (m) delete m.spamReport;
+			return m;
+		},
+		clearOriginalMailboxId: async (id: string) => {
+			const m = messages.get(id);
+			if (m) {
+				delete m.originalMailboxId;
+				delete m.originalUid;
+			}
+			return m;
+		},
+	} as unknown as IMessageRepository;
+
+	const addressService = {
+		mergeFlags: async (
+			_accountConfigId: string,
+			addressId: string,
+			patch: Record<string, unknown>,
+		) => {
+			const entry = addresses.get(addressId);
+			if (!entry) throw new Error(`no address ${addressId}`);
+			const next = { ...entry.flags } as Record<string, unknown>;
+			for (const [key, value] of Object.entries(patch)) {
+				if (value === undefined) continue;
+				if (value === null) {
+					delete next[key];
+					continue;
+				}
+				next[key] = value;
+			}
+			entry.flags = next as AddressFlags;
+			return { addressId, flags: entry.flags };
+		},
+	} as unknown as IAddressRepository;
+
+	const accountService = {
+		get: async () => ({ accountId: ACCOUNT, email: ACCOUNT_EMAIL }),
+	} as unknown as IAccountRepository;
+
+	const mailboxSpecialUseService = {
+		findJunkMailbox: async () => ({
+			mailboxId: JUNK_MAILBOX,
+			fullPath: "Junk",
+		}),
+		findTrashMailbox: async () => null,
+	} as unknown as IMailboxSpecialUseRepository;
+
+	const mailboxService = {
+		get: async (_acc: string, id: string | string[]) => {
+			if (Array.isArray(id)) {
+				return id.map((i) => mailboxes.get(i)).filter(Boolean);
+			}
+			return mailboxes.get(id);
+		},
+	} as unknown as IMailboxRepository;
+
+	const threadMessageService = {
+		getByMessageId: async (_cfg: string, messageId: string) => {
+			const row = threadRows.find((r) => r.messageId === messageId);
+			if (!row) throw new Error(`no thread message ${messageId}`);
+			return row;
+		},
+		update: async (
+			_cfg: string,
+			threadMessageId: string,
+			patch: Record<string, unknown>,
+		) => {
+			const row = threadRows.find((r) => r.threadMessageId === threadMessageId);
+			if (row) Object.assign(row, patch);
+			return row;
+		},
+	} as unknown as IThreadMessageRepository;
+
+	const sent: unknown[] = [];
+	const sqsImpl = {
+		send: async (command: unknown) => {
+			sent.push(command);
+			return {};
+		},
+	};
+
+	const messageMoveService = new MessageMoveService({
+		messageService,
+		mailboxService,
+		mailboxSpecialUseService,
+		threadMessageService,
+		sqsQueueUrl: "http://localhost:9324/000000000000/message-mgmt",
+	});
+	(
+		messageMoveService as unknown as {
+			sqs: { send: (c: unknown) => Promise<unknown> };
+		}
+	).sqs = sqsImpl;
+
+	const markerPuts: Array<Record<string, unknown>> = [];
+	const markerService: IMessageFlagPushRepository = {
+		put: async (input: Record<string, unknown>) => {
+			markerPuts.push(input);
+			return {
+				...input,
+				state: "pending",
+				createdAt: 1,
+				updatedAt: 1,
+			} as never;
+		},
+		find: async () => null,
+		updateState: async () => ({}) as never,
+		delete: async () => {},
+		listByAccountId: async () => [],
+		listByMailboxId: async () => [],
+	};
+
+	const flagPushService = new FlagPushService({
+		markerService,
+		sqsQueueUrl: "http://localhost:9324/000000000000/flag-push",
+	});
+	(
+		flagPushService as unknown as {
+			sqs: { send: (c: unknown) => Promise<unknown> };
+		}
+	).sqs = sqsImpl;
+
+	const service = new SpamReportService({
+		messageService,
+		addressService,
+		accountService,
+		mailboxSpecialUseService,
+		messageMoveService,
+		flagPushService,
+		// Small and fast: these tests simulate settlement explicitly (via
+		// settleMove) rather than waiting out a real timeout.
+		moveSettleTimeoutMs: 30,
+		moveSettlePollMs: 5,
+	});
+
+	return {
+		service,
+		messages,
+		addresses,
+		threadRows,
+		sent,
+		sqsImpl,
+		markerPuts,
+	};
+};
+
+const moveEvents = (sent: unknown[]) =>
+	sent.filter(
+		(cmd) =>
+			JSON.parse((cmd as { input: { MessageBody: string } }).input.MessageBody)
+				.type === "MESSAGE_MOVE",
+	);
+
+describe("SpamReportService.reportSpam", () => {
+	it("sets the blocked flag and enqueues the move to Junk", async () => {
+		const { service, messages, addresses, sent, markerPuts } = buildWorld();
+
+		await service.reportSpam({
+			accountConfigId: ACCOUNT_CONFIG,
+			accountId: ACCOUNT,
+			messageId: MESSAGE_ID,
+			setBy: "user-1",
+		});
+
+		const address = addresses.get(ADDRESS_ID);
+		assert.equal(address?.flags.blocked?.value, true);
+		assert.equal(address?.flags.blocked?.setBy, "user-1");
+
+		const message = messages.get(MESSAGE_ID);
+		assert.equal(message?.mailboxId, JUNK_MAILBOX);
+		assert.equal(moveEvents(sent).length, 1);
+
+		assert.equal(markerPuts.length, 1);
+		assert.equal(markerPuts[0].flagName, "$Junk");
+		assert.equal(markerPuts[0].operation, "add");
+
+		assert.ok(message !== undefined);
+		const spamReport = message.spamReport as { reportedAt: number };
+		assert.ok(spamReport.reportedAt > 0);
+	});
+
+	it("leaves the blocked flag in place when the move fails", async () => {
+		const world = buildWorld();
+		world.sqsImpl.send = async () => {
+			throw new Error("SQS unavailable");
+		};
+
+		await assert.rejects(
+			() =>
+				world.service.reportSpam({
+					accountConfigId: ACCOUNT_CONFIG,
+					accountId: ACCOUNT,
+					messageId: MESSAGE_ID,
+				}),
+			/SQS unavailable/,
+		);
+
+		const address = world.addresses.get(ADDRESS_ID);
+		assert.equal(address?.flags.blocked?.value, true);
+	});
+
+	it("is idempotent under a double press", async () => {
+		const { service, sent } = buildWorld();
+
+		await service.reportSpam({
+			accountConfigId: ACCOUNT_CONFIG,
+			accountId: ACCOUNT,
+			messageId: MESSAGE_ID,
+		});
+		await service.reportSpam({
+			accountConfigId: ACCOUNT_CONFIG,
+			accountId: ACCOUNT,
+			messageId: MESSAGE_ID,
+		});
+
+		// The second call's move is a no-op: MessageMoveService.moveMessage sees
+		// the local mailboxId already equals Junk and skips without enqueueing.
+		assert.equal(moveEvents(sent).length, 1);
+	});
+
+	it("moves the message but writes no sender block when the message is forged from the account's own address", async () => {
+		const { service, messages, addresses, sent } = buildWorld({
+			fromEmail: ACCOUNT_EMAIL,
+		});
+
+		await service.reportSpam({
+			accountConfigId: ACCOUNT_CONFIG,
+			accountId: ACCOUNT,
+			messageId: MESSAGE_ID,
+		});
+
+		const address = addresses.get(ADDRESS_ID);
+		assert.equal(address?.flags.blocked, undefined);
+
+		const message = messages.get(MESSAGE_ID);
+		assert.equal(message?.mailboxId, JUNK_MAILBOX);
+		assert.equal(moveEvents(sent).length, 1);
+		assert.ok(message !== undefined);
+		assert.ok((message.spamReport as { reportedAt: number }).reportedAt > 0);
+	});
+});
+
+describe("SpamReportService.notSpam", () => {
+	it("restores the original mailbox and clears the flag without setting trust", async () => {
+		const { service, messages, addresses } = buildWorld();
+
+		await service.reportSpam({
+			accountConfigId: ACCOUNT_CONFIG,
+			accountId: ACCOUNT,
+			messageId: MESSAGE_ID,
+		});
+		settleMove(messages);
+		await service.notSpam({
+			accountConfigId: ACCOUNT_CONFIG,
+			accountId: ACCOUNT,
+			messageId: MESSAGE_ID,
+		});
+
+		const message = messages.get(MESSAGE_ID);
+		assert.equal(message?.mailboxId, INBOX_MAILBOX);
+		assert.equal(message?.spamReport, undefined);
+
+		const address = addresses.get(ADDRESS_ID);
+		assert.equal(address?.flags.blocked, undefined);
+		assert.equal(address?.flags.wellknown, undefined);
+		assert.equal(address?.flags.trusted, undefined);
+		assert.equal(address?.flags.vip, undefined);
+	});
+
+	it("clears the block and provenance without a 500 when the message never actually moved (same-mailbox no-op)", async () => {
+		// report-spam pressed on a message the provider's filter already placed
+		// in Junk: MessageMoveService.moveMessage's same-mailbox guard skips, so
+		// originalMailboxId is never set — status never becomes "moving" either,
+		// so notSpam has nothing to wait on.
+		const { service, messages, addresses } = buildWorld({
+			startMailbox: JUNK_MAILBOX,
+		});
+
+		await service.reportSpam({
+			accountConfigId: ACCOUNT_CONFIG,
+			accountId: ACCOUNT,
+			messageId: MESSAGE_ID,
+		});
+		await service.notSpam({
+			accountConfigId: ACCOUNT_CONFIG,
+			accountId: ACCOUNT,
+			messageId: MESSAGE_ID,
+		});
+
+		const message = messages.get(MESSAGE_ID);
+		assert.equal(message?.mailboxId, JUNK_MAILBOX, "left where it is");
+		assert.equal(message?.spamReport, undefined);
+
+		const address = addresses.get(ADDRESS_ID);
+		assert.equal(address?.flags.blocked, undefined);
+	});
+
+	it("clears a stale originalMailboxId left by an earlier, unrelated move instead of restoring to it", async () => {
+		// The message is already in Junk (an earlier, unrelated move put it
+		// there) and still carries that move's originalMailboxId. report-spam's
+		// own move is a same-mailbox no-op — moveMessage never touches
+		// originalMailboxId — so without an explicit clear, notSpam would
+		// restore to a folder this report-spam action never moved it out of.
+		const OTHER_MAILBOX = "mbx-other";
+		const { service, messages, addresses } = buildWorld({
+			startMailbox: JUNK_MAILBOX,
+			originalMailboxId: OTHER_MAILBOX,
+		});
+
+		await service.reportSpam({
+			accountConfigId: ACCOUNT_CONFIG,
+			accountId: ACCOUNT,
+			messageId: MESSAGE_ID,
+		});
+
+		assert.equal(messages.get(MESSAGE_ID)?.originalMailboxId, undefined);
+
+		await service.notSpam({
+			accountConfigId: ACCOUNT_CONFIG,
+			accountId: ACCOUNT,
+			messageId: MESSAGE_ID,
+		});
+
+		const message = messages.get(MESSAGE_ID);
+		assert.equal(message?.mailboxId, JUNK_MAILBOX, "left where it is");
+		assert.notEqual(message?.mailboxId, OTHER_MAILBOX);
+
+		const address = addresses.get(ADDRESS_ID);
+		assert.equal(address?.flags.blocked, undefined);
+	});
+
+	it("does not clear originalMailboxId set by an earlier report-spam press — a second report then Undo still restores", async () => {
+		// The most common reason a message is already in Junk when reportSpam
+		// runs is a PREVIOUS reportSpam press, not some unrelated move — and
+		// that earlier press is exactly what owns the originalMailboxId Undo
+		// needs. A second press must not treat its own prior work as stale.
+		const { service, messages, sent } = buildWorld();
+
+		await service.reportSpam({
+			accountConfigId: ACCOUNT_CONFIG,
+			accountId: ACCOUNT,
+			messageId: MESSAGE_ID,
+		});
+		settleMove(messages);
+
+		await service.reportSpam({
+			accountConfigId: ACCOUNT_CONFIG,
+			accountId: ACCOUNT,
+			messageId: MESSAGE_ID,
+		});
+
+		assert.equal(
+			messages.get(MESSAGE_ID)?.originalMailboxId,
+			INBOX_MAILBOX,
+			"the second press must not destroy the first press's originalMailboxId",
+		);
+
+		await service.notSpam({
+			accountConfigId: ACCOUNT_CONFIG,
+			accountId: ACCOUNT,
+			messageId: MESSAGE_ID,
+		});
+
+		const message = messages.get(MESSAGE_ID);
+		assert.equal(
+			message?.mailboxId,
+			INBOX_MAILBOX,
+			"undo must actually restore the message, not leave it stuck in Junk",
+		);
+		// INBOX->Junk (press 1), Junk->INBOX (undo) — press 2 was a same-mailbox
+		// no-op and must not have enqueued a move of its own.
+		assert.equal(moveEvents(sent).length, 2);
+	});
+
+	it("is idempotent under a double press — a second undo does not re-junk the message", async () => {
+		const { service, messages, sent } = buildWorld();
+
+		await service.reportSpam({
+			accountConfigId: ACCOUNT_CONFIG,
+			accountId: ACCOUNT,
+			messageId: MESSAGE_ID,
+		});
+		settleMove(messages);
+		await service.notSpam({
+			accountConfigId: ACCOUNT_CONFIG,
+			accountId: ACCOUNT,
+			messageId: MESSAGE_ID,
+		});
+		// originalMailboxId is already cleared, so the second call has nothing
+		// to wait on or restore — no need to settle again.
+		await service.notSpam({
+			accountConfigId: ACCOUNT_CONFIG,
+			accountId: ACCOUNT,
+			messageId: MESSAGE_ID,
+		});
+
+		const message = messages.get(MESSAGE_ID);
+		assert.equal(message?.mailboxId, INBOX_MAILBOX);
+		assert.equal(message?.originalMailboxId, undefined);
+		// INBOX->Junk (report), Junk->INBOX (undo #1) — undo #2 must not add a
+		// third INBOX->Junk move.
+		assert.equal(moveEvents(sent).length, 2);
+	});
+
+	it("throws without restoring or clearing provenance when the move has not settled yet (R2 wait)", async () => {
+		const { service, messages, addresses } = buildWorld();
+
+		await service.reportSpam({
+			accountConfigId: ACCOUNT_CONFIG,
+			accountId: ACCOUNT,
+			messageId: MESSAGE_ID,
+		});
+		// Deliberately NOT settled: status stays "moving", as it would while
+		// the original MESSAGE_MOVE is still genuinely in flight or retrying.
+
+		await assert.rejects(
+			() =>
+				service.notSpam({
+					accountConfigId: ACCOUNT_CONFIG,
+					accountId: ACCOUNT,
+					messageId: MESSAGE_ID,
+				}),
+			(error: unknown) => {
+				// Must be the dedicated type, not a plain Error — callers that
+				// surface failures to the user (packages/backend) allowlist this
+				// specific type rather than relaying an arbitrary message.
+				assert.ok(error instanceof MoveNotSettledError);
+				assert.match(error.message, /has not settled yet/);
+				return true;
+			},
+		);
+
+		// The sender block clear is independent of the move (R2 reconcile) and
+		// still lands even though the restore did not.
+		const address = addresses.get(ADDRESS_ID);
+		assert.equal(address?.flags.blocked, undefined);
+
+		// But nothing move-related was touched — a real move #2 must not be
+		// enqueued against an unsettled move #1.
+		const message = messages.get(MESSAGE_ID);
+		assert.equal(message?.mailboxId, JUNK_MAILBOX);
+		assert.ok(message !== undefined);
+		assert.ok((message.spamReport as { reportedAt: number }).reportedAt > 0);
+	});
+});

package/src/spam-report.ts

@@ -0,0 +1,253 @@
+import type {
+	IAccountRepository,
+	IAddressRepository,
+	IMailboxSpecialUseRepository,
+	IMessageRepository,
+	MessageItem,
+} from "@remit/data-ports";
+import {
+	AddressRole,
+	MessageKeywordFlag,
+	MessageStatus,
+} from "@remit/domain-enums";
+import type { FlagPushService } from "./flag-push.js";
+import type { MessageMoveService } from "./message-move.js";
+
+export interface SpamReportLogger {
+	info(obj: Record<string, unknown>, msg: string): void;
+	error(obj: Record<string, unknown>, msg: string): void;
+}
+
+/**
+ * The one designed, user-facing outcome of `notSpam`'s R2 wait timing out —
+ * distinct from any other failure so a caller surfacing failures to the user
+ * (the bulk handlers in packages/backend) can allowlist this specific,
+ * pre-written message instead of relaying an arbitrary thrown error's text.
+ */
+export class MoveNotSettledError extends Error {
+	constructor(messageId: string) {
+		super(
+			`Message ${messageId}'s move to Junk has not settled yet; try again in a moment.`,
+		);
+		this.name = "MoveNotSettledError";
+	}
+}
+
+const noopLogger: SpamReportLogger = {
+	info: () => {},
+	error: () => {},
+};
+
+const DEFAULT_MOVE_SETTLE_TIMEOUT_MS = 5_000;
+const DEFAULT_MOVE_SETTLE_POLL_MS = 250;
+
+export interface SpamReportConfig {
+	messageService: IMessageRepository;
+	addressService: IAddressRepository;
+	accountService: IAccountRepository;
+	mailboxSpecialUseService: IMailboxSpecialUseRepository;
+	messageMoveService: MessageMoveService;
+	flagPushService: FlagPushService;
+	logger?: SpamReportLogger;
+	/** How long `notSpam` waits for a still-in-flight move before giving up. */
+	moveSettleTimeoutMs?: number;
+	moveSettlePollMs?: number;
+}
+
+export interface SpamReportParams {
+	accountConfigId: string;
+	accountId: string;
+	messageId: string;
+	setBy?: string;
+}
+
+export class SpamReportService {
+	private messageService: IMessageRepository;
+	private addressService: IAddressRepository;
+	private accountService: IAccountRepository;
+	private mailboxSpecialUseService: IMailboxSpecialUseRepository;
+	private messageMoveService: MessageMoveService;
+	private flagPushService: FlagPushService;
+	private log: SpamReportLogger;
+	private moveSettleTimeoutMs: number;
+	private moveSettlePollMs: number;
+
+	constructor(config: SpamReportConfig) {
+		this.messageService = config.messageService;
+		this.addressService = config.addressService;
+		this.accountService = config.accountService;
+		this.mailboxSpecialUseService = config.mailboxSpecialUseService;
+		this.messageMoveService = config.messageMoveService;
+		this.flagPushService = config.flagPushService;
+		this.log = config.logger ?? noopLogger;
+		this.moveSettleTimeoutMs =
+			config.moveSettleTimeoutMs ?? DEFAULT_MOVE_SETTLE_TIMEOUT_MS;
+		this.moveSettlePollMs =
+			config.moveSettlePollMs ?? DEFAULT_MOVE_SETTLE_POLL_MS;
+	}
+
+	private resolveFromAddress = async (
+		messageId: string,
+	): Promise<{ addressId: string; normalizedEmail: string }> => {
+		const description = await this.messageService.describe(messageId);
+		const from = description.envelopeAddress.find(
+			(a) => a.addressRole === AddressRole.From,
+		);
+		if (!from) {
+			throw new Error(`Message ${messageId} has no From address to act on`);
+		}
+		return { addressId: from.addressId, normalizedEmail: from.normalizedEmail };
+	};
+
+	/**
+	 * R2 wait (docs/architecture/imap-mutations.md): `notSpam`'s restore is a
+	 * dependent write against report-spam's own move — enqueuing it while that
+	 * move is still in flight (`status === moving`) would carry the message's
+	 * pre-move `uid` (only a CONFIRMED move updates it, via `updateUid`) and
+	 * risk acting on the wrong server-side message once both moves are
+	 * in-flight at once. Cheap to block per the doc's default guidance: a move
+	 * ordinarily settles in well under a second. On timeout the dependent
+	 * write is not made — the caller is told to retry, and retrying is safe
+	 * (this whole flow is idempotent).
+	 */
+	private waitForMoveToSettle = async (
+		messageId: string,
+	): Promise<MessageItem> => {
+		const deadline = Date.now() + this.moveSettleTimeoutMs;
+		let message = await this.messageService.get(messageId);
+		while (message.status === MessageStatus.moving && Date.now() < deadline) {
+			await new Promise((resolve) =>
+				setTimeout(resolve, this.moveSettlePollMs),
+			);
+			message = await this.messageService.get(messageId);
+		}
+		return message;
+	};
+
+	reportSpam = async (params: SpamReportParams): Promise<void> => {
+		const { accountConfigId, accountId, messageId, setBy } = params;
+		const now = Date.now();
+
+		const from = await this.resolveFromAddress(messageId);
+		const account = await this.accountService.get(accountId);
+		const isOwnAddress =
+			from.normalizedEmail.toLowerCase() === account.email.toLowerCase();
+
+		if (!isOwnAddress) {
+			await this.addressService.mergeFlags(accountConfigId, from.addressId, {
+				blocked: { value: true, setAt: now, setBy },
+			});
+		}
+
+		// Captured before this call writes anything: `before.spamReport` tells
+		// apart the two reasons the message can already be in Junk. If it is
+		// already set, a PREVIOUS report-spam press put it there and owns
+		// `originalMailboxId` — that value is exactly what Undo needs and must
+		// survive a repeated press. Only when it is absent is the message in
+		// Junk for some unrelated reason (a provider filter, a manual move),
+		// making any `originalMailboxId` on the row stale.
+		const before = await this.messageService.get(messageId);
+		const hadSpamReportAlready = Boolean(before.spamReport);
+
+		await this.messageService.update(messageId, {
+			spamReport: { reportedAt: now },
+		});
+
+		const junkMailbox =
+			await this.mailboxSpecialUseService.findJunkMailbox(accountId);
+		if (!junkMailbox) {
+			throw new Error(`No Junk mailbox found for account ${accountId}`);
+		}
+
+		const alreadyInJunk = before.mailboxId === junkMailbox.mailboxId;
+
+		await this.messageMoveService.moveMessage(
+			accountConfigId,
+			messageId,
+			junkMailbox.mailboxId,
+			accountId,
+		);
+
+		if (alreadyInJunk && before.originalMailboxId && !hadSpamReportAlready) {
+			// moveMessage's same-mailbox guard no-opped — it never touches
+			// originalMailboxId, so a stale value left by some earlier, unrelated
+			// move would otherwise survive and send a later notSpam to the wrong
+			// folder. This report-spam action established no move of its own.
+			await this.messageService.clearOriginalMailboxId(messageId);
+		}
+
+		await this.flagPushService.flip({
+			accountId,
+			accountConfigId,
+			messageId,
+			mailboxId: junkMailbox.mailboxId,
+			flagName: MessageKeywordFlag.Junk,
+			operation: "add",
+		});
+
+		this.log.info(
+			{
+				accountId,
+				messageId,
+				addressId: from.addressId,
+				junkMailboxId: junkMailbox.mailboxId,
+				skippedBlock: isOwnAddress,
+			},
+			"Reported message as spam",
+		);
+	};
+
+	notSpam = async (params: SpamReportParams): Promise<void> => {
+		const { accountConfigId, accountId, messageId } = params;
+
+		const from = await this.resolveFromAddress(messageId);
+		await this.addressService.mergeFlags(accountConfigId, from.addressId, {
+			blocked: null,
+		});
+
+		const message = await this.messageService.get(messageId);
+
+		if (message.originalMailboxId) {
+			// Only wait on the move's settlement when there is actually a
+			// dependent write to make (the restore below) — a move in flight for
+			// an unrelated reason is not this operation's concern.
+			const settled = await this.waitForMoveToSettle(messageId);
+			if (settled.status === MessageStatus.moving) {
+				throw new MoveNotSettledError(messageId);
+			}
+
+			await this.messageMoveService.restoreMessage(
+				accountConfigId,
+				messageId,
+				accountId,
+			);
+			await this.messageService.clearOriginalMailboxId(messageId);
+		}
+
+		const current = await this.messageService.get(messageId);
+
+		await this.flagPushService.flip({
+			accountId,
+			accountConfigId,
+			messageId,
+			mailboxId: current.mailboxId,
+			flagName: MessageKeywordFlag.Junk,
+			operation: "remove",
+		});
+		await this.flagPushService.flip({
+			accountId,
+			accountConfigId,
+			messageId,
+			mailboxId: current.mailboxId,
+			flagName: MessageKeywordFlag.NotJunk,
+			operation: "add",
+		});
+
+		await this.messageService.clearSpamReport(messageId);
+
+		this.log.info(
+			{ accountId, messageId, addressId: from.addressId },
+			"Undid spam report",
+		);
+	};
+}