@remit/backend 0.0.55 → 0.0.57

package/package.json

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

package/src/derive/enrichThreadRows.test.ts

@@ -166,6 +166,35 @@ describe("enrichThreadRows — labels", () => {
 	});
 });
 
+describe("enrichThreadRows — spamReport", () => {
+	test("projects spamReport straight from the Message row", async () => {
+		const rows = [threadRow("tm-1", "msg-1")];
+		const client: EnrichClient = {
+			message: {
+				get: async () =>
+					[
+						{
+							messageId: "msg-1",
+							spamReport: { reportedAt: 1_700_000_000_000 },
+						},
+					] as unknown as MessageItem[],
+			},
+			address: { getAddress: async () => [] },
+			messageLabel: { listByMessageIds: async () => [] },
+			label: { listByAccountConfig: async () => [] },
+		};
+
+		const [result] = await enrichThreadRows(rows, client, "acc-1");
+		assert.deepEqual(result?.spamReport, { reportedAt: 1_700_000_000_000 });
+	});
+
+	test("omits spamReport when the Message has never been reported", async () => {
+		const rows = [threadRow("tm-1", "msg-1")];
+		const [result] = await enrichThreadRows(rows, buildClient([], []), "acc-1");
+		assert.equal(result?.spamReport, undefined);
+	});
+});
+
 describe("enrichThreadRows — muted", () => {
 	const SET_AT = 1_700_000_000_000;
 

package/src/derive/enrichThreadRows.ts

@@ -101,8 +101,9 @@ export const planBatchFetch = (rows: ThreadMessageItem[]): BatchPlan => {
 
 /**
  * Enrich a page of ThreadMessage rows with `senderTrust` and `muted` (both
- * derived from the From Address's flags map), `authenticity` and `autoMoved`
- * (both projected from the Message row, see `deriveAutoMoved`).
+ * derived from the From Address's flags map), `authenticity`, `autoMoved` and
+ * `spamReport` (all projected straight from the Message row — no ThreadMessage
+ * column of their own, see `deriveAutoMoved`).
  *
  * `category` is not enriched: it is denormalized onto the ThreadMessage row
  * (shared with `Message.category`'s write-once value, see body-sync.ts) and
@@ -170,6 +171,9 @@ export const enrichThreadRows = async (
 	const autoMovedByMessageId = new Map(
 		messages.map((m) => [m.messageId, deriveAutoMoved(m)]),
 	);
+	const spamReportByMessageId = new Map(
+		messages.map((m) => [m.messageId, m.spamReport]),
+	);
 	const trustByAddressId = new Map(
 		addresses.map((a) => [a.addressId, deriveSenderTrust(a.flags)]),
 	);
@@ -181,6 +185,7 @@ export const enrichThreadRows = async (
 		const base = toResponse(row);
 		const authenticity = authenticityByMessageId.get(row.messageId);
 		const autoMoved = autoMovedByMessageId.get(row.messageId);
+		const spamReport = spamReportByMessageId.get(row.messageId);
 		const addressId = plan.addressIdByRow.get(row.threadMessageId);
 		const senderTrust = addressId
 			? (trustByAddressId.get(addressId) ?? SenderTrust.Unknown)
@@ -194,6 +199,7 @@ export const enrichThreadRows = async (
 			...(authenticity !== undefined ? { authenticity } : {}),
 			...(autoMoved !== undefined ? { autoMoved } : {}),
 			...(labels !== undefined ? { labels } : {}),
+			...(spamReport !== undefined ? { spamReport } : {}),
 			senderTrust,
 			muted,
 		};

package/src/handlers/message.test.ts

@@ -0,0 +1,88 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { MoveNotSettledError } from "@remit/mailbox-service";
+import { GENERIC_FAILURE_REASON, settleSpamReportBulk } from "./message.js";
+
+describe("settleSpamReportBulk", () => {
+	it("aggregates successes and failures, surfacing the one allowlisted reason verbatim", async () => {
+		const outcome = await settleSpamReportBulk(
+			["msg-1", "msg-2", "msg-3"],
+			async (messageId) => {
+				if (messageId === "msg-2") {
+					throw new MoveNotSettledError(messageId);
+				}
+			},
+		);
+
+		assert.equal(outcome.successCount, 2);
+		assert.equal(outcome.failureCount, 1);
+		assert.deepEqual(outcome.failures, [
+			{
+				messageId: "msg-2",
+				reason:
+					"Message msg-2's move to Junk has not settled yet; try again in a moment.",
+			},
+		]);
+	});
+
+	it("omits failures entirely when every message succeeds", async () => {
+		const outcome = await settleSpamReportBulk(
+			["msg-1", "msg-2"],
+			async () => {},
+		);
+
+		assert.equal(outcome.successCount, 2);
+		assert.equal(outcome.failureCount, 0);
+		assert.equal(outcome.failures, undefined);
+	});
+
+	// The response is user-facing (the field is documented as shown as-is) and
+	// this is a 200, not an error path guarded by error.ts's own flattening —
+	// so this is the one place a raw internal message could otherwise leak: an
+	// account id in "No Junk mailbox found for account <id>", a message id in
+	// "has no From address to act on", or an AWS SDK message naming a queue
+	// URL or ECONNREFUSED host:port on an SQS failure.
+	it("never puts an arbitrary error's raw text in the response — only the allowlisted reason ships", async () => {
+		const outcome = await settleSpamReportBulk(
+			["msg-leaky-error", "msg-leaky-string", "msg-settled-ok"],
+			async (messageId) => {
+				if (messageId === "msg-leaky-error") {
+					throw new Error(
+						"No Junk mailbox found for account acc-super-secret-internal-id",
+					);
+				}
+				if (messageId === "msg-leaky-string") {
+					return Promise.reject("ECONNREFUSED sqs.us-east-1.amazonaws.com:443");
+				}
+			},
+		);
+
+		assert.equal(outcome.failureCount, 2);
+		const reasons = outcome.failures?.map((f) => f.reason) ?? [];
+		assert.deepEqual(reasons, [GENERIC_FAILURE_REASON, GENERIC_FAILURE_REASON]);
+
+		const leaked = reasons.some(
+			(reason) =>
+				reason.includes("acc-super-secret-internal-id") ||
+				reason.includes("ECONNREFUSED") ||
+				reason.includes("amazonaws.com"),
+		);
+		assert.equal(leaked, false, "no internal detail may reach the response");
+	});
+
+	it("runs every message concurrently — total time is one wait, not N waits", async () => {
+		const WAIT_MS = 60;
+		const start = Date.now();
+
+		await settleSpamReportBulk(
+			Array.from({ length: 10 }, (_, i) => `msg-${i}`),
+			() => new Promise((resolve) => setTimeout(resolve, WAIT_MS)),
+		);
+
+		const elapsed = Date.now() - start;
+		assert.ok(
+			elapsed < WAIT_MS * 5,
+			`expected roughly one wait (~${WAIT_MS}ms), took ${elapsed}ms — looks sequential`,
+		);
+	});
+});

package/src/handlers/message.ts

@@ -23,6 +23,7 @@ import {
 	isCursorRebuildNeeded,
 	isMessageBodySyncBroken,
 	MailboxCursorPausedError,
+	MoveNotSettledError,
 } from "@remit/mailbox-service";
 import {
 	isStorageNotFoundError as isStorageNotFoundErrorFromService,
@@ -30,7 +31,7 @@ import {
 } from "@remit/storage-service";
 import type { APIGatewayProxyEvent } from "aws-lambda";
 import type { Context } from "openapi-backend";
-import { getAccountConfigIdFromEvent } from "../auth.js";
+import { getAccountConfigIdFromEvent, getSubFromEvent } from "../auth.js";
 import { deriveAutoMoved } from "../derive/autoMoved.js";
 import {
 	type ContentSigner,
@@ -326,6 +327,74 @@ export const materializeBodyParts = async (
 	}
 };
 
+export interface SpamReportBulkFailure {
+	messageId: string;
+	reason: string;
+}
+
+export interface SpamReportBulkOutcome {
+	successCount: number;
+	failureCount: number;
+	failures?: SpamReportBulkFailure[];
+}
+
+/**
+ * The one designed, allowlisted failure reason returned to the client
+ * verbatim — everything else is flattened to `GENERIC_FAILURE_REASON`, same
+ * policy as `error.ts`'s "Internal server error" flattening for an unhandled
+ * error. Without this, an arbitrary thrown error's raw text — an internal
+ * "No Junk mailbox found for account <id>", an AWS SDK message naming a
+ * queue URL or `ECONNREFUSED host:port` — would land straight in a 200
+ * response body, since `SpamReportBulkResult.reason` is documented as shown
+ * to the user as-is.
+ */
+export const GENERIC_FAILURE_REASON =
+	"This message could not be processed. Please try again.";
+
+const failureReason = (reason: unknown): string =>
+	reason instanceof MoveNotSettledError
+		? reason.message
+		: GENERIC_FAILURE_REASON;
+
+/**
+ * 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>
@@ -379,6 +448,7 @@ export const MessageOperations: Record<
 			authenticity: message.authenticity,
 			...(autoMoved ? { autoMoved } : {}),
 			...(labels.length > 0 ? { labels } : {}),
+			...(message.spamReport ? { spamReport: message.spamReport } : {}),
 		};
 
 		// Batch-fetch the resolved Address rows so each EnvelopeAddressResponse can
@@ -947,4 +1017,60 @@ export const MessageBulkOperations: Record<
 			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 }),
+		);
+	},
 };

package/src/handlers/outbox.test.ts

@@ -0,0 +1,294 @@
+/**
+ * Issue #604: composing a reply, sending it, and then letting one more autosave
+ * land 500'd the browser with "Internal server error" two seconds after a send
+ * that had actually succeeded.
+ *
+ * A PATCH against an entry that is no longer a draft is a foreseeable race, not
+ * a fault: the draft editor debounces its writes, so the last one can be in
+ * flight while the send flips the status. The designed answer is 409 — the
+ * entry is immutable now, and saying so truthfully is what lets a client stop.
+ *
+ * Driven through the real handlers, the real OutboxQueueService and the real
+ * error funnel, so what is asserted is the status code the browser receives.
+ * Only the queue and the store are stood in for.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import type { SQSClient } from "@aws-sdk/client-sqs";
+import type {
+	CreateOutboxMessageInput,
+	IAccountRepository,
+	IOutboxMessageRepository,
+	OutboxMessageItem,
+	UpdateOutboxMessageInput,
+} from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
+import { OutboxMessageStatus } from "@remit/domain-enums";
+import { OutboxQueueService } from "@remit/mailbox-service";
+import type { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
+import type { Context } from "openapi-backend";
+import { deriveAccountConfigId } from "../auth.js";
+import { handleError } from "../error.js";
+import { formatResponse } from "../response.js";
+import {
+	_resetForTest,
+	type RemitClient,
+	setClient,
+} from "../service/data-client.js";
+import { OutboxDetailOperations, OutboxOperations } from "./outbox.js";
+
+const SUB = "cognito-sub-604";
+const ACCOUNT_CONFIG_ID = deriveAccountConfigId(SUB);
+const ACCOUNT_ID = "acc-604";
+const ACCOUNT_EMAIL = "sender@example.com";
+
+const createInMemoryOutboxRepository = (): IOutboxMessageRepository => {
+	const rows = new Map<string, OutboxMessageItem>();
+	let sequence = 0;
+
+	const mustGet = (outboxMessageId: string): OutboxMessageItem => {
+		const row = rows.get(outboxMessageId);
+		if (!row) throw new NotFoundError(`No outbox message ${outboxMessageId}`);
+		return row;
+	};
+
+	const repository = {
+		create: async (
+			input: CreateOutboxMessageInput,
+		): Promise<OutboxMessageItem> => {
+			sequence += 1;
+			const now = Date.now();
+			const row: OutboxMessageItem = {
+				...input,
+				ccAddresses: input.ccAddresses ?? [],
+				bccAddresses: input.bccAddresses ?? [],
+				references: input.references ?? [],
+				outboxMessageId: `outbox-${sequence}`,
+				createdAt: now,
+				updatedAt: now,
+			};
+			rows.set(row.outboxMessageId, row);
+			return row;
+		},
+		get: async (
+			_accountConfigId: string,
+			outboxMessageId: string | string[],
+		) =>
+			Array.isArray(outboxMessageId)
+				? outboxMessageId.map(mustGet)
+				: mustGet(outboxMessageId),
+		update: async (
+			_accountConfigId: string,
+			outboxMessageId: string,
+			input: UpdateOutboxMessageInput,
+		): Promise<OutboxMessageItem> => {
+			const row = {
+				...mustGet(outboxMessageId),
+				...input,
+				updatedAt: Date.now(),
+			};
+			rows.set(outboxMessageId, row);
+			return row;
+		},
+		updateStatus: async (
+			accountConfigId: string,
+			outboxMessageId: string,
+			status: OutboxMessageItem["status"],
+		) => repository.update(accountConfigId, outboxMessageId, { status }),
+		markSent: async (
+			accountConfigId: string,
+			outboxMessageId: string,
+			fields: { sentAt: number; smtpMessageId?: string },
+		) =>
+			repository.update(accountConfigId, outboxMessageId, {
+				...fields,
+				status: OutboxMessageStatus.sent,
+			}),
+		delete: async (_accountConfigId: string, outboxMessageId: string) => {
+			rows.delete(outboxMessageId);
+		},
+		deleteMany: async (
+			_accountConfigId: string,
+			outboxMessageIds: string[],
+		) => {
+			for (const id of outboxMessageIds) rows.delete(id);
+		},
+		listByAccount: async () => ({
+			items: [...rows.values()],
+			continuationToken: null,
+		}),
+		listQueued: async () =>
+			[...rows.values()].filter(
+				(row) => row.status === OutboxMessageStatus.queued,
+			),
+	} as unknown as IOutboxMessageRepository;
+
+	return repository;
+};
+
+const acceptingSqsClient = (): SQSClient =>
+	({ send: async () => ({}) }) as unknown as SQSClient;
+
+const accountRepository = {
+	get: async () => ({
+		accountId: ACCOUNT_ID,
+		accountConfigId: ACCOUNT_CONFIG_ID,
+		email: ACCOUNT_EMAIL,
+	}),
+} as unknown as IAccountRepository;
+
+const installClient = (): void => {
+	const outboxMessage = createInMemoryOutboxRepository();
+	setClient({
+		outboxMessage,
+		account: accountRepository,
+		outboxQueue: new OutboxQueueService({
+			outboxMessageService: outboxMessage,
+			accountService: accountRepository,
+			sqsSmtpQueueUrl: "http://localhost:9324/queue/outbox-test",
+			sqsClient: acceptingSqsClient(),
+		}),
+	} as unknown as RemitClient);
+};
+
+const authorizedEvent = (body?: unknown): APIGatewayProxyEvent =>
+	({
+		body: body === undefined ? null : JSON.stringify(body),
+		requestContext: { authorizer: { claims: { sub: SUB } } },
+	}) as unknown as APIGatewayProxyEvent;
+
+const requestContext = (request: {
+	params?: Record<string, string>;
+	requestBody?: unknown;
+}): Context => ({ request }) as unknown as Context;
+
+type Handler = (
+	context: Context,
+	event: APIGatewayProxyEvent,
+) => Promise<Record<string, unknown>>;
+
+const createDraft =
+	OutboxOperations.OutboxOperations_createOutboxMessage as Handler;
+const sendMessage =
+	OutboxDetailOperations.OutboxDetailOperations_sendOutboxMessage as Handler;
+const updateDraft =
+	OutboxDetailOperations.OutboxDetailOperations_updateOutboxMessage as Handler;
+const deleteDraft =
+	OutboxDetailOperations.OutboxDetailOperations_deleteOutboxMessage as Handler;
+
+type Outcome =
+	| { readonly ok: true; readonly body: Record<string, unknown> }
+	| { readonly ok: false; readonly error: unknown };
+
+/** The response the browser would receive, error funnel included. */
+const respond = async (
+	run: () => Promise<Record<string, unknown>>,
+): Promise<APIGatewayProxyResult> => {
+	const outcome: Outcome = await run().then(
+		(body) => ({ ok: true, body }) as const,
+		(error: unknown) => ({ ok: false, error }) as const,
+	);
+	if (!outcome.ok) return handleError(outcome.error);
+	return formatResponse(outcome.body);
+};
+
+const sentOutboxMessageId = async (): Promise<string> => {
+	const draft = await createDraft(
+		requestContext({}),
+		authorizedEvent({
+			accountId: ACCOUNT_ID,
+			toAddresses: ["recipient@example.com"],
+			subject: "Re: the thing",
+			textBody: "on it",
+		}),
+	);
+	const outboxMessageId = draft.outboxMessageId;
+	assert.equal(typeof outboxMessageId, "string");
+
+	const sent = await sendMessage(
+		requestContext({ params: { outboxMessageId: String(outboxMessageId) } }),
+		authorizedEvent(),
+	);
+	assert.notEqual(sent.status, "draft");
+
+	return String(outboxMessageId);
+};
+
+afterEach(() => {
+	_resetForTest();
+});
+
+describe("an outbox entry that has left draft (#604)", () => {
+	it("answers a late autosave PATCH with 409, never a 500", async () => {
+		installClient();
+		const outboxMessageId = await sentOutboxMessageId();
+
+		const response = await respond(() =>
+			updateDraft(
+				requestContext({
+					params: { outboxMessageId },
+					requestBody: { subject: "Re: the thing", textBody: "on it!" },
+				}),
+				authorizedEvent(),
+			),
+		);
+
+		assert.equal(response.statusCode, 409);
+		const body = JSON.parse(response.body) as { message?: string };
+		assert.match(String(body.message), /can no longer be edited/);
+	});
+
+	it("refuses a second send with 409, never a 500", async () => {
+		installClient();
+		const outboxMessageId = await sentOutboxMessageId();
+
+		const response = await respond(() =>
+			sendMessage(
+				requestContext({ params: { outboxMessageId } }),
+				authorizedEvent(),
+			),
+		);
+
+		assert.equal(response.statusCode, 409);
+	});
+
+	it("refuses a discard with 409, never a 500", async () => {
+		installClient();
+		const outboxMessageId = await sentOutboxMessageId();
+
+		const response = await respond(() =>
+			deleteDraft(
+				requestContext({ params: { outboxMessageId } }),
+				authorizedEvent(),
+			),
+		);
+
+		assert.equal(response.statusCode, 409);
+	});
+
+	it("still accepts an autosave PATCH while the entry is a draft", async () => {
+		installClient();
+		const draft = await createDraft(
+			requestContext({}),
+			authorizedEvent({
+				accountId: ACCOUNT_ID,
+				toAddresses: ["recipient@example.com"],
+			}),
+		);
+
+		const response = await respond(() =>
+			updateDraft(
+				requestContext({
+					params: { outboxMessageId: String(draft.outboxMessageId) },
+					requestBody: { subject: "still editing" },
+				}),
+				authorizedEvent(),
+			),
+		);
+
+		assert.equal(response.statusCode, 200);
+		const body = JSON.parse(response.body) as { subject?: string };
+		assert.equal(body.subject, "still editing");
+	});
+});

package/src/index.ts

@@ -160,15 +160,18 @@ const rawHandler = async (event: APIGatewayProxyEvent, context: Context) =>
 
 			const origin = readOriginHeader(event.headers);
 
-			if (usesBetterAuthJwt()) {
-				const denied = await authenticateSelfHostRequest(event);
-				if (denied) return denied;
-			}
-
-			return runWithRequestContext({ origin }, () =>
-				api
-					.handleRequest(normalizeRequest(event), event, context)
-					.catch(handleError),
+			return runWithRequestContext(
+				{ origin, correlationId: context.awsRequestId },
+				async () => {
+					if (usesBetterAuthJwt()) {
+						const denied = await authenticateSelfHostRequest(event);
+						if (denied) return denied;
+					}
+
+					return api
+						.handleRequest(normalizeRequest(event), event, context)
+						.catch(handleError);
+				},
 			);
 		},
 	);

package/src/request-context.ts

@@ -2,6 +2,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 
 interface RequestContext {
 	origin?: string;
+	correlationId?: string;
 }
 
 const storage = new AsyncLocalStorage<RequestContext>();
@@ -12,6 +13,9 @@ export const runWithRequestContext = <T>(ctx: RequestContext, fn: () => T): T =>
 export const getRequestOrigin = (): string | undefined =>
 	storage.getStore()?.origin;
 
+export const getRequestCorrelationId = (): string | undefined =>
+	storage.getStore()?.correlationId;
+
 const parseAllowedOrigins = (): readonly string[] => {
 	const raw = process.env.CORS_ALLOWED_ORIGINS;
 	if (!raw) return [];

package/src/response.test.ts

@@ -1,7 +1,8 @@
 import assert from "node:assert/strict";
 import { afterEach, beforeEach, describe, it } from "node:test";
 import type { Context as OpenAPIContext } from "openapi-backend";
-import { postResponseHandler } from "./response.js";
+import { runWithRequestContext } from "./request-context.js";
+import { formatResponse, postResponseHandler } from "./response.js";
 
 type ValidateResponseFn = (
 	response: unknown,
@@ -105,3 +106,25 @@ describe("postResponseHandler validation gating", () => {
 		assert.equal(result.statusCode, 200);
 	});
 });
+
+// A bug report quotes the correlation id off the failing response. Without the
+// header it reads "(none)" and there is nothing to grep the server logs for.
+describe("the correlation id travels back on the response", () => {
+	it("carries the request's id, and exposes the header to the browser", () => {
+		const result = runWithRequestContext({ correlationId: "req-604" }, () =>
+			formatResponse({ message: "Conflict" }, 409),
+		);
+
+		assert.equal(result.headers?.["x-correlation-id"], "req-604");
+		assert.match(
+			String(result.headers?.["Access-Control-Expose-Headers"]),
+			/x-correlation-id/,
+		);
+	});
+
+	it("omits the header when the request carried no id", () => {
+		const result = formatResponse({ message: "Conflict" }, 409);
+
+		assert.equal(result.headers?.["x-correlation-id"], undefined);
+	});
+});

package/src/response.ts

@@ -1,7 +1,11 @@
 import { logger } from "@remit/logger-lambda";
 import type { APIGatewayProxyResult } from "aws-lambda";
 import type { Context as OpenAPIContext } from "openapi-backend";
-import { getRequestOrigin, resolveAllowedOrigin } from "./request-context.js";
+import {
+	getRequestCorrelationId,
+	getRequestOrigin,
+	resolveAllowedOrigin,
+} from "./request-context.js";
 
 export const formatResponse = (
 	body: Record<string, unknown>,
@@ -30,11 +34,23 @@ export const formatResponse = (
 		corsHeaders["Access-Control-Allow-Credentials"] = "true";
 	}
 
+	// The id the request's log lines are already tagged with. Returning it is
+	// what makes a bug report's "correlation id" resolve to a server-side line;
+	// the browser can only read a non-safelisted header when it is exposed.
+	const correlationId = getRequestCorrelationId();
+	const correlationHeaders: Record<string, string> = correlationId
+		? {
+				"x-correlation-id": correlationId,
+				"Access-Control-Expose-Headers": "x-correlation-id",
+			}
+		: {};
+
 	return {
 		statusCode: statusCode,
 		headers: {
 			"Content-Type": "application/json",
 			...corsHeaders,
+			...correlationHeaders,
 		},
 		body: JSON.stringify(body),
 	};

package/src/service/create-remit-client.ts

@@ -35,6 +35,7 @@ import {
 	MessageMoveService,
 	OutboxQueueService,
 	PlacementMoveService,
+	SpamReportService,
 } from "@remit/mailbox-service";
 import { createSearchService, type SearchService } from "@remit/search-service";
 import {
@@ -145,6 +146,11 @@ export interface RemitClient {
 	messageMove: MessageMoveService;
 	outboxQueue: OutboxQueueService;
 
+	// Report-spam / not-spam (block-and-move, unified from the old separate
+	// Block + Mark spam actions). Composed over `messageMove` and the same
+	// `flagPushService` instance `flagQueue` shares below.
+	spamReport: SpamReportService;
+
 	// Helper to create IMAP connection scope from accountId
 	createConnectionScope: (accountId: string) => Promise<ConnectionScope>;
 }
@@ -341,6 +347,15 @@ export const createRemitClient = (deps: RemitClientDeps): RemitClient => {
 		logger,
 	});
 
+	const messageMoveService = new MessageMoveService({
+		messageService: repositories.message,
+		mailboxService: repositories.mailbox,
+		mailboxSpecialUseService: repositories.mailboxSpecialUse,
+		threadMessageService: repositories.threadMessage,
+		sqsQueueUrl,
+		logger,
+	});
+
 	const bodySync = new BodySyncService(
 		repositories.message,
 		storage,
@@ -392,20 +407,22 @@ export const createRemitClient = (deps: RemitClientDeps): RemitClient => {
 			sqsQueueUrl,
 			logger,
 		}),
-		messageMove: new MessageMoveService({
-			messageService: repositories.message,
-			mailboxService: repositories.mailbox,
-			mailboxSpecialUseService: repositories.mailboxSpecialUse,
-			threadMessageService: repositories.threadMessage,
-			sqsQueueUrl,
-			logger,
-		}),
+		messageMove: messageMoveService,
 		outboxQueue: new OutboxQueueService({
 			outboxMessageService: repositories.outboxMessage,
 			accountService: repositories.account,
 			sqsSmtpQueueUrl,
 			logger,
 		}),
+		spamReport: new SpamReportService({
+			messageService: repositories.message,
+			addressService: repositories.address,
+			accountService: repositories.account,
+			mailboxSpecialUseService: repositories.mailboxSpecialUse,
+			messageMoveService,
+			flagPushService,
+			logger,
+		}),
 
 		createConnectionScope: buildConnectionScope(repositories.account, secrets),
 	};

package/src/service/data-client.test.ts

@@ -32,6 +32,7 @@ const REQUIRED_KEYS: ReadonlyArray<keyof RemitClient> = [
 	"mailboxQueue",
 	"messageMove",
 	"outboxQueue",
+	"spamReport",
 	"createConnectionScope",
 ] as const;
 

package/src/types.ts

@@ -54,6 +54,8 @@ export type OperationIds =
 	| "MessageBulkOperations_updateFlags"
 	| "MessageBulkOperations_copyMessages"
 	| "MessageBulkOperations_updateMessageLabels"
+	| "MessageBulkOperations_reportSpam"
+	| "MessageBulkOperations_notSpam"
 	| "TrashOperations_emptyTrash"
 	| "OutboxOperations_createOutboxMessage"
 	| "OutboxOperations_listOutboxMessages"