@remit/backend 0.0.1

package/src/derive/filterThreadCriteria.test.ts

@@ -0,0 +1,119 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { ThreadMessageResponse } from "@remit/api-openapi-types";
+import { MessageCategory, SenderTrust, StarColor } from "@remit/domain-enums";
+import {
+	filterByOffRowCriteria,
+	hasOffRowCriteria,
+} from "./filterThreadCriteria.js";
+
+const row = (
+	overrides: Partial<ThreadMessageResponse>,
+): ThreadMessageResponse => ({
+	threadMessageId: "tm",
+	threadId: "t",
+	messageId: "m",
+	accountConfigId: "acc",
+	mailboxId: "mb",
+	subject: "s",
+	fromEmail: "a@example.com",
+	fromName: "A",
+	sentDate: 0,
+	isRead: false,
+	hasAttachment: false,
+	hasStars: false,
+	star: StarColor.None,
+	isDeleted: false,
+	snippet: "",
+	createdAt: 0,
+	updatedAt: 0,
+	senderTrust: SenderTrust.Unknown,
+	...overrides,
+});
+
+describe("hasOffRowCriteria", () => {
+	it("is false for an empty criteria object", () => {
+		assert.equal(hasOffRowCriteria({}), false);
+	});
+
+	it("is false for empty arrays", () => {
+		assert.equal(hasOffRowCriteria({ senderTrust: [], category: [] }), false);
+	});
+
+	it("is true when any criterion is set", () => {
+		assert.equal(hasOffRowCriteria({ senderTrust: [SenderTrust.Vip] }), true);
+		assert.equal(hasOffRowCriteria({ dkimMismatch: false }), true);
+	});
+});
+
+describe("filterByOffRowCriteria", () => {
+	it("returns rows untouched when no criteria are active", () => {
+		const rows = [row({}), row({})];
+		assert.equal(filterByOffRowCriteria(rows, {}).length, 2);
+	});
+
+	it("filters by senderTrust any-of", () => {
+		const rows = [
+			row({ senderTrust: SenderTrust.Vip }),
+			row({ senderTrust: SenderTrust.Wellknown }),
+			row({ senderTrust: SenderTrust.Unknown }),
+		];
+		const result = filterByOffRowCriteria(rows, {
+			senderTrust: [SenderTrust.Vip, SenderTrust.Wellknown],
+		});
+		assert.equal(result.length, 2);
+		assert.ok(result.every((r) => r.senderTrust !== SenderTrust.Unknown));
+	});
+
+	it("filters by category any-of and excludes rows with no category", () => {
+		const rows = [
+			row({ category: MessageCategory.newsletter }),
+			row({ category: MessageCategory.personal }),
+			row({ category: undefined }),
+		];
+		const result = filterByOffRowCriteria(rows, {
+			category: [MessageCategory.newsletter],
+		});
+		assert.equal(result.length, 1);
+		assert.equal(result[0].category, MessageCategory.newsletter);
+	});
+
+	it("filters by dkimMismatch and never matches rows lacking an authenticity signal", () => {
+		const rows = [
+			row({ authenticity: { fromDomain: "x", dkimMismatch: false } }),
+			row({ authenticity: { fromDomain: "y", dkimMismatch: true } }),
+			row({ authenticity: undefined }),
+		];
+		const aligned = filterByOffRowCriteria(rows, { dkimMismatch: false });
+		assert.equal(aligned.length, 1);
+		assert.equal(aligned[0].authenticity?.dkimMismatch, false);
+
+		const mismatched = filterByOffRowCriteria(rows, { dkimMismatch: true });
+		assert.equal(mismatched.length, 1);
+		assert.equal(mismatched[0].authenticity?.dkimMismatch, true);
+	});
+
+	it("ANDs criteria together (Rescue shape: trust set + dkim aligned)", () => {
+		const rows = [
+			row({
+				senderTrust: SenderTrust.Vip,
+				authenticity: { fromDomain: "x", dkimMismatch: false },
+			}),
+			row({
+				senderTrust: SenderTrust.Vip,
+				authenticity: { fromDomain: "y", dkimMismatch: true },
+			}),
+			row({
+				senderTrust: SenderTrust.Unknown,
+				authenticity: { fromDomain: "z", dkimMismatch: false },
+			}),
+		];
+		const result = filterByOffRowCriteria(rows, {
+			senderTrust: [SenderTrust.Vip, SenderTrust.Wellknown],
+			dkimMismatch: false,
+		});
+		assert.equal(result.length, 1);
+		assert.equal(result[0].senderTrust, SenderTrust.Vip);
+		assert.equal(result[0].authenticity?.dkimMismatch, false);
+	});
+});

