@remit/mailbox-service 0.0.110 → 0.0.112

package/src/folder-operations.test.ts

@@ -0,0 +1,273 @@
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import type { AccountItem, MailboxItem } from "@remit/data-ports";
+import { MailboxSyncStatus } from "@remit/domain-enums";
+import {
+	changeFolderPath,
+	createFolder,
+	type FolderPathOutcome,
+} from "./folder-operations.js";
+import { MailboxQueueService } from "./mailbox-queue.js";
+import { folderInAccount } from "./ownership.js";
+import type { Refusable } from "./refusal.js";
+import {
+	captureQueue,
+	openStore,
+	type QueueCapture,
+	type Store,
+	seedAccount,
+	seedMailbox,
+} from "./test-helpers/test-store.js";
+
+let store: Store;
+let capture: QueueCapture;
+let account: AccountItem;
+let mailboxQueue: MailboxQueueService;
+
+beforeEach(async () => {
+	capture = captureQueue();
+	store = await openStore();
+	account = await seedAccount(store);
+	mailboxQueue = new MailboxQueueService({
+		mailboxService: store.mailbox,
+		sqsQueueUrl: "http://localhost:4566/000000000000/mailbox",
+	});
+});
+
+afterEach(async () => {
+	capture.restore();
+	await store.close();
+});
+
+const rename = (
+	mailbox: MailboxItem,
+	fullPath: string,
+): Promise<Refusable<FolderPathOutcome>> =>
+	changeFolderPath(
+		{ account: store.account, mailbox: store.mailbox, mailboxQueue },
+		account.accountConfigId,
+		{
+			accountId: mailbox.accountId,
+			mailboxId: mailbox.mailboxId,
+			fullPath,
+		},
+	);
+
+const refusalOf = <T>(outcome: Refusable<T>) => {
+	assert.equal(outcome.ok, false, "expected a refusal");
+	return outcome.ok ? undefined : outcome.refusal;
+};
+
+const invalid = (message: string) => ({ kind: "Invalid", message });
+
+describe("changeFolderPath refuses a rename no retry could satisfy", () => {
+	it("keeps INBOX where it is", async () => {
+		const inbox = await seedMailbox(store, account, "INBOX");
+
+		assert.deepEqual(
+			refusalOf(await rename(inbox, "Old inbox")),
+			invalid("The inbox can't be renamed."),
+		);
+	});
+
+	it("keeps the INBOX name for the inbox", async () => {
+		const folder = await seedMailbox(store, account, "Receipts");
+
+		assert.deepEqual(
+			refusalOf(await rename(folder, "inbox")),
+			invalid("“INBOX” is reserved for the inbox."),
+		);
+	});
+
+	it("needs a name", async () => {
+		const folder = await seedMailbox(store, account, "Receipts");
+
+		assert.deepEqual(
+			refusalOf(await rename(folder, "  ")),
+			invalid("A folder needs a name."),
+		);
+	});
+
+	it("keeps a system folder's conventional name free", async () => {
+		const folder = await seedMailbox(store, account, "Receipts");
+
+		assert.deepEqual(
+			refusalOf(await rename(folder, "Projects/Trash")),
+			invalid("“Trash” is reserved for a system folder. Pick another name."),
+		);
+	});
+
+	it("refuses a path another folder holds", async () => {
+		await seedMailbox(store, account, "Archive 2024");
+		const folder = await seedMailbox(store, account, "Receipts");
+
+		assert.deepEqual(
+			refusalOf(await rename(folder, "Archive 2024")),
+			invalid("A folder named “Archive 2024” is already there."),
+		);
+	});
+
+	it("refuses a path a pending rename is heading for", async () => {
+		const first = await seedMailbox(store, account, "Bills");
+		const second = await seedMailbox(store, account, "Receipts");
+		assert.equal((await rename(first, "Paperwork")).ok, true);
+
+		assert.deepEqual(
+			refusalOf(await rename(second, "Paperwork")),
+			invalid("“Bills” is already being renamed to “Paperwork”."),
+		);
+	});
+});
+
+describe("changeFolderPath records a pending rename the mail server settles", () => {
+	it("keeps the confirmed path, records the target and queues the rename", async () => {
+		const folder = await seedMailbox(store, account, "Receipts");
+
+		const outcome = await rename(folder, "Paperwork");
+
+		assert.equal(outcome.ok, true);
+		const row = await store.mailbox.get(account.accountId, folder.mailboxId);
+		assert.equal(row.fullPath, "Receipts");
+		assert.equal(row.pendingPath, "Paperwork");
+		assert.equal(row.syncStatus, MailboxSyncStatus.pending);
+		assert.deepEqual(
+			capture.sent.map((event) => event.body.type),
+			["MAILBOX_RENAME"],
+		);
+	});
+
+	it("dismisses a failed rename when asked for the path the folder has", async () => {
+		const folder = await seedMailbox(store, account, "Receipts");
+		await store.mailbox.transition(account.accountId, folder.mailboxId, {
+			from: [MailboxSyncStatus.synced],
+			to: MailboxSyncStatus.failed,
+			set: { pendingPath: "Paperwork" },
+		});
+
+		const outcome = await rename(folder, "Receipts");
+
+		assert.equal(outcome.ok, true);
+		const row = await store.mailbox.get(account.accountId, folder.mailboxId);
+		assert.equal(row.syncStatus, MailboxSyncStatus.synced);
+		assert.equal(row.pendingPath, undefined);
+		assert.deepEqual(capture.sent, []);
+	});
+
+	it("returns the recorded intent when asked for the target it is already heading for", async () => {
+		const folder = await seedMailbox(store, account, "Receipts");
+		assert.equal((await rename(folder, "Paperwork")).ok, true);
+
+		const again = await rename(folder, "Paperwork");
+
+		assert.equal(again.ok && again.value.outcome, "AlreadyRecorded");
+		assert.equal(again.ok && again.value.mailbox.pendingPath, "Paperwork");
+		assert.equal(capture.sent.length, 1);
+	});
+
+	it("refuses a new target while another change is in flight", async () => {
+		const folder = await seedMailbox(store, account, "Receipts");
+		assert.equal((await rename(folder, "Paperwork")).ok, true);
+
+		assert.deepEqual(refusalOf(await rename(folder, "Bills")), {
+			kind: "Conflict",
+			message: `A rename is in progress for "Receipts".`,
+		});
+		assert.equal(capture.sent.length, 1);
+	});
+});
+
+describe("createFolder", () => {
+	it("records a pending folder and queues its create", async () => {
+		const outcome = await createFolder(
+			{ account: store.account, mailbox: store.mailbox, mailboxQueue },
+			account.accountConfigId,
+			{
+				accountId: account.accountId,
+				namespaceType: "personal",
+				fullPath: "Receipts",
+			},
+		);
+
+		assert.equal(outcome.ok, true);
+		assert.equal(outcome.ok && outcome.value.outcome, "Created");
+		assert.equal(outcome.ok && outcome.value.mailbox.syncStatus, "pending");
+		assert.deepEqual(
+			capture.sent.map((event) => event.body.type),
+			["MAILBOX_CREATE"],
+		);
+	});
+
+	it("returns the folder already at that path", async () => {
+		const existing = await seedMailbox(store, account, "Receipts");
+
+		const outcome = await createFolder(
+			{ account: store.account, mailbox: store.mailbox, mailboxQueue },
+			account.accountConfigId,
+			{
+				accountId: account.accountId,
+				namespaceType: "personal",
+				fullPath: "Receipts",
+			},
+		);
+
+		assert.equal(outcome.ok && outcome.value.outcome, "Existing");
+		assert.equal(
+			outcome.ok && outcome.value.mailbox.mailboxId,
+			existing.mailboxId,
+		);
+		assert.deepEqual(capture.sent, []);
+	});
+});
+
+describe("createFolder for another tenant", () => {
+	it("refuses a caller who does not own the account, recording nothing", async () => {
+		const outcome = await createFolder(
+			{ account: store.account, mailbox: store.mailbox, mailboxQueue },
+			"cfg-x",
+			{
+				accountId: account.accountId,
+				namespaceType: "personal",
+				fullPath: "Receipts",
+			},
+		);
+
+		assert.deepEqual(refusalOf(outcome), {
+			kind: "Forbidden",
+			message: `Account ${account.accountId} not in account config`,
+		});
+		assert.deepEqual(capture.sent, []);
+	});
+});
+
+describe("changeFolderPath for another tenant", () => {
+	it("refuses a caller who does not own the account, recording nothing", async () => {
+		const folder = await seedMailbox(store, account, "Receipts");
+		const outcome = await changeFolderPath(
+			{ account: store.account, mailbox: store.mailbox, mailboxQueue },
+			"cfg-x",
+			{
+				accountId: account.accountId,
+				mailboxId: folder.mailboxId,
+				fullPath: "Paperwork",
+			},
+		);
+
+		assert.deepEqual(refusalOf(outcome), {
+			kind: "Forbidden",
+			message: `Account ${account.accountId} not in account config`,
+		});
+		assert.deepEqual(capture.sent, []);
+	});
+});
+
+describe("folderInAccount", () => {
+	it("refuses another account's folder as not found on a read", async () => {
+		const other = await seedAccount(store, { accountConfigId: "cfg-other" });
+		const theirs = await seedMailbox(store, other, "Receipts");
+
+		assert.deepEqual(
+			refusalOf(folderInAccount(theirs, account.accountId, "read")),
+			{ kind: "NotFound", message: `Mailbox not found: ${theirs.mailboxId}` },
+		);
+	});
+});

