@remit/imap-worker 0.0.63 → 0.0.65

package/package.json

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

package/src/credential-less-sync-fence.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Regression test for issue #1120.
+ *
+ * A sync triggered for an account that stores no credential used to fail the
+ * batch item, so the poller left the message undeleted for its whole
+ * visibility timeout. `remit-mailboxes.fifo` groups by accountId and a FIFO
+ * queue never delivers past an in-flight message in a group, so the account
+ * was fenced from every later sync — including the one the user asks for right
+ * after saving the password.
+ *
+ * Runs against the real QueueStore and the real queue definition the stack
+ * ships, with the poller's own contract modelled around it: ack deletes the
+ * message, a batch item failure leaves it in flight.
+ */
+
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { after, describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
+import { buildSyncMailboxesCommand } from "@remit/backend/trigger-sync";
+import type { AccountItem } from "@remit/data-ports";
+import { ConnectionState } from "@remit/domain-enums";
+import {
+	bootstrapQueues,
+	loadQueuesConfig,
+	QueueStore,
+} from "@remit/queue-sidecar";
+import { DEFAULT_VISIBILITY_TIMEOUT_SECONDS } from "@remit/sqs-client/poller";
+import {
+	type OAuthLifecycleDeps,
+	withOAuthLifecycle,
+} from "./with-oauth-lifecycle.js";
+
+const QUEUE_NAME = "remit-mailboxes.fifo";
+const QUEUE_URL = `http://localhost:9324/000000000000/${QUEUE_NAME}`;
+const ACCOUNT_ID = "acct_imported";
+const T0 = 1_700_000_000_000;
+
+const here = fileURLToPath(new URL(".", import.meta.url));
+const repoRoot = join(here, "..", "..", "..");
+const tmpRoot = join(here, "..", ".tmp", "credential-less-sync-fence");
+
+const silentLogger = {
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+	debug: () => {},
+	trace: () => {},
+	fatal: () => {},
+	child: () => silentLogger,
+} as never;
+
+/** The account the import wizard lands: no password until its owner types one. */
+const importedAccount = {
+	accountId: ACCOUNT_ID,
+	accountConfigId: "acfg_1",
+	username: "alice@example.com",
+	email: "alice@example.com",
+	authType: "password",
+	imapHost: "imap.example.com",
+	imapPort: 993,
+	imapTls: true,
+	imapStartTls: false,
+	isActive: true,
+	connectionState: ConnectionState.CredentialsMissing,
+	createdAt: T0,
+	updatedAt: T0,
+} as unknown as AccountItem;
+
+const enqueueSync = (store: QueueStore, now: number): void => {
+	const command = buildSyncMailboxesCommand({
+		queueUrl: QUEUE_URL,
+		accountId: ACCOUNT_ID,
+	});
+	store.sendMessage({
+		queueName: QUEUE_NAME,
+		body: command.input.MessageBody ?? "",
+		groupId: command.input.MessageGroupId,
+		deduplicationId: command.input.MessageDeduplicationId,
+		now,
+	});
+};
+
+describe("a credential-less sync trigger (issue #1120)", () => {
+	after(() => {
+		rmSync(tmpRoot, { recursive: true, force: true });
+	});
+
+	it("is acked, leaving the account's queue group deliverable", async () => {
+		mkdirSync(tmpRoot, { recursive: true });
+		const store = new QueueStore(
+			join(mkdtempSync(join(tmpRoot, "store-")), "queue.db"),
+		);
+		bootstrapQueues(
+			store,
+			loadQueuesConfig(join(repoRoot, "deploy/vps/queues.json")),
+		);
+
+		const stateUpdates: string[] = [];
+		const deps: OAuthLifecycleDeps = {
+			secrets: {
+				decrypt: async () => "",
+				encrypt: async () => ({}) as never,
+			},
+			tokenService: { getAccessToken: async () => ({}) as never },
+			persistRotatedToken: async () => {},
+			updateConnectionState: async (_accountId, state) => {
+				stateUpdates.push(state);
+			},
+		};
+
+		// The GET /config poll while the user is still typing the password.
+		enqueueSync(store, T0);
+
+		const [received] = store.receiveMessages({
+			queueName: QUEUE_NAME,
+			maxMessages: 1,
+			visibilityTimeoutSeconds: DEFAULT_VISIBILITY_TIMEOUT_SECONDS,
+			now: T0,
+		});
+		assert.ok(received, "the trigger is on the queue");
+
+		// The poller's contract: an ack deletes the message, a batch item failure
+		// leaves it in flight until the visibility timeout expires.
+		let batchItemFailure: unknown;
+		await withOAuthLifecycle(deps, importedAccount, silentLogger, async () => {
+			throw new Error("IMAP work must not run without a credential");
+		}).then(
+			() => store.deleteMessage(QUEUE_NAME, received.receiptHandle),
+			(err: unknown) => {
+				batchItemFailure = err;
+			},
+		);
+
+		// The refresh the user presses after saving the password.
+		enqueueSync(store, T0 + 2_000);
+		const deliverable = store.receiveMessages({
+			queueName: QUEUE_NAME,
+			maxMessages: 10,
+			now: T0 + 3_000,
+		});
+
+		assert.equal(
+			deliverable.length,
+			1,
+			"the account's group must stay deliverable, not fenced for the visibility timeout",
+		);
+		assert.equal(
+			batchItemFailure,
+			undefined,
+			"the event is acked, not retried",
+		);
+		assert.deepEqual(stateUpdates, [ConnectionState.CredentialsMissing]);
+	});
+});

package/src/handlers/append-sent-message.ts

@@ -10,6 +10,7 @@ import {
 	buildMailMessage,
 	renderRawMessage,
 } from "@remit/smtp-service/message-builder";
+import { attemptBudget } from "@remit/sqs-client/attempt-budget";
 import { isAccountDeleted } from "../account-check.js";
 import { createConnectionScopeWithCredentials } from "../connection-scope.js";
 import type { AppendSentMessageEvent } from "../events.js";
@@ -29,23 +30,9 @@ const ROW_SURVIVED_ITS_DELETE =
 const unfiledAppendRefused = (fullPath: string, error: unknown): string =>
 	`Sent, but not filed: the mail server refused to store a copy in ${fullPath} (${error instanceof Error ? error.message : String(error)}).`;
 
-/**
- * Fallback when `APPEND_SENT_MAX_ATTEMPTS` is unset (local dev, unit tests).
- * Matches the shared `MAX_RECEIVE_COUNT` every queue's redrive policy uses,
- * same pattern as `FLAG_PUSH_MAX_ATTEMPTS` / `BODY_SYNC_MAX_ATTEMPTS`.
- */
-const DEFAULT_APPEND_SENT_MAX_ATTEMPTS = 3;
-
 export const getAppendSentMaxAttempts = (
 	processEnv: NodeJS.ProcessEnv = process.env,
-): number => {
-	const raw = processEnv.APPEND_SENT_MAX_ATTEMPTS;
-	if (!raw) return DEFAULT_APPEND_SENT_MAX_ATTEMPTS;
-	const parsed = Number.parseInt(raw, 10);
-	return Number.isFinite(parsed) && parsed > 0
-		? parsed
-		: DEFAULT_APPEND_SENT_MAX_ATTEMPTS;
-};
+): number => attemptBudget("APPEND_SENT_MAX_ATTEMPTS", 3, processEnv);
 
 export const APPEND_SENT_MAX_ATTEMPTS = getAppendSentMaxAttempts();
 

