@remit/imap-worker 0.0.66 → 0.0.67

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/imap-worker",
-  "version": "0.0.66",
+  "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/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
 		}