package/src/derive/filterThreadCriteria.ts

@@ -0,0 +1,60 @@
+import type {
+	MessageCategory,
+	SenderTrust,
+	ThreadMessageResponse,
+} from "@remit/api-openapi-types";
+
+/**
+ * Off-row search criteria — fields that live on the underlying Message/Address,
+ * not on the ThreadMessage DynamoDB item. They are resolved by enriching the
+ * windowed rows (see enrichThreadRows) and filtering in app code, because no
+ * index or FilterExpression can serve them.
+ */
+export interface OffRowCriteria {
+	senderTrust?: SenderTrust[];
+	category?: MessageCategory[];
+	dkimMismatch?: boolean;
+}
+
+export const hasOffRowCriteria = (criteria: OffRowCriteria): boolean =>
+	Boolean(criteria.senderTrust?.length) ||
+	Boolean(criteria.category?.length) ||
+	criteria.dkimMismatch !== undefined;
+
+/**
+ * Filter enriched rows by the off-row criteria. Each active criterion is an
+ * any-of set (AND across criteria, OR within a set). A row with no `category`
+ * never matches a category filter; a row with no `authenticity` signal never
+ * matches a `dkimMismatch` filter (absence means no signal, not a verdict).
+ */
+export const filterByOffRowCriteria = (
+	rows: ThreadMessageResponse[],
+	criteria: OffRowCriteria,
+): ThreadMessageResponse[] => {
+	if (!hasOffRowCriteria(criteria)) return rows;
+
+	const trustSet = criteria.senderTrust?.length
+		? new Set(criteria.senderTrust)
+		: undefined;
+	const categorySet = criteria.category?.length
+		? new Set(criteria.category)
+		: undefined;
+	const { dkimMismatch } = criteria;
+
+	return rows.filter((row) => {
+		if (trustSet && !trustSet.has(row.senderTrust)) return false;
+		if (
+			categorySet &&
+			(row.category === undefined || !categorySet.has(row.category))
+		) {
+			return false;
+		}
+		if (
+			dkimMismatch !== undefined &&
+			row.authenticity?.dkimMismatch !== dkimMismatch
+		) {
+			return false;
+		}
+		return true;
+	});
+};

package/src/derive/pendingMoveCounts.ts

