@remit/backend 0.0.119 → 0.0.121

package/src/handlers/mailbox-rename-refusal.test.ts

@@ -0,0 +1,247 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { MailboxItem } from "@remit/data-ports";
+import { MailboxSyncStatus } from "@remit/domain-enums";
+import { applyMailboxPatch, type MailboxPatchClient } from "./mailbox.js";
+
+const ACCOUNT_ID = "acc-1";
+const CONFIG_ID = "cfg-1";
+
+const mailbox = (over: Partial<MailboxItem> = {}): MailboxItem =>
+	({
+		mailboxId: "mbx-1",
+		accountId: ACCOUNT_ID,
+		fullPath: "Work",
+		hierarchyDelimiter: "/",
+		syncStatus: MailboxSyncStatus.synced,
+		...over,
+	}) as MailboxItem;
+
+const clientOver = (
+	row: MailboxItem,
+	others: MailboxItem[] = [],
+): {
+	client: MailboxPatchClient;
+	renames: { mailboxId: string; newPath: string }[];
+	dismissals: string[];
+	settings: string[];
+} => {
+	const renames: { mailboxId: string; newPath: string }[] = [];
+	const dismissals: string[] = [];
+	const settings: string[] = [];
+	const client: MailboxPatchClient = {
+		mailbox: {
+			get: async () => row,
+			listAllByAccount: async () => [row, ...others],
+		},
+		mailboxQueue: {
+			renameMailbox: async (mailboxId, newPath) => {
+				renames.push({ mailboxId, newPath });
+				return mailbox({ pendingPath: newPath });
+			},
+			dismissMailboxIntent: async (mailboxId) => {
+				dismissals.push(mailboxId);
+				return mailbox();
+			},
+		},
+		accountSetting: {
+			get: async () => null,
+			upsert: async (item) => {
+				settings.push(item.name);
+				return item as never;
+			},
+			delete: async (_configId, name) => {
+				settings.push(name);
+			},
+		},
+	};
+	return { client, renames, dismissals, settings };
+};
+
+const patch = (
+	client: MailboxPatchClient,
+	body: Record<string, unknown>,
+): Promise<MailboxItem> =>
+	applyMailboxPatch(client, CONFIG_ID, "mbx-1", ACCOUNT_ID, body);
+
+const refusedWith = (message: string) => (error: unknown) =>
+	(error as { statusCode?: number }).statusCode === 400 &&
+	(error as Error).message === message;
+
+describe("applyMailboxPatch — renames that can never succeed (D4, D5)", () => {
+	it("refuses to rename the inbox", async () => {
+		const { client, renames } = clientOver(mailbox({ fullPath: "INBOX" }));
+
+		await assert.rejects(
+			patch(client, { fullPath: "Postvak" }),
+			refusedWith("The inbox can't be renamed."),
+		);
+		assert.equal(renames.length, 0);
+	});
+
+	it("refuses a target that canonicalizes to the inbox", async () => {
+		const { client, renames } = clientOver(mailbox());
+
+		await assert.rejects(
+			patch(client, { fullPath: "inbox" }),
+			refusedWith("“INBOX” is reserved for the inbox."),
+		);
+		assert.equal(renames.length, 0);
+	});
+
+	it("refuses an empty target", async () => {
+		const { client, renames } = clientOver(mailbox());
+
+		await assert.rejects(
+			patch(client, { fullPath: "   " }),
+			refusedWith("A folder needs a name."),
+		);
+		assert.equal(renames.length, 0);
+	});
+
+	it("refuses a target another folder already holds", async () => {
+		const { client, renames } = clientOver(mailbox(), [
+			mailbox({ mailboxId: "mbx-2", fullPath: "Projects" }),
+		]);
+
+		await assert.rejects(
+			patch(client, { fullPath: "Projects" }),
+			refusedWith("A folder named “Projects” is already there."),
+		);
+		assert.equal(renames.length, 0);
+	});
+
+	/**
+	 * The sweep reads a folder whose leaf name is a role's conventional name but
+	 * which lacks the server's flag as a duplicate, and deletes its row — under
+	 * D8, with the folder's mail — as soon as another folder holds the flag. A
+	 * rename to one of those settles `synced` and is then reaped.
+	 */
+	for (const [name, leaf] of [
+		["Archive", "Archive"],
+		["Trash", "Trash"],
+		["Drafts", "Drafts"],
+		["Sent", "Sent"],
+		["Junk", "Spam"],
+	] as const) {
+		it(`refuses a rename to the reserved ${name} name`, async () => {
+			const { client, renames } = clientOver(mailbox());
+
+			await assert.rejects(
+				patch(client, { fullPath: `Work/${leaf}` }),
+				refusedWith(
+					`“${leaf}” is reserved for a system folder. Pick another name.`,
+				),
+			);
+			assert.equal(renames.length, 0);
+		});
+	}
+
+	it("refuses a target another rename is already on its way to", async () => {
+		// A path a rename is aiming at is as taken as one a folder sits at (D2).
+		// Two renames onto one target both settle, both write it, and the sweep
+		// then reaps one row — with its mail — and inserts a duplicate.
+		const { client, renames } = clientOver(mailbox(), [
+			mailbox({
+				mailboxId: "mbx-2",
+				fullPath: "Admin",
+				syncStatus: MailboxSyncStatus.pending,
+				pendingPath: "Projects",
+			}),
+		]);
+
+		await assert.rejects(
+			patch(client, { fullPath: "Projects" }),
+			refusedWith("“Admin” is already being renamed to “Projects”."),
+		);
+		assert.equal(renames.length, 0);
+	});
+
+	it("lets a failed rename's stale target go to somebody else", async () => {
+		// `failed` keeps its target so the client can name what the rename was
+		// aiming at and offer a retry (T6), and nothing clears it until the user
+		// retries or dismisses. Honouring that claim would tell everyone else the
+		// path is taken by a rename that is not happening, with nothing to wait
+		// for and no way to find out.
+		const { client, renames } = clientOver(mailbox(), [
+			mailbox({
+				mailboxId: "mbx-2",
+				fullPath: "Admin",
+				syncStatus: MailboxSyncStatus.failed,
+				pendingPath: "Projects",
+			}),
+		]);
+
+		await patch(client, { fullPath: "Projects" });
+
+		assert.deepEqual(renames, [{ mailboxId: "mbx-1", newPath: "Projects" }]);
+	});
+
+	it("lets a retry aim at the target its own failed rename recorded", async () => {
+		const { client, renames } = clientOver(
+			mailbox({
+				syncStatus: MailboxSyncStatus.failed,
+				pendingPath: "Projects",
+			}),
+		);
+
+		await patch(client, { fullPath: "Projects" });
+
+		assert.deepEqual(renames, [{ mailboxId: "mbx-1", newPath: "Projects" }]);
+	});
+
+	it("records the intent for an ordinary target", async () => {
+		const { client, renames } = clientOver(mailbox());
+
+		const renamed = await patch(client, { fullPath: "Projects" });
+
+		assert.deepEqual(renames, [{ mailboxId: "mbx-1", newPath: "Projects" }]);
+		assert.equal(renamed.pendingPath, "Projects");
+	});
+});
+
+describe("applyMailboxPatch — dismissing a failed intent (T10, T11)", () => {
+	it("reads a target equal to the confirmed path as a dismissal, not a rename", async () => {
+		const { client, renames, dismissals } = clientOver(
+			mailbox({
+				syncStatus: MailboxSyncStatus.failed,
+				pendingPath: "Projects",
+			}),
+		);
+
+		const dismissed = await patch(client, { fullPath: "Work" });
+
+		assert.deepEqual(dismissals, ["mbx-1"]);
+		assert.equal(renames.length, 0, "nothing is enqueued for a dismissal");
+		assert.equal(dismissed.syncStatus, MailboxSyncStatus.synced);
+	});
+
+	it("dismisses even where the folder's own name is reserved", async () => {
+		// The refusals gate a rename's target. Keeping the name a folder already
+		// has is not one, and a folder called `Archive` must still be able to
+		// dismiss a rename that failed.
+		const { client, dismissals } = clientOver(
+			mailbox({ fullPath: "Archive", syncStatus: MailboxSyncStatus.failed }),
+		);
+
+		await patch(client, { fullPath: "Archive" });
+
+		assert.deepEqual(dismissals, ["mbx-1"]);
+	});
+});
+
+describe("applyMailboxPatch — an override-only PATCH", () => {
+	it("touches no mutation state", async () => {
+		const { client, renames, dismissals, settings } = clientOver(mailbox());
+
+		await patch(client, { muted: true });
+
+		assert.equal(renames.length, 0);
+		assert.equal(dismissals.length, 0);
+		assert.equal(
+			settings.length > 0,
+			true,
+			"the override row is still written",
+		);
+	});
+});

