@remit/mailbox-service 0.0.59 → 0.0.61

package/package.json

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

package/src/body-sync-placement-flags.test.ts

@@ -19,7 +19,6 @@ import type {
 	IThreadMessageRepository,
 	UpdateMessageInput,
 } from "@remit/data-ports";
-import { MailboxSpecialUse } from "@remit/domain-enums";
 import type { StorageService } from "@remit/storage-service";
 import type { PlacementConfig } from "./body-sync.js";
 import { BodySyncService } from "./body-sync.js";
@@ -116,11 +115,8 @@ const buildHarness = (
 	} as unknown as IEnvelopeRepository;
 
 	const mailboxSpecialUseService = {
-		findBySpecialUse: async (_accountId: string, specialUse: string) => {
-			if (specialUse === MailboxSpecialUse.Junk) return MAILBOXES.junk;
-			if (specialUse === MailboxSpecialUse.Archive) return MAILBOXES.archive;
-			return null;
-		},
+		findJunkMailbox: async () => MAILBOXES.junk,
+		findArchiveMailbox: async () => MAILBOXES.archive,
 		findInboxMailbox: async () => MAILBOXES.inbox,
 	} as unknown as IMailboxSpecialUseRepository;
 

package/src/body-sync-placement-writeonce.test.ts

@@ -30,7 +30,6 @@ import type {
 	MessageItem,
 	UpdateMessageInput,
 } from "@remit/data-ports";
-import { MailboxSpecialUse } from "@remit/domain-enums";
 import type { StorageService } from "@remit/storage-service";
 import type { PlacementConfig } from "./body-sync.js";
 import { BodySyncService } from "./body-sync.js";
@@ -129,8 +128,8 @@ const buildHarness = (
 	} as unknown as IEnvelopeRepository;
 
 	const mailboxSpecialUseService = {
-		findBySpecialUse: async (_accountId: string, specialUse: string) =>
-			specialUse === MailboxSpecialUse.Junk ? MAILBOXES.junk : null,
+		findJunkMailbox: async () => MAILBOXES.junk,
+		findArchiveMailbox: async () => null,
 		findInboxMailbox: async () => MAILBOXES.inbox,
 	} as unknown as IMailboxSpecialUseRepository;
 

package/src/body-sync.ts