package/src/handlers/flag-push.ts

@@ -8,6 +8,7 @@ import {
 	MailboxCursorPausedError,
 	resolveExhaustedFlagPushFailure,
 } from "@remit/mailbox-service";
+import { attemptBudget } from "@remit/sqs-client/attempt-budget";
 import { isAccountDeleted } from "../account-check.js";
 import { createConnectionScopeWithCredentials } from "../connection-scope.js";
 import type { FlagPushEvent } from "../events.js";
@@ -15,24 +16,9 @@ import { isNotFoundError } from "../is-not-found.js";
 import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
 import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
 
-/**
- * Fallback when `FLAG_PUSH_MAX_ATTEMPTS` is unset (local dev, unit tests).
- * Matches the shared `MAX_RECEIVE_COUNT` every queue's redrive policy uses
- * (`infra/stacks/dev/stacks/remit-queue-stack.ts`), same pattern as
- * `BODY_SYNC_MAX_ATTEMPTS` (#1270) / `PLACEMENT_MOVE_MAX_ATTEMPTS` (#1289).
- */
-const DEFAULT_FLAG_PUSH_MAX_ATTEMPTS = 3;
-
 export const getFlagPushMaxAttempts = (
 	processEnv: NodeJS.ProcessEnv = process.env,
-): number => {
-	const raw = processEnv.FLAG_PUSH_MAX_ATTEMPTS;
-	if (!raw) return DEFAULT_FLAG_PUSH_MAX_ATTEMPTS;
-	const parsed = Number.parseInt(raw, 10);
-	return Number.isFinite(parsed) && parsed > 0
-		? parsed
-		: DEFAULT_FLAG_PUSH_MAX_ATTEMPTS;
-};
+): number => attemptBudget("FLAG_PUSH_MAX_ATTEMPTS", 3, processEnv);
 
 export const FLAG_PUSH_MAX_ATTEMPTS = getFlagPushMaxAttempts();
 

