@remit/mailbox-service 0.0.58 → 0.0.60

package/package.json

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

package/src/index.ts

@@ -185,6 +185,7 @@ export {
 	type MessageMoveConfig,
 	type MessageMoveLogger,
 	MessageMoveService,
+	NoTrashMailboxError,
 } from "./message-move.js";
 export {
 	type ParsedMessageContent,

package/src/message-delete-junk-reconcile.test.ts

@@ -0,0 +1,110 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type {
+	IAddressRepository,
+	IMailboxRepository,
+	IMailboxSpecialUseRepository,
+	IMessageRepository,
+	IThreadMessageRepository,
+} from "@remit/data-ports";
+import { type MessageMoveConfig, MessageMoveService } from "./message-move.js";
+
+const ACCOUNT = "acc-1";
+const ACCOUNT_CONFIG = "cfg-1";
+const INBOX = "mbx-inbox";
+const TRASH = "mbx-trash";
+const MESSAGE_ID = "msg-1";
+
+const buildWorld = (trashExists: boolean) => {
+	const reconciled: string[] = [];
+	const message = {
+		messageId: MESSAGE_ID,
+		mailboxId: INBOX,
+		uid: 337,
+		status: "active",
+		syncStatus: "synced",
+	};
+
+	const messageService = {
+		get: async () => [message],
+		update: async (_id: string, patch: Record<string, unknown>) =>
+			Object.assign(message, patch),
+		updateForMove: async (_id: string, patch: Record<string, unknown>) =>
+			Object.assign(message, patch),
+	} as unknown as IMessageRepository;
+
+	const threadMessageService = {
+		findAllByMessageId: async () => [],
+		getByMessageId: async () => ({
+			accountConfigId: ACCOUNT_CONFIG,
+			threadMessageId: "tm-1",
+			messageId: MESSAGE_ID,
+			mailboxId: INBOX,
+		}),
+		update: async () => {},
+		delete: async () => {},
+	} as unknown as IThreadMessageRepository;
+
+	const mailboxService = {
+		get: async () => [
+			{ mailboxId: INBOX, fullPath: "INBOX", accountId: ACCOUNT },
+		],
+	} as unknown as IMailboxRepository;
+
+	const mailboxSpecialUseService = {
+		findTrashMailbox: async () =>
+			trashExists ? { mailboxId: TRASH, fullPath: "Trash" } : null,
+	} as unknown as IMailboxSpecialUseRepository;
+
+	const addressService = {
+		reconcileJunkOnlyForMessage: async (messageId: string) => {
+			reconciled.push(`${messageId}@${message.mailboxId}`);
+		},
+	} as unknown as IAddressRepository;
+
+	const config: MessageMoveConfig = {
+		messageService,
+		mailboxService,
+		mailboxSpecialUseService,
+		threadMessageService,
+		addressService,
+		sqsQueueUrl: "http://localhost:9324/000000000000/remit-messages.fifo",
+	};
+
+	const service = new MessageMoveService(config);
+	(
+		service as unknown as { enqueueEventsBatch: () => Promise<void> }
+	).enqueueEventsBatch = async () => {};
+
+	return { service, reconciled };
+};
+
+describe("deleting a message re-asks what its senders stand on", () => {
+	it("re-asks when the delete moves the message to Trash", async () => {
+		const { service, reconciled } = buildWorld(true);
+
+		await service.deleteMessages(ACCOUNT_CONFIG, [MESSAGE_ID], ACCOUNT);
+
+		assert.deepEqual(reconciled, [`${MESSAGE_ID}@${TRASH}`]);
+	});
+
+	it("asks nothing when the delete is permanent", async () => {
+		const { service, reconciled } = buildWorld(true);
+
+		await service.deleteMessages(ACCOUNT_CONFIG, [MESSAGE_ID], ACCOUNT, {
+			permanent: true,
+		});
+
+		assert.deepEqual(reconciled, []);
+	});
+
+	it("asks nothing when the account has no Trash folder, because the delete is refused", async () => {
+		const { service, reconciled } = buildWorld(false);
+
+		await assert.rejects(() =>
+			service.deleteMessages(ACCOUNT_CONFIG, [MESSAGE_ID], ACCOUNT),
+		);
+
+		assert.deepEqual(reconciled, []);
+	});
+});

package/src/message-delete-no-trash.test.ts

@@ -0,0 +1,168 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type {
+	IAddressRepository,
+	IMailboxRepository,
+	IMailboxSpecialUseRepository,
+	IMessageRepository,
+	IThreadMessageRepository,
+} from "@remit/data-ports";
+import {
+	type MessageMoveConfig,
+	MessageMoveService,
+	NoTrashMailboxError,
+} from "./message-move.js";
+
+const ACCOUNT = "acc-1";
+const ACCOUNT_CONFIG = "cfg-1";
+const INBOX = "mbx-inbox";
+const TRASH = "mbx-trash";
+const MESSAGE_ID = "msg-1";
+
+interface EnqueuedEvent {
+	operation: string;
+	destinationMailboxPath?: string;
+}
+
+const buildWorld = (
+	trash: { mailboxId: string; fullPath: string } | null,
+	startingMailboxId = INBOX,
+) => {
+	const patches: Array<Record<string, unknown>> = [];
+	const events: EnqueuedEvent[] = [];
+	const threadMessageDeletes: string[] = [];
+
+	const message = {
+		messageId: MESSAGE_ID,
+		mailboxId: startingMailboxId,
+		uid: 337,
+		status: "active",
+		syncStatus: "synced",
+	};
+
+	const messageService = {
+		get: async () => [message],
+		update: async (_id: string, patch: Record<string, unknown>) => {
+			patches.push(patch);
+			return Object.assign(message, patch);
+		},
+		updateForMove: async (_id: string, patch: Record<string, unknown>) => {
+			patches.push(patch);
+			return Object.assign(message, patch);
+		},
+	} as unknown as IMessageRepository;
+
+	const threadMessageService = {
+		findAllByMessageId: async () => [],
+		getByMessageId: async () => ({
+			accountConfigId: ACCOUNT_CONFIG,
+			threadMessageId: "tm-1",
+			messageId: MESSAGE_ID,
+			mailboxId: startingMailboxId,
+		}),
+		update: async () => {},
+		delete: async (_cfg: string, id: string) => {
+			threadMessageDeletes.push(id);
+		},
+	} as unknown as IThreadMessageRepository;
+
+	const mailboxService = {
+		get: async () => [
+			{ mailboxId: INBOX, fullPath: "INBOX", accountId: ACCOUNT },
+			{ mailboxId: TRASH, fullPath: "INBOX/Trash", accountId: ACCOUNT },
+		],
+	} as unknown as IMailboxRepository;
+
+	const mailboxSpecialUseService = {
+		findTrashMailbox: async () => trash,
+	} as unknown as IMailboxSpecialUseRepository;
+
+	const addressService = {
+		reconcileJunkOnlyForMessage: async () => {},
+	} as unknown as IAddressRepository;
+
+	const config: MessageMoveConfig = {
+		messageService,
+		mailboxService,
+		mailboxSpecialUseService,
+		threadMessageService,
+		addressService,
+		sqsQueueUrl: "http://localhost:9324/000000000000/remit-messages.fifo",
+	};
+
+	const service = new MessageMoveService(config);
+	(
+		service as unknown as {
+			enqueueEventsBatch: (batch: EnqueuedEvent[]) => Promise<void>;
+		}
+	).enqueueEventsBatch = async (batch) => {
+		events.push(...batch);
+	};
+
+	return { service, patches, events, message };
+};
+
+describe("delete only expunges when it was asked to", () => {
+	it("moves to a Trash the account resolves under a nested path", async () => {
+		const { service, events, message } = buildWorld({
+			mailboxId: TRASH,
+			fullPath: "INBOX/Trash",
+		});
+
+		await service.deleteMessages(ACCOUNT_CONFIG, [MESSAGE_ID], ACCOUNT);
+
+		assert.deepEqual(
+			events.map((event) => event.operation),
+			["move_to_trash"],
+		);
+		assert.equal(events[0].destinationMailboxPath, "INBOX/Trash");
+		assert.equal(message.mailboxId, TRASH);
+	});
+
+	it("refuses, and touches nothing, when no Trash resolves", async () => {
+		const { service, patches, events, message } = buildWorld(null);
+
+		await assert.rejects(
+			() => service.deleteMessages(ACCOUNT_CONFIG, [MESSAGE_ID], ACCOUNT),
+			(error: unknown) =>
+				error instanceof NoTrashMailboxError &&
+				error.statusCode === 409 &&
+				error.message.includes("no Trash folder"),
+		);
+
+		assert.deepEqual(events, []);
+		assert.deepEqual(patches, []);
+		assert.equal(message.mailboxId, INBOX);
+		assert.equal(message.status, "active");
+	});
+
+	it("expunges only when the caller asked for a permanent delete", async () => {
+		const { service, events } = buildWorld({
+			mailboxId: TRASH,
+			fullPath: "INBOX/Trash",
+		});
+
+		await service.deleteMessages(ACCOUNT_CONFIG, [MESSAGE_ID], ACCOUNT, {
+			permanent: true,
+		});
+
+		assert.deepEqual(
+			events.map((event) => event.operation),
+			["permanent_delete"],
+		);
+	});
+
+	it("expunges a message already in Trash, which the dialog asks as such", async () => {
+		const { service, events } = buildWorld(
+			{ mailboxId: TRASH, fullPath: "INBOX/Trash" },
+			TRASH,
+		);
+
+		await service.deleteMessages(ACCOUNT_CONFIG, [MESSAGE_ID], ACCOUNT);
+
+		assert.deepEqual(
+			events.map((event) => event.operation),
+			["permanent_delete"],
+		);
+	});
+});

package/src/message-move-copy.test.ts

@@ -17,6 +17,11 @@ import { type MessageMoveConfig, MessageMoveService } from "./message-move.js";
 import { MessageSyncService } from "./message-sync.js";
 import type { IImapConnection, ImapMessage } from "./types.js";
 
+const stubAddressService = (): IAddressRepository =>
+	({
+		reconcileJunkOnlyForMessage: async () => {},
+	}) as unknown as IAddressRepository;
+
 // A copy is a per-folder placement of the same mail. These tests pin the three
 // properties issue #75 turns on: the copy row is deterministic (idempotent), a
 // delete removes exactly the placement it targets, and neither the copy nor the
@@ -176,6 +181,7 @@ const buildWorld = () => {
 		mailboxService,
 		mailboxSpecialUseService,
 		threadMessageService,
+		addressService: stubAddressService(),
 		sqsQueueUrl: "http://localhost:9324/000000000000/message-mgmt",
 	};
 
@@ -288,7 +294,7 @@ const buildSyncOverDestination = (
 					upsertBodyParts: async () => undefined,
 				} as unknown as IEnvelopeRepository,
 				address: {
-					upsertAddress: async () => undefined,
+					upsertCorrespondentAddress: async () => undefined,
 					upsertEnvelopeAddress: async () => undefined,
 				} as unknown as IAddressRepository,
 				threadMessage: world.threadMessageService,

package/src/message-move-same-mailbox.test.ts

@@ -1,6 +1,7 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 import type {
+	IAddressRepository,
 	IMailboxRepository,
 	IMailboxSpecialUseRepository,
 	IMessageRepository,
@@ -8,6 +9,11 @@ import type {
 } from "@remit/data-ports";
 import { type MessageMoveConfig, MessageMoveService } from "./message-move.js";
 
+const stubAddressService = (): IAddressRepository =>
+	({
+		reconcileJunkOnlyForMessage: async () => {},
+	}) as unknown as IAddressRepository;
+
 const ACCOUNT = "acc-1";
 const ACCOUNT_CONFIG = "cfg-1";
 const INBOX = "mbx-inbox";
@@ -67,6 +73,7 @@ const buildWorld = () => {
 		mailboxService,
 		mailboxSpecialUseService,
 		threadMessageService,
+		addressService: stubAddressService(),
 		sqsQueueUrl: "http://localhost:9324/000000000000/remit-messages.fifo",
 	};
 

package/src/message-move.ts

@@ -5,11 +5,13 @@ import {
 	type SQSClient,
 } from "@aws-sdk/client-sqs";
 import type {
+	IAddressRepository,
 	IMailboxRepository,
 	IMailboxSpecialUseRepository,
 	IMessageRepository,
 	IThreadMessageRepository,
 } from "@remit/data-ports";
+import { HTTPError } from "@remit/data-ports/errors";
 import { deriveCopyMessageId } from "@remit/data-ports/id";
 import { MessageStatus, MessageSyncStatus } from "@remit/domain-enums";
 import { createQueueProducer } from "@remit/sqs-client/producer";
@@ -96,11 +98,29 @@ export interface MessageMoveConfig {
 	mailboxService: IMailboxRepository;
 	mailboxSpecialUseService: IMailboxSpecialUseRepository;
 	threadMessageService: IThreadMessageRepository;
+	addressService: IAddressRepository;
 	sqsQueueUrl: string;
 	sqsEndpoint?: string;
 	logger?: MessageMoveLogger;
 }
 
+/**
+ * The account resolves no Trash folder, so a move-to-Trash delete has nowhere
+ * to put the mail. A designed, user-facing outcome carrying its own text and
+ * a 409 so the backend returns it verbatim: the absence of a Trash folder is
+ * a blocker the user resolves by appointing one, never a licence to expunge.
+ */
+export class NoTrashMailboxError extends HTTPError {
+	name = "NoTrashMailboxError";
+	statusCode = 409;
+
+	constructor() {
+		super(
+			"This account has no Trash folder, so nothing was deleted. Appoint one under Settings → Folder roles, then delete again.",
+		);
+	}
+}
+
 /**
  * Options for delete operations
  */
@@ -125,6 +145,7 @@ export class MessageMoveService {
 	private mailboxService: IMailboxRepository;
 	private mailboxSpecialUseService: IMailboxSpecialUseRepository;
 	private threadMessageService: IThreadMessageRepository;
+	private addressService: IAddressRepository;
 	private sqs: SQSClient;
 	private queueUrl: string;
 	private log: MessageMoveLogger;
@@ -134,6 +155,7 @@ export class MessageMoveService {
 		this.mailboxService = config.mailboxService;
 		this.mailboxSpecialUseService = config.mailboxSpecialUseService;
 		this.threadMessageService = config.threadMessageService;
+		this.addressService = config.addressService;
 		this.queueUrl = config.sqsQueueUrl;
 		this.log = config.logger ?? noopLogger;
 
@@ -187,9 +209,26 @@ export class MessageMoveService {
 		);
 		const mailboxMap = new Map(mailboxes.map((m) => [m.mailboxId, m]));
 
-		// Find trash mailbox once
-		const trashMailbox =
-			await this.mailboxSpecialUseService.findTrashMailbox(accountId);
+		// A permanent delete is only ever what the caller explicitly asked for.
+		// Everything else is a move to Trash, and a Trash folder that does not
+		// resolve blocks it — the user was asked "move to Trash?" and expunging
+		// their mail instead is unrecoverable and answers a question nobody put
+		// to them. Thrown before any local write or event, so the server and the
+		// projection are both left untouched.
+		const wantsPermanentDelete =
+			options.permanent === true || options.toTrash === false;
+
+		const trashMailbox = wantsPermanentDelete
+			? null
+			: await this.mailboxSpecialUseService.findTrashMailbox(accountId);
+
+		if (!wantsPermanentDelete && !trashMailbox) {
+			this.log.error(
+				{ accountId, messageCount: messages.length },
+				"Refused to delete: account resolves no Trash mailbox",
+			);
+			throw new NoTrashMailboxError();
+		}
 
 		// Group messages by operation type
 		const moveToTrashMessages: Array<{
@@ -208,12 +247,8 @@ export class MessageMoveService {
 			if (!sourceMailbox) continue;
 
 			const isInTrash =
-				trashMailbox && message.mailboxId === trashMailbox.mailboxId;
-			const shouldMoveToTrash =
-				options.toTrash !== false &&
-				!options.permanent &&
-				!isInTrash &&
-				trashMailbox;
+				trashMailbox !== null && message.mailboxId === trashMailbox.mailboxId;
+			const shouldMoveToTrash = trashMailbox !== null && !isInTrash;
 
 			const entry = {
 				messageId: message.messageId,
@@ -224,7 +259,7 @@ export class MessageMoveService {
 				},
 			};
 
-			if (shouldMoveToTrash && trashMailbox) {
+			if (shouldMoveToTrash) {
 				moveToTrashMessages.push(entry);
 			} else {
 				permanentDeleteMessages.push(entry);
@@ -254,6 +289,8 @@ export class MessageMoveService {
 					true,
 				);
 
+				await this.addressService.reconcileJunkOnlyForMessage(messageId);
+
 				events.push({
 					type: "MESSAGE_DELETE",
 					eventId: randomUUID(),
@@ -385,6 +422,8 @@ export class MessageMoveService {
 			isMovingToTrash,
 		);
 
+		await this.addressService.reconcileJunkOnlyForMessage(messageId);
+
 		// If moving FROM Trash, clear isDeleted
 		if (isMovingFromTrash) {
 			await this.updateThreadMessageDeleted(accountConfigId, messageId, false);

package/src/message-sync-address-spoof.test.ts

@@ -9,6 +9,7 @@ import type {
 	IMailboxRepository,
 	IMessageRepository,
 	IThreadMessageRepository,
+	MailboxItem,
 	MessageItem,
 	ThreadMessageItem,
 } from "@remit/data-ports";
@@ -64,7 +65,7 @@ const harvest = async (envelope: Partial<ImapEnvelope>): Promise<Saved> => {
 	} as unknown as IEnvelopeRepository;
 
 	const addressService = {
-		upsertAddress: async (input: CreateAddressInput) => {
+		upsertCorrespondentAddress: async (input: CreateAddressInput) => {
 			saved.addresses.push(input);
 		},
 		upsertEnvelopeAddress: async (input: CreateEnvelopeAddressInput) => {
@@ -93,13 +94,18 @@ const harvest = async (envelope: Partial<ImapEnvelope>): Promise<Saved> => {
 	await (
 		service as unknown as {
 			saveMessage: (
-				mailboxId: string,
+				mailbox: MailboxItem,
 				accountId: string,
 				accountConfigId: string,
 				msg: ImapMessage,
 			) => Promise<unknown>;
 		}
-	).saveMessage("mbx-1", "acct-1", "cfg-1", msg);
+	).saveMessage(
+		{ mailboxId: "mbx-1", fullPath: "INBOX" } as MailboxItem,
+		"acct-1",
+		"cfg-1",
+		msg,
+	);
 
 	return saved;
 };

package/src/message-sync-category.test.ts

@@ -25,6 +25,7 @@ import type {
 	IMailboxRepository,
 	IMessageRepository,
 	IThreadMessageRepository,
+	MailboxItem,
 	MessageItem,
 	ThreadMessageItem,
 } from "@remit/data-ports";
@@ -89,7 +90,7 @@ const saveIntoMailbox = async (
 	} as unknown as IEnvelopeRepository;
 
 	const addressService = {
-		upsertAddress: async () => {},
+		upsertCorrespondentAddress: async () => {},
 		upsertEnvelopeAddress: async () => {},
 	} as unknown as IAddressRepository;
 
@@ -105,13 +106,18 @@ const saveIntoMailbox = async (
 	await (
 		service as unknown as {
 			saveMessage: (
-				mailboxId: string,
+				mailbox: MailboxItem,
 				accountId: string,
 				accountConfigId: string,
 				msg: ImapMessage,
 			) => Promise<unknown>;
 		}
-	).saveMessage("mbx-1", "acct-1", "cfg-1", imapMessage);
+	).saveMessage(
+		{ mailboxId: "mbx-1", fullPath: "INBOX" } as MailboxItem,
+		"acct-1",
+		"cfg-1",
+		imapMessage,
+	);
 
 	assert.equal(inputs.length, 1);
 	const [input] = inputs;

package/src/message-sync-changedsince.test.ts

@@ -219,7 +219,7 @@ const buildHarness = (options: HarnessOptions): Harness => {
 					upsertBodyParts: async () => undefined,
 				} as unknown as IEnvelopeRepository,
 				address: {
-					upsertAddress: async () => undefined,
+					upsertCorrespondentAddress: async () => undefined,
 					upsertEnvelopeAddress: async () => undefined,
 				} as unknown as IAddressRepository,
 				threadMessage: threadMessageService,

package/src/message-sync-junk-harvest.test.ts

@@ -0,0 +1,233 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type {
+	CreateAddressInput,
+	CreateEnvelopeAddressInput,
+	CreateThreadMessageInput,
+	IAddressRepository,
+	IEnvelopeRepository,
+	IMailboxRepository,
+	IMessageRepository,
+	IThreadMessageRepository,
+	MailboxItem,
+	MessageItem,
+	ThreadMessageItem,
+} from "@remit/data-ports";
+import { MailboxSpecialUse } from "@remit/domain-enums";
+import type { ManagedConnectionFactory } from "./connection-factory.js";
+import { addressSightingIn, MessageSyncService } from "./message-sync.js";
+import type { ImapEnvelope, ImapMessage } from "./types.js";
+
+const stub = <T>(): T => ({}) as T;
+
+const envelope: ImapEnvelope = {
+	date: new Date(0).toISOString(),
+	messageId: "<root@example.com>",
+	subject: "Subject",
+	from: [{ name: "Pharma Deals", mailbox: "sales", host: "pharma.example" }],
+	sender: [],
+	replyTo: [],
+	to: [{ name: "", mailbox: "victim", host: "ischen.nl" }],
+	cc: [],
+	bcc: [],
+	inReplyTo: "",
+};
+
+interface Saved {
+	correspondents: CreateAddressInput[];
+	junk: CreateAddressInput[];
+	neutral: CreateAddressInput[];
+	envelopeAddresses: CreateEnvelopeAddressInput[];
+	reconciled: string[];
+}
+
+const mailboxAt = (
+	fullPath: string,
+	specialUse?: MailboxItem["specialUse"],
+): MailboxItem =>
+	({
+		fullPath,
+		hierarchyDelimiter: "/",
+		specialUse,
+	}) as MailboxItem;
+
+const save = async (mailbox: MailboxItem): Promise<Saved> => {
+	const saved: Saved = {
+		correspondents: [],
+		junk: [],
+		neutral: [],
+		envelopeAddresses: [],
+		reconciled: [],
+	};
+
+	const messageService = {
+		upsertWithStatus: async (input: unknown) => ({
+			item: input as MessageItem,
+			created: true,
+		}),
+	} as unknown as IMessageRepository;
+
+	const threadMessageService = {
+		create: async (input: CreateThreadMessageInput) =>
+			input as unknown as ThreadMessageItem,
+	} as unknown as IThreadMessageRepository;
+
+	const envelopeService = {
+		upsertEnvelope: async () => {},
+		upsertBodyParts: async () => {},
+	} as unknown as IEnvelopeRepository;
+
+	const addressService = {
+		upsertCorrespondentAddress: async (input: CreateAddressInput) => {
+			saved.correspondents.push(input);
+		},
+		upsertJunkAddress: async (input: CreateAddressInput) => {
+			saved.junk.push(input);
+		},
+		upsertAddress: async (input: CreateAddressInput) => {
+			saved.neutral.push(input);
+		},
+		upsertEnvelopeAddress: async (input: CreateEnvelopeAddressInput) => {
+			saved.envelopeAddresses.push(input);
+		},
+		reconcileJunkOnlyForMessage: async (messageId: string) => {
+			saved.reconciled.push(messageId);
+		},
+	} as unknown as IAddressRepository;
+
+	const service = new MessageSyncService(
+		stub<ManagedConnectionFactory>(),
+		stub<IMailboxRepository>(),
+		messageService,
+		envelopeService,
+		addressService,
+		threadMessageService,
+	);
+
+	const msg = {
+		uid: 42,
+		seq: 1,
+		size: 100,
+		internalDate: new Date(0),
+		flags: [],
+		envelope,
+	} as unknown as ImapMessage;
+
+	await (
+		service as unknown as {
+			saveMessage: (
+				mailbox: MailboxItem,
+				accountId: string,
+				accountConfigId: string,
+				msg: ImapMessage,
+			) => Promise<unknown>;
+		}
+	).saveMessage(mailbox, "acct-1", "cfg-1", msg);
+
+	return saved;
+};
+
+const emails = (inputs: Array<{ normalizedEmail: string }>): string[] =>
+	inputs.map((input) => input.normalizedEmail);
+
+const BOTH = ["sales@pharma.example", "victim@ischen.nl"];
+
+describe("what a mailbox says about the addresses on its messages", () => {
+	const at = (fullPath: string, specialUse?: string[]) => ({
+		fullPath,
+		hierarchyDelimiter: "/",
+		specialUse,
+	});
+
+	it("reads the special-use designation", () => {
+		assert.equal(
+			addressSightingIn(at("INBOX/Spam", [MailboxSpecialUse.Junk])),
+			"junk",
+		);
+		assert.equal(addressSightingIn(at("INBOX")), "correspondent");
+	});
+
+	it("falls back to the folder name on a server without SPECIAL-USE", () => {
+		assert.equal(addressSightingIn(at("Spam")), "junk");
+		assert.equal(addressSightingIn(at("[Gmail]/Spam")), "junk");
+		assert.equal(addressSightingIn(at("Deleted Items")), "discarded");
+	});
+
+	it("reads a Junk folder nested under any prefix", () => {
+		assert.equal(addressSightingIn(at("INBOX/Spam")), "junk");
+		assert.equal(addressSightingIn(at("INBOX/Junk E-mail")), "junk");
+		assert.equal(
+			addressSightingIn({ fullPath: "Mail.Junk", hierarchyDelimiter: "." }),
+			"junk",
+		);
+	});
+
+	it("never reads a prefix as the folder it names", () => {
+		assert.equal(addressSightingIn(at("Spam/Receipts")), "correspondent");
+	});
+
+	it("answers for a mailbox carrying no delimiter", () => {
+		assert.equal(addressSightingIn({ fullPath: "Spam" }), "junk");
+		assert.equal(addressSightingIn({ fullPath: "INBOX" }), "correspondent");
+	});
+
+	it("harvests every envelope address of an ordinary message", async () => {
+		const saved = await save(mailboxAt("INBOX"));
+
+		assert.deepEqual(emails(saved.correspondents), BOTH);
+		assert.equal(saved.junk.length, 0);
+		assert.equal(saved.neutral.length, 0);
+	});
+
+	it("withholds every envelope address of a message in Junk", async () => {
+		const saved = await save(mailboxAt("INBOX/Spam", [MailboxSpecialUse.Junk]));
+
+		assert.deepEqual(emails(saved.junk), BOTH);
+		assert.equal(saved.correspondents.length, 0);
+	});
+
+	it("still records the envelope a message in Junk renders", async () => {
+		const saved = await save(mailboxAt("INBOX/Spam", [MailboxSpecialUse.Junk]));
+
+		assert.deepEqual(emails(saved.envelopeAddresses), BOTH);
+	});
+
+	it("withholds when Junk is one designation among several", async () => {
+		const saved = await save(
+			mailboxAt("Archive", [MailboxSpecialUse.Junk, MailboxSpecialUse.Archive]),
+		);
+
+		assert.equal(saved.correspondents.length, 0);
+		assert.equal(saved.junk.length, 2);
+	});
+
+	it("keeps a message in Trash from deciding either way", async () => {
+		const saved = await save(mailboxAt("Trash", [MailboxSpecialUse.Trash]));
+
+		assert.deepEqual(emails(saved.neutral), BOTH);
+		assert.equal(saved.correspondents.length, 0);
+		assert.equal(saved.junk.length, 0);
+	});
+
+	it("re-asks every sighting of a sender a message in Junk carries", async () => {
+		const saved = await save(mailboxAt("INBOX/Spam", [MailboxSpecialUse.Junk]));
+
+		assert.equal(saved.reconciled.length, 1);
+		assert.deepEqual(saved.reconciled, [saved.envelopeAddresses[0].messageId]);
+	});
+
+	it("asks nothing of a sender met on live mail", async () => {
+		const inbox = await save(mailboxAt("INBOX"));
+		const trash = await save(mailboxAt("Trash", [MailboxSpecialUse.Trash]));
+
+		assert.deepEqual(inbox.reconciled, []);
+		assert.deepEqual(trash.reconciled, []);
+	});
+
+	it("harvests the same message once an ordinary folder holds it", async () => {
+		await save(mailboxAt("INBOX/Spam", [MailboxSpecialUse.Junk]));
+		const moved = await save(mailboxAt("INBOX"));
+
+		assert.deepEqual(emails(moved.correspondents), BOTH);
+	});
+});

package/src/message-sync-quarantine.test.ts

@@ -159,7 +159,7 @@ const buildHarness = (options: {
 					upsertBodyParts: async () => undefined,
 				} as unknown as IEnvelopeRepository,
 				address: {
-					upsertAddress: async () => undefined,
+					upsertCorrespondentAddress: async () => undefined,
 					upsertEnvelopeAddress: async () => undefined,
 				} as unknown as IAddressRepository,
 				threadMessage: threadMessageService,

package/src/message-sync.ts

@@ -21,6 +21,11 @@ import {
 	deriveThreadId,
 	isValidMessageId,
 } from "@remit/data-ports/id";
+import {
+	isJunkMailbox,
+	isTrashMailbox,
+	type MailboxRole,
+} from "@remit/data-ports/mailbox-role";
 import {
 	AddressRole,
 	MailboxCursorState,
@@ -86,6 +91,14 @@ export const isParseableEmailAddress = (
 	return host.includes(".");
 };
 
+export type AddressSighting = "junk" | "discarded" | "correspondent";
+
+export const addressSightingIn = (mailbox: MailboxRole): AddressSighting => {
+	if (isJunkMailbox(mailbox)) return "junk";
+	if (isTrashMailbox(mailbox)) return "discarded";
+	return "correspondent";
+};
+
 /**
  * The name an envelope carries for an address, as it should be stored: any
  * claim to be some other address removed (issue #826), the rest of the name
@@ -424,7 +437,7 @@ export class MessageSyncService {
 		// poison pill that previously froze the mailbox, #817).
 		const outcomes = await pMap(
 			applicable,
-			(msg) => this.trySaveMessage(mailboxId, accountId, accountConfigId, msg),
+			(msg) => this.trySaveMessage(mailbox, accountId, accountConfigId, msg),
 			{ concurrency: MESSAGE_SAVE_CONCURRENCY },
 		);
 
@@ -657,7 +670,7 @@ export class MessageSyncService {
 		const applicable = newMessages.filter((msg) => msg.envelope !== undefined);
 		const outcomes = await pMap(
 			applicable,
-			(msg) => this.trySaveMessage(mailboxId, accountId, accountConfigId, msg),
+			(msg) => this.trySaveMessage(mailbox, accountId, accountConfigId, msg),
 			{ concurrency: MESSAGE_SAVE_CONCURRENCY },
 		);
 		const syncedMessages: SyncedMessage[] = outcomes.flatMap((o) =>
@@ -883,7 +896,7 @@ export class MessageSyncService {
 
 		const outcomes = await pMap(
 			applicable,
-			(msg) => this.tryApplyChange(mailboxId, accountId, accountConfigId, msg),
+			(msg) => this.tryApplyChange(mailbox, accountId, accountConfigId, msg),
 			{ concurrency: MESSAGE_SAVE_CONCURRENCY },
 		);
 
@@ -988,12 +1001,13 @@ export class MessageSyncService {
 	 * holds the watermark back instead of failing the round.
 	 */
 	private async tryApplyChange(
-		mailboxId: string,
+		mailbox: MailboxItem,
 		accountId: string,
 		accountConfigId: string,
 		msg: ImapMessage,
 	): Promise<BatchOutcome> {
-		return this.applyChange(mailboxId, accountId, accountConfigId, msg)
+		const mailboxId = mailbox.mailboxId;
+		return this.applyChange(mailbox, accountId, accountConfigId, msg)
 			.then((result): BatchOutcome => ({ kind: "saved", uid: msg.uid, result }))
 			.catch((error): BatchOutcome => {
 				this.log.warn(
@@ -1010,7 +1024,7 @@ export class MessageSyncService {
 	}
 
 	private async applyChange(
-		mailboxId: string,
+		mailbox: MailboxItem,
 		accountId: string,
 		accountConfigId: string,
 		msg: ImapMessage,
@@ -1020,7 +1034,7 @@ export class MessageSyncService {
 		const messageId = deriveMessageIdFromSource(accountId, {
 			messageId: msg.envelope.messageId,
 			uid: msg.uid,
-			mailboxId,
+			mailboxId: mailbox.mailboxId,
 			date: msg.envelope.date,
 			subject: msg.envelope.subject,
 			fromMailbox: msg.envelope.from?.[0]?.mailbox,
@@ -1032,7 +1046,7 @@ export class MessageSyncService {
 			messageId,
 		);
 		if (!existing) {
-			return this.saveMessage(mailboxId, accountId, accountConfigId, msg);
+			return this.saveMessage(mailbox, accountId, accountConfigId, msg);
 		}
 
 		await this.applyServerFlags(existing, msg.flags);
@@ -1227,12 +1241,13 @@ export class MessageSyncService {
 	 * permanently freezing the mailbox (#817).
 	 */
 	private async trySaveMessage(
-		mailboxId: string,
+		mailbox: MailboxItem,
 		accountId: string,
 		accountConfigId: string,
 		msg: ImapMessage,
 	): Promise<BatchOutcome> {
-		return this.saveMessage(mailboxId, accountId, accountConfigId, msg)
+		const mailboxId = mailbox.mailboxId;
+		return this.saveMessage(mailbox, accountId, accountConfigId, msg)
 			.then((result): BatchOutcome => ({ kind: "saved", uid: msg.uid, result }))
 			.catch((error): BatchOutcome => {
 				this.log.warn(
@@ -1249,13 +1264,16 @@ export class MessageSyncService {
 	}
 
 	private async saveMessage(
-		mailboxId: string,
+		mailbox: MailboxItem,
 		accountId: string,
 		accountConfigId: string,
 		msg: ImapMessage,
 	): Promise<SaveMessageResult | null> {
 		if (!msg.envelope) return null;
 
+		const mailboxId = mailbox.mailboxId;
+		const sighting = addressSightingIn(mailbox);
+
 		// Store envelope to preserve narrowing in closures
 		const envelope = msg.envelope;
 
@@ -1338,6 +1356,7 @@ export class MessageSyncService {
 					accountConfigId,
 					addresses,
 					role,
+					sighting,
 				);
 			}
 
@@ -1359,6 +1378,10 @@ export class MessageSyncService {
 			});
 			owned = created || item.mailboxId === mailboxId;
 
+			if (sighting === "junk") {
+				await repos.address.reconcileJunkOnlyForMessage(messageId);
+			}
+
 			await this.createThreadForMessage(
 				repos.threadMessage,
 				messageId,
@@ -1393,6 +1416,7 @@ export class MessageSyncService {
 		accountConfigId: string,
 		addresses: ImapAddress[] | undefined,
 		role: (typeof AddressRole)[keyof typeof AddressRole],
+		sighting: AddressSighting,
 	) {
 		if (!addresses) return;
 
@@ -1430,7 +1454,7 @@ export class MessageSyncService {
 
 			const envelopeAddressId = deriveEnvelopeAddressId(messageId, role, order);
 
-			await addressService.upsertAddress({
+			const addressInput = {
 				addressId,
 				accountConfigId,
 				localPart,
@@ -1438,7 +1462,14 @@ export class MessageSyncService {
 				normalizedEmail,
 				normalizedCompound,
 				displayName,
-			});
+			};
+			if (sighting === "junk") {
+				await addressService.upsertJunkAddress(addressInput);
+			} else if (sighting === "discarded") {
+				await addressService.upsertAddress(addressInput);
+			} else {
+				await addressService.upsertCorrespondentAddress(addressInput);
+			}
 
 			await addressService.upsertEnvelopeAddress({
 				envelopeAddressId,

package/src/placement-move-unsettled.test.ts

@@ -10,6 +10,7 @@ import assert from "node:assert/strict";
 import { afterEach, beforeEach, describe, it, mock } from "node:test";
 import { SQSClient } from "@aws-sdk/client-sqs";
 import type {
+	IAddressRepository,
 	IMessagePlacementMoveRepository,
 	IMessageRepository,
 	IThreadMessageRepository,
@@ -33,6 +34,7 @@ interface Harness {
 	row: MessageItem;
 	puts: PutMessagePlacementMoveInput[];
 	marker: MessagePlacementMoveItem | null;
+	reconciled: string[];
 }
 
 const buildHarness = (): Harness => {
@@ -46,7 +48,14 @@ const buildHarness = (): Harness => {
 	} as unknown as MessageItem;
 
 	const puts: PutMessagePlacementMoveInput[] = [];
-	const harness = { row, puts, marker: null } as Harness;
+	const reconciled: string[] = [];
+	const harness = { row, puts, marker: null, reconciled } as Harness;
+
+	const addressService = {
+		reconcileJunkOnlyForMessage: async (messageId: string) => {
+			reconciled.push(`${messageId}@${row.mailboxId}`);
+		},
+	} as unknown as IAddressRepository;
 
 	const messageService = {
 		get: async () => row,
@@ -101,6 +110,7 @@ const buildHarness = (): Harness => {
 		messageService,
 		threadMessageService,
 		markerService,
+		addressService,
 		sqsQueueUrl: "https://sqs.eu-west-1.amazonaws.com/000/message-mgmt",
 		moveSettleTimeoutMs: 200,
 		moveSettlePollMs: 10,
@@ -222,4 +232,28 @@ describe("PlacementMoveService — a second destination while the first move is
 		assert.equal(harness.puts[1]?.sourceMailboxId, ARCHIVE_ID);
 		assert.equal(harness.puts[1]?.destinationMailboxId, JUNK_ID);
 	});
+
+	it("marks the sender when the classifier demotes the message", async () => {
+		await harness.service.moveMessage(
+			ACCOUNT_CONFIG_ID,
+			MESSAGE_ID,
+			JUNK_ID,
+			ACCOUNT_ID,
+		);
+
+		assert.deepEqual(harness.reconciled, [`${MESSAGE_ID}@${JUNK_ID}`]);
+	});
+
+	it("asks nothing of a destination the message is already in", async () => {
+		Object.assign(harness.row, { mailboxId: JUNK_ID });
+
+		await harness.service.moveMessage(
+			ACCOUNT_CONFIG_ID,
+			MESSAGE_ID,
+			JUNK_ID,
+			ACCOUNT_ID,
+		);
+
+		assert.deepEqual(harness.reconciled, []);
+	});
 });

package/src/placement-move.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { SendMessageCommand, type SQSClient } from "@aws-sdk/client-sqs";
 import type {
+	IAddressRepository,
 	IMessagePlacementMoveRepository,
 	IMessageRepository,
 	IThreadMessageRepository,
@@ -42,6 +43,7 @@ export interface PlacementMoveConfig {
 	messageService: IMessageRepository;
 	threadMessageService: IThreadMessageRepository;
 	markerService: IMessagePlacementMoveRepository;
+	addressService: IAddressRepository;
 	sqsQueueUrl: string;
 	sqsEndpoint?: string;
 	logger?: PlacementMoveLogger;
@@ -84,6 +86,7 @@ export class PlacementMoveService {
 	private messageService: IMessageRepository;
 	private threadMessageService: IThreadMessageRepository;
 	private markerService: IMessagePlacementMoveRepository;
+	private addressService: IAddressRepository;
 	private sqs: SQSClient;
 	private queueUrl: string;
 	private log: PlacementMoveLogger;
@@ -94,6 +97,7 @@ export class PlacementMoveService {
 		this.messageService = config.messageService;
 		this.threadMessageService = config.threadMessageService;
 		this.markerService = config.markerService;
+		this.addressService = config.addressService;
 		this.queueUrl = config.sqsQueueUrl;
 		this.log = config.logger ?? noopLogger;
 		this.moveSettleTimeoutMs =
@@ -196,6 +200,8 @@ export class PlacementMoveService {
 			originalUid: message.uid,
 		});
 
+		await this.addressService.reconcileJunkOnlyForMessage(messageId);
+
 		// The queue kick is a serious operational step, not a routine one — a
 		// failure here MUST propagate (never swallowed): the marker stays
 		// `pending`, the surrounding body-sync call fails, SQS redelivers, and

package/src/spam-report.test.ts

@@ -204,6 +204,7 @@ const buildWorld = (
 			addresses.set(input.addressId, { flags: {} });
 			return { ...input, flags: {} };
 		},
+		reconcileJunkOnlyForMessage: async () => {},
 		mergeFlags: async (
 			_accountConfigId: string,
 			addressId: string,
@@ -273,6 +274,7 @@ const buildWorld = (
 		mailboxService,
 		mailboxSpecialUseService,
 		threadMessageService,
+		addressService,
 		sqsQueueUrl: "http://localhost:9324/000000000000/message-mgmt",
 	});
 	(