@remit/backend 0.0.119 → 0.0.121

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/backend",
-  "version": "0.0.119",
+  "version": "0.0.121",
   "description": "Remit Mail Inspector API backend",
   "license": "MIT",
   "author": "",
@@ -23,6 +23,10 @@
       "types": "./src/handlers/folder-role-appointments.ts",
       "default": "./src/handlers/folder-role-appointments.ts"
     },
+    "./folder-role-labels": {
+      "types": "./src/handlers/folder-role-labels.ts",
+      "default": "./src/handlers/folder-role-labels.ts"
+    },
     "./organize": {
       "types": "./src/service/organize.ts",
       "default": "./src/service/organize.ts"

package/src/handlers/filter.ts

@@ -5,8 +5,10 @@ import type {
 } from "@remit/api-openapi-types";
 import {
 	deriveFilterTtl,
+	FILTER_NO_ACTION,
 	type FilterItem,
 	type IFilterAnchorTransaction,
+	type IMailboxRepository,
 	type UpdateFilterInput,
 } from "@remit/data-ports";
 import { BadRequestError } from "@remit/data-ports/errors";
@@ -22,6 +24,7 @@ import type {
 	OperationHandler,
 } from "../types.js";
 import { assertAccountOwnership } from "./account-ownership.js";
+import { assertMailboxInAccount, assertMailboxSettled } from "./mailbox.js";
 
 /**
  * Minimal filter-service surface the create handler needs — declared as a
@@ -222,6 +225,25 @@ export const createFilterWithAnchor = async (
 	);
 };
 
+/**
+ * A filter's `actionMailboxId` is a durable reference, so its target has to be
+ * a folder the mail server has settled (D12, first row) — 422 otherwise. The
+ * sentinel means "no move action" and binds to nothing, so it is not gated,
+ * and neither is a filter that touches the field at all.
+ */
+const assertActionMailboxSettled = async (
+	client: { mailbox: Pick<IMailboxRepository, "get"> },
+	accountId: string,
+	actionMailboxId: string | undefined,
+): Promise<void> => {
+	if (actionMailboxId === undefined || actionMailboxId === FILTER_NO_ACTION) {
+		return;
+	}
+	const target = await client.mailbox.get(accountId, actionMailboxId);
+	assertMailboxInAccount(target, accountId, "act");
+	assertMailboxSettled(target);
+};
+
 export const FilterOperations: Record<
 	FilterOperationIds,
 	OperationHandler<FilterOperationIds>
@@ -265,6 +287,7 @@ export const FilterOperations: Record<
 		const client = await getClient();
 		const account = await client.account.get(accountId);
 		assertAccountOwnership(account, accountConfigId, "act");
+		await assertActionMailboxSettled(client, accountId, input.actionMailboxId);
 
 		const filter = await createFilterWithAnchor(
 			{
@@ -316,6 +339,7 @@ export const FilterDetailOperations: Record<
 
 		const { filter } = client;
 		const patch = pickFilterUpdate(body as Partial<UpdateFilterRequestBody>);
+		await assertActionMailboxSettled(client, accountId, patch.actionMailboxId);
 		const touchesScopeOrExpiry =
 			Object.hasOwn(patch, "scope") || Object.hasOwn(patch, "expiresAt");
 		const resolvedPatch: Partial<UpdateFilterInput> = touchesScopeOrExpiry

package/src/handlers/folder-role-labels.ts

@@ -0,0 +1,63 @@
+import type { IAccountSettingRepository } from "@remit/data-ports";
+import {
+	type CanonicalMailboxRoleValue,
+	composeFolderRoleAppointmentLabelName,
+} from "@remit/data-ports/folder-role";
+import { rebaseMailboxPath } from "@remit/data-ports/mailbox-name";
+import { loadFolderAppointmentsForAccount } from "./folder-role-appointments.js";
+
+/**
+ * The label row beside each role appointment records the path its folder had at
+ * the time (#887), so a folder another client later deletes can still be named
+ * back to the user. It is display only, and it lives here rather than beside
+ * the appointment writer because that writer is guarded as the only writer of
+ * the appointment row itself.
+ *
+ * A rename keeps every mailboxId, so an appointment survives it — but the path
+ * recorded beside it still names where the folder was. Move the labels with the
+ * branch, or a later third-party delete names a path the user has not seen
+ * since the rename.
+ *
+ * Driven by the settle, not by the intent: under D2 the row keeps the path the
+ * mail server holds until the rename lands, so a label moved when the intent
+ * was recorded would name a path that does not exist — permanently, if the
+ * rename then fails.
+ *
+ * The renamed folder is matched by id; its descendants are matched by the path
+ * each label already holds.
+ */
+export const refreshFolderAppointmentLabels = async (
+	accountSetting: Pick<IAccountSettingRepository, "get" | "upsert">,
+	accountConfigId: string,
+	accountId: string,
+	renamed: { mailboxId: string; oldPath: string; newPath: string },
+	delimiter: string,
+): Promise<void> => {
+	const persisted = await loadFolderAppointmentsForAccount(
+		accountSetting,
+		accountConfigId,
+		accountId,
+	);
+	for (const [role, appointment] of persisted) {
+		const moved =
+			appointment.mailboxId === renamed.mailboxId
+				? renamed.newPath
+				: appointment.lastKnownPath === undefined
+					? undefined
+					: rebaseMailboxPath(
+							appointment.lastKnownPath,
+							renamed.oldPath,
+							renamed.newPath,
+							delimiter,
+						);
+		if (moved === undefined || moved === appointment.lastKnownPath) continue;
+		await accountSetting.upsert({
+			accountConfigId,
+			name: composeFolderRoleAppointmentLabelName(
+				accountId,
+				role as CanonicalMailboxRoleValue,
+			),
+			value: { kind: "String", value: moved },
+		});
+	}
+};

package/src/handlers/folder-role.test.ts

@@ -4,8 +4,8 @@ import type { AccountSettingItem, MailboxItem } from "@remit/data-ports";
 import { isPublicApiError } from "@remit/data-ports/errors";
 import { composeFolderRoleAppointmentLabelName } from "@remit/data-ports/folder-role";
 import { CanonicalMailboxRole, MailboxSyncStatus } from "@remit/domain-enums";
-import { assertMailboxSettled } from "./folder-role.js";
-import { applyMailboxPatch, type MailboxPatchClient } from "./mailbox.js";
+import { refreshFolderAppointmentLabels } from "./folder-role-labels.js";
+import { assertMailboxSettled } from "./mailbox.js";
 
 const mailbox = (over: Partial<MailboxItem>): MailboxItem =>
 	({
@@ -57,18 +57,45 @@ describe("assertMailboxSettled", () => {
 		});
 	});
 
-	it("allows a settled folder, and one whose delete failed", () => {
-		assert.doesNotThrow(() =>
-			assertMailboxSettled(mailbox({ syncStatus: MailboxSyncStatus.synced })),
+	it("refuses a folder whose last change failed", () => {
+		// `failed` means the folder exists at `fullPath` and the last rename or
+		// delete did not land, so it is exactly as unready to be bound to as a
+		// folder mid-mutation — and the user has a retry or a dismissal to make
+		// before anything should point at it.
+		const error = caught(() =>
+			assertMailboxSettled(mailbox({ syncStatus: MailboxSyncStatus.failed })),
 		);
+		assert.equal(publicErrorOf(error)?.code, "mailbox_not_settled");
+	});
+
+	it("answers 422, not 409", () => {
+		// 409 already means "this folder is being changed right now, refresh".
+		// This means "the folder you are pointing at has not settled yet", which
+		// is different copy and a different remedy (D4).
+		const error = caught(() =>
+			assertMailboxSettled(mailbox({ syncStatus: MailboxSyncStatus.pending })),
+		);
+		assert.equal((error as { statusCode?: number }).statusCode, 422);
+	});
+
+	it("words each state differently, because each has its own remedy", () => {
+		const messageFor = (syncStatus: MailboxItem["syncStatus"]) =>
+			(caught(() => assertMailboxSettled(mailbox({ syncStatus }))) as Error)
+				.message;
+
+		assert.match(messageFor(MailboxSyncStatus.pending), /hasn.t confirmed it/);
+		assert.match(messageFor(MailboxSyncStatus.deleting), /being deleted/);
+		assert.match(messageFor(MailboxSyncStatus.failed), /Retry or dismiss/);
+	});
+
+	it("allows a settled folder", () => {
 		assert.doesNotThrow(() =>
-			assertMailboxSettled(mailbox({ syncStatus: MailboxSyncStatus.failed })),
+			assertMailboxSettled(mailbox({ syncStatus: MailboxSyncStatus.synced })),
 		);
-		assert.doesNotThrow(() => assertMailboxSettled(mailbox({})));
 	});
 });
 
-describe("applyMailboxPatch — the appointment label follows a rename", () => {
+describe("refreshFolderAppointmentLabels — the label follows a settled rename", () => {
 	const labelName = composeFolderRoleAppointmentLabelName(
 		"acc-1",
 		CanonicalMailboxRole.Trash,
@@ -82,68 +109,68 @@ describe("applyMailboxPatch — the appointment label follows a rename", () => {
 
 	const settingsFor = (
 		rows: Record<string, string>,
-		renamed = "INBOX",
-	): { store: Record<string, string>; client: MailboxPatchClient } => {
+	): {
+		store: Record<string, string>;
+		accountSetting: Parameters<typeof refreshFolderAppointmentLabels>[0];
+	} => {
 		const store: Record<string, string> = { ...rows };
-		const client = {
-			mailbox: {
-				get: async () => mailbox({ fullPath: renamed }),
+		const accountSetting = {
+			get: async (_configId: string, name: string) =>
+				store[name] === undefined
+					? undefined
+					: ({
+							name,
+							value: { kind: "String", value: store[name] },
+						} as AccountSettingItem),
+			upsert: async (item: AccountSettingItem) => {
+				if (item.value.kind === "String") store[item.name] = item.value.value;
+				return item;
 			},
-			mailboxQueue: {
-				renameMailbox: async (mailboxId: string, newPath: string) =>
-					mailbox({ mailboxId, fullPath: newPath }),
-			},
-			accountSetting: {
-				get: async (_configId: string, name: string) =>
-					store[name] === undefined
-						? undefined
-						: ({
-								name,
-								value: { kind: "String", value: store[name] },
-							} as AccountSettingItem),
-				upsert: async (item: AccountSettingItem) => {
-					if (item.value.kind === "String") store[item.name] = item.value.value;
-					return item;
-				},
-				delete: async (_configId: string, name: string) => {
-					delete store[name];
-				},
-			},
-		} as unknown as MailboxPatchClient;
-		return { store, client };
+		} as unknown as Parameters<typeof refreshFolderAppointmentLabels>[0];
+		return { store, accountSetting };
 	};
 
-	it("rewrites the recorded path for the folder that was renamed", async () => {
-		const { store, client } = settingsFor(
-			{
-				[appointmentName(CanonicalMailboxRole.Trash)]: "mb-1",
-				[labelName]: "INBOX/Prullenbak",
-			},
-			"INBOX/Prullenbak",
+	const settle = (
+		accountSetting: Parameters<typeof refreshFolderAppointmentLabels>[0],
+		renamed: { mailboxId: string; oldPath: string; newPath: string },
+	) =>
+		refreshFolderAppointmentLabels(
+			accountSetting,
+			"cfg-1",
+			"acc-1",
+			renamed,
+			"/",
 		);
 
-		await applyMailboxPatch(client, "cfg-1", "mb-1", "acc-1", {
-			fullPath: "INBOX/Verwijderd",
+	it("rewrites the recorded path for the folder that was renamed", async () => {
+		const { store, accountSetting } = settingsFor({
+			[appointmentName(CanonicalMailboxRole.Trash)]: "mb-1",
+			[labelName]: "INBOX/Prullenbak",
+		});
+
+		await settle(accountSetting, {
+			mailboxId: "mb-1",
+			oldPath: "INBOX/Prullenbak",
+			newPath: "INBOX/Verwijderd",
 		});
 
 		assert.equal(store[labelName], "INBOX/Verwijderd");
 	});
 
-	// IMAP RENAME moves the subtree in one command and `renameChildPaths`
-	// rewrites every descendant row, so every label under the branch moves too.
+	// IMAP RENAME moves the subtree in one command, so every label under the
+	// branch moves with it.
 	it("carries every appointed folder under the renamed branch with it", async () => {
-		const { store, client } = settingsFor(
-			{
-				[appointmentName(CanonicalMailboxRole.Trash)]: "mb-trash",
-				[labelName]: "INBOX/Prullenbak",
-				[appointmentName(CanonicalMailboxRole.Sent)]: "mb-sent",
-				[sentLabelName]: "INBOX/Verzonden",
-			},
-			"INBOX",
-		);
+		const { store, accountSetting } = settingsFor({
+			[appointmentName(CanonicalMailboxRole.Trash)]: "mb-trash",
+			[labelName]: "INBOX/Prullenbak",
+			[appointmentName(CanonicalMailboxRole.Sent)]: "mb-sent",
+			[sentLabelName]: "INBOX/Verzonden",
+		});
 
-		await applyMailboxPatch(client, "cfg-1", "mb-1", "acc-1", {
-			fullPath: "Mail",
+		await settle(accountSetting, {
+			mailboxId: "mb-1",
+			oldPath: "INBOX",
+			newPath: "Mail",
 		});
 
 		assert.equal(store[labelName], "Mail/Prullenbak");
@@ -151,32 +178,30 @@ describe("applyMailboxPatch — the appointment label follows a rename", () => {
 	});
 
 	it("leaves a folder outside the renamed branch alone", async () => {
-		const { store, client } = settingsFor(
-			{
-				[appointmentName(CanonicalMailboxRole.Trash)]: "mb-trash",
-				[labelName]: "Archief/Prullenbak",
-			},
-			"INBOX",
-		);
+		const { store, accountSetting } = settingsFor({
+			[appointmentName(CanonicalMailboxRole.Trash)]: "mb-trash",
+			[labelName]: "Archief/Prullenbak",
+		});
 
-		await applyMailboxPatch(client, "cfg-1", "mb-1", "acc-1", {
-			fullPath: "Mail",
+		await settle(accountSetting, {
+			mailboxId: "mb-1",
+			oldPath: "INBOX",
+			newPath: "Mail",
 		});
 
 		assert.equal(store[labelName], "Archief/Prullenbak");
 	});
 
 	it("never rebases a sibling that merely shares the prefix", async () => {
-		const { store, client } = settingsFor(
-			{
-				[appointmentName(CanonicalMailboxRole.Trash)]: "mb-trash",
-				[labelName]: "INBOXES/Prullenbak",
-			},
-			"INBOX",
-		);
+		const { store, accountSetting } = settingsFor({
+			[appointmentName(CanonicalMailboxRole.Trash)]: "mb-trash",
+			[labelName]: "INBOXES/Prullenbak",
+		});
 
-		await applyMailboxPatch(client, "cfg-1", "mb-1", "acc-1", {
-			fullPath: "Mail",
+		await settle(accountSetting, {
+			mailboxId: "mb-1",
+			oldPath: "INBOX",
+			newPath: "Mail",
 		});
 
 		assert.equal(store[labelName], "INBOXES/Prullenbak");

package/src/handlers/folder-role.ts

@@ -2,9 +2,6 @@ import type {
 	AppointFolderRoleInput,
 	CanonicalMailboxRole,
 } from "@remit/api-openapi-types";
-import type { MailboxItem } from "@remit/data-ports";
-import { MailboxNotSettledError } from "@remit/data-ports/errors";
-import { MailboxSyncStatus } from "@remit/domain-enums";
 import type { APIGatewayProxyEvent } from "aws-lambda";
 import { getAccountConfigIdFromEvent } from "../auth.js";
 import { getClient } from "../service/data-client.js";
@@ -17,31 +14,7 @@ import {
 	resolveAccountFolderAppointments,
 	writeFolderRoleAppointment,
 } from "./folder-role-appointments.js";
-import { assertMailboxInAccount } from "./mailbox.js";
-
-/** Mailbox states in which the mail server has not settled the folder yet. */
-const UNSETTLED: ReadonlySet<string> = new Set([
-	MailboxSyncStatus.pending,
-	MailboxSyncStatus.deleting,
-]);
-
-/**
- * Appointing a role to a folder the mail server is still creating or deleting
- * would bind the account's Trash to a folder that may never exist (D16 item 3,
- * imap-mutations R2: wait). A `\Noselect` container is refused by construction
- * — mailbox-sync keeps no row for one — so there is nothing to appoint.
- */
-export const assertMailboxSettled = (
-	target: Pick<MailboxItem, "mailboxId" | "fullPath" | "syncStatus">,
-): void => {
-	const syncStatus = target.syncStatus;
-	if (!syncStatus || !UNSETTLED.has(syncStatus)) return;
-	throw new MailboxNotSettledError(
-		`Mailbox ${target.fullPath} is not settled on the mail server yet`,
-		target.mailboxId,
-		syncStatus,
-	);
-};
+import { assertMailboxInAccount, assertMailboxSettled } from "./mailbox.js";
 
 /**
  * RFC 032 exclusive-folder-appointment (#976): the single write operation for

package/src/handlers/mailbox-bindings.ts

@@ -0,0 +1,111 @@
+import type {
+	FilterItem,
+	IAccountSettingRepository,
+	IFilterRepository,
+	MailboxItem,
+} from "@remit/data-ports";
+import { FILTER_NO_ACTION } from "@remit/data-ports";
+import { BadRequestError } from "@remit/data-ports/errors";
+import type { CanonicalMailboxRoleValue } from "@remit/data-ports/folder-role";
+import { loadFolderAppointmentsForAccount } from "./folder-role-appointments.js";
+
+/**
+ * What a folder is bound to: the filters that move mail into it, and the
+ * canonical roles it has been appointed to.
+ */
+export interface MailboxBindings {
+	filterNames: string[];
+	roles: CanonicalMailboxRoleValue[];
+}
+
+/**
+ * `filter.actionMailboxId` has no reverse index, so the filters are listed for
+ * the account config and matched — they are few and per-config, so this is not
+ * a mailbox scan. Role appointments are `account_setting` rows whose *value* is
+ * a mailboxId, which a `mailbox_id` column scan cannot find, so the existing
+ * per-account appointment map answers for them.
+ */
+export const loadMailboxBindings = async (
+	client: {
+		filter: Pick<IFilterRepository, "listByAccountConfig">;
+		accountSetting: Pick<IAccountSettingRepository, "get">;
+	},
+	accountConfigId: string,
+	accountId: string,
+	mailboxId: string,
+): Promise<MailboxBindings> => {
+	const [filters, appointments] = await Promise.all([
+		client.filter.listByAccountConfig(accountConfigId),
+		loadFolderAppointmentsForAccount(
+			client.accountSetting,
+			accountConfigId,
+			accountId,
+		),
+	]);
+
+	const filterNames = filters
+		.filter(
+			(filter: FilterItem) =>
+				filter.actionMailboxId !== FILTER_NO_ACTION &&
+				filter.actionMailboxId === mailboxId,
+		)
+		.map((filter: FilterItem) => filter.name);
+
+	const roles: CanonicalMailboxRoleValue[] = [];
+	for (const [role, appointment] of appointments) {
+		if (appointment.mailboxId === mailboxId) {
+			roles.push(role as CanonicalMailboxRoleValue);
+		}
+	}
+
+	return { filterNames, roles };
+};
+
+const asList = (items: readonly string[]): string =>
+	items.length === 1
+		? items[0]
+		: `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+
+/**
+ * Refuse a delete while any durable reference is bound to the folder (D16).
+ *
+ * This 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 of a filter's `actionMailboxId` or a
+ * role appointment needs a missing-target branch. It removes code rather than
+ * adding a check.
+ *
+ * The alternatives both cost more than they look. `Filter` has no enabled flag
+ * and its `actionMailboxId` sentinel means "no move action", so clearing the
+ * target silently turns a move-filter into one that does something else;
+ * deleting the user's filters outright is not a decision a folder delete gets
+ * to make.
+ *
+ * The message **names** each binding rather than counting them, because a count
+ * is not actionable — and this fires on ordinary configurations, since pointing
+ * a filter at a folder is what filters are for.
+ */
+export const assertNoBindings = (
+	mailbox: Pick<MailboxItem, "fullPath">,
+	bindings: MailboxBindings,
+): void => {
+	const clauses: string[] = [];
+	if (bindings.filterNames.length > 0) {
+		clauses.push(
+			`the ${bindings.filterNames.length === 1 ? "filter" : "filters"} ${asList(
+				bindings.filterNames.map((name) => `“${name}”`),
+			)}`,
+		);
+	}
+	if (bindings.roles.length > 0) {
+		clauses.push(
+			`the ${asList(bindings.roles)} ${
+				bindings.roles.length === 1 ? "role" : "roles"
+			}`,
+		);
+	}
+	if (clauses.length === 0) return;
+	throw new BadRequestError(
+		`“${mailbox.fullPath}” is used by ${asList(clauses)}.`,
+	);
+};