package/src/handlers/mailbox-settled-target.test.ts

@@ -0,0 +1,239 @@
+/**
+ * Every API write that binds a durable reference to a folder requires that
+ * folder to be settled (D12, first row; imap-mutations R2: wait). Driven
+ * through the real handlers rather than the helper, because the claim is that
+ * each call site is wired to it — a helper that nothing calls refuses nothing.
+ *
+ * The other half of the same invariant is the delete refusal (D16), in
+ * `mailbox.test.ts`: a binding is only created against a settled folder and
+ * only removed by the user, so a `mailboxId` that names nothing never exists.
+ */
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import type { MailboxItem } from "@remit/data-ports";
+import { CanonicalMailboxRole, MailboxSyncStatus } from "@remit/domain-enums";
+import type { APIGatewayProxyEvent } from "aws-lambda";
+import type { Context } from "openapi-backend";
+import { deriveAccountConfigId } from "../auth.js";
+import {
+	_resetForTest,
+	type RemitClient,
+	setClient,
+} from "../service/data-client.js";
+import { FilterDetailOperations, FilterOperations } from "./filter.js";
+import { FolderRoleOperations } from "./folder-role.js";
+import { MessageBulkOperations } from "./message.js";
+
+const SUB = "cognito-sub-365";
+const ACCOUNT_ID = "acc-365";
+const CONFIG_ID = deriveAccountConfigId(SUB);
+const TARGET = "mbx-target";
+
+const target = (syncStatus: MailboxItem["syncStatus"]): MailboxItem =>
+	({
+		mailboxId: TARGET,
+		accountId: ACCOUNT_ID,
+		fullPath: "Receipts",
+		hierarchyDelimiter: "/",
+		syncStatus,
+	}) as MailboxItem;
+
+interface Writes {
+	filters: unknown[];
+	filterPatches: unknown[];
+	appointments: unknown[];
+	moves: unknown[];
+	copies: unknown[];
+}
+
+const world = (syncStatus: MailboxItem["syncStatus"]): Writes => {
+	const writes: Writes = {
+		filters: [],
+		filterPatches: [],
+		appointments: [],
+		moves: [],
+		copies: [],
+	};
+	const row = target(syncStatus);
+
+	setClient({
+		account: {
+			get: async () => ({ accountId: ACCOUNT_ID, accountConfigId: CONFIG_ID }),
+			listAllByAccountConfig: async () => [{ accountId: ACCOUNT_ID }],
+		},
+		mailbox: {
+			get: async (_accountId: string, mailboxId: string | string[]) =>
+				Array.isArray(mailboxId)
+					? mailboxId.map((id) => ({ mailboxId: id, accountId: ACCOUNT_ID }))
+					: row,
+			listAllByAccount: async () => [row],
+		},
+		message: {
+			get: async () => ({ mailboxId: "mbx-source" }),
+		},
+		filter: {
+			get: async () => ({ filterId: "flt-1", scope: "Standing" }),
+			update: async (...args: unknown[]) => {
+				writes.filterPatches.push(args);
+				return { filterId: "flt-1" };
+			},
+			listByAccountConfig: async () => [],
+		},
+		filterAnchorTransaction: {
+			createWithAnchor: async (input: unknown) => {
+				writes.filters.push(input);
+				return { filterId: "flt-1" };
+			},
+		},
+		accountSetting: {
+			get: async () => null,
+			upsert: async (item: unknown) => {
+				writes.appointments.push(item);
+				return item;
+			},
+			delete: async () => undefined,
+		},
+		messageMove: {
+			moveMessages: async (...args: unknown[]) => {
+				writes.moves.push(args);
+			},
+			copyMessages: async (...args: unknown[]) => {
+				writes.copies.push(args);
+			},
+		},
+	} as unknown as RemitClient);
+
+	return writes;
+};
+
+const event = {
+	requestContext: { authorizer: { claims: { sub: SUB } } },
+} as unknown as APIGatewayProxyEvent;
+
+const call = <T>(
+	handler: unknown,
+	request: Record<string, unknown>,
+): Promise<T> =>
+	(handler as (context: Context, event: APIGatewayProxyEvent) => Promise<T>)(
+		{ request } as unknown as Context,
+		event,
+	);
+
+const appoint = () =>
+	call(FolderRoleOperations.FolderRoleOperations_appointFolderRole, {
+		params: { accountId: ACCOUNT_ID, role: CanonicalMailboxRole.Archive },
+		requestBody: { mailboxId: TARGET },
+	});
+
+const createFilter = () =>
+	call(FilterOperations.FilterOperations_createFilter, {
+		params: { accountId: ACCOUNT_ID },
+		requestBody: {
+			name: "Invoices",
+			scope: "Standing",
+			actionMailboxId: TARGET,
+		},
+	});
+
+const updateFilter = () =>
+	call(FilterDetailOperations.FilterDetailOperations_updateFilter, {
+		params: { accountId: ACCOUNT_ID, filterId: "flt-1" },
+		requestBody: { actionMailboxId: TARGET },
+	});
+
+const moveMessages = () =>
+	call(MessageBulkOperations.MessageBulkOperations_moveMessages, {
+		params: {},
+		requestBody: { messageIds: ["msg-1"], destinationMailboxId: TARGET },
+	});
+
+const copyMessages = () =>
+	call(MessageBulkOperations.MessageBulkOperations_copyMessages, {
+		params: {},
+		requestBody: { messageIds: ["msg-1"], destinationMailboxId: TARGET },
+	});
+
+const unready = (error: unknown): boolean =>
+	(error as { statusCode?: number }).statusCode === 422 &&
+	(error as { publicApiError?: { code?: string } }).publicApiError?.code ===
+		"mailbox_not_settled";
+
+const SITES = [
+	["appointing a role", appoint, (w: Writes) => w.appointments],
+	["creating a filter", createFilter, (w: Writes) => w.filters],
+	["updating a filter", updateFilter, (w: Writes) => w.filterPatches],
+	["moving messages", moveMessages, (w: Writes) => w.moves],
+	["copying messages", copyMessages, (w: Writes) => w.copies],
+] as const;
+
+describe("a write that binds to a folder requires a settled folder", () => {
+	afterEach(() => {
+		_resetForTest();
+	});
+
+	for (const [what, run, written] of SITES) {
+		for (const state of [
+			MailboxSyncStatus.pending,
+			MailboxSyncStatus.deleting,
+			MailboxSyncStatus.failed,
+		]) {
+			it(`refuses ${what} against a ${state} folder, writing nothing`, async () => {
+				const writes = world(state);
+
+				await assert.rejects(run(), unready);
+				assert.deepEqual(written(writes), []);
+			});
+		}
+
+		it(`accepts ${what} against a settled folder`, async () => {
+			const writes = world(MailboxSyncStatus.synced);
+
+			await run();
+			assert.equal(written(writes).length > 0, true);
+		});
+	}
+
+	it("never answers 409 from these paths", async () => {
+		// 409 belongs to the folder's own mutation losing a compare-and-set
+		// (#362, #363). Reusing it here would make "somebody else is changing this
+		// folder" and "the folder you are pointing at is not ready" the same
+		// answer, with different copy and different remedies behind it.
+		world(MailboxSyncStatus.pending);
+
+		await assert.rejects(
+			appoint(),
+			(error: unknown) => (error as { statusCode?: number }).statusCode !== 409,
+		);
+	});
+
+	it("does not gate clearing a role whose folder is on its way out", async () => {
+		const writes = world(MailboxSyncStatus.deleting);
+
+		await call(FolderRoleOperations.FolderRoleOperations_appointFolderRole, {
+			params: { accountId: ACCOUNT_ID, role: CanonicalMailboxRole.Archive },
+			requestBody: { mailboxId: null },
+		});
+
+		assert.deepEqual(
+			writes.appointments,
+			[],
+			"the row is deleted, not upserted",
+		);
+	});
+
+	it("does not gate a filter that applies no move action", async () => {
+		// `None` is the sentinel for "no move action", so it binds to nothing.
+		const writes = world(MailboxSyncStatus.deleting);
+
+		await call(FilterOperations.FilterOperations_createFilter, {
+			params: { accountId: ACCOUNT_ID },
+			requestBody: {
+				name: "Just a label",
+				scope: "Standing",
+				actionMailboxId: "None",
+			},
+		});
+
+		assert.equal(writes.filters.length, 1);
+	});
+});

