@remit/backend 0.0.105 → 0.0.107

package/package.json

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

package/src/handlers/account-oauth-start.test.ts

@@ -0,0 +1,190 @@
+/**
+ * What an operator can tell from the log when the Microsoft OAuth start fails.
+ *
+ * Every credential failure answers the same 500 with the same body, so the
+ * backend log for that request is the only place the four are told apart: an
+ * instance with no Microsoft app registered must not read like a live outage.
+ * Driven through the real handler so what is asserted is the line a deployment
+ * actually writes, correlation id and all.
+ */
+
+import assert from "node:assert/strict";
+import { randomUUID } from "node:crypto";
+import { after, before, describe, it } from "node:test";
+import { SecretsManagerClient } from "@aws-sdk/client-secrets-manager";
+import type { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
+import { captureStdout, restoreStdout } from "../stdout-capture-fixture.js";
+
+const WEB_ORIGIN = "https://mail.example.com";
+const START_PATH = "/accounts/oauth/microsoft/start";
+const SECRET_ARN =
+	"arn:aws:secretsmanager:eu-west-1:000000000000:secret:msoauth-AbCdEf";
+
+let handler: (
+	event: APIGatewayProxyEvent,
+	context: unknown,
+) => Promise<APIGatewayProxyResult>;
+
+const originalSend = SecretsManagerClient.prototype.send;
+let secretString: string | undefined;
+
+interface Outcome {
+	response: APIGatewayProxyResult;
+	log: string;
+	logged: string;
+}
+
+const headerOf = (
+	response: APIGatewayProxyResult,
+	name: string,
+): string | undefined => {
+	for (const [key, value] of Object.entries(response.headers ?? {})) {
+		if (key.toLowerCase() === name) return String(value);
+	}
+	return undefined;
+};
+
+const start = async (): Promise<Outcome> => {
+	const awsRequestId = `req-${randomUUID()}`;
+	const { result: response, logged } = await captureStdout(() =>
+		handler(
+			{
+				httpMethod: "POST",
+				path: START_PATH,
+				headers: {},
+				queryStringParameters: null,
+				body: JSON.stringify({ email: "matthijs@example.com" }),
+				requestContext: { authorizer: { claims: { sub: "cognito-sub" } } },
+			} as unknown as APIGatewayProxyEvent,
+			{ awsRequestId, functionName: "test" },
+		),
+	);
+
+	assert.equal(
+		headerOf(response, "x-correlation-id"),
+		awsRequestId,
+		"the id the client reports has to be the id the log lines carry",
+	);
+
+	const forThisRequest = logged
+		.split("\n")
+		.filter((line) => line.length > 0)
+		.map((line) => JSON.parse(line) as Record<string, unknown>)
+		.filter((line) => line.requestId === awsRequestId);
+
+	assert.ok(
+		forThisRequest.length > 0,
+		"the failure left no line carrying the correlation id the client was handed",
+	);
+
+	return { response, log: JSON.stringify(forThisRequest), logged };
+};
+
+/** The name each condition, and only that condition, puts in the log. */
+const NO_APP_REGISTERED = "MicrosoftOAuthNotConfigured";
+const SECRET_HAS_NO_STRING = "MicrosoftOAuthSecretEmpty";
+const SECRET_MISSING_FIELDS = "MicrosoftOAuthSecretIncomplete";
+const SECRET_IS_NOT_JSON = "MicrosoftOAuthSecretUnparseable";
+
+const CONDITIONS = [
+	NO_APP_REGISTERED,
+	SECRET_HAS_NO_STRING,
+	SECRET_MISSING_FIELDS,
+	SECRET_IS_NOT_JSON,
+];
+
+const assertNamesOnly = (log: string, condition: string): void => {
+	assert.ok(
+		log.includes(condition),
+		`the log for this request never names the condition ${condition}: ${log}`,
+	);
+	for (const other of CONDITIONS) {
+		if (other === condition) continue;
+		assert.ok(
+			!log.includes(other),
+			`the log also names ${other}, so the two conditions are indistinguishable`,
+		);
+	}
+};
+
+const assertGenericFiveHundred = (response: APIGatewayProxyResult): void => {
+	assert.equal(response.statusCode, 500);
+	assert.deepEqual(JSON.parse(response.body), {
+		message: "Internal server error",
+	});
+};
+
+before(async () => {
+	process.env.LOG_LEVEL = "error";
+	process.env.DATA_BACKEND = "sqlite";
+	process.env.CORS_ALLOWED_ORIGINS = WEB_ORIGIN;
+	process.env.MSOAUTH_REDIRECT_URI = `${WEB_ORIGIN}/accounts/oauth/microsoft/callback`;
+
+	SecretsManagerClient.prototype.send = (async () => ({
+		SecretString: secretString,
+	})) as typeof SecretsManagerClient.prototype.send;
+
+	({ handler } = (await import("../index.js")) as unknown as {
+		handler: typeof handler;
+	});
+});
+
+after(() => {
+	SecretsManagerClient.prototype.send = originalSend;
+	restoreStdout();
+});
+
+describe("a Microsoft OAuth start that cannot load its credentials", () => {
+	it("names an instance with no Microsoft app registered", async () => {
+		delete process.env.MSOAUTH_CLIENT_ID;
+		delete process.env.MSOAUTH_CLIENT_SECRET;
+		delete process.env.MSOAUTH_SECRET_ARN;
+
+		const { response, log } = await start();
+
+		assertGenericFiveHundred(response);
+		assertNamesOnly(log, NO_APP_REGISTERED);
+	});
+
+	it("names a secret that carries no string value", async () => {
+		delete process.env.MSOAUTH_CLIENT_ID;
+		delete process.env.MSOAUTH_CLIENT_SECRET;
+		process.env.MSOAUTH_SECRET_ARN = SECRET_ARN;
+		secretString = undefined;
+
+		const { response, log } = await start();
+
+		assertGenericFiveHundred(response);
+		assertNamesOnly(log, SECRET_HAS_NO_STRING);
+	});
+
+	it("names a secret whose credential fields are absent", async () => {
+		delete process.env.MSOAUTH_CLIENT_ID;
+		delete process.env.MSOAUTH_CLIENT_SECRET;
+		process.env.MSOAUTH_SECRET_ARN = SECRET_ARN;
+		secretString = JSON.stringify({ clientId: "an-app-id" });
+
+		const { response, log } = await start();
+
+		assertGenericFiveHundred(response);
+		assertNamesOnly(log, SECRET_MISSING_FIELDS);
+	});
+
+	it("names a secret that is not JSON without quoting what it holds", async () => {
+		const secretMaterial = "s3cr3t-not-json-9d41c0b7";
+		delete process.env.MSOAUTH_CLIENT_ID;
+		delete process.env.MSOAUTH_CLIENT_SECRET;
+		process.env.MSOAUTH_SECRET_ARN = SECRET_ARN;
+		secretString = secretMaterial;
+
+		const { response, log, logged } = await start();
+
+		assertGenericFiveHundred(response);
+		assertNamesOnly(log, SECRET_IS_NOT_JSON);
+		assert.equal(
+			logged.includes(secretMaterial),
+			false,
+			"a parse failure quoting the secret into the log turns a misconfiguration into a leak",
+		);
+	});
+});

package/src/handlers/account-oauth.ts

@@ -123,6 +123,21 @@ function getSecretsManagerClient(): SecretsManagerClient {
 	return smClient;
 }
 
+type MsOAuthCredentialFailure =
+	| "MicrosoftOAuthNotConfigured"
+	| "MicrosoftOAuthSecretEmpty"
+	| "MicrosoftOAuthSecretIncomplete"
+	| "MicrosoftOAuthSecretUnparseable";
+
+function credentialFailure(
+	name: MsOAuthCredentialFailure,
+	message: string,
+): Error {
+	const error = new Error(message);
+	error.name = name;
+	return error;
+}
+
 async function getMsOAuthCredentials(): Promise<MsOAuthCredentials> {
 	const config = getMsOAuthConfig();
 
@@ -133,8 +148,9 @@ async function getMsOAuthCredentials(): Promise<MsOAuthCredentials> {
 
 	// Production: fetch from Secrets Manager
 	if (!config.secretArn) {
-		throw new Error(
-			"MSOAUTH_SECRET_ARN is required when MSOAUTH_CLIENT_ID/MSOAUTH_CLIENT_SECRET are not set",
+		throw credentialFailure(
+			"MicrosoftOAuthNotConfigured",
+			"No Microsoft OAuth credentials are configured on this instance: set MSOAUTH_CLIENT_ID and MSOAUTH_CLIENT_SECRET, or MSOAUTH_SECRET_ARN",
 		);
 	}
 
@@ -144,13 +160,29 @@ async function getMsOAuthCredentials(): Promise<MsOAuthCredentials> {
 	);
 
 	if (!result.SecretString) {
-		throw new Error("MSOAUTH secret has no SecretString value");
+		throw credentialFailure(
+			"MicrosoftOAuthSecretEmpty",
+			"The Microsoft OAuth secret named by MSOAUTH_SECRET_ARN holds no SecretString",
+		);
+	}
+
+	const parsed = await safeJsonParse<MsOAuthCredentials>(
+		result.SecretString,
+	).catch(() => null);
+	if (!parsed) {
+		throw credentialFailure(
+			"MicrosoftOAuthSecretUnparseable",
+			"The Microsoft OAuth secret named by MSOAUTH_SECRET_ARN does not hold a JSON object",
+		);
 	}
 
-	const parsed = JSON.parse(result.SecretString) as MsOAuthCredentials;
-	if (!parsed.clientId || !parsed.clientSecret) {
-		throw new Error(
-			"MSOAUTH secret must contain clientId and clientSecret fields",
+	const absent = (["clientId", "clientSecret"] as const).filter(
+		(field) => !parsed[field],
+	);
+	if (absent.length > 0) {
+		throw credentialFailure(
+			"MicrosoftOAuthSecretIncomplete",
+			`The Microsoft OAuth secret named by MSOAUTH_SECRET_ARN is missing ${absent.join(" and ")}`,
 		);
 	}
 

package/src/handlers/message.test.ts

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
+import { MessagePlacementUnsettledError } from "@remit/data-ports/errors";
 import {
 	MoveNotSettledError,
 	NoJunkMailboxError,
@@ -41,6 +42,32 @@ describe("settleSpamReportBulk", () => {
 		assert.notEqual(reason, GENERIC_FAILURE_REASON);
 	});
 
+	// A refusal the move gate raises used to collapse to the generic retry copy,
+	// which is a dead end for the reason no retry clears (#665).
+	it("words a placement refusal from its reason, never from the server's sentence", async () => {
+		const outcome = await settleSpamReportBulk(
+			["msg-1", "msg-2"],
+			async (messageId) => {
+				throw new MessagePlacementUnsettledError(
+					`Message ${messageId} was not acted on: its folder and uid do not name the same message`,
+					"acc-1",
+					messageId,
+					messageId === "msg-1" ? "in_flight" : "unverified",
+				);
+			},
+		);
+
+		const [inFlight, unverified] = outcome.failures?.map((f) => f.reason) ?? [];
+		assert.match(inFlight ?? "", /try again in a moment/i);
+		assert.match(unverified ?? "", /sync the folder/i);
+		assert.doesNotMatch(unverified ?? "", /try again in a moment/i);
+		for (const reason of [inFlight, unverified]) {
+			assert.notEqual(reason, GENERIC_FAILURE_REASON);
+			assert.doesNotMatch(reason ?? "", /folder and uid/);
+			assert.doesNotMatch(reason ?? "", /acc-1/);
+		}
+	});
+
 	it("omits failures entirely when every message succeeds", async () => {
 		const outcome = await settleSpamReportBulk(
 			["msg-1", "msg-2"],

package/src/handlers/message.ts

@@ -7,6 +7,7 @@ import type { MailboxItem } from "@remit/data-ports";
 import {
 	BadRequestError,
 	ForbiddenError,
+	MessagePlacementUnsettledError,
 	NotFoundError,
 	UnrecoverableBodyError,
 } from "@remit/data-ports/errors";
@@ -356,13 +357,35 @@ export const GENERIC_FAILURE_REASON =
  * each names what happened and what the user can do about it, which the
  * generic text cannot.
  */
-const DESIGNED_FAILURES = [MoveNotSettledError, NoJunkMailboxError];
+const DESIGNED_FAILURES = [
+	MoveNotSettledError,
+	NoJunkMailboxError,
+	MessagePlacementUnsettledError,
+];
 
 const isDesignedFailure = (reason: unknown): reason is Error =>
 	DESIGNED_FAILURES.some((designed) => reason instanceof designed);
 
-const failureReason = (reason: unknown): string =>
-	isDesignedFailure(reason) ? reason.message : GENERIC_FAILURE_REASON;
+/**
+ * The placement refusal is the one designed outcome whose own message is not
+ * the text to ship: it names a uuid and no remedy, and the two reasons do not
+ * share a remedy — an in-flight move settles on its own, an abandoned one only
+ * clears once the folder is resynced. Worded here off `details.reason`, the way
+ * the delete path words the same refusal for the client.
+ */
+const placementRefusalReason = (
+	error: MessagePlacementUnsettledError,
+): string =>
+	error.publicApiError?.details?.reason === "unverified"
+		? "An earlier move of this message never finished, so where it sits is unknown. Sync the folder, then report it again."
+		: "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

package/src/log-redaction.test.ts

@@ -11,25 +11,7 @@
 import assert from "node:assert/strict";
 import { after, before, describe, it } from "node:test";
 import type { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
-
-// pino writes to `process.stdout` only when its `write` has been replaced, so
-// the hook goes in before the logger is imported — which every import below
-// does transitively. Writes pass through whenever nothing is capturing, so the
-// test runner's own output still reaches the terminal.
-const originalWrite = process.stdout.write.bind(process.stdout);
-const written: string[] = [];
-let capturing = false;
-
-process.stdout.write = ((
-	chunk: string | Uint8Array,
-	...rest: unknown[]
-): boolean => {
-	if (capturing && typeof chunk === "string") {
-		written.push(chunk);
-		return true;
-	}
-	return (originalWrite as (...args: unknown[]) => boolean)(chunk, ...rest);
-}) as typeof process.stdout.write;
+import { captureStdout, restoreStdout } from "./stdout-capture-fixture.js";
 
 process.env.LOG_LEVEL = "trace";
 
@@ -45,19 +27,6 @@ let handler: (
 ) => Promise<APIGatewayProxyResult>;
 let cleanup: () => void;
 
-const capture = async (
-	run: () => Promise<APIGatewayProxyResult>,
-): Promise<{ response: APIGatewayProxyResult; logged: string }> => {
-	written.length = 0;
-	capturing = true;
-	try {
-		const response = await run();
-		return { response, logged: written.join("") };
-	} finally {
-		capturing = false;
-	}
-};
-
 const send = (
 	event: Partial<APIGatewayProxyEvent> & { httpMethod: string; path: string },
 ): Promise<APIGatewayProxyResult> =>
@@ -85,7 +54,7 @@ before(async () => {
 
 after(() => {
 	_resetForTest();
-	process.stdout.write = originalWrite as typeof process.stdout.write;
+	restoreStdout();
 	cleanup();
 });
 
@@ -93,7 +62,7 @@ describe("what a request leaves in the log", () => {
 	it("never writes the feed token a subscriber polls with", async () => {
 		const { token } = mintCalendarFeedToken();
 
-		const { response, logged } = await capture(() =>
+		const { result: response, logged } = await captureStdout(() =>
 			send({ httpMethod: "GET", path: `/feeds/calendar/${token}.ics` }),
 		);
 
@@ -119,7 +88,7 @@ describe("what a request leaves in the log", () => {
 		// request reaches validation — where the whole parsed request, headers and
 		// all, used to be logged. The delete refuses because it declares
 		// `calendarId` as a required query parameter and none was sent.
-		const { response, logged } = await capture(() =>
+		const { result: response, logged } = await captureStdout(() =>
 			send({
 				httpMethod: "DELETE",
 				path: "/calendar-events/8f14e45f-ceea-467a-9c9e-9c9e9c9e9c9e",

package/src/stdout-capture-fixture.ts

@@ -0,0 +1,40 @@
+/**
+ * A test's view of what a request wrote to the log.
+ *
+ * pino writes through `process.stdout` once its `write` is replaced, so the hook
+ * is installed when this module is evaluated — import it above anything that
+ * pulls in the logger. Writes pass through whenever nothing is capturing, so the
+ * test runner's own output still reaches the terminal.
+ */
+
+const originalWrite = process.stdout.write.bind(process.stdout);
+const written: string[] = [];
+let capturing = false;
+
+process.stdout.write = ((
+	chunk: string | Uint8Array,
+	...rest: unknown[]
+): boolean => {
+	if (capturing && typeof chunk === "string") {
+		written.push(chunk);
+		return true;
+	}
+	return (originalWrite as (...args: unknown[]) => boolean)(chunk, ...rest);
+}) as typeof process.stdout.write;
+
+export const captureStdout = async <T>(
+	run: () => Promise<T>,
+): Promise<{ result: T; logged: string }> => {
+	written.length = 0;
+	capturing = true;
+	try {
+		const result = await run();
+		return { result, logged: written.join("") };
+	} finally {
+		capturing = false;
+	}
+};
+
+export const restoreStdout = (): void => {
+	process.stdout.write = originalWrite as typeof process.stdout.write;
+};