package/src/folder-operations.ts

@@ -0,0 +1,217 @@
+import type {
+	AccountItem,
+	IAccountRepository,
+	IMailboxRepository,
+	MailboxItem,
+} from "@remit/data-ports";
+import { isReservedFolderName } from "@remit/data-ports/folder-role";
+import { mailboxLeafName } from "@remit/data-ports/mailbox-name";
+import { MailboxSyncStatus } from "@remit/domain-enums";
+import { carriesIntent, folderInFlight } from "./mailbox-intent.js";
+import type { MailboxQueueService } from "./mailbox-queue.js";
+import { folderInAccount, ownedAccount } from "./ownership.js";
+import { accept, invalid, type Refusable, refuse } from "./refusal.js";
+
+export interface FolderPathDeps {
+	account: { get(accountId: string): Promise<AccountItem> };
+	mailbox: {
+		get(accountId: string, mailboxId: string): Promise<MailboxItem>;
+		listAllByAccount(accountId: string): Promise<MailboxItem[]>;
+	};
+	mailboxQueue: Pick<
+		MailboxQueueService,
+		"renameMailbox" | "dismissMailboxIntent"
+	>;
+}
+
+export interface CreateFolderDeps {
+	account: Pick<IAccountRepository, "get">;
+	mailbox: Pick<IMailboxRepository, "findByPath">;
+	mailboxQueue: Pick<MailboxQueueService, "createMailbox">;
+}
+
+export interface NewFolder {
+	accountId: string;
+	namespaceType: MailboxItem["namespaceType"];
+	fullPath: string;
+}
+
+// AlreadyRecorded: the folder is already heading for the requested path, so
+// nothing new was recorded or queued.
+export interface FolderPathOutcome {
+	outcome: "Recorded" | "AlreadyRecorded";
+	mailbox: MailboxItem;
+}
+
+export interface NewFolderOutcome {
+	outcome: "Created" | "Existing";
+	mailbox: MailboxItem;
+}
+
+export interface FolderPathChange {
+	accountId: string;
+	mailboxId: string;
+	fullPath: string;
+}
+
+const renameTargetRefusal = async (
+	deps: Pick<FolderPathDeps, "mailbox">,
+	accountId: string,
+	before: MailboxItem,
+	target: string,
+): Promise<Refusable<string>> => {
+	// Renaming INBOX leaves an empty INBOX behind, and INBOX is the one name
+	// RFC 3501 reserves.
+	if (before.fullPath.toUpperCase() === "INBOX") {
+		return invalid("The inbox can't be renamed.");
+	}
+	if (target.trim().length === 0) {
+		return invalid("A folder needs a name.");
+	}
+	if (target.toUpperCase() === "INBOX") {
+		return invalid("“INBOX” is reserved for the inbox.");
+	}
+
+	// The mailbox sweep reads an unflagged folder under a role's conventional
+	// name as a duplicate and reaps it, with its mail, once another folder holds
+	// the flag.
+	const leaf = mailboxLeafName({
+		fullPath: target,
+		hierarchyDelimiter: before.hierarchyDelimiter,
+	});
+	if (isReservedFolderName(leaf)) {
+		return invalid(
+			`“${leaf}” is reserved for a system folder. Pick another name.`,
+		);
+	}
+
+	// A path a pending rename is heading for is as taken as one a folder sits
+	// at. A failed rename keeps its target only so the client can offer a
+	// retry; nothing is coming for it, so it claims nothing.
+	const folders = await deps.mailbox.listAllByAccount(accountId);
+	for (const folder of folders) {
+		if (folder.mailboxId === before.mailboxId) continue;
+		if (folder.fullPath === target) {
+			return invalid(`A folder named “${target}” is already there.`);
+		}
+		if (
+			folder.syncStatus === MailboxSyncStatus.pending &&
+			folder.pendingPath === target
+		) {
+			return invalid(
+				`“${folder.fullPath}” is already being renamed to “${target}”.`,
+			);
+		}
+	}
+	return accept(target);
+};
+
+// A fullPath equal to the confirmed one is not a rename: it dismisses a failed
+// intent, the one route out of `failed` that enqueues nothing. The row keeps
+// the path the server holds until the rename settles.
+export const ownedFolder = async (
+	deps: Pick<FolderPathDeps, "account" | "mailbox">,
+	accountConfigId: string,
+	accountId: string,
+	mailboxId: string,
+): Promise<Refusable<MailboxItem>> => {
+	const owned = ownedAccount(
+		await deps.account.get(accountId),
+		accountConfigId,
+		"act",
+	);
+	if (!owned.ok) return owned;
+	return folderInAccount(
+		await deps.mailbox.get(accountId, mailboxId),
+		accountId,
+		"act",
+	);
+};
+
+export const changeFolderPath = async (
+	deps: FolderPathDeps,
+	accountConfigId: string,
+	change: FolderPathChange,
+): Promise<Refusable<FolderPathOutcome>> => {
+	const { accountId, mailboxId, fullPath } = change;
+	const folder = await ownedFolder(deps, accountConfigId, accountId, mailboxId);
+	if (!folder.ok) return folder;
+	const before = folder.value;
+	if (fullPath === before.fullPath) {
+		return accept({
+			outcome: "Recorded",
+			mailbox: await deps.mailboxQueue.dismissMailboxIntent(
+				mailboxId,
+				accountId,
+			),
+		});
+	}
+
+	const target = await renameTargetRefusal(deps, accountId, before, fullPath);
+	if (!target.ok) return target;
+
+	if (!carriesIntent(before)) {
+		if (
+			before.syncStatus === MailboxSyncStatus.pending &&
+			before.pendingPath === fullPath
+		) {
+			return accept({ outcome: "AlreadyRecorded", mailbox: before });
+		}
+		return refuse({ kind: "Conflict", message: folderInFlight(before) });
+	}
+
+	return accept({
+		outcome: "Recorded",
+		mailbox: await deps.mailboxQueue.renameMailbox(
+			mailboxId,
+			fullPath,
+			accountId,
+		),
+	});
+};
+
+export const createFolder = async (
+	deps: CreateFolderDeps,
+	accountConfigId: string,
+	folder: NewFolder,
+): Promise<Refusable<NewFolderOutcome>> => {
+	const { accountId, namespaceType, fullPath } = folder;
+	const owned = ownedAccount(
+		await deps.account.get(accountId),
+		accountConfigId,
+		"act",
+	);
+	if (!owned.ok) return owned;
+
+	const created = await deps.mailboxQueue.createMailbox(
+		{
+			accountId,
+			namespaceType,
+			namespacePrefix: "",
+			hierarchyDelimiter: "/",
+			fullPath,
+			uidValidity: 0,
+			uidNext: 1,
+			highestModseq: "0",
+			messageCount: 0,
+			unseenCount: 0,
+			deletedCount: 0,
+			totalSize: 0,
+			lastSyncUid: 0,
+			highWaterMarkUid: 0,
+			lastMessageSyncAt: 0,
+		},
+		accountId,
+		true,
+	);
+	if (created.outcome === "PathTaken") {
+		const existing = await deps.mailbox.findByPath(accountId, fullPath);
+		if (!existing) {
+			throw new Error(
+				`No folder at "${fullPath}" after its create reported the path taken`,
+			);
+		}
+		return accept({ outcome: "Existing", mailbox: existing });
+	}
+	return accept({ outcome: "Created", mailbox: created.mailbox });
+};