package/src/handlers/mailbox.test.ts

@@ -11,36 +11,7 @@ import {
 	type RemitClient,
 	setClient,
 } from "../service/data-client.js";
-import { excludeDeletingMailboxes, TrashOperations } from "./mailbox.js";
-
-const mailbox = (
-	over: Partial<MailboxItem> & { mailboxId: string },
-): MailboxItem =>
-	({ fullPath: over.mailboxId, ...over }) as unknown as MailboxItem;
-
-describe("excludeDeletingMailboxes", () => {
-	it("drops a folder being deleted so it leaves the list before the worker reaps it", () => {
-		const items = [
-			mailbox({ mailboxId: "inbox", syncStatus: MailboxSyncStatus.synced }),
-			mailbox({ mailboxId: "gone", syncStatus: MailboxSyncStatus.deleting }),
-			mailbox({ mailboxId: "new", syncStatus: MailboxSyncStatus.pending }),
-		];
-		assert.deepEqual(
-			excludeDeletingMailboxes(items).map((m) => m.mailboxId),
-			["inbox", "new"],
-		);
-	});
-
-	it("keeps a folder whose delete failed and was restored off `deleting`", () => {
-		const items = [
-			mailbox({ mailboxId: "restored", syncStatus: MailboxSyncStatus.failed }),
-		];
-		assert.deepEqual(
-			excludeDeletingMailboxes(items).map((m) => m.mailboxId),
-			["restored"],
-		);
-	});
-});
+import { MailboxDetailOperations, TrashOperations } from "./mailbox.js";
 
 const SUB = "cognito-sub-887";
 const ACCOUNT_ID = "acc-887";
