@remit/backend 0.0.143 → 0.0.144

package/src/handlers/message.ts

@@ -1,1131 +0,0 @@
-import type {
-	BodyPartResponse,
-	EnvelopeAddressResponse,
-	EnvelopeResponse,
-} from "@remit/api-openapi-types";
-import type { MailboxItem } from "@remit/data-ports";
-import {
-	BadRequestError,
-	ForbiddenError,
-	MessagePlacementUnsettledError,
-	NotFoundError,
-	UnrecoverableBodyError,
-} from "@remit/data-ports/errors";
-import {
-	ContentDisposition,
-	MediaType,
-	MessageCategory,
-	SenderTrust,
-	type StarColor,
-} from "@remit/domain-enums";
-import { logger } from "@remit/logger-lambda";
-import {
-	guardConnectionCursor,
-	isCursorRebuildNeeded,
-	isMessageBodySyncBroken,
-	MailboxCursorPausedError,
-	MoveNotSettledError,
-	NoJunkMailboxError,
-	resolveFolderPlacement,
-} from "@remit/mailbox-service";
-import {
-	isStorageNotFoundError as isStorageNotFoundErrorFromService,
-	parseStorageUri,
-} from "@remit/storage-service";
-import type { APIGatewayProxyEvent } from "aws-lambda";
-import type { Context } from "openapi-backend";
-import { getAccountConfigIdFromEvent, getSubFromEvent } from "../auth.js";
-import { deriveAutoMoved } from "../derive/autoMoved.js";
-import {
-	type ContentSigner,
-	getContentSigner,
-} from "../derive/contentSignature.js";
-import {
-	buildContentUrl,
-	getContentDeliveryDomain,
-} from "../derive/contentUrl.js";
-import { deriveSenderTrust } from "../derive/senderTrust.js";
-import { getClient } from "../service/data-client.js";
-import type {
-	MessageBulkOperationIds,
-	MessageOperationIds,
-	OperationHandler,
-} from "../types.js";
-import { assertMailboxSettled } from "./mailbox.js";
-
-type StarColorValue = (typeof StarColor)[keyof typeof StarColor];
-
-interface MessageOwnershipClient {
-	message: { get(messageId: string): Promise<{ mailboxId: string }> };
-	mailbox: {
-		get(
-			accountId: string,
-			mailboxIds: string[],
-		): Promise<{ mailboxId: string; accountId: string }[]>;
-	};
-	account: {
-		listAllByAccountConfig(
-			accountConfigId: string,
-		): Promise<{ accountId: string }[]>;
-	};
-}
-
-/**
- * Resolve the account that owns every message in `messageIds` and assert the
- * caller owns it. Messages have no tenant column, so ownership resolves through
- * the mailbox: the caller's own accounts (from their accountConfigId) scope a
- * mailbox lookup, and a mailbox resolves only under the account that owns it —
- * a foreign message never resolves and throws before any content is returned or
- * mutated (`read` -> 404, no existence leak; `act` -> 403). The tenant comes
- * from the caller's config, never from the row being read. The whole batch must
- * resolve to a single account — the downstream flag/move/delete services take
- * one accountId — so a batch spanning accounts is rejected. Returns that
- * accountId so callers reuse it without another lookup.
- */
-export const assertMessagesOwned = async (
-	client: MessageOwnershipClient,
-	messageIds: string[],
-	callerAccountConfigId: string,
-	mode: "read" | "act",
-): Promise<string> => {
-	const messages = await Promise.all(
-		messageIds.map((id) => client.message.get(id)),
-	);
-	const mailboxIds = [...new Set(messages.map((m) => m.mailboxId))];
-
-	const ownedAccounts = await client.account.listAllByAccountConfig(
-		callerAccountConfigId,
-	);
-
-	const accountByMailbox = new Map<string, string>();
-	for (const { accountId } of ownedAccounts) {
-		const rows = await client.mailbox.get(accountId, mailboxIds);
-		for (const row of rows) {
-			accountByMailbox.set(row.mailboxId, row.accountId);
-		}
-	}
-
-	if (mailboxIds.some((id) => !accountByMailbox.has(id))) {
-		if (mode === "read") {
-			throw new NotFoundError("Message not found");
-		}
-		throw new ForbiddenError("Message not in account config");
-	}
-
-	const accountIds = [...new Set(accountByMailbox.values())];
-	if (accountIds.length !== 1) {
-		throw new BadRequestError("All messages must belong to the same account");
-	}
-
-	return accountIds[0];
-};
-
-export const isStorageNotFoundError = (error: unknown): boolean =>
-	isStorageNotFoundErrorFromService(error);
-
-/**
- * Decode the raw `.eml` bytes into a string for inspection. RFC822/MIME
- * sources are 7-bit/8-bit ASCII-compatible (non-ASCII bytes are encoded via
- * quoted-printable / base64 inside the body), so `latin1` round-trips every
- * byte 1:1 without loss or replacement characters — unlike `utf8`, which would
- * mangle raw 8-bit bytes. Headers and structure stay byte-accurate.
- */
-export const decodeRawEml = (body: Buffer): string => body.toString("latin1");
-
-/**
- * Extract the accountConfigId + accountId segments from a bodyStorageKey URI
- * such as
- * `s3://bucket/accounts/{accountConfigId}/{accountId}/messages/{messageId}/body.eml`.
- * Returns null when the URI shape doesn't match — caller falls back to the
- * slow path without writing a parsed-body cache.
- */
-export const extractAccountIdsFromBodyKey = (
-	uri: string,
-): { accountConfigId: string; accountId: string } | null => {
-	const parsed = parseStorageUri(uri);
-	const match = parsed.storageKey.match(
-		/^accounts\/([^/]+)\/([^/]+)\/messages\//,
-	);
-	if (!match) return null;
-	return { accountConfigId: match[1], accountId: match[2] };
-};
-
-/**
- * Map a list of stored `BodyPart` rows to API `BodyPartResponse` objects,
- * populating `contentUrl` from the CloudFront distribution domain. Pure
- * function so the URL-construction contract can be pinned in tests without
- * standing up the full handler. The contract requires every `contentUrl`
- * to be a real URL (#299) — `getContentDeliveryDomain` throws when the
- * Lambda env is missing the domain, and this function expects a non-empty
- * string from the caller.
- */
-export interface BodyPartLike {
-	bodyPartId: string;
-	mediaType: string;
-	mediaSubtype: string;
-	sizeOctets: number;
-	disposition?: string;
-	dispositionFilename?: string;
-	isMultipart: boolean;
-	contentId?: string;
-	partPath: string;
-}
-
-const MEDIA_TYPE_VALUES: ReadonlySet<string> = new Set(
-	Object.values(MediaType),
-);
-const CONTENT_DISPOSITION_VALUES: ReadonlySet<string> = new Set(
-	Object.values(ContentDisposition),
-);
-
-export const isMediaType = (
-	value: unknown,
-): value is BodyPartResponse["mediaType"] =>
-	typeof value === "string" && MEDIA_TYPE_VALUES.has(value);
-
-export const isContentDisposition = (
-	value: unknown,
-): value is NonNullable<BodyPartResponse["disposition"]> =>
-	typeof value === "string" && CONTENT_DISPOSITION_VALUES.has(value);
-
-const assertMediaType = (
-	value: string,
-	bodyPartId: string,
-): BodyPartResponse["mediaType"] => {
-	if (!isMediaType(value)) {
-		throw new Error(
-			`Invalid mediaType "${value}" on BodyPart ${bodyPartId}; expected one of ${[...MEDIA_TYPE_VALUES].join(", ")}`,
-		);
-	}
-	return value;
-};
-
-const assertDisposition = (
-	value: string | undefined,
-	bodyPartId: string,
-): BodyPartResponse["disposition"] => {
-	if (value === undefined) return undefined;
-	if (!isContentDisposition(value)) {
-		throw new Error(
-			`Invalid disposition "${value}" on BodyPart ${bodyPartId}; expected one of ${[...CONTENT_DISPOSITION_VALUES].join(", ")}`,
-		);
-	}
-	return value;
-};
-
-export const buildBodyPartResponses = (
-	parts: readonly BodyPartLike[],
-	context: {
-		contentDeliveryDomain: string;
-		accountConfigId: string;
-		accountId: string;
-		messageId: string;
-		sign?: ContentSigner;
-	},
-): BodyPartResponse[] => {
-	return parts.map((part) => ({
-		bodyPartId: part.bodyPartId,
-		mediaType: assertMediaType(part.mediaType, part.bodyPartId),
-		mediaSubtype: part.mediaSubtype,
-		sizeOctets: part.sizeOctets,
-		disposition: assertDisposition(part.disposition, part.bodyPartId),
-		dispositionFilename: part.dispositionFilename,
-		isMultipart: part.isMultipart,
-		contentId: part.contentId,
-		contentUrl: buildContentUrl({
-			domain: context.contentDeliveryDomain,
-			accountConfigId: context.accountConfigId,
-			accountId: context.accountId,
-			messageId: context.messageId,
-			partPath: part.partPath,
-			sign: context.sign,
-		}),
-	}));
-};
-
-/**
- * The slice of `BodySyncService` the read path needs to lazily materialize
- * deferred per-part objects. Narrowed to one method so the orchestration below
- * can be unit-tested without standing up the whole client.
- */
-export interface BodyPartMaterializer {
-	ensureBodyPartsStored(
-		accountConfigId: string,
-		accountId: string,
-		messageId: string,
-		bodyStorageKey: string,
-	): Promise<unknown>;
-}
-
-export interface MaterializeLogger {
-	warn(obj: Record<string, unknown>, msg: string): void;
-	error(obj: Record<string, unknown>, msg: string): void;
-}
-
-/**
- * Re-arms the body-sync cue for one message (the read-path slice of
- * `BodySyncQueueService`). Narrowed to one method so the orchestration below can
- * be unit-tested without an SQS client.
- */
-export interface BodySyncCue {
-	requestBodySync(input: {
-		accountId: string;
-		mailboxId: string;
-		messageId: string;
-		uid?: number;
-	}): Promise<void>;
-}
-
-export interface MaterializeResult {
-	/** `false` when the body object was missing — the caller must not 200 the body. */
-	ready: boolean;
-}
-
-/**
- * Materialize the deferred per-part storage objects for a message before the
- * SPA fetches any `contentUrl`. Distinguishes the two failure modes the body
- * contract cares about:
- *
- * - Missing storage object (never synced or lost) — re-arm the SYNC_MESSAGE_BODY
- *   cue so the worker (re)stores the body, and report `ready: false`. Not a
- *   500: a retry succeeds once the worker catches up.
- * - Any other error — rethrow so the request 500s and the bug is observable.
- *   Never swallowed, never "best-effort".
- *
- * No-op (`ready: true`) when the body isn't stored yet (no `bodyStorageKey`) or
- * when the parts were written eagerly.
- */
-export const materializeBodyParts = async (
-	materializer: BodyPartMaterializer,
-	args: {
-		accountConfigId: string;
-		accountId: string;
-		mailboxId: string;
-		messageId: string;
-		uid?: number;
-		bodyStorageKey: string | undefined;
-		cue: BodySyncCue | undefined;
-		logger: MaterializeLogger;
-	},
-): Promise<MaterializeResult> => {
-	const { accountConfigId, accountId, mailboxId, messageId, uid } = args;
-	if (!args.bodyStorageKey) return { ready: true };
-
-	try {
-		await materializer.ensureBodyPartsStored(
-			accountConfigId,
-			accountId,
-			messageId,
-			args.bodyStorageKey,
-		);
-		return { ready: true };
-	} catch (error: unknown) {
-		if (!isStorageNotFoundError(error)) throw error;
-
-		args.logger.warn(
-			{ messageId, accountId, mailboxId },
-			"Body object missing on read; re-arming body-sync cue and signalling retry",
-		);
-		await args.cue?.requestBodySync({ accountId, mailboxId, messageId, uid });
-		return { ready: false };
-	}
-};
-
-export interface SpamReportBulkFailure {
-	messageId: string;
-	reason: string;
-}
-
-export interface SpamReportBulkOutcome {
-	successCount: number;
-	failureCount: number;
-	failures?: SpamReportBulkFailure[];
-}
-
-/**
- * The fallback for a failure nobody designed copy for — an AWS SDK message
- * naming a queue URL, an `ECONNREFUSED host:port`, a programmer error.
- * Everything reaching it is flattened, same policy as `error.ts`'s "Internal
- * server error" flattening, because `SpamReportBulkResult.reason` is shown to
- * the user as-is. It says "try again" because retrying is the only thing left
- * to say about a cause we cannot name; an outcome the service DOES understand
- * carries its own text through `DESIGNED_FAILURES` instead of landing here.
- */
-export const GENERIC_FAILURE_REASON =
-	"This message could not be processed. Please try again. If it keeps failing, report it.";
-
-/**
- * The designed, user-facing outcomes whose own message is returned verbatim:
- * each names what happened and what the user can do about it, which the
- * generic text cannot.
- */
-const DESIGNED_FAILURES = [
-	MoveNotSettledError,
-	NoJunkMailboxError,
-	MessagePlacementUnsettledError,
-];
-
-const isDesignedFailure = (reason: unknown): reason is Error =>
-	DESIGNED_FAILURES.some((designed) => reason instanceof designed);
-
-/**
- * The placement refusal is the one designed outcome whose own message is not
- * the text to ship: it names a uuid and no remedy. One remedy answers it, and
- * only one refusal reaches it — a mutation still in flight, which settles on
- * its own (imap-mutations R3). Worded here, the way the delete path words the
- * same refusal for the client.
- */
-const placementRefusalReason = (
-	_error: MessagePlacementUnsettledError,
-): string =>
-	"This message is still being moved on the mail server. Try again in a moment.";
-
-const failureReason = (reason: unknown): string => {
-	if (!isDesignedFailure(reason)) return GENERIC_FAILURE_REASON;
-	if (reason instanceof MessagePlacementUnsettledError)
-		return placementRefusalReason(reason);
-	return reason.message;
-};
-
-/**
- * Drive one report-spam/not-spam operation per message, concurrently. Each
- * message's own wait for its move to settle (SpamReportService's R2 wait) is
- * bounded on its own, but running the batch sequentially would let those
- * waits accumulate across the whole request — 50 messages could each wait
- * seconds, serializing into minutes and dying at the proxy. Running them
- * concurrently instead bounds the whole request by a single message's wait,
- * regardless of batch size.
- */
-export const settleSpamReportBulk = async (
-	messageIds: string[],
-	run: (messageId: string) => Promise<void>,
-): Promise<SpamReportBulkOutcome> => {
-	const results = await Promise.allSettled(
-		messageIds.map((messageId) => run(messageId)),
-	);
-
-	let successCount = 0;
-	const failures: SpamReportBulkFailure[] = [];
-	results.forEach((result, index) => {
-		if (result.status === "fulfilled") {
-			successCount += 1;
-			return;
-		}
-		const messageId = messageIds[index];
-		failures.push({ messageId, reason: failureReason(result.reason) });
-		logger.error(
-			{ messageId, error: result.reason },
-			"spam-report bulk operation failed for one message",
-		);
-	});
-
-	return {
-		successCount,
-		failureCount: failures.length,
-		...(failures.length > 0 ? { failures } : {}),
-	};
-};
-
-export const MessageOperations: Record<
-	MessageOperationIds,
-	OperationHandler<MessageOperationIds>
-> = {
-	MessageOperations_describeMessage: async (
-		context: Context,
-		...args: unknown[]
-	) => {
-		const event = args[0] as APIGatewayProxyEvent;
-		const accountConfigId = getAccountConfigIdFromEvent(event);
-		const { messageId } = context.request.params as { messageId: string };
-		const client = await getClient();
-		const ownedAccountId = await assertMessagesOwned(
-			client,
-			[messageId],
-			accountConfigId,
-			"read",
-		);
-		const description = await client.message.describe(messageId);
-
-		const message = description.message[0];
-		const envelope = description.envelope[0];
-
-		const autoMoved = deriveAutoMoved(message);
-
-		// Labels applied to this message (issue #26) — filter-, organize-, and
-		// manually-applied alike. A message rarely carries more than a handful, so
-		// a `get` per label id (not a batch fetch) is the whole cost.
-		const messageLabelRows = await client.messageLabel.listByMessageId(
-			message.messageId,
-		);
-		const labels = await Promise.all(
-			messageLabelRows.map(async (row) => {
-				const label = await client.label.get(accountConfigId, row.labelId);
-				return { labelId: label.labelId, name: label.name, color: label.color };
-			}),
-		);
-
-		// Not typed against the generated `MessageSummaryResponse`: `labels` is a
-		// new field on it in this same PR, and that package publishes separately
-		// from this repo — a local-codegen-only field would fail
-		// `check-consumer-typecheck`/`release:dry-run`, which resolve generated
-		// `@remit/*` packages off the registry, not the local `build/` output.
-		const messageSummary = {
-			messageId: message.messageId,
-			mailboxId: message.mailboxId,
-			uid: message.uid,
-			rfc822Size: message.rfc822Size,
-			internalDate: message.internalDate,
-			messageIdHeader: message.messageIdHeader,
-			authenticity: message.authenticity,
-			status: message.status,
-			syncStatus: message.syncStatus,
-			abandonedMutation: message.abandonedMutation,
-			...(autoMoved ? { autoMoved } : {}),
-			...(labels.length > 0 ? { labels } : {}),
-			...(message.spamReport ? { spamReport: message.spamReport } : {}),
-		};
-
-		// Batch-fetch the resolved Address rows so each EnvelopeAddressResponse can
-		// carry the sender-level `flags` map. Without this the From-line UI would
-		// need a second round-trip to render trust state on every message open.
-		const uniqueAddressIds = Array.from(
-			new Set(description.envelopeAddress.map((a) => a.addressId)),
-		);
-		const addresses = uniqueAddressIds.length
-			? await client.address.getAddress(accountConfigId, uniqueAddressIds)
-			: [];
-		const flagsByAddressId = new Map(
-			addresses.map((a) => [a.addressId, a.flags]),
-		);
-
-		const groupedAddresses = description.envelopeAddress.reduce(
-			(acc, addr) => {
-				const role = addr.addressRole;
-				if (!acc[role]) acc[role] = [];
-				acc[role].push({
-					addressId: addr.addressId,
-					displayName: addr.displayName,
-					normalizedEmail: addr.normalizedEmail,
-					addressRole: addr.addressRole,
-					addressOrder: addr.addressOrder,
-					flags: flagsByAddressId.get(addr.addressId),
-				});
-				return acc;
-			},
-			{} as Record<string, EnvelopeAddressResponse[]>,
-		);
-
-		const fromAddress = groupedAddresses.from?.[0];
-		const fromFlags = fromAddress
-			? flagsByAddressId.get(fromAddress.addressId)
-			: undefined;
-		const senderTrust = fromAddress
-			? deriveSenderTrust(fromFlags)
-			: SenderTrust.Unknown;
-
-		const envelopeResponse: EnvelopeResponse = {
-			messageId: envelope?.messageId ?? messageId,
-			date: envelope?.dateValue ?? message.internalDate,
-			subject: envelope?.subject,
-			messageIdValue: envelope?.messageIdValue,
-			from: groupedAddresses.from ?? [],
-			to: groupedAddresses.to ?? [],
-			cc: groupedAddresses.cc ?? [],
-			bcc: groupedAddresses.bcc ?? [],
-			replyTo: groupedAddresses.reply_to ?? [],
-			category: message.category ?? MessageCategory.uncategorized,
-			senderTrust,
-		};
-
-		const flags = description.messageFlag.map((f) => f.flagName);
-
-		// `accountId` is needed to build per-part `contentUrl` values for the
-		// BodyPartResponse list and on the IMAP-backfill path. Resolve it from
-		// the bodyStorageKey when the body has already been synced (free — the
-		// URI encodes both ids), or fall back to a single Mailbox.get() lookup
-		// to avoid a redundant query on the fast path.
-		const idsFromKey = message.bodyStorageKey
-			? extractAccountIdsFromBodyKey(message.bodyStorageKey)
-			: null;
-		let accountId = idsFromKey?.accountId;
-		let mailbox: MailboxItem | undefined;
-		if (!accountId) {
-			mailbox = await client.mailbox.get(ownedAccountId, message.mailboxId);
-			accountId = mailbox.accountId;
-		}
-
-		// Trigger an IMAP backfill when the body has never been stored. The
-		// fetcher writes the raw .eml + parsed.json.gz cache + per-part rows
-		// as a side-effect; the SPA then renders body content via each
-		// BodyPartResponse.contentUrl (CloudFront-fronted, JWT-authorized at
-		// the edge). The handler no longer returns body text/html — that
-		// payload moved to per-part fetches once content delivery cut over
-		// (#224 PR 3/3). When bodyStorageKey is already set we skip IMAP
-		// entirely; the worker has already populated parts.
-		let bodyPartRows = description.bodyPart;
-		let bodyStorageKey = message.bodyStorageKey;
-		if (!bodyStorageKey) {
-			// A message whose body-sync exhausted every retry against real
-			// (broken) content never gets a bodyStorageKey (issue #1270 / epic
-			// #1281 invariant 3) — this branch is the ONLY place that condition
-			// can occur, so the sentinel check lives here instead of unconditionally
-			// at the top of the handler, which would tax every already-synced
-			// read with an S3 HEAD it can never need. Checking before the backfill
-			// attempt stops a client from looping through repeated 202s
-			// (materializeBodyParts) or repeated synchronous IMAP round-trips
-			// (fetchAndGetBody) on a message that can never succeed.
-			if (
-				await isMessageBodySyncBroken(
-					client.storage,
-					accountConfigId,
-					accountId,
-					messageId,
-				)
-			) {
-				throw new UnrecoverableBodyError(
-					"This message's content could not be retrieved. Please report this issue.",
-				);
-			}
-
-			if (!mailbox) {
-				mailbox = await client.mailbox.get(accountId, message.mailboxId);
-			}
-
-			// Cheap frugal skip (epic #1281 invariant 6): a mailbox already known
-			// paused never even opens a connection. Optimization only —
-			// guardConnectionCursor's openBox wrap below is the structural
-			// guarantee (issue #1272's read-path detection point).
-			if (isCursorRebuildNeeded(mailbox.cursorState)) {
-				logger.debug(
-					{
-						accountId,
-						mailboxId: mailbox.mailboxId,
-						messageId,
-						cursorState: mailbox.cursorState,
-					},
-					"Mailbox cursor not normal; skipping IMAP body backfill for this request",
-				);
-			} else {
-				const folder = {
-					fullPath: mailbox.fullPath,
-					placement: await resolveFolderPlacement(
-						client.mailboxSpecialUse,
-						accountId,
-						mailbox.mailboxId,
-					),
-				};
-				const scope = await client.createConnectionScope(accountId);
-				// Guard at the one choke point every UID-based IMAP op already
-				// passes through: openBox. A mismatch trips the mailbox to
-				// cursor_invalid and throws; caught below as a routine skip (epic
-				// #1281 invariant 3) — the request just returns without a fresh
-				// backfill this time.
-				const connection = guardConnectionCursor(
-					await scope.getConnection(),
-					{ mailboxService: client.mailbox },
-					accountId,
-					mailbox,
-				);
-
-				await client.bodySync
-					.fetchAndGetBody(messageId, accountId, accountConfigId, folder, () =>
-						Promise.resolve(connection),
-					)
-					.catch((error: unknown) => {
-						if (error instanceof MailboxCursorPausedError) {
-							logger.debug(
-								{
-									accountId,
-									mailboxId: mailbox?.mailboxId,
-									messageId,
-									cursorState: error.state,
-								},
-								"Mailbox cursor not normal; skipping IMAP body backfill for this request",
-							);
-							return;
-						}
-						throw error;
-					})
-					.finally(() => scope.disconnect());
-
-				// Body just landed via IMAP — re-read so the response includes the
-				// parts the worker just wrote. Without this the first describe of a
-				// never-synced message would return an empty bodyParts array.
-				const refreshed = await client.message.describe(messageId);
-				bodyPartRows = refreshed.bodyPart;
-				bodyStorageKey = refreshed.message[0]?.bodyStorageKey;
-			}
-		}
-
-		// Per-part storage objects are deferred during bulk sync (DEFER_BODY_PARTS)
-		// to cut write amplification. Content delivery serves each part straight
-		// from storage with no Lambda in the request path, so a deferred (missing)
-		// object would surface to the SPA as a hard failure. Materialize them here —
-		// idempotent, skips parts already stored — so every contentUrl below
-		// resolves on first open. No-op when parts were written eagerly.
-		//
-		// A missing body object re-arms the SYNC_MESSAGE_BODY cue (so the worker
-		// (re)stores it) and leaves the contentUrls to surface a retryable 202 on
-		// the content route; any other error is rethrown and 500s loudly.
-		await materializeBodyParts(client.bodySync, {
-			accountConfigId,
-			accountId,
-			mailboxId: message.mailboxId,
-			messageId,
-			uid: message.uid,
-			bodyStorageKey,
-			cue: client.bodySyncQueue,
-			logger,
-		});
-
-		const bodyParts = buildBodyPartResponses(bodyPartRows, {
-			contentDeliveryDomain: getContentDeliveryDomain(),
-			accountConfigId,
-			accountId,
-			messageId,
-			sign: getContentSigner(),
-		});
-
-		const references = description.messageReference.map((ref) => ({
-			messageIdValue: ref.messageIdValue,
-			referenceType: ref.referenceType,
-			referenceOrder: ref.referenceOrder,
-		}));
-
-		return {
-			message: messageSummary,
-			envelope: envelopeResponse,
-			flags,
-			bodyParts,
-			references,
-		};
-	},
-
-	MessageOperations_getRawMessage: async (
-		context: Context,
-		...args: unknown[]
-	) => {
-		const event = args[0] as APIGatewayProxyEvent;
-		const accountConfigId = getAccountConfigIdFromEvent(event);
-		const { messageId } = context.request.params as { messageId: string };
-		const client = await getClient();
-
-		// Cross-tenant ownership guard. Returning raw RFC822 bytes is sensitive,
-		// so resolve the owning account and prove the caller owns it BEFORE any
-		// storage read or backfill. `read` mode throws NotFoundError (→ 404) on a
-		// foreign message and never leaks the owner's accountConfigId.
-		const accountId = await assertMessagesOwned(
-			client,
-			[messageId],
-			accountConfigId,
-			"read",
-		);
-
-		// Resolve the message row for its mailboxId / bodyStorageKey.
-		const message = await client.message.get(messageId);
-
-		// Backfill from IMAP when the body has never been stored, reusing the
-		// exact path describeMessage uses. fetchAndGetBody writes the raw .eml +
-		// parsed cache + per-part rows and sets message.bodyStorageKey as a
-		// side-effect; we then re-read the row to pick up the freshly written key.
-		if (!message.bodyStorageKey) {
-			const mailbox = await client.mailbox.get(accountId, message.mailboxId);
-
-			// Cheap frugal skip (epic #1281 invariant 6): a mailbox already known
-			// paused never even opens a connection. The existing "no
-			// bodyStorageKey after backfill" check just past this block is
-			// already the right signal for that case, so no new response shape
-			// is needed here.
-			if (isCursorRebuildNeeded(mailbox.cursorState)) {
-				logger.debug(
-					{
-						accountId,
-						mailboxId: mailbox.mailboxId,
-						messageId,
-						cursorState: mailbox.cursorState,
-					},
-					"Mailbox cursor not normal; skipping IMAP body backfill for this request",
-				);
-			} else {
-				const folder = {
-					fullPath: mailbox.fullPath,
-					placement: await resolveFolderPlacement(
-						client.mailboxSpecialUse,
-						accountId,
-						mailbox.mailboxId,
-					),
-				};
-				const scope = await client.createConnectionScope(accountId);
-				// Guard at the openBox choke point — a fresh mismatch trips the
-				// mailbox and throws once the SELECT reveals it; caught below.
-				const connection = guardConnectionCursor(
-					await scope.getConnection(),
-					{ mailboxService: client.mailbox },
-					accountId,
-					mailbox,
-				);
-				await client.bodySync
-					.fetchAndGetBody(messageId, accountId, accountConfigId, folder, () =>
-						Promise.resolve(connection),
-					)
-					.catch((error: unknown) => {
-						if (error instanceof MailboxCursorPausedError) {
-							logger.debug(
-								{
-									accountId,
-									mailboxId: mailbox.mailboxId,
-									messageId,
-									cursorState: error.state,
-								},
-								"Mailbox cursor not normal; skipping IMAP body backfill for this request",
-							);
-							return;
-						}
-						throw error;
-					})
-					.finally(() => scope.disconnect());
-			}
-		}
-
-		// Re-read so we have the bodyStorageKey the backfill just wrote (or the
-		// key that was already present), then pull the raw bytes from storage.
-		const stored = await client.message.get(messageId);
-		if (!stored.bodyStorageKey) {
-			throw new Error(
-				`Raw source unavailable for message ${messageId}: no bodyStorageKey after backfill`,
-			);
-		}
-
-		const body = await client.storage.retrieve(stored.bodyStorageKey);
-
-		return { raw: decodeRawEml(body) };
-	},
-
-	MessageOperations_updateMessageFlags: async (context, ...args: unknown[]) => {
-		const event = args[0] as APIGatewayProxyEvent;
-		const accountConfigId = getAccountConfigIdFromEvent(event);
-		const { messageId } = context.request.params as { messageId: string };
-		const { isRead, isStarred, starColor } = context.request.requestBody as {
-			isRead?: boolean;
-			isStarred?: boolean;
-			starColor?: string;
-		};
-
-		const client = await getClient();
-		const accountId = await assertMessagesOwned(
-			client,
-			[messageId],
-			accountConfigId,
-			"act",
-		);
-
-		// FlagQueueService handles: MessageFlag + ThreadMessage updates + SQS event
-		const result = await client.flagQueue.updateFlags(
-			accountConfigId,
-			messageId,
-			accountId,
-			{
-				isRead,
-				isStarred,
-				starColor: starColor as StarColorValue | undefined,
-			},
-		);
-
-		return {
-			messageId: result.messageId,
-			isRead: result.isRead,
-			isStarred: result.isStarred,
-		};
-	},
-};
-
-export const MessageBulkOperations: Record<
-	MessageBulkOperationIds,
-	OperationHandler<MessageBulkOperationIds>
-> = {
-	MessageBulkOperations_updateFlags: async (context, ...args: unknown[]) => {
-		const event = args[0] as APIGatewayProxyEvent;
-		const accountConfigId = getAccountConfigIdFromEvent(event);
-		const { messageIds, isRead, isStarred, starColor } = context.request
-			.requestBody as {
-			messageIds: string[];
-			isRead?: boolean;
-			isStarred?: boolean;
-			starColor?: string;
-		};
-
-		if (messageIds.length === 0) {
-			return { successCount: 0, failureCount: 0 };
-		}
-
-		const client = await getClient();
-		const accountId = await assertMessagesOwned(
-			client,
-			messageIds,
-			accountConfigId,
-			"act",
-		);
-
-		// FlagQueueService handles: MessageFlag + ThreadMessage updates + SQS events
-		// Process each message individually (same pattern as moveMessages)
-		for (const messageId of messageIds) {
-			await client.flagQueue.updateFlags(
-				accountConfigId,
-				messageId,
-				accountId,
-				{
-					isRead,
-					isStarred,
-					starColor: starColor as StarColorValue | undefined,
-				},
-			);
-		}
-
-		return {
-			successCount: messageIds.length,
-			failureCount: 0,
-		};
-	},
-
-	MessageBulkOperations_deleteMessages: async (context, ...args: unknown[]) => {
-		const event = args[0] as APIGatewayProxyEvent;
-		const accountConfigId = getAccountConfigIdFromEvent(event);
-		const { messageIds, permanent } = context.request.requestBody as {
-			messageIds: string[];
-			permanent?: boolean;
-		};
-
-		if (messageIds.length === 0) {
-			return { successCount: 0, failureCount: 0 };
-		}
-
-		const client = await getClient();
-		const accountId = await assertMessagesOwned(
-			client,
-			messageIds,
-			accountConfigId,
-			"act",
-		);
-
-		// MessageMoveService handles: Message + ThreadMessage updates + SQS events
-		const { refusedMessageIds } = await client.messageMove.deleteMessages(
-			accountConfigId,
-			messageIds,
-			accountId,
-			{
-				permanent,
-			},
-		);
-
-		// A row whose placement changed under the batch is reported, not dropped.
-		// The response already carries per-row counts, which is the honest shape
-		// for a batch that partly applied — a 409 over it would deny the deletes
-		// that did happen, and silence leaves the client's optimistic removal to
-		// reappear with nothing said (imap-mutations R3).
-		return {
-			successCount: messageIds.length - refusedMessageIds.length,
-			failureCount: refusedMessageIds.length,
-		};
-	},
-
-	MessageBulkOperations_moveMessages: async (context, ...args: unknown[]) => {
-		const event = args[0] as APIGatewayProxyEvent;
-		const accountConfigId = getAccountConfigIdFromEvent(event);
-		const { messageIds, destinationMailboxId } = context.request
-			.requestBody as {
-			messageIds: string[];
-			destinationMailboxId: string;
-		};
-
-		if (messageIds.length === 0) {
-			return { successCount: 0, failureCount: 0 };
-		}
-
-		const client = await getClient();
-		const accountId = await assertMessagesOwned(
-			client,
-			messageIds,
-			accountConfigId,
-			"act",
-		);
-
-		// 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,
-		);
-		if (destination.accountId !== accountId) {
-			throw new ForbiddenError(
-				`Destination mailbox ${destinationMailboxId} not in account`,
-			);
-		}
-		assertMailboxSettled(destination);
-
-		// MessageMoveService handles: Message + ThreadMessage updates + SQS events
-		await client.messageMove.moveMessages(
-			accountConfigId,
-			messageIds,
-			destinationMailboxId,
-			accountId,
-		);
-
-		return {
-			successCount: messageIds.length,
-			failureCount: 0,
-		};
-	},
-
-	MessageBulkOperations_copyMessages: async (context, ...args: unknown[]) => {
-		const event = args[0] as APIGatewayProxyEvent;
-		const accountConfigId = getAccountConfigIdFromEvent(event);
-		const { messageIds, destinationMailboxId } = context.request
-			.requestBody as {
-			messageIds: string[];
-			destinationMailboxId: string;
-		};
-
-		if (messageIds.length === 0) {
-			return { successCount: 0, failureCount: 0 };
-		}
-
-		const client = await getClient();
-		const accountId = await assertMessagesOwned(
-			client,
-			messageIds,
-			accountConfigId,
-			"act",
-		);
-
-		// 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,
-		);
-		if (destination.accountId !== accountId) {
-			throw new ForbiddenError(
-				`Destination mailbox ${destinationMailboxId} not in account`,
-			);
-		}
-		assertMailboxSettled(destination);
-
-		// MessageMoveService handles: Message copies + ThreadMessage creation + SQS events
-		await client.messageMove.copyMessages(
-			accountConfigId,
-			messageIds,
-			destinationMailboxId,
-			accountId,
-		);
-
-		return {
-			successCount: messageIds.length,
-			failureCount: 0,
-		};
-	},
-
-	MessageBulkOperations_updateMessageLabels: async (
-		context,
-		...args: unknown[]
-	) => {
-		const event = args[0] as APIGatewayProxyEvent;
-		const accountConfigId = getAccountConfigIdFromEvent(event);
-		const { messageIds, labelId, action } = context.request.requestBody as {
-			messageIds: string[];
-			labelId: string;
-			action: "Apply" | "Remove";
-		};
-
-		if (messageIds.length === 0) {
-			return { successCount: 0, failureCount: 0 };
-		}
-
-		const client = await getClient();
-		await assertMessagesOwned(client, messageIds, accountConfigId, "act");
-
-		// Scoped by accountConfigId (RFC 030) — a foreign labelId 404s here rather
-		// than silently applying to messages under someone else's label.
-		await client.label.get(accountConfigId, labelId);
-
-		// `appliedByFilterId` stays absent — this is the manual "just these" scope
-		// (RFC 034 Decision 3.3), never filter-attributed.
-		if (action === "Apply") {
-			for (const messageId of messageIds) {
-				await client.messageLabel.apply({
-					accountConfigId,
-					messageId,
-					labelId,
-				});
-			}
-		} else {
-			for (const messageId of messageIds) {
-				await client.messageLabel.remove(messageId, labelId);
-			}
-		}
-
-		return {
-			successCount: messageIds.length,
-			failureCount: 0,
-		};
-	},
-
-	MessageBulkOperations_reportSpam: async (context, ...args: unknown[]) => {
-		const event = args[0] as APIGatewayProxyEvent;
-		const accountConfigId = getAccountConfigIdFromEvent(event);
-		const { messageIds: requestedIds } = context.request.requestBody as {
-			messageIds: string[];
-		};
-		const messageIds = [...new Set(requestedIds)];
-
-		if (messageIds.length === 0) {
-			return { successCount: 0, failureCount: 0 };
-		}
-
-		const client = await getClient();
-		const accountId = await assertMessagesOwned(
-			client,
-			messageIds,
-			accountConfigId,
-			"act",
-		);
-		const setBy = getSubFromEvent(event) ?? accountConfigId;
-
-		return settleSpamReportBulk(messageIds, (messageId) =>
-			client.spamReport.reportSpam({
-				accountConfigId,
-				accountId,
-				messageId,
-				setBy,
-			}),
-		);
-	},
-
-	MessageBulkOperations_notSpam: async (context, ...args: unknown[]) => {
-		const event = args[0] as APIGatewayProxyEvent;
-		const accountConfigId = getAccountConfigIdFromEvent(event);
-		const { messageIds: requestedIds } = context.request.requestBody as {
-			messageIds: string[];
-		};
-		const messageIds = [...new Set(requestedIds)];
-
-		if (messageIds.length === 0) {
-			return { successCount: 0, failureCount: 0 };
-		}
-
-		const client = await getClient();
-		const accountId = await assertMessagesOwned(
-			client,
-			messageIds,
-			accountConfigId,
-			"act",
-		);
-
-		return settleSpamReportBulk(messageIds, (messageId) =>
-			client.spamReport.notSpam({ accountConfigId, accountId, messageId }),
-		);
-	},
-};