@@ -0,0 +1,90 @@
+import type { MailboxItem } from "@remit/data-ports";
+
+/**
+ * The subset of a pending placement-move marker (issue #1271) this
+ * derivation needs — decoupled from the concrete marker type so it stays a
+ * pure function over plain data.
+ */
+export interface PendingPlacementMove {
+	sourceMailboxId: string;
+	destinationMailboxId: string;
+}
+
+/**
+ * The subset of a pending flag-push marker (issue #1273) this derivation
+ * needs. Only `\Seen` markers are meaningful here — `mailboxId` is the
+ * marker's denormalized "last-known" mailbox, the same read-time-only hint
+ * `applyPendingMoveCountPrediction` already tolerates for placement moves.
+ */
+export interface PendingUnseenFlagPush {
+	mailboxId: string;
+	operation: "add" | "remove";
+}
+
+/**
+ * Adjusts `messageCount` and `unseenCount` on a set of mailboxes to reflect
+ * every pending placement move (issue #1271) and pending `\Seen` flag push
+ * (issue #1273): a prediction applied at READ TIME, never written back to
+ * storage (epic #1281 invariant 4). Stored counts are refreshed only by
+ * mailbox-sync re-reading IMAP.
+ *
+ * - A pending move has already relocated the message locally
+ *   (`ThreadMessage.mailboxId`), so its destination folder's live listing
+ *   outnumbers the stored `messageCount` by one until the marker confirms
+ *   and a resync catches up.
+ * - A pending `\Seen` push has already flipped `ThreadMessage.isRead`
+ *   locally: `add` (marked read) means the stored `unseenCount` is one HIGH
+ *   until the push confirms; `remove` (marked unread) means it is one LOW.
+ *   Only `\Seen` markers carry read/unread state — a pending `\Flagged`
+ *   (star) marker never adjusts either count, same reasoning the placement
+ *   move prediction already applies to its own scope.
+ *
+ * Pure: takes the mailboxes and the pending markers as plain input, returns a
+ * new array. Never mutates its arguments.
+ */
+export const applyPendingMoveCountPrediction = (
+	mailboxes: readonly MailboxItem[],
+	pendingMoves: readonly PendingPlacementMove[],
+	pendingUnseenFlagPushes: readonly PendingUnseenFlagPush[] = [],
+): MailboxItem[] => {
+	if (pendingMoves.length === 0 && pendingUnseenFlagPushes.length === 0) {
+		return [...mailboxes];
+	}
+
+	const messageCountDelta = new Map<string, number>();
+	for (const move of pendingMoves) {
+		if (move.sourceMailboxId === move.destinationMailboxId) continue;
+		messageCountDelta.set(
+			move.sourceMailboxId,
+			(messageCountDelta.get(move.sourceMailboxId) ?? 0) - 1,
+		);
+		messageCountDelta.set(
+			move.destinationMailboxId,
+			(messageCountDelta.get(move.destinationMailboxId) ?? 0) + 1,
+		);
+	}
+
+	const unseenCountDelta = new Map<string, number>();
+	for (const push of pendingUnseenFlagPushes) {
+		const adjustment = push.operation === "add" ? -1 : 1;
+		unseenCountDelta.set(
+			push.mailboxId,
+			(unseenCountDelta.get(push.mailboxId) ?? 0) + adjustment,
+		);
+	}
+
+	return mailboxes.map((mailbox) => {
+		const messageAdjustment = messageCountDelta.get(mailbox.mailboxId);
+		const unseenAdjustment = unseenCountDelta.get(mailbox.mailboxId);
+		if (!messageAdjustment && !unseenAdjustment) return mailbox;
+		return {
+			...mailbox,
+			messageCount: messageAdjustment
+				? Math.max(0, mailbox.messageCount + messageAdjustment)
+				: mailbox.messageCount,
+			unseenCount: unseenAdjustment
+				? Math.max(0, mailbox.unseenCount + unseenAdjustment)
+				: mailbox.unseenCount,
+		};
+	});
+};

package/src/derive/senderTrust.test.ts

@@ -0,0 +1,67 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { AddressFlags } from "@remit/api-openapi-types";
+import { deriveSenderTrust } from "./senderTrust.js";
+
+// AddressFlagBase requires setAt; deriveSenderTrust only reads `value`, so the
+// timestamp value is irrelevant to these assertions.
+const SET_AT = 1_700_000_000_000;
+
+describe("deriveSenderTrust", () => {
+	it("returns 'unknown' when flags is undefined", () => {
+		assert.equal(deriveSenderTrust(undefined), "unknown");
+	});
+
+	it("returns 'unknown' for an empty flags object", () => {
+		assert.equal(deriveSenderTrust({}), "unknown");
+	});
+
+	it("returns 'unknown' when wellknown.value is false", () => {
+		const flags: AddressFlags = { wellknown: { value: false, setAt: SET_AT } };
+		assert.equal(deriveSenderTrust(flags), "unknown");
+	});
+
+	it("returns 'wellknown' when wellknown.value is true", () => {
+		const flags: AddressFlags = { wellknown: { value: true, setAt: SET_AT } };
+		assert.equal(deriveSenderTrust(flags), "wellknown");
+	});
+
+	it("returns 'vip' when vip.value is true", () => {
+		const flags: AddressFlags = { vip: { value: true, setAt: SET_AT } };
+		assert.equal(deriveSenderTrust(flags), "vip");
+	});
+
+	it("returns 'unknown' when vip.value is false", () => {
+		const flags: AddressFlags = { vip: { value: false, setAt: SET_AT } };
+		assert.equal(deriveSenderTrust(flags), "unknown");
+	});
+
+	it("vip wins over wellknown when both are true", () => {
+		const flags: AddressFlags = {
+			vip: { value: true, setAt: SET_AT },
+			wellknown: { value: true, setAt: SET_AT },
+		};
+		assert.equal(deriveSenderTrust(flags), "vip");
+	});
+
+	it("falls back to wellknown when vip is false but wellknown is true", () => {
+		const flags: AddressFlags = {
+			vip: { value: false, setAt: SET_AT },
+			wellknown: { value: true, setAt: SET_AT },
+		};
+		assert.equal(deriveSenderTrust(flags), "wellknown");
+	});
+
+	it("ignores trusted flag (orthogonal axis)", () => {
+		const flags: AddressFlags = { trusted: { value: true, setAt: SET_AT } };
+		assert.equal(deriveSenderTrust(flags), "unknown");
+	});
+
+	it("ignores trusted even when wellknown is also set", () => {
+		const flags: AddressFlags = {
+			trusted: { value: true, setAt: SET_AT },
+			wellknown: { value: true, setAt: SET_AT },
+		};
+		assert.equal(deriveSenderTrust(flags), "wellknown");
+	});
+});

