@remit/backend 0.0.120 → 0.0.122

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/backend",
-  "version": "0.0.120",
+  "version": "0.0.122",
   "description": "Remit Mail Inspector API backend",
   "license": "MIT",
   "author": "",

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.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 { refreshFolderAppointmentLabels } from "./folder-role-labels.js";
+import { assertMailboxSettled } from "./mailbox.js";
 
 const mailbox = (over: Partial<MailboxItem>): MailboxItem =>
 	({
@@ -57,14 +57,41 @@ 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({})));
 	});
 });
 

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)}.`,
+	);
+};

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"]);
+	});
+});

package/src/handlers/mailbox.ts

@@ -6,6 +6,7 @@ import type { IAccountSettingRepository, MailboxItem } from "@remit/data-ports";
 import {
 	BadRequestError,
 	ForbiddenError,
+	MailboxNotSettledError,
 	NotFoundError,
 } from "@remit/data-ports/errors";
 import { isReservedFolderName } from "@remit/data-ports/folder-role";
@@ -31,6 +32,7 @@ import {
 	type MailboxOverrides,
 } from "./account-overrides.js";
 import { assertAccountOwnership } from "./account-ownership.js";
+import { assertNoBindings, loadMailboxBindings } from "./mailbox-bindings.js";
 
 /**
  * The mute flag and the display-name override are user preferences that live
@@ -227,6 +229,51 @@ export const assertMailboxInAccount = (
 	throw new ForbiddenError(`Mailbox ${mailbox.mailboxId} not in account`);
 };
 
+/**
+ * Why a folder cannot be bound to yet, per state — one wording in one place,
+ * because the remedy differs and the client has only the sentence to show.
+ */
+const UNSETTLED_REASON: Record<string, (path: string) => string> = {
+	[MailboxSyncStatus.pending]: (path) =>
+		`“${path}” isn’t ready yet — the mail server hasn’t confirmed it.`,
+	[MailboxSyncStatus.deleting]: (path) => `“${path}” is being deleted.`,
+	[MailboxSyncStatus.failed]: (path) =>
+		`The last change to “${path}” failed. Retry or dismiss it first.`,
+};
+
+/**
+ * Every API write that binds a durable reference to a mailbox requires that
+ * mailbox to be `synced` (D12, first row; imap-mutations R2: wait). A dangling
+ * reference is permanent; blocking costs seconds.
+ *
+ * This is the server-side floor under the client-side wait, and it is not
+ * redundant with it: there is more than one client, and a script hitting the
+ * API directly gets no wait at all.
+ *
+ * It is the other half of D16. A binding is only ever created against a settled
+ * folder (here) and only ever removed by the user (the delete refusal below),
+ * so a `mailboxId` that names nothing never exists — which is what lets every
+ * reader of a filter's `actionMailboxId` or a role appointment treat the
+ * reference as resolvable, with no missing-target branch.
+ *
+ * A `\Noselect` container is refused by construction — mailbox-sync keeps no
+ * row for one — so there is nothing to bind to. Clearing a reference is not a
+ * bind and is never gated, and neither is a move *out of* a folder: a
+ * `deleting` folder still holds its mail until the DELETE lands, which is the
+ * delete-with-move flow (D13).
+ */
+export const assertMailboxSettled = (
+	target: Pick<MailboxItem, "mailboxId" | "fullPath" | "syncStatus">,
+): void => {
+	const reason = UNSETTLED_REASON[target.syncStatus];
+	if (!reason) return;
+	throw new MailboxNotSettledError(
+		reason(target.fullPath),
+		target.mailboxId,
+		target.syncStatus,
+	);
+};
+
 /**
  * Every pending placement move (issue #1271) for an account, on whichever
  * backend is active (`RemitClient.placementMove` is present on both — see
@@ -286,24 +333,6 @@ const toMailboxResponse = (
 	updatedAt: mailbox.updatedAt,
 });
 
-/**
- * Drop folders the user has deleted but the imap-worker has not yet reaped.
- *
- * A delete is a soft delete: the row lives on with syncStatus=deleting until the
- * worker confirms the IMAP delete and removes it (mailbox-queue.deleteMailbox).
- * The list is the settings view a client refetches right after confirming, so a
- * still-`deleting` row here would keep a deleted folder on screen until the
- * worker finishes. Hiding it makes the folder leave the list the moment the
- * delete is confirmed; a delete that fails restores the row off `deleting`,
- * which brings the folder back on the next read.
- */
-export const excludeDeletingMailboxes = (
-	mailboxes: readonly MailboxItem[],
-): MailboxItem[] =>
-	mailboxes.filter(
-		(mailbox) => mailbox.syncStatus !== MailboxSyncStatus.deleting,
-	);
-
 export const MailboxOperations: Record<
 	MailboxOperationIds,
 	OperationHandler<MailboxOperationIds>
@@ -324,8 +353,6 @@ export const MailboxOperations: Record<
 			continuationToken,
 		});
 
-		const visibleItems = excludeDeletingMailboxes(result.items);
-
 		// Overrides (mute / display-name / role) live in per-mailbox AccountSetting
 		// rows (RFC 032). Load the whole config's set in one query and key it by
 		// mailboxId so each mailbox surfaces its overrides without an N+1.
@@ -342,8 +369,11 @@ export const MailboxOperations: Record<
 			client,
 			accountId,
 		);
+		// A folder mid-mutation is listed, labelled (D11). Hiding a `deleting` one
+		// made a delete that does not settle look like a folder that silently
+		// vanished, while the server still held it.
 		const items = applyPendingMoveCountPrediction(
-			visibleItems,
+			result.items,
 			pendingMoves,
 			pendingUnseenFlagPushes,
 		);
@@ -492,6 +522,31 @@ export const MailboxDetailOperations: Record<
 		const mailbox = await client.mailbox.get(accountId, mailboxId);
 		assertMailboxInAccount(mailbox, accountId, "act");
 
+		// Cheapest first (D4, D13). None of the three becomes possible by
+		// retrying the same request, so all three are 400 and all three run
+		// before anything is recorded.
+		if (mailbox.fullPath.toUpperCase() === "INBOX") {
+			throw new BadRequestError("The inbox can't be deleted.");
+		}
+
+		const children = await client.mailbox.findByPathPrefix(
+			accountId,
+			mailbox.fullPath,
+			mailbox.hierarchyDelimiter,
+		);
+		if (children.length > 0) {
+			// The server would keep the parent's name as a placeholder and leave the
+			// children untouched — an outcome no local row describes (D9).
+			throw new BadRequestError(
+				`“${mailbox.fullPath}” has folders inside it. Delete those first.`,
+			);
+		}
+
+		assertNoBindings(
+			mailbox,
+			await loadMailboxBindings(client, accountConfigId, accountId, mailboxId),
+		);
+
 		await client.mailboxQueue.deleteMailbox(mailboxId, accountId);
 		return { statusCode: 204 };
 	},

package/src/handlers/message.ts

@@ -50,6 +50,7 @@ import type {
 	MessageOperationIds,
 	OperationHandler,
 } from "../types.js";
+import { assertMailboxSettled } from "./mailbox.js";
 
 type StarColorValue = (typeof StarColor)[keyof typeof StarColor];
 
@@ -939,7 +940,10 @@ export const MessageBulkOperations: Record<
 			"act",
 		);
 
-		// Destination must belong to the same (caller-owned) account.
+		// Destination must belong to the same (caller-owned) account, and must be
+		// a folder the mail server has settled: the row records the destination
+		// before the move confirms, so binding to a folder that may never exist
+		// leaves the message pointing at nothing (D12, first row).
 		const destination = await client.mailbox.get(
 			accountId,
 			destinationMailboxId,
@@ -949,6 +953,7 @@ export const MessageBulkOperations: Record<
 				`Destination mailbox ${destinationMailboxId} not in account`,
 			);
 		}
+		assertMailboxSettled(destination);
 
 		// MessageMoveService handles: Message + ThreadMessage updates + SQS events
 		await client.messageMove.moveMessages(
@@ -985,7 +990,10 @@ export const MessageBulkOperations: Record<
 			"act",
 		);
 
-		// Destination must belong to the same (caller-owned) account.
+		// Destination must belong to the same (caller-owned) account, and must be
+		// a folder the mail server has settled: the row records the destination
+		// before the move confirms, so binding to a folder that may never exist
+		// leaves the message pointing at nothing (D12, first row).
 		const destination = await client.mailbox.get(
 			accountId,
 			destinationMailboxId,
@@ -995,6 +1003,7 @@ export const MessageBulkOperations: Record<
 				`Destination mailbox ${destinationMailboxId} not in account`,
 			);
 		}
+		assertMailboxSettled(destination);
 
 		// MessageMoveService handles: Message copies + ThreadMessage creation + SQS events
 		await client.messageMove.copyMessages(

package/src/index.test.ts

@@ -0,0 +1,83 @@
+/**
+ * Issue #1054: the backend must log one structured access line per request
+ * (method, path, status, duration, correlation id) at a level that is on in
+ * production. The access log lives in `rawHandler` in `src/index.ts`, wrapping
+ * the authenticated request path — so a 401 denial from edge-auth also gets an
+ * access line (once it flows through `formatResponse` with the correlation id).
+ *
+ * The 401 response shape (correlation id header + CORS on the denial) is tested
+ * directly in `jwt-auth.test.ts` via `runWithRequestContext`; this file tests
+ * that the handler emits the access log line on every request by spying on the
+ * logger's info method.
+ */
+import assert from "node:assert/strict";
+import { describe, it, mock } from "node:test";
+import { logger } from "@remit/logger-lambda";
+import type { APIGatewayProxyEvent, Context } from "aws-lambda";
+import { handler } from "./index.js";
+
+const buildEvent = (
+	overrides: Partial<APIGatewayProxyEvent> = {},
+): APIGatewayProxyEvent =>
+	({
+		path: "/api/test",
+		httpMethod: "GET",
+		pathParameters: {},
+		queryStringParameters: {},
+		headers: {},
+		requestContext: {},
+		...overrides,
+	}) as unknown as APIGatewayProxyEvent;
+
+const buildContext = (correlationId = "ctx-test-1"): Context =>
+	({
+		awsRequestId: correlationId,
+		functionName: "test-function",
+		getRemainingTimeInMillis: () => 30000,
+	}) as unknown as Context;
+
+describe("issue #1054: per-request access log", () => {
+	it('emits one "Request completed" line at info level with method, path, status, duration and correlation id', async () => {
+		delete process.env.LOCAL_ACCOUNT_CONFIG_ID;
+
+		// Spy on logger.info — the real logger passes (fields, message) in
+		// pino order, so the spy captures the structured fields and message.
+		const infoSpy = mock.method(logger, "info");
+
+		try {
+			await handler(
+				buildEvent({ path: "/api/__nonexistent_for_test__" }),
+				buildContext("ctx-access-log"),
+			).catch(() => {
+				// 404s are expected; we only care about the log line.
+			});
+
+			// `logger.info` is overloaded ((obj, msg?) and (msg, obj?)), so the
+			// mock types `call.arguments` by a single overload. Read the
+			// arguments positionally through an unknown[] view instead.
+			const accessCalls = infoSpy.mock.calls.filter((call) => {
+				// pino calls logger.info(fields, message)
+				const args = call.arguments as unknown[];
+				return args[1] === "Request completed";
+			});
+
+			assert.ok(accessCalls.length >= 1, "expected an access log line");
+			const fields = (accessCalls[0].arguments as unknown[])[0] as Record<
+				string,
+				unknown
+			>;
+
+			// infoSpy was called on logger.info, so the level is "info" by
+			// construction — pino's adapter routes .info() calls to the info
+			// level. No separate level field needed.
+
+			assert.equal(fields.method, "GET");
+			assert.equal(fields.path, "/api/__nonexistent_for_test__");
+			assert.equal(fields.correlationId, "ctx-access-log");
+			assert.equal(typeof fields.statusCode, "number");
+			assert.equal(typeof fields.durationMs, "number");
+		} finally {
+			infoSpy.mock.restore();
+		}
+	});
+});

package/src/index.ts

@@ -180,9 +180,17 @@ const rawHandler = async (event: APIGatewayProxyEvent, context: Context) => {
 			logger.debug({ method: event.httpMethod, path }, "Request received");
 
 			const origin = readOriginHeader(event.headers);
-
-			return runWithRequestContext(
-				{ origin, correlationId: context.awsRequestId },
+			const startedAt = Date.now();
+			// Capture the correlation id here: it is seeded by
+			// runWithRequestContext below (from context.awsRequestId), but that
+			// AsyncLocalStorage scope does not reliably survive the
+			// openapi-backend handleRequest call chain, so we read it from
+			// `context.awsRequestId` directly rather than via
+			// getRequestCorrelationId at log time.
+			const correlationId = context.awsRequestId;
+
+			const result = await runWithRequestContext(
+				{ origin, correlationId },
 				async () => {
 					if (usesBetterAuthJwt()) {
 						const denied = await authenticateSelfHostRequest(event);
@@ -194,6 +202,25 @@ const rawHandler = async (event: APIGatewayProxyEvent, context: Context) => {
 						.catch(handleError);
 				},
 			);
+
+			// One structured access line per request: method, path, status, and
+			// duration. The correlation id is inlined as a top-level field so a bug
+			// report quoting the id can grep logs by it directly, and emitted at
+			// info so it is on by default in production (the debug "Request
+			// received" above already filters out under normal log levels).
+			// biome-ignore lint/plugin/no-logger-info: one access line per request is an audit-grade signal (issue #1054)
+			logger.info(
+				{
+					method: event.httpMethod,
+					path,
+					statusCode: result.statusCode,
+					durationMs: Date.now() - startedAt,
+					correlationId,
+				},
+				"Request completed",
+			);
+
+			return result;
 		},
 	);
 };

package/src/jwt-auth.test.ts

@@ -5,6 +5,7 @@ import {
 	_setVerifierForTest,
 	authenticateSelfHostRequest,
 } from "./jwt-auth.js";
+import { runWithRequestContext } from "./request-context.js";
 
 const buildEvent = (
 	overrides: Partial<APIGatewayProxyEvent> = {},
@@ -41,7 +42,7 @@ test("valid token injects verified sub into authorizer claims", async () => {
 	assert.equal(event.requestContext.authorizer?.claims?.email, "a@b.com");
 });
 
-test("invalid token returns 401 and does not inject claims", async () => {
+test("invalid token returns 401 with correlation id and CORS headers", async () => {
 	_setVerifierForTest(async () => {
 		throw new Error("bad signature");
 	});
@@ -49,9 +50,29 @@ test("invalid token returns 401 and does not inject claims", async () => {
 		headers: { authorization: "Bearer bad.token" },
 	});
 
-	const result = await authenticateSelfHostRequest(event);
+	const result = await runWithRequestContext(
+		{ correlationId: "req-invalid-token" },
+		async () => authenticateSelfHostRequest(event),
+	);
 
 	assert.equal(result?.statusCode, 401);
+	assert.equal(
+		result?.headers?.["x-correlation-id"],
+		"req-invalid-token",
+		"edge-auth 401 must carry the correlation id",
+	);
+	assert.equal(
+		result?.headers?.["Access-Control-Allow-Origin"],
+		"*",
+		"edge-auth 401 must carry CORS headers",
+	);
+	assert.equal(
+		result?.body,
+		JSON.stringify({
+			code: "unauthorized",
+			message: "Invalid or expired token",
+		}),
+	);
 	assert.equal(event.requestContext.authorizer, undefined);
 });
 
@@ -64,12 +85,25 @@ test("no token with a local bypass configured is allowed", async () => {
 	assert.equal(result, null);
 });
 
-test("no token and no bypass returns 401", async () => {
+test("no token and no bypass returns 401 with correlation id", async () => {
 	const event = buildEvent();
 
-	const result = await authenticateSelfHostRequest(event);
+	const result = await runWithRequestContext(
+		{ correlationId: "req-no-token" },
+		async () => authenticateSelfHostRequest(event),
+	);
 
 	assert.equal(result?.statusCode, 401);
+	assert.equal(
+		result?.headers?.["x-correlation-id"],
+		"req-no-token",
+		"edge-auth 401 must carry the correlation id",
+	);
+	assert.equal(
+		result?.headers?.["Access-Control-Allow-Origin"],
+		"*",
+		"edge-auth 401 must carry CORS headers",
+	);
 });
 
 test("a tokenless GET to the Microsoft OAuth callback is admitted", async () => {

package/src/jwt-auth.ts

@@ -8,6 +8,7 @@ import { readCalendarFeedToken } from "@remit/calendar-service";
 import { logger } from "@remit/logger-lambda";
 import type { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
 import { defaultErrorCode } from "./error.js";
+import { formatResponse } from "./response.js";
 
 let verifier: JwtVerifier | null = null;
 
@@ -31,11 +32,8 @@ const readHeader = (
 	return undefined;
 };
 
-const unauthorized = (message: string): APIGatewayProxyResult => ({
-	statusCode: 401,
-	headers: { "Content-Type": "application/json" },
-	body: JSON.stringify({ code: defaultErrorCode(401), message }),
-});
+const unauthorized = (message: string): APIGatewayProxyResult =>
+	formatResponse({ code: defaultErrorCode(401), message }, 401);
 
 const injectClaims = (
 	event: APIGatewayProxyEvent,