@remit/backend 0.0.56 → 0.0.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/backend",
-  "version": "0.0.56",
+  "version": "0.0.58",
   "description": "Remit Mail Inspector API backend",
   "license": "MIT",
   "author": "",
@@ -50,7 +50,7 @@
     "@types/swagger-ui-express": "^4.1.8",
     "better-sqlite3": "^12.11.1",
     "electrodb": "*",
-    "esbuild": "^0.27.7",
+    "esbuild": "^0.28.1",
     "express": "^5.1.0",
     "swagger-ui-express": "^5.0.1",
     "tsx": "*"

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/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"