package/src/derive/senderTrust.ts

@@ -0,0 +1,23 @@
+import type { AddressFlags } from "@remit/api-openapi-types";
+import { SenderTrust } from "@remit/domain-enums";
+
+export type SenderTrustValue = (typeof SenderTrust)[keyof typeof SenderTrust];
+
+/**
+ * Derive the SenderTrust discriminator from an Address's flags map.
+ *
+ * Precedence (per EDD #232):
+ *   flags.vip.value === true       → "vip"
+ *   flags.wellknown.value === true → "wellknown"
+ *   otherwise                      → "unknown"
+ *
+ * Pure function, no I/O. Frontend never derives this — single source of
+ * truth for the UI badge state.
+ */
+export const deriveSenderTrust = (
+	flags: AddressFlags | undefined,
+): SenderTrustValue => {
+	if (flags?.vip?.value === true) return SenderTrust.Vip;
+	if (flags?.wellknown?.value === true) return SenderTrust.Wellknown;
+	return SenderTrust.Unknown;
+};

package/src/error.ts

@@ -0,0 +1,55 @@
+import { logger } from "@remit/logger-lambda";
+import type { APIGatewayProxyResult } from "aws-lambda";
+import { formatResponse } from "./response.js";
+
+export const handleError = async (
+	error: unknown,
+): Promise<APIGatewayProxyResult> => {
+	if (error instanceof Error) {
+		if ("statusCode" in error) {
+			logger.error(
+				{
+					error: error.message,
+					statusCode: error.statusCode,
+					stack: error.stack,
+				},
+				"Error with statusCode",
+			);
+			return formatResponse(
+				{ message: error.message },
+				error.statusCode as number,
+			);
+		}
+
+		if (error.name === "ElectroError") {
+			// DynamoDB client/infrastructure errors should be 500
+			// These contain "aws-error" in the message or reference URL
+			const isInfrastructureError =
+				error.message.includes("aws-error") ||
+				error.message.includes("DynamoDB client");
+
+			const statusCode = isInfrastructureError ? 500 : 400;
+			const logMessage = isInfrastructureError
+				? "DynamoDB infrastructure error"
+				: "ElectroError";
+
+			logger.error({ error: error.message, stack: error.stack }, logMessage);
+
+			// Don't expose internal details for infrastructure errors
+			const responseMessage = isInfrastructureError
+				? "Database temporarily unavailable"
+				: error.message;
+
+			return formatResponse({ message: responseMessage }, statusCode);
+		}
+
+		logger.error(
+			{ error: error.message, name: error.name, stack: error.stack },
+			"Unhandled Error",
+		);
+		return formatResponse({ message: "Internal server error" }, 500);
+	}
+
+	logger.error({ error: JSON.stringify(error) }, "Unknown error type");
+	return formatResponse({ message: "Internal server error" }, 500);
+};

package/src/handlers/account-guards.ts