@@ -14,7 +14,6 @@ import { NotFoundError } from "@remit/data-ports/errors";
 import { deriveAddressId } from "@remit/data-ports/id";
 import { isBulkSender } from "@remit/data-ports/wellknown";
 import {
-	MailboxSpecialUse,
 	MessageCategory,
 	PlacementAction,
 	PlacementConfidence,
@@ -1477,10 +1476,8 @@ export class BodySyncService {
 		// against the same signals that placed it in the first place.
 		if (hasDecidedPlacement(message.placementDecidedAt)) return {};
 
-		const junkMailbox = await mailboxSpecialUseService.findBySpecialUse(
-			accountId,
-			MailboxSpecialUse.Junk,
-		);
+		const junkMailbox =
+			await mailboxSpecialUseService.findJunkMailbox(accountId);
 		const inboxMailbox =
 			await mailboxSpecialUseService.findInboxMailbox(accountId);
 
@@ -1612,10 +1609,8 @@ export class BodySyncService {
 	): Promise<PlacementOutcome> {
 		if (!autoArchive) return {};
 
-		const archiveMailbox = await mailboxSpecialUseService.findBySpecialUse(
-			accountId,
-			MailboxSpecialUse.Archive,
-		);
+		const archiveMailbox =
+			await mailboxSpecialUseService.findArchiveMailbox(accountId);
 		if (!archiveMailbox || message.mailboxId === archiveMailbox.mailboxId) {
 			return {};
 		}

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

@@ -98,10 +98,12 @@ describe("deleting a message re-asks what its senders stand on", () => {
 		assert.deepEqual(reconciled, []);
 	});
 
-	it("asks nothing when the account has no Trash folder", async () => {
+	it("asks nothing when the account has no Trash folder, because the delete is refused", async () => {
 		const { service, reconciled } = buildWorld(false);
 
-		await service.deleteMessages(ACCOUNT_CONFIG, [MESSAGE_ID], ACCOUNT);
+		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

@@ -15,6 +15,7 @@ import { MailboxCursorState } from "@remit/domain-enums";
 import type { ManagedConnectionFactory } from "./connection-factory.js";
 import { type MessageMoveConfig, MessageMoveService } from "./message-move.js";
 import { MessageSyncService } from "./message-sync.js";
+import { noFolderRoles } from "./test-helpers/folder-roles.js";
 import type { IImapConnection, ImapMessage } from "./types.js";
 
 const stubAddressService = (): IAddressRepository =>
@@ -304,6 +305,7 @@ const buildSyncOverDestination = (
 	return new MessageSyncService(
 		connectionFactory,
 		mailboxService,
+		noFolderRoles,
 		world.messageService,
 		{} as IEnvelopeRepository,
 		{} as IAddressRepository,

package/src/message-move-empty-trash.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Empty Trash is an EXPUNGE with no undo, so it resolves its folder through
+ * `findConfirmedTrashMailbox` — what the user appointed, or what the server
+ * flagged `\Trash`. The name proposal that serves every other lookup is a
+ * guess, and a wrong guess here destroys mail (#837, audit #841).
+ */
+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 DELETED_FOLDER = "mbx-deleted";
+const REAL_TRASH = "mbx-trash";
+
+const buildWorld = (
+	confirmedTrash: { mailboxId: string; fullPath: string } | null,
+) => {
+	const emptied: string[] = [];
+	const messagesByMailbox = new Map<string, { messageId: string }[]>([
+		[DELETED_FOLDER, [{ messageId: "keepsake-1" }]],
+		[REAL_TRASH, [{ messageId: "junk-1" }]],
+	]);
+
+	const messageService = {
+		listAllByMailbox: async (mailboxId: string) => {
+			emptied.push(mailboxId);
+			return messagesByMailbox.get(mailboxId) ?? [];
+		},
+		update: async () => {},
+	} as unknown as IMessageRepository;
+
+	const threadMessageService = {
+		getByMessageId: async () => ({
+			accountConfigId: ACCOUNT_CONFIG,
+			threadMessageId: "tm-1",
+			sentDate: 1_700_000_000_000,
+		}),
+		update: async () => {},
+	} as unknown as IThreadMessageRepository;
+
+	const config: MessageMoveConfig = {
+		messageService,
+		mailboxService: {} as unknown as IMailboxRepository,
+		addressService: {
+			reconcileJunkOnlyForMessage: async () => {},
+		} as unknown as IAddressRepository,
+		mailboxSpecialUseService: {
+			// A folder merely named `Deleted` is what the name proposal would
+			// return; the confirmed lookup is what this path asks for.
+			findTrashMailbox: async () => ({
+				mailboxId: DELETED_FOLDER,
+				fullPath: "Deleted",
+			}),
+			findConfirmedTrashMailbox: async () => confirmedTrash,
+		} as unknown as IMailboxSpecialUseRepository,
+		threadMessageService,
+		sqsQueueUrl: "http://localhost:9324/000000000000/remit-messages.fifo",
+	};
+
+	const service = new MessageMoveService(config);
+	(
+		service as unknown as { sqs: { send: (c: unknown) => Promise<unknown> } }
+	).sqs = { send: async () => ({}) };
+
+	return { service, emptied };
+};
+
+describe("MessageMoveService.emptyTrash", () => {
+	it("empties the appointed Trash, never the user folder called Deleted", async () => {
+		const { service, emptied } = buildWorld({
+			mailboxId: REAL_TRASH,
+			fullPath: "[Gmail]/Trash",
+		});
+
+		await service.emptyTrash(ACCOUNT_CONFIG, ACCOUNT);
+
+		assert.deepEqual(emptied, [REAL_TRASH]);
+	});
+
+	it("refuses and names the remedy when no folder is appointed or flagged", async () => {
+		const { service, emptied } = buildWorld(null);
+
+		await assert.rejects(
+			service.emptyTrash(ACCOUNT_CONFIG, ACCOUNT),
+			/Appoint one under Settings/,
+		);
+
+		// Nothing was read, so nothing was marked for deletion and no expunge
+		// was enqueued: an unresolved Trash stops the operation dead.
+		assert.deepEqual(emptied, []);
+	});
+});

package/src/message-move.ts

@@ -11,6 +11,8 @@ import type {
 	IMessageRepository,
 	IThreadMessageRepository,
 } from "@remit/data-ports";
+import { HTTPError } from "@remit/data-ports/errors";
+import { NO_TRASH_FOLDER_REASON } from "@remit/data-ports/folder-role";
 import { deriveCopyMessageId } from "@remit/data-ports/id";
 import { MessageStatus, MessageSyncStatus } from "@remit/domain-enums";
 import { createQueueProducer } from "@remit/sqs-client/producer";
@@ -103,6 +105,22 @@ export interface MessageMoveConfig {
 	logger?: MessageMoveLogger;
 }
 
+/**
+ * The account resolves no Trash folder, so a move-to-Trash delete has nowhere
+ * to put the mail and an Empty Trash has nothing it may empty. A designed,
+ * user-facing outcome carrying its own text and a 409 the backend returns
+ * 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(NO_TRASH_FOLDER_REASON);
+	}
+}
+
 /**
  * Options for delete operations
  */
@@ -191,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<{
@@ -212,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,
@@ -228,7 +259,7 @@ export class MessageMoveService {
 				},
 			};
 
-			if (shouldMoveToTrash && trashMailbox) {
+			if (shouldMoveToTrash) {
 				moveToTrashMessages.push(entry);
 			} else {
 				permanentDeleteMessages.push(entry);
@@ -618,19 +649,25 @@ export class MessageMoveService {
 	};
 
 	/**
-	 * Empty the Trash mailbox (permanent delete all).
+	 * Empty the Trash mailbox: an EXPUNGE of everything in it, with no undo.
 	 *
-	 * @param accountId - Account ID
+	 * Resolved through `findConfirmedTrashMailbox`, so the folder is the one the
+	 * user appointed or the one the server flagged \Trash — never one that
+	 * merely reads like a trash folder. A user with an ordinary folder called
+	 * `Deleted` would otherwise lose its contents permanently, and on a
+	 * `.`-delimited server the old whole-path name match resolved nothing at all
+	 * and the operation reported success over an empty count. Unresolved is a
+	 * refusal that names the remedy, not a silent no-op.
 	 */
 	emptyTrash = async (
 		accountConfigId: string,
 		accountId: string,
 	): Promise<void> => {
 		const trashMailbox =
-			await this.mailboxSpecialUseService.findTrashMailbox(accountId);
+			await this.mailboxSpecialUseService.findConfirmedTrashMailbox(accountId);
 
 		if (!trashMailbox) {
-			throw new Error("No Trash mailbox found for account");
+			throw new NoTrashMailboxError();
 		}
 
 		// Get all messages in Trash

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

@@ -14,7 +14,8 @@ import type {
 	ThreadMessageItem,
 } from "@remit/data-ports";
 import type { ManagedConnectionFactory } from "./connection-factory.js";
-import { MessageSyncService } from "./message-sync.js";
+import { type AccountFolderRoles, MessageSyncService } from "./message-sync.js";
+import { NO_FOLDER_ROLES, noFolderRoles } from "./test-helpers/folder-roles.js";
 import type { ImapAddress, ImapEnvelope, ImapMessage } from "./types.js";
 
 const stub = <T>(): T => ({}) as T;
@@ -76,6 +77,7 @@ const harvest = async (envelope: Partial<ImapEnvelope>): Promise<Saved> => {
 	const service = new MessageSyncService(
 		stub<ManagedConnectionFactory>(),
 		stub<IMailboxRepository>(),
+		noFolderRoles,
 		messageService,
 		envelopeService,
 		addressService,
@@ -98,6 +100,7 @@ const harvest = async (envelope: Partial<ImapEnvelope>): Promise<Saved> => {
 				accountId: string,
 				accountConfigId: string,
 				msg: ImapMessage,
+				roles: AccountFolderRoles,
 			) => Promise<unknown>;
 		}
 	).saveMessage(
@@ -105,6 +108,7 @@ const harvest = async (envelope: Partial<ImapEnvelope>): Promise<Saved> => {
 		"acct-1",
 		"cfg-1",
 		msg,
+		NO_FOLDER_ROLES,
 	);
 
 	return saved;

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

@@ -31,7 +31,8 @@ import type {
 } from "@remit/data-ports";
 import { MessageCategory } from "@remit/domain-enums";
 import type { ManagedConnectionFactory } from "./connection-factory.js";
-import { MessageSyncService } from "./message-sync.js";
+import { type AccountFolderRoles, MessageSyncService } from "./message-sync.js";
+import { NO_FOLDER_ROLES, noFolderRoles } from "./test-helpers/folder-roles.js";
 import type { ImapMessage } from "./types.js";
 
 const envelope = {
@@ -97,6 +98,7 @@ const saveIntoMailbox = async (
 	const service = new MessageSyncService(
 		stub<ManagedConnectionFactory>(),
 		stub<IMailboxRepository>(),
+		noFolderRoles,
 		messageService,
 		envelopeService,
 		addressService,
@@ -110,6 +112,7 @@ const saveIntoMailbox = async (
 				accountId: string,
 				accountConfigId: string,
 				msg: ImapMessage,
+				roles: AccountFolderRoles,
 			) => Promise<unknown>;
 		}
 	).saveMessage(
@@ -117,6 +120,7 @@ const saveIntoMailbox = async (
 		"acct-1",
 		"cfg-1",
 		imapMessage,
+		NO_FOLDER_ROLES,
 	);
 
 	assert.equal(inputs.length, 1);

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

@@ -23,6 +23,7 @@ import type { ManagedConnectionFactory } from "./connection-factory.js";
 import type { FlagPushService } from "./flag-push.js";
 import { FlagQueueService } from "./flag-queue.js";
 import { MessageSyncService } from "./message-sync.js";
+import { noFolderRoles } from "./test-helpers/folder-roles.js";
 import type { IImapConnection, ImapMessage } from "./types.js";
 
 const ACCOUNT_ID = "acc-1";
@@ -267,6 +268,7 @@ const buildHarness = (options: HarnessOptions): Harness => {
 	const service = new MessageSyncService(
 		connectionFactory,
 		mailboxService,
+		noFolderRoles,
 		{} as IMessageRepository,
 		{} as IEnvelopeRepository,
 		addressRepository,

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

@@ -12,6 +12,7 @@ import type {
 import { MessageCategory, MessageSystemFlag } from "@remit/domain-enums";
 import type { ManagedConnectionFactory } from "./connection-factory.js";
 import { MessageSyncService } from "./message-sync.js";
+import { noFolderRoles } from "./test-helpers/folder-roles.js";
 import type { ImapEnvelope } from "./types.js";
 
 // #44: initial sync hardcoded `hasStars: false` on row create, so mail flagged
@@ -83,6 +84,7 @@ const createThreadWithFlags = async (
 	const service = new MessageSyncService(
 		stub<ManagedConnectionFactory>(),
 		stub<IMailboxRepository>(),
+		noFolderRoles,
 		stub<IMessageRepository>(),
 		stub<IEnvelopeRepository>(),
 		stub<IAddressRepository>(),

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

@@ -13,9 +13,13 @@ import type {
 	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 AccountFolderRoles,
+	addressSightingIn,
+	MessageSyncService,
+} from "./message-sync.js";
+import { folderRoles } from "./test-helpers/folder-roles.js";
 import type { ImapEnvelope, ImapMessage } from "./types.js";
 
 const stub = <T>(): T => ({}) as T;
@@ -41,17 +45,21 @@ interface Saved {
 	reconciled: string[];
 }
 
-const mailboxAt = (
-	fullPath: string,
-	specialUse?: MailboxItem["specialUse"],
-): MailboxItem =>
+const mailboxAt = (fullPath: string): MailboxItem =>
 	({
+		mailboxId: `mbx-${fullPath}`,
 		fullPath,
 		hierarchyDelimiter: "/",
-		specialUse,
 	}) as MailboxItem;
 
-const save = async (mailbox: MailboxItem): Promise<Saved> => {
+/**
+ * Save one message into `mailbox`, with the account holding `role` in that same
+ * folder. `undefined` is an account whose Junk and Trash are elsewhere.
+ */
+const save = async (
+	mailbox: MailboxItem,
+	role?: "Junk" | "Trash",
+): Promise<Saved> => {
 	const saved: Saved = {
 		correspondents: [],
 		junk: [],
@@ -98,6 +106,13 @@ const save = async (mailbox: MailboxItem): Promise<Saved> => {
 	const service = new MessageSyncService(
 		stub<ManagedConnectionFactory>(),
 		stub<IMailboxRepository>(),
+		folderRoles(
+			role === "Junk"
+				? { junkMailboxId: mailbox.mailboxId }
+				: role === "Trash"
+					? { trashMailboxId: mailbox.mailboxId }
+					: {},
+		),
 		messageService,
 		envelopeService,
 		addressService,
@@ -120,9 +135,13 @@ const save = async (mailbox: MailboxItem): Promise<Saved> => {
 				accountId: string,
 				accountConfigId: string,
 				msg: ImapMessage,
+				roles: AccountFolderRoles,
 			) => Promise<unknown>;
 		}
-	).saveMessage(mailbox, "acct-1", "cfg-1", msg);
+	).saveMessage(mailbox, "acct-1", "cfg-1", msg, {
+		junkMailboxId: role === "Junk" ? mailbox.mailboxId : null,
+		trashMailboxId: role === "Trash" ? mailbox.mailboxId : null,
+	});
 
 	return saved;
 };
@@ -133,42 +152,32 @@ const emails = (inputs: Array<{ normalizedEmail: string }>): string[] =>
 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");
+	const ROLES = (junk: string | null, trash: string | null) => ({
+		junkMailboxId: junk,
+		trashMailboxId: trash,
 	});
 
-	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 the folder the account appointed, not the folder’s name", () => {
+		// The account appointed `INBOX/Rubbish` as Junk. A second folder called
+		// `Spam` is an ordinary folder, and its senders are correspondents —
+		// a role belongs to one folder (RFC 032), so a name cannot claim it.
+		const roles = ROLES("mbx-rubbish", null);
+		assert.equal(addressSightingIn("mbx-rubbish", roles), "junk");
+		assert.equal(addressSightingIn("mbx-spam", roles), "correspondent");
 	});
 
-	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");
+	it("keeps a message in Trash from deciding either way", () => {
 		assert.equal(
-			addressSightingIn({ fullPath: "Mail.Junk", hierarchyDelimiter: "." }),
-			"junk",
+			addressSightingIn("mbx-trash", ROLES(null, "mbx-trash")),
+			"discarded",
 		);
 	});
 
-	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("reads an account with neither role as all correspondents", () => {
+		assert.equal(
+			addressSightingIn("mbx-anything", ROLES(null, null)),
+			"correspondent",
+		);
 	});
 
 	it("harvests every envelope address of an ordinary message", async () => {
@@ -180,29 +189,20 @@ describe("what a mailbox says about the addresses on its messages", () => {
 	});
 
 	it("withholds every envelope address of a message in Junk", async () => {
-		const saved = await save(mailboxAt("INBOX/Spam", [MailboxSpecialUse.Junk]));
+		const saved = await save(mailboxAt("INBOX/Rubbish"), "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]));
+		const saved = await save(mailboxAt("INBOX/Rubbish"), "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]));
+		const saved = await save(mailboxAt("Trash"), "Trash");
 
 		assert.deepEqual(emails(saved.neutral), BOTH);
 		assert.equal(saved.correspondents.length, 0);
@@ -210,7 +210,7 @@ describe("what a mailbox says about the addresses on its messages", () => {
 	});
 
 	it("re-asks every sighting of a sender a message in Junk carries", async () => {
-		const saved = await save(mailboxAt("INBOX/Spam", [MailboxSpecialUse.Junk]));
+		const saved = await save(mailboxAt("INBOX/Rubbish"), "Junk");
 
 		assert.equal(saved.reconciled.length, 1);
 		assert.deepEqual(saved.reconciled, [saved.envelopeAddresses[0].messageId]);
@@ -218,14 +218,14 @@ describe("what a mailbox says about the addresses on its messages", () => {
 
 	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]));
+		const trash = await save(mailboxAt("Trash"), "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]));
+		await save(mailboxAt("INBOX/Rubbish"), "Junk");
 		const moved = await save(mailboxAt("INBOX"));
 
 		assert.deepEqual(emails(moved.correspondents), BOTH);

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

@@ -30,6 +30,7 @@ import { MailboxCursorState } from "@remit/domain-enums";
 import type { ManagedConnectionFactory } from "./connection-factory.js";
 import { MessageSyncService, selectUidsToSync } from "./message-sync.js";
 import { QuarantineService } from "./quarantine.js";
+import { noFolderRoles } from "./test-helpers/folder-roles.js";
 import type { IImapConnection, ImapMessage } from "./types.js";
 
 const ACCOUNT_ID = "acc-1";
@@ -179,6 +180,7 @@ const buildHarness = (options: {
 			close: async () => {},
 		} as ManagedConnectionFactory,
 		mailboxService,
+		noFolderRoles,
 		{} as IMessageRepository,
 		{} as IEnvelopeRepository,
 		{} as IAddressRepository,

package/src/message-sync.ts

@@ -3,6 +3,7 @@ import type {
 	IAddressRepository,
 	IEnvelopeRepository,
 	IMailboxRepository,
+	IMailboxSpecialUseRepository,
 	IMessageFlagPushRepository,
 	IMessageFlagRepository,
 	IMessageRepository,
@@ -21,11 +22,6 @@ import {
 	deriveThreadId,
 	isValidMessageId,
 } from "@remit/data-ports/id";
-import {
-	isJunkMailbox,
-	isTrashMailbox,
-	type MailboxRole,
-} from "@remit/data-ports/mailbox-role";
 import {
 	AddressRole,
 	MailboxCursorState,
@@ -93,9 +89,34 @@ export const isParseableEmailAddress = (
 
 export type AddressSighting = "junk" | "discarded" | "correspondent";
 
-export const addressSightingIn = (mailbox: MailboxRole): AddressSighting => {
-	if (isJunkMailbox(mailbox)) return "junk";
-	if (isTrashMailbox(mailbox)) return "discarded";
+/** The account's Junk and Trash mailboxes, resolved once per batch. */
+export interface AccountFolderRoles {
+	readonly junkMailboxId: string | null;
+	readonly trashMailboxId: string | null;
+}
+
+/**
+ * What a sighting of an address in this mailbox is worth. Junk withholds the
+ * sender from autocomplete (#822), Trash decides nothing either way, and
+ * anywhere else is a correspondent.
+ *
+ * Decided by mailbox IDENTITY against the account's resolved roles, not by the
+ * folder's flag and name: a role belongs to exactly one folder (RFC 032), and
+ * the folder it belongs to is whichever one the user appointed. Reading the
+ * name here meant a second folder called `Spam` also withheld its senders,
+ * while the folder the user actually appointed harvested every spammer in it as
+ * a correspondent (#837).
+ */
+export const addressSightingIn = (
+	mailboxId: string,
+	roles: AccountFolderRoles,
+): AddressSighting => {
+	if (roles.junkMailboxId !== null && mailboxId === roles.junkMailboxId) {
+		return "junk";
+	}
+	if (roles.trashMailboxId !== null && mailboxId === roles.trashMailboxId) {
+		return "discarded";
+	}
 	return "correspondent";
 };
 
@@ -238,6 +259,13 @@ export class MessageSyncService {
 	constructor(
 		private connectionFactory: ManagedConnectionFactory,
 		private mailboxService: IMailboxRepository,
+		/**
+		 * The account’s folder-role map. Required, not optional: which folder
+		 * holds the Junk role decides whether a sighting withholds its sender
+		 * from autocomplete, and a construction without it would quietly harvest
+		 * spammers as correspondents.
+		 */
+		private mailboxSpecialUseService: IMailboxSpecialUseRepository,
 		messageService: IMessageRepository,
 		envelopeService: IEnvelopeRepository,
 		addressService: IAddressRepository,
@@ -435,9 +463,11 @@ export class MessageSyncService {
 		// which catches its own error and reports a `failed` outcome instead of
 		// rejecting. So one bad message can no longer abort the whole batch (the
 		// poison pill that previously froze the mailbox, #817).
+		const roles = await this.folderRolesFor(accountId);
 		const outcomes = await pMap(
 			applicable,
-			(msg) => this.trySaveMessage(mailbox, accountId, accountConfigId, msg),
+			(msg) =>
+				this.trySaveMessage(mailbox, accountId, accountConfigId, msg, roles),
 			{ concurrency: MESSAGE_SAVE_CONCURRENCY },
 		);
 
@@ -668,9 +698,11 @@ export class MessageSyncService {
 		const newMessages =
 			newUids.length > 0 ? await this.fetchMessageBatch(newUids) : [];
 		const applicable = newMessages.filter((msg) => msg.envelope !== undefined);
+		const roles = await this.folderRolesFor(accountId);
 		const outcomes = await pMap(
 			applicable,
-			(msg) => this.trySaveMessage(mailbox, accountId, accountConfigId, msg),
+			(msg) =>
+				this.trySaveMessage(mailbox, accountId, accountConfigId, msg, roles),
 			{ concurrency: MESSAGE_SAVE_CONCURRENCY },
 		);
 		const syncedMessages: SyncedMessage[] = outcomes.flatMap((o) =>
@@ -894,9 +926,11 @@ export class MessageSyncService {
 			);
 		}
 
+		const roles = await this.folderRolesFor(accountId);
 		const outcomes = await pMap(
 			applicable,
-			(msg) => this.tryApplyChange(mailbox, accountId, accountConfigId, msg),
+			(msg) =>
+				this.tryApplyChange(mailbox, accountId, accountConfigId, msg, roles),
 			{ concurrency: MESSAGE_SAVE_CONCURRENCY },
 		);
 
@@ -1005,9 +1039,10 @@ export class MessageSyncService {
 		accountId: string,
 		accountConfigId: string,
 		msg: ImapMessage,
+		roles: AccountFolderRoles,
 	): Promise<BatchOutcome> {
 		const mailboxId = mailbox.mailboxId;
-		return this.applyChange(mailbox, accountId, accountConfigId, msg)
+		return this.applyChange(mailbox, accountId, accountConfigId, msg, roles)
 			.then((result): BatchOutcome => ({ kind: "saved", uid: msg.uid, result }))
 			.catch((error): BatchOutcome => {
 				this.log.warn(
@@ -1028,6 +1063,7 @@ export class MessageSyncService {
 		accountId: string,
 		accountConfigId: string,
 		msg: ImapMessage,
+		roles: AccountFolderRoles,
 	): Promise<SaveMessageResult | null> {
 		if (!msg.envelope) return null;
 
@@ -1046,7 +1082,7 @@ export class MessageSyncService {
 			messageId,
 		);
 		if (!existing) {
-			return this.saveMessage(mailbox, accountId, accountConfigId, msg);
+			return this.saveMessage(mailbox, accountId, accountConfigId, msg, roles);
 		}
 
 		await this.applyServerFlags(existing, msg.flags);
@@ -1240,14 +1276,31 @@ export class MessageSyncService {
 	 * cycle. This is the guardrail that stops a single unsaveable message from
 	 * permanently freezing the mailbox (#817).
 	 */
+	/**
+	 * Which folders hold Junk and Trash for this account, resolved once per
+	 * batch rather than per message: the lookup reads an appointment row and
+	 * the account’s mailbox list, and every message in a batch shares both.
+	 */
+	private async folderRolesFor(accountId: string): Promise<AccountFolderRoles> {
+		const [junk, trash] = await Promise.all([
+			this.mailboxSpecialUseService.findJunkMailbox(accountId),
+			this.mailboxSpecialUseService.findTrashMailbox(accountId),
+		]);
+		return {
+			junkMailboxId: junk?.mailboxId ?? null,
+			trashMailboxId: trash?.mailboxId ?? null,
+		};
+	}
+
 	private async trySaveMessage(
 		mailbox: MailboxItem,
 		accountId: string,
 		accountConfigId: string,
 		msg: ImapMessage,
+		roles: AccountFolderRoles,
 	): Promise<BatchOutcome> {
 		const mailboxId = mailbox.mailboxId;
-		return this.saveMessage(mailbox, accountId, accountConfigId, msg)
+		return this.saveMessage(mailbox, accountId, accountConfigId, msg, roles)
 			.then((result): BatchOutcome => ({ kind: "saved", uid: msg.uid, result }))
 			.catch((error): BatchOutcome => {
 				this.log.warn(
@@ -1268,11 +1321,12 @@ export class MessageSyncService {
 		accountId: string,
 		accountConfigId: string,
 		msg: ImapMessage,
+		roles: AccountFolderRoles,
 	): Promise<SaveMessageResult | null> {
 		if (!msg.envelope) return null;
 
 		const mailboxId = mailbox.mailboxId;
-		const sighting = addressSightingIn(mailbox);
+		const sighting = addressSightingIn(mailboxId, roles);
 
 		// Store envelope to preserve narrowing in closures
 		const envelope = msg.envelope;

package/src/test-helpers/folder-roles.ts

@@ -0,0 +1,34 @@
+import type { IMailboxSpecialUseRepository } from "@remit/data-ports";
+
+/**
+ * A folder-role map for an account that has appointed nothing and whose server
+ * flags nothing — every mailbox is an ordinary folder. The stand-in for the
+ * many suites that construct `MessageSyncService` for a reason unrelated to
+ * which folder holds which role.
+ */
+export const noFolderRoles = {
+	findJunkMailbox: async () => null,
+	findTrashMailbox: async () => null,
+} as unknown as IMailboxSpecialUseRepository;
+
+/** A folder-role map naming the mailboxes that hold Junk and Trash. */
+export const folderRoles = (roles: {
+	junkMailboxId?: string;
+	trashMailboxId?: string;
+}): IMailboxSpecialUseRepository =>
+	({
+		findJunkMailbox: async () =>
+			roles.junkMailboxId
+				? { mailboxId: roles.junkMailboxId, fullPath: roles.junkMailboxId }
+				: null,
+		findTrashMailbox: async () =>
+			roles.trashMailboxId
+				? { mailboxId: roles.trashMailboxId, fullPath: roles.trashMailboxId }
+				: null,
+	}) as unknown as IMailboxSpecialUseRepository;
+
+/** The same account, as the resolved map `saveMessage` is handed. */
+export const NO_FOLDER_ROLES = {
+	junkMailboxId: null,
+	trashMailboxId: null,
+};