package/src/handlers/message-copy.ts

@@ -9,6 +9,7 @@ import {
 	MailboxCursorPausedError,
 	reconcileStaleMessage,
 } from "@remit/mailbox-service";
+import { attemptBudget } from "@remit/sqs-client/attempt-budget";
 import { isAccountDeleted } from "../account-check.js";
 import { createConnectionScopeWithCredentials } from "../connection-scope.js";
 import type { MessageCopyEvent } from "../events.js";
@@ -31,24 +32,9 @@ const defaultDeps: MessageCopyDeps = {
 	createConnectionScope: createConnectionScopeWithCredentials,
 };
 
-/**
- * Fallback when `MESSAGE_COPY_MAX_ATTEMPTS` is unset (local dev, unit tests).
- * Matches the `maxReceiveCount` the message queue's redrive policy uses
- * (`remit-messages.fifo`, `deploy/vps/queues.json`), same pattern as
- * `MESSAGE_MOVE_MAX_ATTEMPTS`.
- */
-const DEFAULT_MESSAGE_COPY_MAX_ATTEMPTS = 3;
-
 export const getMessageCopyMaxAttempts = (
 	processEnv: NodeJS.ProcessEnv = process.env,
-): number => {
-	const raw = processEnv.MESSAGE_COPY_MAX_ATTEMPTS;
-	if (!raw) return DEFAULT_MESSAGE_COPY_MAX_ATTEMPTS;
-	const parsed = Number.parseInt(raw, 10);
-	return Number.isFinite(parsed) && parsed > 0
-		? parsed
-		: DEFAULT_MESSAGE_COPY_MAX_ATTEMPTS;
-};
+): number => attemptBudget("MESSAGE_COPY_MAX_ATTEMPTS", 3, processEnv);
 
 export const MESSAGE_COPY_MAX_ATTEMPTS = getMessageCopyMaxAttempts();
 

package/src/handlers/message-delete.ts

@@ -14,6 +14,7 @@ import {
 	isMessageGoneFromOpenMailbox,
 	MailboxCursorPausedError,
 } from "@remit/mailbox-service";
+import { attemptBudget } from "@remit/sqs-client/attempt-budget";
 import { isAccountDeleted } from "../account-check.js";
 import { createConnectionScopeWithCredentials } from "../connection-scope.js";
 import { emitEvent } from "../emit.js";
