@remit/imap-worker 0.0.65 → 0.0.67

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/imap-worker",
-  "version": "0.0.65",
+  "version": "0.0.67",
   "type": "module",
   "main": "dist/index.js",
   "exports": {
@@ -25,6 +25,7 @@
     "dev": "node --import tsx src/e2e-processor-shim.ts"
   },
   "devDependencies": {
+    "@remit/drizzle-service": "*",
     "@remit/queue-sidecar": "*",
     "@remit/storage-service": "*",
     "aws-sdk-client-mock": "*",

package/src/handlers/message-copy.test.ts

@@ -229,6 +229,25 @@ describe("handleMessageCopy", () => {
 		assert.equal(called("threadMessage.update").length, 1);
 	});
 
+	// Issue #1122. `deriveCopyMessageId` reuses the row, so copying the same
+	// message into the same folder twice issues a second server COPY and leaves
+	// the destination holding both. Nothing here can rule the older one out the
+	// way the trash probe's source check does — a COPY leaves the source
+	// untouched — so the row must settle on the highest match. Settling on 12
+	// points it at the earlier copy and orphans the one just made.
+	it("settles on the copy this event made, not on an earlier copy of the same message", async () => {
+		h.connection.copyMessages = async () => ({ uidMap: new Map() });
+		h.destinationHolds = [12, 42];
+
+		await handleMessageCopy(event, noopLog, 1, deps());
+
+		assert.deepEqual(called("message.updateUid")[0]?.args, [
+			"new-msg",
+			42,
+			"dst-mbx",
+		]);
+	});
+
 	it("reconciles the optimistic row away when the destination does not hold the copy", async () => {
 		h.connection.copyMessages = async () => ({ uidMap: new Map() });
 		h.destinationHolds = [];

package/src/handlers/message-copy.ts

@@ -16,7 +16,7 @@ import type { MessageCopyEvent } from "../events.js";
 import { isNotFoundError } from "../is-not-found.js";
 import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
 import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
-import { searchMailboxByMessageId } from "./message-move.js";
+import { searchMailboxForHighestMessageIdUid } from "./message-move.js";
 
 export interface MessageCopyDeps {
 	getClient: typeof getClient;
@@ -188,11 +188,18 @@ export const handleMessageCopy = async (
 			// handle: a `guardConnectionCursor` wrap is bound to the SOURCE mailbox
 			// snapshot alone, and opening the destination through it trips that
 			// mailbox into a rebuild.
+			//
+			// This is the call site with no source-side gate to fall back on
+			// (#1122): a COPY leaves the source untouched, so nothing here can rule
+			// an older destination copy out the way `confirmTrashMoveUid` does. The
+			// fresh copy is the highest matching uid, and `deriveCopyMessageId`
+			// makes a repeated copy of the same message a second server COPY, so
+			// this probe must never bind to the earlier one.
 			const probeDestination = async (
 				connection: IImapConnection,
 			): Promise<CopyProbe> => {
 				if (!copyRow.messageIdHeader) return { kind: "unprobeable" };
-				const probedUid = await searchMailboxByMessageId(
+				const probedUid = await searchMailboxForHighestMessageIdUid(
 					connection,
 					destinationMailboxPath,
 					copyRow.messageIdHeader,

package/src/handlers/message-delete.test.ts

@@ -516,6 +516,30 @@ describe("handleMessageDelete", () => {
 			);
 		});
 
+		// Issue #1122. Trash already holds an older copy of this Message-ID (a
+		// resend, a sieve `fileinto` + `keep`, an earlier delete of another
+		// folder's copy). Settling on uid 12 points the row at that copy and
+		// orphans the one this MOVE just delivered: Empty Trash then expunges by
+		// the wrong uid and the fresh copy survives, unreachable.
+		it("settles on the copy this move delivered, not on an older copy already in Trash", async () => {
+			h.connection.moveMessages = async () => ({ uidMap: new Map() });
+			sourceNoLongerHoldsTheUid();
+			h.destinationSearchUids = [12, 77];
+
+			await handleMessageDelete(moveEvent, noopLog, 1, deps());
+
+			assert.deepEqual(called("message.updateUid")[0]?.args, [
+				"msg-1",
+				77,
+				"trash-mbx",
+			]);
+			assert.deepEqual(called("threadMessage.update")[0]?.args[2], {
+				uid: 77,
+				mailboxId: "trash-mbx",
+				isDeleted: true,
+			});
+		});
+
 		it("probes the DESTINATION mailbox, read-only, by Message-ID", async () => {
 			h.connection.moveMessages = async () => ({ uidMap: new Map() });
 			sourceNoLongerHoldsTheUid();
@@ -650,11 +674,11 @@ describe("handleMessageDelete", () => {
 			assert.equal(called("emitEvent").length, 0);
 		});
 
-		// `searchMailboxByMessageId` returns the LOWEST matching uid, and one
-		// Message-ID can have several server copies in one account while
+		// One Message-ID can have several server copies in one account while
 		// `deriveMessageId` gives them one local row. A source that still holds
 		// the uid proves the MOVE did not happen, so any hit at the destination
-		// is a different copy.
+		// is a different copy — including the highest one #1122 now takes, since
+		// with no fresh copy at all the highest match is still an older copy.
 		it("never takes a destination hit while the source still holds the uid (duplicate Message-ID)", async () => {
 			h.connection.moveMessages = async () => ({ uidMap: new Map() });
 			h.destinationSearchUids = [100];

package/src/handlers/message-delete.ts

@@ -23,7 +23,10 @@ import { isNotFoundError } from "../is-not-found.js";
 import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
 import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
 import { resolveExhaustedMessageDeleteFailure } from "./message-delete-terminal.js";
-import { emitMoveResync, searchMailboxByMessageId } from "./message-move.js";
+import {
+	emitMoveResync,
+	searchMailboxForHighestMessageIdUid,
+} from "./message-move.js";
 import {
 	buildThreadMessageMoveRevert,
 	buildThreadMessageTrashUpdate,
@@ -70,14 +73,14 @@ export const deleteAllThreadMessagesForMessage = async (
  * never be opened through the source's guard.
  *
  * The source is asked first, and a source that still holds the uid ends it: the
- * MOVE did not happen, so nothing at the destination can be this message.
- * Skipping that question is not safe, because `searchMailboxByMessageId`
- * returns the LOWEST matching uid rather than the one that just arrived, and
- * one Message-ID can have several server copies in one account (a sieve
- * `fileinto` + `keep`, a multi-label store, a resend) while
- * `deriveMessageId` is folder-independent and gives them one local row. An
- * ungated probe can hand back an earlier copy's uid, and Empty Trash then
- * expunges by that uid. It also closes the second half of #912: an empty
+ * MOVE did not happen, so nothing at the destination can be this message. The
+ * gate survives #1122's switch to the highest matching uid and is not made
+ * redundant by it — highest picks the fresh copy out of several only once a
+ * fresh copy exists, and where the MOVE never ran every hit at the destination
+ * is an older copy of the same Message-ID (a sieve `fileinto` + `keep`, a
+ * multi-label store, a resend) that `deriveMessageId` folds into this one local
+ * row. An ungated probe hands back that copy's uid, and Empty Trash then
+ * expunges by it. The gate also closes the second half of #912: an empty
  * `uidMap` can mean the MOVE matched nothing at all.
  *
  * A row with no `messageIdHeader`, and a row that is already deleted, have
@@ -109,7 +112,7 @@ const confirmTrashMoveUid = async (
 	if (!message) return { outcome: "row-gone" };
 	if (!message.messageIdHeader) return { outcome: "unprobeable" };
 
-	const probedUid = await searchMailboxByMessageId(
+	const probedUid = await searchMailboxForHighestMessageIdUid(
 		destinationConnection,
 		destinationMailboxPath,
 		message.messageIdHeader,

package/src/handlers/message-move.test.ts

@@ -12,7 +12,7 @@ import {
 	handleMessageMove,
 	MESSAGE_MOVE_MAX_ATTEMPTS,
 	moveThenResync,
-	searchMailboxByMessageId,
+	searchMailboxForHighestMessageIdUid,
 } from "./message-move.js";
 
 const silentLogger = (() => {
@@ -343,7 +343,7 @@ describe("handleMessageMove — the move's own pending state gates every attempt
 	});
 });
 
-describe("searchMailboxByMessageId — the probe that binds a move to a UID (#912)", () => {
+describe("searchMailboxForHighestMessageIdUid — the probe that binds a move to a UID (#912)", () => {
 	const isMessageIdCriterion = (
 		criterion: unknown,
 	): criterion is [string, string, string] =>
@@ -381,7 +381,7 @@ describe("searchMailboxByMessageId — the probe that binds a move to a UID (#91
 			},
 		} as unknown as IImapConnection;
 
-		await searchMailboxByMessageId(
+		await searchMailboxForHighestMessageIdUid(
 			destination,
 			"Archive",
 			'<a"b@example.com>\r\nUID 1',
@@ -392,14 +392,14 @@ describe("searchMailboxByMessageId — the probe that binds a move to a UID (#91
 		]);
 	});
 
-	it("answers null, not the lowest UID, when the folder holds no such message", async () => {
+	it("answers null, not another message's UID, when the folder holds no such message", async () => {
 		const destination = buildDestination([
 			{ uid: 11, messageIdHeader: "<stranger-a@example.com>" },
 			{ uid: 12, messageIdHeader: "<stranger-b@example.com>" },
 		]);
 
 		assert.strictEqual(
-			await searchMailboxByMessageId(
+			await searchMailboxForHighestMessageIdUid(
 				destination,
 				"Archive",
 				"<moved@example.com>",
@@ -415,7 +415,7 @@ describe("searchMailboxByMessageId — the probe that binds a move to a UID (#91
 		]);
 
 		assert.strictEqual(
-			await searchMailboxByMessageId(
+			await searchMailboxForHighestMessageIdUid(
 				destination,
 				"Archive",
 				"<moved@example.com>",
@@ -423,4 +423,43 @@ describe("searchMailboxByMessageId — the probe that binds a move to a UID (#91
 			12,
 		);
 	});
+
+	// Issue #1122. The folder already held an older copy of this Message-ID — a
+	// sieve `fileinto` + `keep`, a resend, an earlier copy of the same message —
+	// and the uid this probe hands back settles the row the fresh copy lives in.
+	// Answering 12 binds that row to mail this operation never touched and
+	// leaves the copy that just arrived unreachable by any later delete.
+	it("answers the newest copy's UID when the folder already held an older copy of it", async () => {
+		const destination = buildDestination([
+			{ uid: 12, messageIdHeader: "<moved@example.com>" },
+			{ uid: 40, messageIdHeader: "<moved@example.com>" },
+		]);
+
+		assert.strictEqual(
+			await searchMailboxForHighestMessageIdUid(
+				destination,
+				"Archive",
+				"<moved@example.com>",
+			),
+			40,
+		);
+	});
+
+	// RFC 3501 does not order a SEARCH response, so the fresh copy is the
+	// highest uid returned rather than the last one returned.
+	it("takes the highest match whatever order the server lists them in", async () => {
+		const destination = buildDestination([
+			{ uid: 40, messageIdHeader: "<moved@example.com>" },
+			{ uid: 12, messageIdHeader: "<moved@example.com>" },
+		]);
+
+		assert.strictEqual(
+			await searchMailboxForHighestMessageIdUid(
+				destination,
+				"Archive",
+				"<moved@example.com>",
+			),
+			40,
+		);
+	});
 });

package/src/handlers/message-move.ts

@@ -53,11 +53,28 @@ export const emitMoveResync = async (
 };
 
 /**
- * SEARCH a mailbox for a message by its RFC822 Message-ID header. Read-only
- * (EXAMINE, not SELECT) — this is a verification probe, never a write.
- * Returns the first matching UID, or `null` if nothing matched.
+ * SEARCH a mailbox for copies of a message identified by its RFC822 Message-ID
+ * header and answer the HIGHEST matching uid. Read-only (EXAMINE, not SELECT) —
+ * this is a verification probe, never a write. `null` when nothing matched.
+ *
+ * The highest uid is the freshly delivered copy only when one exists; deciding
+ * that it does is the caller's job, not this function's. Every probe in this
+ * package wants the highest: uids ascend with arrival inside a UIDVALIDITY, so a
+ * copy that has just landed outranks every copy of the same Message-ID the
+ * folder already held. Where nothing was delivered, the highest is simply the
+ * newest pre-existing copy, and a caller that has not ruled that case out binds
+ * itself to unrelated mail.
+ * One Message-ID can have several server copies in one account (a sieve
+ * `fileinto` + `keep`, a resend, a repeated COPY — `deriveCopyMessageId` reuses
+ * the row, so the second copy is a second server COPY), while `deriveMessageId`
+ * is folder-independent and gives them one local row. Taking the lowest bound
+ * the fresh copy's row to an older copy's uid and orphaned the fresh one, which
+ * a later delete or Empty Trash then expunged by the wrong uid (issue #1122).
+ *
+ * The maximum is computed rather than read off the tail: RFC 3501 leaves the
+ * order of a SEARCH response unspecified, so "last returned" is not "highest".
  */
-export const searchMailboxByMessageId = async (
+export const searchMailboxForHighestMessageIdUid = async (
 	connection: IImapConnection,
 	mailboxPath: string,
 	messageIdHeader: string,
@@ -66,7 +83,8 @@ export const searchMailboxByMessageId = async (
 	const uids = await connection.search([
 		["HEADER", "Message-ID", messageIdHeader],
 	]);
-	return uids[0] ?? null;
+	if (uids.length === 0) return null;
+	return uids.reduce((highest, uid) => (uid > highest ? uid : highest));
 };
 
 /**
@@ -273,7 +291,7 @@ export const handleMessageMove = async (
 							const newUid =
 								result.uidMap.get(uid) ??
 								(message.messageIdHeader
-									? await searchMailboxByMessageId(
+									? await searchMailboxForHighestMessageIdUid(
 											rawConnection,
 											destinationMailboxPath,
 											message.messageIdHeader,

package/src/handlers/placement-move-push.test.ts

@@ -156,6 +156,28 @@ describe("attemptMove — the IMAP push (issue #1271)", () => {
 			assert.equal(outcome.newUid, 77);
 		});
 
+		// Issue #1122. The destination already held an older copy of this
+		// Message-ID; the marker must bind to the copy this MOVE delivered, or
+		// the placement row names mail this push never touched.
+		it("moved: binds to the newest copy when the destination already held an older one", async () => {
+			const connection = buildConnection({
+				uidMap: new Map(),
+				destinationSearchUids: [15, 77],
+			});
+
+			const outcome = await attemptMove(
+				connection,
+				connection,
+				"Junk",
+				"INBOX",
+				42,
+				MESSAGE_ID_HEADER,
+			);
+
+			assert.equal(outcome.kind, "moved");
+			assert.equal(outcome.newUid, 77);
+		});
+
 		it("throws (never deletes) when unconfirmed at the destination but STILL present at the source", async () => {
 			const connection = buildConnection({
 				uidMap: new Map(),

package/src/handlers/placement-move-push.ts

@@ -21,7 +21,7 @@ import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
 import {
 	buildThreadMessageMoveUpdate,
 	emitMoveResync,
-	searchMailboxByMessageId,
+	searchMailboxForHighestMessageIdUid,
 } from "./message-move.js";
 
 export const getPlacementMoveMaxAttempts = (
@@ -97,9 +97,16 @@ export const attemptMove = async (
 	}
 
 	// Unconfirmed: either no COPYUID entry, or the server explicitly claimed
-	// "not found" — never trust either without independent verification.
+	// "not found" — never trust either without independent verification. A
+	// message this MOVE delivered is the newest copy of that Message-ID at the
+	// destination, so the probe binds to the highest matching uid (#1122).
+	// Unlike `confirmTrashMoveUid`, this probe is ungated: where the MOVE never
+	// ran and an older copy filed there earlier is the only match, the marker
+	// binds to that unrelated mail. Pre-existing, and not narrowed by taking the
+	// highest — the source is not asked first here, so nothing rules the case
+	// out.
 	if (messageIdHeader) {
-		const destinationUid = await searchMailboxByMessageId(
+		const destinationUid = await searchMailboxForHighestMessageIdUid(
 			destinationConnection,
 			destinationMailboxPath,
 			messageIdHeader,

package/src/with-oauth-lifecycle-deps.sqlite.test.ts

@@ -0,0 +1,138 @@
+/**
+ * What the account row holds after the lifecycle has written to it.
+ *
+ * The deps builder is the half that talks to the store, so it is tested against
+ * the real repository over the shipped SQLite schema rather than a stand-in
+ * that would only agree with itself: whether a stored reason survives, and
+ * whether one that no longer applies is gone, is decided by the repository's
+ * update semantics, where an absent field means "leave it alone".
+ */
+
+import assert from "node:assert/strict";
+import { after, before, describe, it } from "node:test";
+import type { AccountItem } from "@remit/data-ports";
+import { AccountAuthType, ConnectionState } from "@remit/domain-enums";
+import { AccountRepo } from "@remit/drizzle-service";
+import { createShippedSqliteDb } from "@remit/drizzle-service/test-sqlite";
+import { RefreshTokenError } from "@remit/mail-oauth-service";
+import { MailConnectionError } from "@remit/mailbox-service/types";
+import type { SecretsService } from "@remit/secrets-service";
+import {
+	type OAuthLifecycleDeps,
+	withOAuthLifecycle,
+} from "./with-oauth-lifecycle.js";
+import { buildLifecycleDeps } from "./with-oauth-lifecycle-deps.js";
+
+const silentLogger = {
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+	debug: () => {},
+	trace: () => {},
+	fatal: () => {},
+	child: () => silentLogger,
+} as never;
+
+const secrets = {
+	decrypt: async () => "decrypted",
+	encrypt: async () => ({}) as never,
+} as unknown as SecretsService;
+
+/**
+ * The real deps, with only credential resolution stubbed — minting a token is
+ * a call to Microsoft and not what these tests are about. `updateConnectionState`
+ * is the one under test and stays exactly as the handlers build it.
+ */
+const deps = (): OAuthLifecycleDeps => ({
+	...buildLifecycleDeps(secrets, repo),
+	resolveCredentials: async () => ({
+		status: "resolved",
+		credentials: { kind: "accessToken", accessToken: "access-token" },
+	}),
+});
+
+const STALE_SYNC_ERROR = "Mailbox does not exist: [NONEXISTENT]";
+const REFUSAL =
+	"IMAP authentication failed: LOGIN failed. User is authenticated but not connected.";
+
+let repo: AccountRepo;
+let close: () => void;
+
+const account = async (): Promise<AccountItem> =>
+	repo.create({
+		accountConfigId: "cfg-1",
+		username: "matthijs@example.com",
+		email: "matthijs@example.com",
+		authType: AccountAuthType.OauthMicrosoft,
+		oauthRefreshTokenHash: "encrypted-refresh-token",
+		imapHost: "outlook.office365.com",
+		imapPort: 993,
+		imapTls: true,
+		imapStartTls: false,
+		isActive: true,
+		connectionState: ConnectionState.Authenticated,
+	});
+
+before(() => {
+	const db = createShippedSqliteDb();
+	close = db.close;
+	repo = new AccountRepo(db.db);
+});
+
+after(() => {
+	close();
+});
+
+describe("the reason an account card reads back", () => {
+	it("keeps the refusal the mail server gave", async () => {
+		const created = await account();
+
+		await withOAuthLifecycle(deps(), created, silentLogger, async () => {
+			throw new MailConnectionError("auth", REFUSAL);
+		});
+
+		const stored = await repo.get(created.accountId);
+		assert.equal(stored.connectionState, ConnectionState.ReauthRequired);
+		assert.equal(stored.lastError, REFUSAL);
+	});
+
+	it("drops a reason the account has moved on from", async () => {
+		const created = await account();
+		// What a failed sync leaves behind (sync-mailboxes.ts): a folder that went
+		// away, nothing to do with signing in.
+		await repo.update(created.accountId, { lastError: STALE_SYNC_ERROR });
+
+		// Hours later the refresh token is revoked. Re-authenticating is now the
+		// whole story, and the mailbox that went missing is not it.
+		await withOAuthLifecycle(
+			deps(),
+			await repo.get(created.accountId),
+			silentLogger,
+			async () => {
+				throw new RefreshTokenError({
+					kind: "reauth-required",
+					code: "invalid_grant",
+				});
+			},
+		);
+
+		const stored = await repo.get(created.accountId);
+		assert.equal(stored.connectionState, ConnectionState.ReauthRequired);
+		assert.equal(
+			stored.lastError,
+			undefined,
+			"a stale sync error beside a Reconnect button reads as the reason for it",
+		);
+	});
+
+	it("stores a chatty refusal at a length a card can hold", async () => {
+		const created = await account();
+
+		await withOAuthLifecycle(deps(), created, silentLogger, async () => {
+			throw new MailConnectionError("auth", "x".repeat(4000));
+		});
+
+		const stored = await repo.get(created.accountId);
+		assert.equal(stored.lastError?.length, 500);
+	});
+});

package/src/with-oauth-lifecycle-deps.ts

@@ -53,10 +53,19 @@ export const buildLifecycleDeps = (
 			oauthTokenUpdatedAt: updatedAt,
 		});
 	},
+	// A state flip with no reason of its own removes the stored one. Left in
+	// place it would describe a failure the account has moved on from — the
+	// mailbox a sync could not find, still on the card beside a Reconnect
+	// button, after the token was revoked hours later.
 	updateConnectionState: async (
 		accountId: string,
 		state: ConnectionStateValue,
+		lastError?: string,
 	) => {
-		await accountService.update(accountId, { connectionState: state });
+		await accountService.update(
+			accountId,
+			{ connectionState: state, lastError },
+			lastError === undefined ? ["lastError"] : undefined,
+		);
 	},
 });

package/src/with-oauth-lifecycle.test.ts

@@ -1,8 +1,9 @@
 import assert from "node:assert/strict";
-import { describe, it } from "node:test";
+import { describe, it, mock } from "node:test";
 import type { AccountItem } from "@remit/data-ports";
 import { AccountAuthType, ConnectionState } from "@remit/domain-enums";
 import { RefreshTokenError } from "@remit/mail-oauth-service";
+import { ImapFlowConnection } from "@remit/mailbox-service/imapflow-connection";
 import {
 	MailConnectionError,
 	type MailCredentials,
@@ -41,11 +42,19 @@ const buildAccount = (overrides: Partial<AccountItem> = {}): AccountItem =>
 	}) as unknown as AccountItem;
 
 interface Recorded {
-	stateUpdates: Array<{ accountId: string; state: ConnectionStateValue }>;
+	stateUpdates: Array<{
+		accountId: string;
+		state: ConnectionStateValue;
+		lastError?: string;
+	}>;
 	resolveCalls: number;
 	workCalls: number;
 }
 
+/** What Microsoft says to a mailbox whose tenant has IMAP switched off. */
+const REFUSAL =
+	"LOGIN failed. User is authenticated but not connected. SmtpClientAuthentication is disabled for the Tenant.";
+
 const passwordCreds: MailCredentials = {
 	kind: "password",
 	password: "secret",
@@ -68,8 +77,8 @@ const buildDeps = (
 		},
 		tokenService: { getAccessToken: async () => ({}) as never },
 		persistRotatedToken: async () => {},
-		updateConnectionState: async (accountId, state) => {
-			recorded.stateUpdates.push({ accountId, state });
+		updateConnectionState: async (accountId, state, lastError) => {
+			recorded.stateUpdates.push({ accountId, state, lastError });
 		},
 		resolveCredentials:
 			options.resolveCredentials ??
@@ -124,9 +133,12 @@ describe("withOAuthLifecycle", () => {
 			"work must not run after resolve fails",
 		);
 		assert.equal(recorded.stateUpdates.length, 1);
+		// A revoked token has nothing to add: re-authenticating is the whole of
+		// what the account needs, and the card says so on its own.
 		assert.deepEqual(recorded.stateUpdates[0], {
 			accountId: "acc-1",
 			state: ConnectionState.ReauthRequired,
+			lastError: undefined,
 		});
 	});
 
@@ -142,7 +154,48 @@ describe("withOAuthLifecycle", () => {
 		assert.deepEqual(recorded.stateUpdates[0], {
 			accountId: "acc-1",
 			state: ConnectionState.ReauthRequired,
+			lastError: "auth failed",
+		});
+	});
+
+	it("keeps what the server said when it refused, so the card can repeat it", async () => {
+		const { deps, recorded } = buildDeps();
+		const account = buildAccount({ authType: AccountAuthType.OauthMicrosoft });
+
+		// The error an Exchange mailbox with IMAP switched off hands back, built
+		// the way imapflow builds it and classified by the code that ships.
+		const connection = new ImapFlowConnection({
+			host: "outlook.office365.com",
+			port: 993,
+			user: "matthijs@example.com",
+			credentials: { kind: "accessToken", accessToken: "access-token" },
+			tls: true,
+		});
+		mock.method(
+			connection as unknown as { attemptConnect: () => Promise<void> },
+			"attemptConnect",
+			async () => {
+				throw Object.assign(new Error("Command failed"), {
+					authenticationFailed: true,
+					serverResponseCode: "AUTHENTICATIONFAILED",
+					responseText: REFUSAL,
+				});
+			},
+		);
+
+		await withOAuthLifecycle(deps, account, silentLogger, async () => {
+			await connection.connect();
 		});
+
+		assert.equal(recorded.stateUpdates.length, 1);
+		assert.equal(
+			recorded.stateUpdates[0].state,
+			ConnectionState.ReauthRequired,
+		);
+		assert.ok(
+			recorded.stateUpdates[0].lastError?.includes(REFUSAL),
+			`the refusal must survive to the account row, got: ${recorded.stateUpdates[0].lastError}`,
+		);
 	});
 
 	it("on MailConnectionError auth for password account: rethrows (batch item failure, no state flip)", async () => {
@@ -221,7 +274,11 @@ describe("withOAuthLifecycle", () => {
 
 		assert.equal(recorded.workCalls, 0, "no IMAP traffic without a credential");
 		assert.deepEqual(recorded.stateUpdates, [
-			{ accountId: "acc-1", state: ConnectionState.CredentialsMissing },
+			{
+				accountId: "acc-1",
+				state: ConnectionState.CredentialsMissing,
+				lastError: undefined,
+			},
 		]);
 	});
 
@@ -236,7 +293,11 @@ describe("withOAuthLifecycle", () => {
 
 		assert.equal(recorded.workCalls, 0, "no IMAP traffic without a credential");
 		assert.deepEqual(recorded.stateUpdates, [
-			{ accountId: "acc-1", state: ConnectionState.ReauthRequired },
+			{
+				accountId: "acc-1",
+				state: ConnectionState.ReauthRequired,
+				lastError: undefined,
+			},
 		]);
 	});
 

package/src/with-oauth-lifecycle.ts

@@ -16,6 +16,10 @@
  *  - On a terminal auth failure (RefreshTokenError reauth-required, or
  *    MailConnectionError auth), flip the account to reauth_required and return
  *    WITHOUT rethrowing — this ACKs the SQS message so it is not retried.
+ *    An IMAP refusal is stored with it, because not every refusal a mail server
+ *    hands back is one re-authenticating clears: "SmtpClientAuthentication is
+ *    disabled" needs a tenant setting changed, and an account card that only
+ *    ever says "Re-authentication required" sends the user around a loop.
  *  - On transient / config / network errors, rethrow so SQS retries with
  *    backoff (let-it-crash).
  *
@@ -42,12 +46,17 @@ export type { ConnectionStateValue };
 
 export interface OAuthLifecycleDeps extends AccountCredentialsDeps {
 	/**
-	 * Persist the account's connectionState. Called when a terminal auth
-	 * failure is detected so the account is fenced off until the user re-auths.
+	 * Persist the account's connectionState, and with it the sentence the
+	 * account card shows for the failure. `lastError` carries the server's own
+	 * words when the failure came with any; it is absent when nothing was said,
+	 * as for a credential that was never stored or a token simply revoked, and
+	 * the stored reason is then cleared rather than left to describe an older
+	 * failure the account has moved on from.
 	 */
 	updateConnectionState: (
 		accountId: string,
 		state: ConnectionStateValue,
+		lastError?: string,
 	) => Promise<void>;
 	/**
 	 * Resolve credentials for the account. Defaults to
@@ -131,12 +140,14 @@ export const withOAuthLifecycle = async (
 				{
 					accountId: account.accountId,
 					errorKind: err.kind,
+					error: err.message,
 				},
 				"IMAP auth rejected; marking account reauth_required",
 			);
 			await deps.updateConnectionState(
 				account.accountId,
 				ConnectionState.ReauthRequired,
+				err.message,
 			);
 			return; // ACK — do not retry
 		}