@@ -0,0 +1,137 @@
+import type {
+	AccountResponse,
+	FolderAppointment,
+} from "@remit/api-openapi-types";
+import type { AccountItem } from "@remit/data-ports";
+import { ConflictError } from "@remit/data-ports/errors";
+import { AccountAuthType } from "@remit/domain-enums";
+import type { AccountOverrides } from "./account-overrides.js";
+import type { AccountSignature } from "./account-signature.js";
+
+/**
+ * Natural key identifying "the same mailbox in the same place" within an
+ * account config. IMAP host and login username are both case-insensitive, so we
+ * fold to lowercase before comparing. Used as the explicit server-side
+ * uniqueness key now that message identity is account-scoped (entropy per
+ * onboard) and no longer incidentally dedups duplicate onboards (#633/#635).
+ */
+export interface MailboxNaturalKey {
+	imapHost: string;
+	username: string;
+}
+
+const mailboxKeyOf = (key: MailboxNaturalKey): string =>
+	`${key.imapHost.toLowerCase()}\u0000${key.username.toLowerCase()}`;
+
+/**
+ * Find an existing ACTIVE (non-deleted) account that occupies the same
+ * mailbox-in-the-same-place as `key`. Soft-deleted accounts are ignored so a
+ * re-onboard after delete still succeeds.
+ *
+ * Callers pass the accounts already scoped to one account config (the natural
+ * key's accountConfigId component), so this only matches on host + username.
+ */
+export const findActiveDuplicateMailbox = (
+	existing: AccountItem[],
+	key: MailboxNaturalKey,
+): AccountItem | undefined => {
+	const target = mailboxKeyOf(key);
+	return existing.find(
+		(account) =>
+			!account.deletedAt &&
+			mailboxKeyOf({
+				imapHost: account.imapHost,
+				username: account.username,
+			}) === target,
+	);
+};
+
+/**
+ * Reject the create when an active account already onboards the same mailbox in
+ * the same place. Surfaces as a typed 409 ConflictError so the web-client can
+ * show a "already added" message instead of silently creating a duplicate.
+ */
+export const assertNoDuplicateMailbox = (
+	existing: AccountItem[],
+	key: MailboxNaturalKey,
+): void => {
+	const duplicate = findActiveDuplicateMailbox(existing, key);
+	if (!duplicate) return;
+	throw new ConflictError(
+		`An account for ${key.username} on ${key.imapHost} already exists`,
+	);
+};
+
+/** Rejects OAuth accounts that must go through the dedicated connect flow. */
+export const assertNotOAuthCreate = (authType: string | undefined): void => {
+	if (authType === AccountAuthType.OauthMicrosoft) {
+		throw Object.assign(new Error("Bad Request"), {
+			status: 400,
+			message:
+				"OAuth accounts must be created via the OAuth connect flow (POST /accounts/oauth/microsoft/start)",
+		});
+	}
+};
+
+/** Rejects password-auth account creation when no password is supplied. */
+export const assertPasswordProvided = (
+	authType: string | undefined,
+	password: string | undefined,
+): void => {
+	const isPasswordAuth = authType === AccountAuthType.Password || !authType;
+	if (isPasswordAuth && !password) {
+		throw Object.assign(new Error("Bad Request"), {
+			status: 400,
+			message:
+				"password is required when authType is 'password' (or when authType is omitted)",
+		});
+	}
+};
+
+// SECURITY: passwordHash, oauthRefreshTokenHash, and smtpPasswordHash are
+// intentionally omitted — never expose token material in API responses.
+// Display name, mute flag, and signatures live in per-account AccountSetting
+// rows (RFC 032); the caller resolves them and passes them in. Absent means the
+// override is unset. `folderAppointments` (RFC 032 exclusive-folder-appointment,
+// #976) is resolved the same way — persisted rows merged with server-proposed
+// defaults for any unfilled role — via `resolveFolderAppointments`.
+export const toAccountResponse = (
+	account: AccountItem,
+	signature: AccountSignature = {},
+	overrides: AccountOverrides = {},
+	folderAppointments: FolderAppointment[] = [],
+): AccountResponse => ({
+	accountId: account.accountId,
+	accountConfigId: account.accountConfigId,
+	displayName: overrides.displayName,
+	username: account.username,
+	email: account.email,
+	authType: account.authType ?? AccountAuthType.Password,
+	imapHost: account.imapHost,
+	imapPort: account.imapPort,
+	imapTls: account.imapTls,
+	imapStartTls: account.imapStartTls,
+	// RFC 032 Tier 2: SMTP config is total. ElectroDB `default` applies on write
+	// only, so rows written before this change still lack these attributes —
+	// coalesce to the schema defaults on read so the response is always complete.
+	smtpEnabled: account.smtpEnabled ?? false,
+	smtpHost: account.smtpHost ?? "",
+	smtpPort: account.smtpPort ?? 587,
+	smtpTls: account.smtpTls ?? false,
+	smtpStartTls: account.smtpStartTls ?? true,
+	smtpUsername: account.smtpUsername ?? "",
+	signaturePlainText: signature.plainText,
+	signatureHtml: signature.html,
+	isActive: account.isActive,
+	connectionState: account.connectionState,
+	lastConnectedAt: account.lastConnectedAt,
+	lastSyncAt: account.lastSyncAt,
+	lastError: account.lastError,
+	syncPhase: account.syncPhase,
+	mailboxCountTotal: account.mailboxCountTotal,
+	mailboxCountSynced: account.mailboxCountSynced,
+	muted: overrides.muted,
+	createdAt: account.createdAt,
+	updatedAt: account.updatedAt,
+	folderAppointments,
+});