package/src/forwarded-message.test.ts

@@ -0,0 +1,122 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
+import {
+	mapMessagePartsToContent,
+	parsePartSource,
+} from "./body-part-mapper.js";
+import { type MimeNode, walkMimeStructure } from "./mime-walker.js";
+
+const FIXTURE = readFileSync(
+	resolve(
+		dirname(fileURLToPath(import.meta.url)),
+		"../../e2e/fixtures/mime-adversarial/04-forwarded-rfc822-with-attachments.eml",
+	),
+	"utf8",
+).replace(/\r?\n/g, "\r\n");
+
+const ATTACHED = 'Content-Disposition: attachment; filename="forwarded.eml"';
+const INLINE = 'Content-Disposition: inline; filename="forwarded.eml"';
+
+/** Fixture 04 as imapflow hands it over: the forwarded message's root reuses part "2". */
+const structure = (disposition: string): MimeNode => ({
+	type: "multipart/mixed",
+	childNodes: [
+		{ part: "1", type: "text/plain", encoding: "7bit", size: 115 },
+		{
+			part: "2",
+			type: "message/rfc822",
+			encoding: "7bit",
+			size: 638,
+			disposition,
+			dispositionParameters: { filename: "forwarded.eml" },
+			childNodes: [
+				{
+					part: "2",
+					type: "multipart/mixed",
+					childNodes: [
+						{ part: "2.1", type: "text/plain", encoding: "7bit", size: 40 },
+						{
+							part: "2.2",
+							type: "application/pdf",
+							encoding: "base64",
+							size: 44,
+							disposition: "attachment",
+							dispositionParameters: { filename: "original.pdf" },
+						},
+					],
+				},
+			],
+		},
+	],
+});
+
+const forwardedSource = (): string => {
+	const start = FIXTURE.indexOf("From: carol@example.com");
+	const end = FIXTURE.indexOf("\r\n--=_adv04_outer_=--");
+	return FIXTURE.slice(start, end);
+};
+
+const storedContent = async (
+	source: string,
+	disposition: string,
+): Promise<Map<string, string>> => {
+	const pairs = await mapMessagePartsToContent(
+		walkMimeStructure(structure(disposition)),
+		await parsePartSource(Buffer.from(source)),
+	);
+	return new Map(
+		pairs.map((pair) => [pair.partPath, pair.content.toString("utf8")]),
+	);
+};
+
+describe("a forwarded message/rfc822 part", () => {
+	it("is stored as its own part, apart from the message it carries", () => {
+		const records = walkMimeStructure(structure("attachment"));
+
+		assert.deepEqual(
+			records.map((record) => [
+				record.partPath,
+				record.parentPartPath,
+				`${record.mediaType}/${record.mediaSubtype}`,
+			]),
+			[
+				["0", null, "MULTIPART/mixed"],
+				["1", "0", "TEXT/plain"],
+				["2", "0", "MESSAGE/rfc822"],
+				["2.0", "2", "MULTIPART/mixed"],
+				["2.1", "2.0", "TEXT/plain"],
+				["2.2", "2.0", "APPLICATION/pdf"],
+			],
+		);
+		const forwarded = records.find((record) => record.partPath === "2");
+		assert.equal(forwarded?.isMultipart, false);
+		assert.equal(forwarded?.dispositionFilename, "forwarded.eml");
+	});
+
+	for (const [disposition, header] of [
+		["attachment", ATTACHED],
+		["inline", INLINE],
+	] as const) {
+		it(`stores the raw forwarded message and its own parts' bytes when it is ${disposition}`, async () => {
+			const content = await storedContent(
+				FIXTURE.replace(ATTACHED, header),
+				disposition,
+			);
+
+			assert.deepEqual([...content.keys()], ["1", "2", "2.1", "2.2"]);
+			assert.match(content.get("1") ?? "", /Forwarding the message below/);
+			assert.equal(
+				(content.get("2") ?? "").trimEnd(),
+				forwardedSource().trimEnd(),
+			);
+			assert.equal(
+				(content.get("2.1") ?? "").trimEnd(),
+				"Original message body before forwarding.",
+			);
+			assert.equal(content.get("2.2"), "%PDF-1.4\n%adv 04 inner pdf\n%EOF\n");
+		});
+	}
+});