@@ -28,24 +29,9 @@ import {
 	buildThreadMessageTrashUpdate,
 } from "./thread-message-rows.js";
 
-/**
- * Fallback when `MESSAGE_DELETE_MAX_ATTEMPTS` is unset (local dev, unit tests).
- * Matches the `maxReceiveCount` the redrive policy of the queue `emit.ts`
- * routes MESSAGE_DELETE onto uses (`remit-message-mgmt`,
- * `deploy/vps/queues.json`), same pattern as `MESSAGE_MOVE_MAX_ATTEMPTS`.
- */
-const DEFAULT_MESSAGE_DELETE_MAX_ATTEMPTS = 3;
-
 export const getMessageDeleteMaxAttempts = (
 	processEnv: NodeJS.ProcessEnv = process.env,
-): number => {
-	const raw = processEnv.MESSAGE_DELETE_MAX_ATTEMPTS;
-	if (!raw) return DEFAULT_MESSAGE_DELETE_MAX_ATTEMPTS;
-	const parsed = Number.parseInt(raw, 10);
-	return Number.isFinite(parsed) && parsed > 0
-		? parsed
-		: DEFAULT_MESSAGE_DELETE_MAX_ATTEMPTS;
-};
+): number => attemptBudget("MESSAGE_DELETE_MAX_ATTEMPTS", 3, processEnv);
 
 export const MESSAGE_DELETE_MAX_ATTEMPTS = getMessageDeleteMaxAttempts();
 

package/src/handlers/message-move.ts

@@ -10,6 +10,7 @@ import {
 	isPlacementUnsettled,
 	MailboxCursorPausedError,
 } from "@remit/mailbox-service";
+import { attemptBudget } from "@remit/sqs-client/attempt-budget";
 import { isAccountDeleted } from "../account-check.js";
 import { createConnectionScopeWithCredentials } from "../connection-scope.js";
 import { emitEvent } from "../emit.js";
@@ -19,24 +20,9 @@ import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
 import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
 import { resolveExhaustedMessageMoveFailure } from "./message-move-terminal.js";
 
-/**
- * Fallback when `MESSAGE_MOVE_MAX_ATTEMPTS` is unset (local dev, unit tests).
- * Matches the `maxReceiveCount` the message queue's redrive policy uses
- * (`remit-messages.fifo`, `deploy/vps/queues.json`), same pattern as
- * `FLAG_PUSH_MAX_ATTEMPTS` and `PLACEMENT_MOVE_MAX_ATTEMPTS`.
- */
-const DEFAULT_MESSAGE_MOVE_MAX_ATTEMPTS = 3;
-
 export const getMessageMoveMaxAttempts = (
 	processEnv: NodeJS.ProcessEnv = process.env,
-): number => {
-	const raw = processEnv.MESSAGE_MOVE_MAX_ATTEMPTS;
-	if (!raw) return DEFAULT_MESSAGE_MOVE_MAX_ATTEMPTS;
-	const parsed = Number.parseInt(raw, 10);
-	return Number.isFinite(parsed) && parsed > 0
-		? parsed
-		: DEFAULT_MESSAGE_MOVE_MAX_ATTEMPTS;
-};
+): number => attemptBudget("MESSAGE_MOVE_MAX_ATTEMPTS", 3, processEnv);
 
 export const MESSAGE_MOVE_MAX_ATTEMPTS = getMessageMoveMaxAttempts();
 

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

@@ -10,6 +10,7 @@ import {
 	reconcileStaleMessage,
 	resolveExhaustedPlacementMoveFailure,
 } from "@remit/mailbox-service";
+import { attemptBudget } from "@remit/sqs-client/attempt-budget";
 import { isAccountDeleted } from "../account-check.js";
 import { createConnectionScopeWithCredentials } from "../connection-scope.js";
 import { emitEvent } from "../emit.js";
@@ -23,24 +24,9 @@ import {
 	searchMailboxByMessageId,
 } from "./message-move.js";
 
