@remit/mailbox-service 0.0.111 → 0.0.112

package/src/ownership.ts

@@ -0,0 +1,140 @@
+import type { AccountItem, MailboxItem } from "@remit/data-ports";
+import { MailboxSyncStatus } from "@remit/domain-enums";
+import {
+	type AccessMode,
+	accept,
+	invalid,
+	type Refusable,
+	refuse,
+} from "./refusal.js";
+
+// A read refuses with NotFound so another tenant's account does not leak its
+// existence; an action names the resource already, so it is refused outright.
+export const ownedAccount = <
+	A extends Pick<AccountItem, "accountId" | "accountConfigId">,
+>(
+	account: A,
+	accountConfigId: string,
+	mode: AccessMode,
+): Refusable<A> => {
+	if (account.accountConfigId === accountConfigId) return accept(account);
+	if (mode === "read") {
+		return refuse({
+			kind: "NotFound",
+			message: `Account not found: ${account.accountId}`,
+		});
+	}
+	return refuse({
+		kind: "Forbidden",
+		message: `Account ${account.accountId} not in account config`,
+	});
+};
+
+// Owning the account in a path proves nothing about the mailboxId beside it.
+export const folderInAccount = <
+	M extends Pick<MailboxItem, "mailboxId" | "accountId">,
+>(
+	mailbox: M,
+	accountId: string,
+	mode: AccessMode,
+): Refusable<M> => {
+	if (mailbox.accountId === accountId) return accept(mailbox);
+	if (mode === "read") {
+		return refuse({
+			kind: "NotFound",
+			message: `Mailbox not found: ${mailbox.mailboxId}`,
+		});
+	}
+	return refuse({
+		kind: "Forbidden",
+		message: `Mailbox ${mailbox.mailboxId} not in account`,
+	});
+};
+
+const UNSETTLED_REASON: Partial<
+	Record<MailboxItem["syncStatus"], (path: string) => string>
+> = {
+	[MailboxSyncStatus.pending]: (path) =>
+		`“${path}” isn’t ready yet — the mail server hasn’t confirmed it.`,
+	[MailboxSyncStatus.deleting]: (path) => `“${path}” is being deleted.`,
+	[MailboxSyncStatus.failed]: (path) =>
+		`The last change to “${path}” failed. Retry or dismiss it first.`,
+};
+
+// A durable reference binds only to a folder the mail server has confirmed
+// (imap-mutations R2: wait). This is the server-side floor under the client's
+// own wait, because a script calling the API directly gets no wait at all.
+export const settledFolder = <
+	M extends Pick<MailboxItem, "mailboxId" | "fullPath" | "syncStatus">,
+>(
+	target: M,
+): Refusable<M> => {
+	const reason = UNSETTLED_REASON[target.syncStatus];
+	if (!reason) return accept(target);
+	return refuse({
+		kind: "NotSettled",
+		message: reason(target.fullPath),
+		mailboxId: target.mailboxId,
+		syncStatus: target.syncStatus,
+	});
+};
+
+export 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 }[]>;
+	};
+}
+
+// Messages carry no tenant, so ownership resolves through the caller's own
+// accounts: a mailbox resolves only under the account that owns it, and the
+// whole batch must land on one account because the downstream services take
+// a single accountId.
+export const ownedMessages = async (
+	client: MessageOwnershipClient,
+	messageIds: string[],
+	callerAccountConfigId: string,
+	mode: AccessMode,
+): Promise<Refusable<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") {
+			return refuse({ kind: "NotFound", message: "Message not found" });
+		}
+		return refuse({
+			kind: "Forbidden",
+			message: "Message not in account config",
+		});
+	}
+
+	const accountIds = [...new Set(accountByMailbox.values())];
+	const [accountId] = accountIds;
+	if (accountIds.length !== 1 || accountId === undefined) {
+		return invalid("All messages must belong to the same account");
+	}
+	return accept(accountId);
+};

package/src/placement-move-terminal.ts

@@ -1,3 +1,4 @@
+import type { IMessageRepository, MessageItem } from "@remit/data-ports";
 import { MessageMutation, MessageSyncStatus } from "@remit/domain-enums";
 import { isMessageGoneFromOpenMailbox } from "./message-presence.js";
 import type { PlacementMoveLogger } from "./placement-move.js";
@@ -5,22 +6,19 @@ import {
 	type RestoreSourcePlacementDeps,
 	restoreSourcePlacement,
 } from "./restore-source-placement.js";