@@ -96,3 +67,166 @@ describe("TrashOperations_emptyTrash", () => {
 		);
 	});
 });
+
+const deleteMailbox =
+	MailboxDetailOperations.MailboxDetailOperations_deleteMailbox as unknown as (
+		context: Context,
+		event: APIGatewayProxyEvent,
+	) => Promise<{ statusCode: number }>;
+
+const folder = (over: Partial<MailboxItem> = {}): MailboxItem =>
+	({
+		mailboxId: "mbx-1",
+		accountId: ACCOUNT_ID,
+		fullPath: "Receipts",
+		hierarchyDelimiter: "/",
+		syncStatus: MailboxSyncStatus.synced,
+		...over,
+	}) as MailboxItem;
+
+interface DeleteWorld {
+	mailbox?: MailboxItem;
+	children?: MailboxItem[];
+	filters?: { name: string; actionMailboxId: string }[];
+	appointments?: Record<string, string>;
+}
+
+const callDelete = (
+	world: DeleteWorld,
+): { run: () => Promise<{ statusCode: number }>; deleted: string[] } => {
+	const deleted: string[] = [];
+	setClient({
+		account: {
+			get: async () => ({
+				accountId: ACCOUNT_ID,
+				accountConfigId: deriveAccountConfigId(SUB),
+			}),
+		},
+		mailbox: {
+			get: async () => world.mailbox ?? folder(),
+			findByPathPrefix: async () => world.children ?? [],
+		},
+		filter: {
+			listByAccountConfig: async () => world.filters ?? [],
+		},
+		accountSetting: {
+			get: async (_configId: string, name: string) => {
+				for (const [role, mailboxId] of Object.entries(
+					world.appointments ?? {},
+				)) {
+					if (name === `FolderRoleAppointment#${ACCOUNT_ID}#${role}`) {
+						return { value: { kind: "String", value: mailboxId } };
+					}
+				}
+				return null;
+			},
+		},
+		mailboxQueue: {
+			deleteMailbox: async (mailboxId: string) => {
+				deleted.push(mailboxId);
+			},
+		},
+	} as unknown as RemitClient);
+
+	return {
+		deleted,
+		run: () =>
+			deleteMailbox(
+				{
+					request: { params: { accountId: ACCOUNT_ID, mailboxId: "mbx-1" } },
+				} as unknown as Context,
+				{
+					requestContext: { authorizer: { claims: { sub: SUB } } },
+				} as unknown as APIGatewayProxyEvent,
+			),
+	};
+};
+
+const refusal = (match: RegExp) => (error: unknown) =>
+	(error as { statusCode?: number }).statusCode === 400 &&
+	match.test((error as Error).message);
+
+describe("MailboxDetailOperations_deleteMailbox — what it refuses (D4, D16)", () => {
+	afterEach(() => {
+		_resetForTest();
+	});
+
+	it("refuses the inbox", async () => {
+		const { run, deleted } = callDelete({
+			mailbox: folder({ fullPath: "INBOX" }),
+		});
+
+		await assert.rejects(run(), refusal(/inbox can't be deleted/));
+		assert.deepEqual(deleted, []);
+	});
+
+	it("refuses a folder that has folders inside it", async () => {
+		// The server would keep the parent's name as a placeholder and leave the
+		// children untouched — an outcome no local row describes.
+		const { run, deleted } = callDelete({
+			children: [folder({ mailboxId: "mbx-2", fullPath: "Receipts/2026" })],
+		});
+
+		await assert.rejects(run(), refusal(/has folders inside it/));
+		assert.deepEqual(deleted, []);
+	});
+
+	/**
+	 * D16. Refusing is what makes the settled-target rule total: a binding is
+	 * only created against a settled folder and only removed by the user, so a
+	 * mailboxId that names nothing never exists and no reader needs a
+	 * missing-target branch.
+	 */
+	it("refuses a folder a filter moves mail into, naming the filter", async () => {
+		const { run, deleted } = callDelete({
+			filters: [{ name: "Invoices → Receipts", actionMailboxId: "mbx-1" }],
+		});
+
+		await assert.rejects(run(), refusal(/the filter “Invoices → Receipts”/));
+		assert.deepEqual(deleted, []);
+	});
+
+	it("refuses a folder appointed to a role, naming the role", async () => {
+		const { run, deleted } = callDelete({ appointments: { Archive: "mbx-1" } });
+
+		await assert.rejects(run(), refusal(/the Archive role/));
+		assert.deepEqual(deleted, []);
+	});
+
+	it("names both when both are bound", async () => {
+		const { run } = callDelete({
+			filters: [{ name: "Invoices", actionMailboxId: "mbx-1" }],
+			appointments: { Archive: "mbx-1" },
+		});
+
+		await assert.rejects(
+			run(),
+			refusal(/the filter “Invoices” and the Archive role/),
+		);
+	});
+
+	it("ignores a filter that moves mail into a different folder", async () => {
+		const { run, deleted } = callDelete({
+			filters: [{ name: "Elsewhere", actionMailboxId: "mbx-9" }],
+		});
+
+		assert.deepEqual(await run(), { statusCode: 204 });
+		assert.deepEqual(deleted, ["mbx-1"]);
+	});
+
+	it("ignores a filter with no move action at all", async () => {
+		const { run, deleted } = callDelete({
+			filters: [{ name: "Just a label", actionMailboxId: "None" }],
+		});
+
+		assert.deepEqual(await run(), { statusCode: 204 });
+		assert.deepEqual(deleted, ["mbx-1"]);
+	});
+
+	it("records the intent for an ordinary folder", async () => {
+		const { run, deleted } = callDelete({});
+
+		assert.deepEqual(await run(), { statusCode: 204 });
+		assert.deepEqual(deleted, ["mbx-1"]);
+	});
+});