-/**
- * Fallback when `PLACEMENT_MOVE_MAX_ATTEMPTS` is unset (local dev, unit
- * tests). Matches the placement-move queue's own `MAX_RECEIVE_COUNT` default
- * (`infra/stacks/dev/stacks/remit-queue-stack.ts`), same pattern as
- * `BODY_SYNC_MAX_ATTEMPTS` (#1270).
- */
-const DEFAULT_PLACEMENT_MOVE_MAX_ATTEMPTS = 3;
-
 export const getPlacementMoveMaxAttempts = (
 	processEnv: NodeJS.ProcessEnv = process.env,
-): number => {
-	const raw = processEnv.PLACEMENT_MOVE_MAX_ATTEMPTS;
-	if (!raw) return DEFAULT_PLACEMENT_MOVE_MAX_ATTEMPTS;
-	const parsed = Number.parseInt(raw, 10);
-	return Number.isFinite(parsed) && parsed > 0
-		? parsed
-		: DEFAULT_PLACEMENT_MOVE_MAX_ATTEMPTS;
-};
+): number => attemptBudget("PLACEMENT_MOVE_MAX_ATTEMPTS", 3, processEnv);
 
 export const PLACEMENT_MOVE_MAX_ATTEMPTS = getPlacementMoveMaxAttempts();
 

package/src/handlers/sync-message-body.ts

@@ -11,6 +11,7 @@ import {
 	QuarantineService,
 	resolveExhaustedBodySyncFailures,
 } from "@remit/mailbox-service";
+import { attemptBudget } from "@remit/sqs-client/attempt-budget";
 import { env } from "expect-env";
 import { isAccountDeleted } from "../account-check.js";
 import { isBodySyncEnabled } from "../body-sync-gate.js";
@@ -27,37 +28,9 @@ import { workerVersion } from "../worker-version.js";
 
 const bodySyncEnabledParameterName = env.BODY_SYNC_ENABLED_PARAMETER_NAME;
 
-/**
- * Fallback when `BODY_SYNC_MAX_ATTEMPTS` is unset (local dev, unit tests).
- * Matches the body queue's own `MAX_RECEIVE_COUNT` default
- * (`infra/stacks/dev/stacks/remit-queue-stack.ts`) so an environment that
- * never injects the var still behaves like production.
- */
-const DEFAULT_BODY_SYNC_MAX_ATTEMPTS = 3;
-
-/**
- * Reads the redelivery-budget-exhaustion threshold. CDK derives
- * `BODY_SYNC_MAX_ATTEMPTS` from the body queue's own `MAX_RECEIVE_COUNT`
- * (`remit-worker-stack.ts`) so the two constants can't drift apart — a
- * hand-copied duplicate here previously risked the worker resolving
- * "last attempt" on a different delivery than the queue's redrive policy
- * actually uses (issue #1270). SQS's own `ApproximateReceiveCount` is the
- * source of truth for how many times a record has been delivered; once it
- * reaches this value, the current invocation is the last attempt before the
- * queue's own redrive would DLQ the record, so retry exhaustion is resolved
- * here (see `resolveExhaustedBodySyncFailures`) instead of letting the
- * record dead-letter with no diagnosis.
- */
 export const getBodySyncMaxAttempts = (
 	processEnv: NodeJS.ProcessEnv = process.env,
-): number => {
-	const raw = processEnv.BODY_SYNC_MAX_ATTEMPTS;
-	if (!raw) return DEFAULT_BODY_SYNC_MAX_ATTEMPTS;
-	const parsed = Number.parseInt(raw, 10);
-	return Number.isFinite(parsed) && parsed > 0
-		? parsed
-		: DEFAULT_BODY_SYNC_MAX_ATTEMPTS;
-};
+): number => attemptBudget("BODY_SYNC_MAX_ATTEMPTS", 3, processEnv);
 
 export const BODY_SYNC_MAX_ATTEMPTS = getBodySyncMaxAttempts();
 

package/src/scheduler/run-tick.test.ts