-import {
-	reconcileStaleMessage,
-	type StaleMessageReconcileDeps,
-} from "./stale-message-reconcile.js";
 import type { IImapConnection } from "./types.js";
 
 export interface ResolveExhaustedPlacementMoveDeps {
-	messageService: StaleMessageReconcileDeps["messageService"] &
+	messageService: Pick<IMessageRepository, "deleteIfPlacement"> &
 		RestoreSourcePlacementDeps["messageService"];
-	threadMessageService: StaleMessageReconcileDeps["threadMessageService"] &
-		RestoreSourcePlacementDeps["threadMessageService"];
+	threadMessageService: RestoreSourcePlacementDeps["threadMessageService"];
 	markerService: { delete(messageId: string): Promise<void> };
 	log: PlacementMoveLogger;
 }
 
 export interface ResolveExhaustedPlacementMoveInput {
+	/** Where the row stood when the caller read it; the delete holds only while it still does. */
+	placement: Pick<MessageItem, "status" | "mailboxId" | "uid">;
 	accountId: string;
 	accountConfigId: string;
 	messageId: string;
@@ -47,7 +45,7 @@ export interface ResolveExhaustedPlacementMoveResult {
  *    than by a FETCH coming back empty. Per invariant 2, an external delete
  *    supersedes the marker entirely: the marker is dropped and the stale
  *    Message/ThreadMessage rows are deleted via
- *    {@link reconcileStaleMessage}. This is also the
+ *    `deleteIfPlacement`. This is also the
  *    outcome for the (rarer, functionally indistinguishable from here) case
  *    where a foreign client moved the message elsewhere — either way, our
  *    prediction no longer holds, and the marker cannot be honoured. Metric
@@ -94,10 +92,9 @@ export const resolveExhaustedPlacementMoveFailure = async (
 
 	if (await isMessageGoneFromOpenMailbox(connection, uid)) {
 		await deps.markerService.delete(messageId);
-		const { threadMessagesDeleted } = await reconcileStaleMessage(
-			deps,
-			accountConfigId,
+		const reconciled = await deps.messageService.deleteIfPlacement(
 			messageId,
+			input.placement,
 		);
 		deps.log.info(
 			{
@@ -107,7 +104,7 @@ export const resolveExhaustedPlacementMoveFailure = async (
 				messageId,
 				uid,
 				sourceMailboxPath,
-				threadMessagesDeleted,
+				reconciled,
 			},
 			"Message no longer at its pending-move source after retry exhaustion (external delete or move); marker dropped, stale row reconciled",
 		);

package/src/placement-move.ts

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { SendMessageCommand, type SQSClient } from "@aws-sdk/client-sqs";
 import type {
 	IAddressRepository,
+	IMailboxRepository,
 	IMailboxSpecialUseRepository,
 	IMessagePlacementMoveRepository,
 	IMessageRepository,
@@ -34,6 +35,9 @@ export interface PlacementMovePushEvent {
 	messageId: string;
 }
 
+/** Whether a filing happened. `refused` names a destination outside the message's account. */
+export type PlacementMoveOutcome = "filed" | "skipped" | "refused";
+
 export interface PlacementMoveLogger {
 	info(obj: Record<string, unknown>, msg: string): void;
 	error(obj: Record<string, unknown>, msg: string): void;
@@ -55,6 +59,7 @@ export interface PlacementMoveConfig {
 	 * every auto-filed spam suggestible in the compose picker.
 	 */
 	mailboxSpecialUseService: IMailboxSpecialUseRepository;
+	mailboxService: Pick<IMailboxRepository, "resolveAccountId">;
 	sqsQueueUrl: string;
 	sqsEndpoint?: string;
 	logger?: PlacementMoveLogger;
@@ -99,6 +104,7 @@ export class PlacementMoveService {
 	private markerService: IMessagePlacementMoveRepository;
 	private addressService: IAddressRepository;
 	private mailboxSpecialUseService: IMailboxSpecialUseRepository;
+	private mailboxService: Pick<IMailboxRepository, "resolveAccountId">;
 	private sqs: SQSClient;
 	private queueUrl: string;
 	private log: PlacementMoveLogger;
@@ -111,6 +117,7 @@ export class PlacementMoveService {
 		this.markerService = config.markerService;
 		this.addressService = config.addressService;
 		this.mailboxSpecialUseService = config.mailboxSpecialUseService;
+		this.mailboxService = config.mailboxService;
 		this.queueUrl = config.sqsQueueUrl;
 		this.log = config.logger ?? noopLogger;
 		this.moveSettleTimeoutMs =
@@ -128,7 +135,7 @@ export class PlacementMoveService {
 		messageId: string,
 		destinationMailboxId: string,
 		accountId: string,
-	): Promise<void> => {
+	): Promise<PlacementMoveOutcome> => {
 		let message = await this.messageService.get(messageId);
 
 		// Recovery: a marker already exists for THIS message and destination —
@@ -156,7 +163,7 @@ export class PlacementMoveService {
 			// queued / processing / processed already has its own driver in
 			// flight (the SQS message, or the reconciler currently running) —
 			// nothing to do here either way.
-			return;
+			return "filed";
 		}
 
 		// A different destination, decided while an earlier move is still
@@ -176,7 +183,7 @@ export class PlacementMoveService {
 				{ messageId, accountId, destinationMailboxId },
 				"Placement move not applied: this message is being deleted",
 			);
-			return;
+			return "skipped";
 		}
 
 		if (isPlacementUnsettled(message)) {
@@ -189,7 +196,7 @@ export class PlacementMoveService {
 					{ messageId, accountId, destinationMailboxId },
 					"Placement move not applied: a delete claimed this message while the earlier move settled",
 				);
-				return;
+				return "skipped";
 			}
 			if (isPlacementUnsettled(message)) {
 				throw new Error(
@@ -203,7 +210,26 @@ export class PlacementMoveService {
 		// Genuine no-op: nothing pending for this destination, and the message
 		// is already there (a duplicate verdict recomputed after a confirmed
 		// move).
-		if (sourceMailboxId === destinationMailboxId) return;
+		if (sourceMailboxId === destinationMailboxId) return "skipped";
+
+		// IMAP has no MOVE between accounts, so a filing into a folder this
+		// account does not own would only ever be handed back.
+		if (
+			(await this.mailboxService.resolveAccountId(destinationMailboxId)) !==
+			accountId
+		) {
+			this.log.error(
+				{
+					alert: "placement_move_foreign_folder",
+					messageId,
+					accountId,
+					sourceMailboxId,
+					destinationMailboxId,
+				},
+				"Placement move refused: the destination is not a folder of this message's account",
+			);
+			return "refused";
+		}
 
 		// Fresh move. Strictly sequential — nothing here is parallel: the local
 		// move (marker + ThreadMessage + Message row) fully commits BEFORE the
@@ -256,7 +282,7 @@ export class PlacementMoveService {
 				{ messageId, accountId, sourceMailboxId, destinationMailboxId },
 				"Placement move not applied: something else claimed this message's placement first",
 			);
-			return;
+			return "skipped";
 		}
 
 		await this.updateThreadMessageMailbox(
@@ -286,6 +312,7 @@ export class PlacementMoveService {
 			{ messageId, accountId, sourceMailboxId, destinationMailboxId },
 			"Placement move applied locally; pending marker queued for IMAP push",
 		);
+		return "filed";
 	};
 
 	private updateThreadMessageMailbox = async (

package/src/placement-settled.ts

@@ -46,17 +46,32 @@ export const isPlacementUnsettled = (
  * untouched, so anything that resolves a uid off a row it did not settle
  * itself asks this rather than the binding below (issue #1217).
  */
-export const carriesForeignUid = (
-	message: Pick<
+export const carriesForeignUid = <
+	T extends Pick<
 		MessageItem,
 		"mailboxId" | "uid" | "originalMailboxId" | "originalUid"
 	>,
-): boolean =>
+>(
+	message: T,
+): message is T & { originalMailboxId: string; originalUid: number } =>
 	message.originalUid !== undefined &&
 	message.originalUid === message.uid &&
 	message.originalMailboxId !== undefined &&
 	message.originalMailboxId !== message.mailboxId;
 
+/**
+ * The folder the row's `uid` is a uid in: the source while a move has not
+ * confirmed, otherwise the folder the row is in. A fetch by uid is only safe
+ * from this folder; from any other the same number names a different message.
+ */
+export const uidMailboxIdOf = (
+	message: Pick<
+		MessageItem,
+		"mailboxId" | "uid" | "originalMailboxId" | "originalUid"
+	>,
+): string =>
+	carriesForeignUid(message) ? message.originalMailboxId : message.mailboxId;
+
 export const bindsForeignUid = (
 	message: Pick<
 		MessageItem,
@@ -64,12 +79,18 @@ export const bindsForeignUid = (
 	>,
 ): boolean => isPlacementUnsettled(message) && carriesForeignUid(message);
 
+/** A copy at `uid: 0`, which names nothing on the server until COPYUID lands (#1387). */
+const awaitsCopiedUid = (
+	message: Pick<MessageItem, "status" | "uid">,
+): boolean => message.status === MessageStatus.moving && message.uid === 0;
+
 /**
  * `in_flight` — a mutation is still working on the row, so waiting resolves it.
  * That includes a row mid-retry: `message-move`, `message-delete` and
  * `message-copy` write `syncStatus: failed` on an ordinary transient attempt
  * and re-throw for redelivery, so a failed attempt is a mutation about to
  * succeed and the settle ceiling is exactly what it is for (imap-mutations R3).
+ * It also includes a fresh copy, whose uid names nothing until COPYUID lands.
  *
  * There is no give-up member, because a give-up cannot reach here: `abandoned`
  * is written only alongside `status: active` (a hand-back) or `deleted` (a copy
@@ -85,7 +106,10 @@ export const placementBindingOf = (
 		MessageItem,
 		"status" | "mailboxId" | "uid" | "originalMailboxId" | "originalUid"
 	>,
-): PlacementBinding => (bindsForeignUid(message) ? "in_flight" : "consistent");
+): PlacementBinding =>
+	bindsForeignUid(message) || awaitsCopiedUid(message)
+		? "in_flight"
+		: "consistent";
 
 export interface PlacementSettleOptions {
 	timeoutMs: number;