@@ -51,6 +51,7 @@ const baseAccount = (overrides: Partial<AccountItem>): AccountItem =>
 		username: "user",
 		email: "user@example.com",
 		authType: "password",
+		passwordHash: '{"ciphertext":"x"}',
 		imapHost: "imap.example.com",
 		imapPort: 993,
 		imapTls: true,
@@ -162,6 +163,36 @@ describe("runSchedulerTick", () => {
 		assert.equal(sent.length, 0);
 	});
 
+	it("skips an account storing no credential (issue #1120)", async () => {
+		const due = baseAccount({ accountId: "acct_due" });
+		const credentialless = baseAccount({
+			accountId: "acct_no_credential",
+			passwordHash: undefined,
+		});
+
+		const accountService = fakeAccountService([
+			{ items: [due, credentialless], cursor: null },
+		]);
+		const { sqsClient, sent } = fakeSqsClient();
+
+		const result = await runSchedulerTick({
+			accountService,
+			sqsClient,
+			queueUrl:
+				"https://sqs.eu-west-1.amazonaws.com/123/remit-dev-mailboxes.fifo",
+			log: createNoopLogger(),
+			tickIntervalMs: TICK_INTERVAL_MS,
+			offlineIntervalMs: OFFLINE_INTERVAL_MS,
+			now: NOW,
+		});
+
+		assert.equal(result.enqueued, 1);
+		assert.equal(result.skipped, 1);
+		assert.equal(sent.length, 1);
+		const body = JSON.parse(sent[0]?.input.MessageBody ?? "{}");
+		assert.equal(body.accountId, "acct_due");
+	});
+
 	it("never logs per-account for ineligible accounts — only the aggregate tick summary (review #1250)", async () => {
 		const deleted = baseAccount({ accountId: "acct_deleted", deletedAt: NOW });
 		const unsyncable = baseAccount({

package/src/scheduler/run-tick.ts

@@ -5,6 +5,7 @@ import {
 } from "@remit/backend/trigger-sync";
 import type { AccountItem, IAccountRepository } from "@remit/data-ports";
 import type { Logger } from "@remit/logger-lambda";
+import { hasStoredCredential } from "@remit/mailbox-service/account-credentials";
 import pMap from "p-map";
 import {
 	isAccountDeleted,
@@ -79,6 +80,10 @@ const isEligible = (account: AccountItem): boolean => {
 	if (isAccountDeleted(account, silentLogger)) return false;
 	if (isUnsyncableHost(account, silentLogger)) return false;
 	if (isAccountReauthRequired(account, silentLogger)) return false;
+	// An account storing no credential can only produce a sync that fails at
+	// credential resolution (issue #1120); the tick would enqueue one every
+	// tick, forever, for an account the user never finished setting up.
+	if (!hasStoredCredential(account)) return false;
 	return true;
 };
 

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

@@ -6,7 +6,7 @@ import { RefreshTokenError } from "@remit/mail-oauth-service";
 import {
 	MailConnectionError,
 	type MailCredentials,
-} from "@remit/mailbox-service";
+} from "@remit/mailbox-service/types";
 import {
 	type ConnectionStateValue,
 	type OAuthLifecycleDeps,
@@ -75,7 +75,7 @@ const buildDeps = (
 			options.resolveCredentials ??
 			(async () => {
 				recorded.resolveCalls += 1;
-				return passwordCreds;
+				return { status: "resolved", credentials: passwordCreds };
 			}),
 	};
 	// Wrap resolveCredentials to record the call count when a custom one is given.
@@ -210,6 +210,36 @@ describe("withOAuthLifecycle", () => {
 		assert.equal(recorded.stateUpdates.length, 0);
 	});
 
+	it("password account with no passwordHash: ACKs and flips to credentials_missing", async () => {
+		const { deps, recorded } = buildDeps();
+		delete deps.resolveCredentials;
+		const account = buildAccount({ authType: AccountAuthType.Password });
+
+		await withOAuthLifecycle(deps, account, silentLogger, async () => {
+			recorded.workCalls += 1;
+		});
+
+		assert.equal(recorded.workCalls, 0, "no IMAP traffic without a credential");
+		assert.deepEqual(recorded.stateUpdates, [
+			{ accountId: "acc-1", state: ConnectionState.CredentialsMissing },
+		]);
+	});
+
+	it("OAuth account with no refresh token: ACKs and flips to reauth_required", async () => {
+		const { deps, recorded } = buildDeps();
+		delete deps.resolveCredentials;
+		const account = buildAccount({ authType: AccountAuthType.OauthMicrosoft });
+
+		await withOAuthLifecycle(deps, account, silentLogger, async () => {
+			recorded.workCalls += 1;
+		});
+
+		assert.equal(recorded.workCalls, 0, "no IMAP traffic without a credential");
+		assert.deepEqual(recorded.stateUpdates, [
+			{ accountId: "acc-1", state: ConnectionState.ReauthRequired },
+		]);
+	});
+
 	it("on RefreshTokenError transient: rethrows", async () => {
 		const { deps, recorded } = buildDeps({
 			resolveCredentials: async () => {

package/src/with-oauth-lifecycle.ts

@@ -8,6 +8,11 @@
  *  - Credential resolution AND the per-handler work both run inside one
  *    try/catch so that a revoked OAuth token is caught regardless of where it
  *    surfaces (token mint vs. first IMAP command).
+ *  - An account storing no credential at all is terminal, not transient: the
+ *    account is flipped to the state that describes it and the event is ACKed.
+ *    Retrying instead fenced the account's FIFO group for the message's whole
+ *    visibility timeout, blocking the sync that follows the credential the
+ *    user was still typing (issue #1120).
  *  - 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.
@@ -23,15 +28,17 @@ import type { Logger } from "@remit/logger-lambda";
 import { RefreshTokenError } from "@remit/mail-oauth-service";
 import {
 	type AccountCredentialsDeps,
+	type ConnectionStateValue,
+	type CredentialResolution,
+	resolveConnectionCredentials,
+} from "@remit/mailbox-service/account-credentials";
+import {
 	MailConnectionError,
 	type MailCredentials,
-	resolveConnectionCredentials,
-} from "@remit/mailbox-service";
+} from "@remit/mailbox-service/types";
 import { isAccountReauthRequired } from "./account-check.js";
 
-/** ConnectionState is a const object (not a TS enum); this is its value type. */
-export type ConnectionStateValue =
-	(typeof ConnectionState)[keyof typeof ConnectionState];
+export type { ConnectionStateValue };
 
 export interface OAuthLifecycleDeps extends AccountCredentialsDeps {
 	/**
@@ -50,7 +57,7 @@ export interface OAuthLifecycleDeps extends AccountCredentialsDeps {
 	resolveCredentials?: (
 		account: AccountItem,
 		deps: AccountCredentialsDeps,
-	) => Promise<MailCredentials>;
+	) => Promise<CredentialResolution>;
 }
 
 /**
@@ -73,8 +80,23 @@ export const withOAuthLifecycle = async (
 	const resolve = deps.resolveCredentials ?? resolveConnectionCredentials;
 
 	try {
-		const credentials = await resolve(account, deps);
-		await work(credentials);
+		const resolution = await resolve(account, deps);
+		if (resolution.status === "missing") {
+			log.warn(
+				{
+					accountId: account.accountId,
+					reason: resolution.reason,
+					connectionState: resolution.terminalState,
+				},
+				"Account stores no credential; acking the event without IMAP traffic",
+			);
+			await deps.updateConnectionState(
+				account.accountId,
+				resolution.terminalState,
+			);
+			return; // ACK — no retry can produce a credential
+		}
+		await work(resolution.credentials);
 	} catch (err) {
 		// Terminal OAuth failure: token revoked / consent withdrawn.
 		if (err instanceof RefreshTokenError) {