@remit/imap-worker 0.0.90 → 0.0.92

package/dist/scheduler/run-tick.js

@@ -0,0 +1,164 @@
+import { buildScheduledSyncDedupId, triggerAccountSync, } from "@remit/backend/trigger-sync";
+import { hasStoredCredential } from "@remit/mailbox-service/account-credentials";
+import pMap from "p-map";
+import { isAccountDeleted, isAccountReauthRequired, isMailSyncDisabled, isUnsyncableHost, } from "../account-check.js";
+import { SCHEDULER_ENQUEUE_CONCURRENCY, SCHEDULER_PAGE_SIZE, } from "./config.js";
+import { isSyncDue } from "./decide-due.js";
+/**
+ * `isAccountDeleted` / `isUnsyncableHost` / `isAccountReauthRequired` each log
+ * one line per ineligible account — the right volume for their real call site
+ * (once per SYNC_MAILBOXES event). Run across the whole account base every
+ * tick, that becomes one log line per deleted/reauth/placeholder account
+ * every 5 minutes, forever (review #1250). The tick already reports the
+ * aggregate `skipped` count, so eligibility checks here go through a silent
+ * logger — the per-event path (sync-mailboxes.ts) is untouched and keeps
+ * logging normally.
+ */
+const silentLogger = (() => {
+    const noop = () => { };
+    const stub = {
+        info: noop,
+        warn: noop,
+        error: noop,
+        debug: noop,
+        fatal: noop,
+        trace: noop,
+        child: () => stub,
+    };
+    return stub;
+})();
+const isEligible = (account) => {
+    if (isAccountDeleted(account, silentLogger))
+        return false;
+    if (isMailSyncDisabled(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;
+};
+/**
+ * One tick of the periodic mailbox-sync scheduler (#1247, restructured
+ * #1251). Pages through every account (never loading the whole account base
+ * into memory), decides per account via `isSyncDue` against the single
+ * offline threshold, and enqueues SYNC_MAILBOXES for the accounts that are
+ * due — in bounded-concurrency batches, never an unbounded `Promise.all`.
+ *
+ * Every enqueue goes through the same `triggerAccountSync` the manual
+ * POST /sync path uses, with a scheduler-specific, time-bucketed dedup id
+ * (`buildScheduledSyncDedupId`, bucketed by `tickIntervalMs`) so this tick
+ * can never collide with its own previous tick or with a concurrent manual
+ * trigger (see trigger-sync.ts). Concurrent-sync safety for the mailbox
+ * itself is MailboxLockService's job, inside the worker handler — this tick
+ * only decides "is a sync due" and enqueues; it never talks to IMAP.
+ */
+export const runSchedulerTick = async (deps) => {
+    const { accountService, queue, log, offlineIntervalMs, tickIntervalMs } = deps;
+    const now = deps.now ?? Date.now();
+    let cursor;
+    let scanned = 0;
+    let enqueued = 0;
+    let skipped = 0;
+    let swept = 0;
+    let sweepFailed = 0;
+    let redriven = 0;
+    let redriveFailed = 0;
+    do {
+        const page = await accountService.listAllAccountsPage({
+            limit: SCHEDULER_PAGE_SIZE,
+            cursor,
+        });
+        scanned += page.items.length;
+        const due = page.items.filter((account) => isEligible(account) && isSyncDue(account, now, offlineIntervalMs));
+        skipped += page.items.length - due.length;
+        await pMap(due, (account) => triggerAccountSync({
+            queue,
+            accountId: account.accountId,
+            dedupId: buildScheduledSyncDedupId(account.accountId, now, tickIntervalMs),
+        }), { concurrency: SCHEDULER_ENQUEUE_CONCURRENCY });
+        enqueued += due.length;
+        if (deps.sweepAttachments) {
+            // After the enqueue, never before it. Enqueuing mail is the tick's job
+            // and collecting bytes is housekeeping; on a hosted Lambda a slow sweep
+            // ahead of the enqueue eats the invocation budget, and a timeout is not
+            // catchable, so the remaining pages would never be enqueued at all.
+            //
+            // Every account, not only the ones due a sync: abandoned bytes have
+            // nothing to do with how recently mail was fetched. Bounded to the same
+            // concurrency as the enqueues.
+            //
+            // Contained, because this is housekeeping and enqueuing mail is not. An
+            // unreadable input or a storage permission error thrown from here would
+            // otherwise reach the loop, which logs and exits, and compose would
+            // restart the process every five seconds — no account would ever be
+            // enqueued again. A failed sweep costs a tick's collection and nothing
+            // else; the count is what makes that visible.
+            const sweep = deps.sweepAttachments;
+            const outcomes = await pMap(page.items, (account) => sweep(account).then(() => true, (error) => {
+                log.error({ accountId: account.accountId, error }, "Outbox attachment sweep failed for account");
+                return false;
+            }), { concurrency: SCHEDULER_ENQUEUE_CONCURRENCY });
+            swept += outcomes.filter(Boolean).length;
+            sweepFailed += outcomes.filter((ok) => !ok).length;
+        }
+        // Contained like the sweep, and for the same reason: a failed re-drive
+        // costs one account this tick, never the scheduler. Eligible accounts
+        // only, since a re-driven event needs a connection to settle anything.
+        const redrives = await pMap(page.items.filter(isEligible), (account) => deps.redriveStrandedPlacements(account, now).then((count) => count, (error) => {
+            log.error({ accountId: account.accountId, error }, "Stranded placement re-drive failed for account");
+            return null;
+        }), { concurrency: SCHEDULER_ENQUEUE_CONCURRENCY });
+        for (const count of redrives) {
+            if (count === null) {
+                redriveFailed += 1;
+                continue;
+            }
+            redriven += count;
+        }
+        cursor = page.cursor ?? undefined;
+    } while (cursor);
+    let subscriptionsRefreshed = 0;
+    let subscriptionsFailed = 0;
+    if (deps.refreshCalendarSubscriptions) {
+        // After every page is enqueued, for the same reason the sweep runs after
+        // the enqueue: a slow feed must never cost an account its mail. Contained
+        // like the sweep, so an unreadable store costs a tick's refresh and not
+        // the scheduler.
+        const tally = await deps
+            .refreshCalendarSubscriptions(now, offlineIntervalMs)
+            .catch((error) => {
+            log.error({ error }, "Calendar subscription refresh failed");
+            return { refreshed: 0, failed: 0, notDue: 0 };
+        });
+        subscriptionsRefreshed = tally.refreshed;
+        subscriptionsFailed = tally.failed;
+    }
+    log.info({
+        scanned,
+        enqueued,
+        skipped,
+        swept,
+        sweepFailed,
+        subscriptionsRefreshed,
+        subscriptionsFailed,
+        redriven,
+        redriveFailed,
+    }, "Scheduled-sync tick complete");
+    return {
+        scanned,
+        enqueued,
+        skipped,
+        swept,
+        sweepFailed,
+        subscriptionsRefreshed,
+        subscriptionsFailed,
+        redriven,
+        redriveFailed,
+    };
+};

package/dist/scheduler/runner.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/scheduler/runner.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { setTimeout as delay } from "node:timers/promises";
+import { finishHalfDeletedAccounts } from "@remit/backend/account-deletion";
+import { getClient } from "@remit/backend/client";
+import { createLogger } from "@remit/logger";
+import { installNodeLogger } from "@remit/logger-lambda/node";
+import { backfillSearchText } from "@remit/mailbox-service";
+import { clearHeartbeats, createHeartbeat } from "@remit/sqs-client/heartbeat";
+import { lambdaEmitEvent } from "../lambda-context.js";
+import { sqsWorkerQueues, workerQueueUrlsFromEnv } from "../sqs-queues.js";
+import { buildCalendarSubscriptionRefresh } from "./calendar-subscriptions.js";
+import { getOfflineIntervalMs, getTickIntervalMs } from "./config.js";
+import { runSchedulerLoop } from "./loop.js";
+import { buildAttachmentSweep, redriveStrandedPlacements, runSchedulerTick, } from "./tick.js";
+installNodeLogger();
+/**
+ * The scheduled-sync runner for every deployment that has no EventBridge: the
+ * self-host stack's `scheduler` service and the local dev compose stack. A
+ * managed deployment fires `runSchedulerTick` off an EventBridge schedule (see
+ * handler.ts); this process ticks the same function on a plain loop at the same
+ * `MAILBOX_SYNC_TICK_INTERVAL_SECONDS` cadence, so there is one scheduling
+ * implementation and one set of knobs.
+ *
+ * A tick failure crashes the process loudly rather than being swallowed —
+ * compose's `restart: unless-stopped` brings it back for the next tick.
+ *
+ * Liveness is a heartbeat file, the same mechanism as a worker's poll loop (D1
+ * of docs/design/standalone-observability.md); loop.ts carries where in the loop
+ * it is written and why. Clearing the previous generation's file here is what
+ * extends that answer across a restart. A completed round is still not the same
+ * as mail arriving: the accounts that came due are enqueued for workers to
+ * fetch, and whether that fetch lands is what
+ * `remit_account_sync_age_seconds` measures.
+ */
+const log = createLogger();
+const queues = sqsWorkerQueues(workerQueueUrlsFromEnv());
+const tickIntervalMs = getTickIntervalMs(process.env);
+const offlineIntervalMs = getOfflineIntervalMs(process.env);
+// A persistent failure (e.g. Postgres not up yet at container boot) throws
+// before the loop ever reaches its own `delay`, so `restart: unless-stopped`
+// would otherwise respawn the process immediately — a tight, log-flooding
+// crash loop (review #1250). This fixed pause before exiting is not retry
+// logic (there is nothing to retry here; the container restart IS the
+// retry) — it only paces how fast that restart can happen.
+const CRASH_BACKOFF_MS = 5_000;
+log.info({ tickIntervalMs, offlineIntervalMs }, "Scheduled-sync runner started");
+const runLoop = async () => {
+    // Neither call on the monitoring file may take the scheduler down with it. An
+    // unreadable or full /data/heartbeat is a reason to keep enqueuing mail, not
+    // to stop. A clear that fails leaves the previous generation's file, which
+    // ages out at the same threshold; a write that fails is the missed beat that
+    // is itself the signal. Two messages because they are different problems: one
+    // is a volume this container could not read at boot, the other a write it
+    // could not make this round.
+    const onClearError = (error) => {
+        log.error({ error }, "Scheduled-sync heartbeat clear failed");
+    };
+    const onBeatError = (error) => {
+        log.error({ error }, "Scheduled-sync heartbeat write failed");
+    };
+    await clearHeartbeats().catch(onClearError);
+    const client = await getClient();
+    const { account } = client;
+    await finishHalfDeletedAccounts({
+        account,
+        configImport: client.configImport,
+        queue: client.queues.accountFanout,
+        log,
+    });
+    const searchTextBackfill = backfillSearchText({ messageService: client.message, storageService: client.storage }, log).then((result) => {
+        log.debug({ ...result }, "Search text backfill finished");
+    });
+    const schedulerLoop = runSchedulerLoop({
+        tick: runSchedulerTick,
+        tickDeps: {
+            accountService: account,
+            queue: queues.mailboxes,
+            log,
+            tickIntervalMs,
+            offlineIntervalMs,
+            sweepAttachments: buildAttachmentSweep(client, log),
+            refreshCalendarSubscriptions: buildCalendarSubscriptionRefresh(client, log),
+            redriveStrandedPlacements: (stranded, now) => redriveStrandedPlacements({
+                client,
+                emit: lambdaEmitEvent(queues, client.mailboxLock),
+                log,
+            }, stranded, now),
+        },
+        heartbeat: createHeartbeat("tick"),
+        onHeartbeatError: onBeatError,
+        tickIntervalMs,
+    });
+    await Promise.all([searchTextBackfill, schedulerLoop]);
+};
+runLoop()
+    .catch(async (error) => {
+    log.error({ error }, "Scheduled-sync tick failed");
+    await delay(CRASH_BACKOFF_MS);
+})
+    .finally(() => {
+    process.exit(1);
+});

package/dist/scheduler/stranded-placement-redrive.d.ts

@@ -0,0 +1,16 @@
+import type { RemitClient } from "@remit/backend/client";
+import type { AccountItem } from "@remit/data-ports";
+import type { Logger } from "@remit/logger";
+import type { MessageCopyEventV3, MessageDeleteEventV3, MessageMoveEventV3, PlacementMovePushEvent } from "../events.js";
+/** Well past three attempts on a 60 s visibility timeout. */
+export declare const STRANDED_PLACEMENT_AFTER_MILLIS: number;
+type Unstamped<T> = Omit<T, "eventId" | "timestamp">;
+export type StrandedPlacementEvent = Unstamped<PlacementMovePushEvent> | Unstamped<MessageDeleteEventV3> | Unstamped<MessageMoveEventV3> | Unstamped<MessageCopyEventV3>;
+export interface StrandedPlacementRedriveDeps {
+    client: Pick<RemitClient, "mailbox" | "mailboxSpecialUse" | "message" | "placementMove" | "threadMessage">;
+    emit: (event: StrandedPlacementEvent) => Promise<void>;
+    log: Logger;
+}
+/** The claim restarts the row's clock; a folder awaiting a cursor rebuild waits until it is normal. */
+export declare const redriveStrandedPlacements: (deps: StrandedPlacementRedriveDeps, account: AccountItem, now: number) => Promise<number>;
+export {};

package/dist/scheduler/stranded-placement-redrive.js

@@ -0,0 +1,172 @@
+import { trashMailboxAt } from "@remit/data-ports/folder-role";
+import { deriveCopyMessageId, deriveMessageId, isValidMessageId, } from "@remit/data-ports/id";
+import { PATHLESS_MUTATION_EVENT_SCHEMA_VERSION } from "@remit/data-ports/mutation-events";
+import { MessageStatus, MessageSyncStatus } from "@remit/domain-enums";
+import { isCursorRebuildNeeded } from "@remit/mailbox-service";
+/** Well past three attempts on a 60 s visibility timeout. */
+export const STRANDED_PLACEMENT_AFTER_MILLIS = 60 * 60 * 1000;
+const isStrandedCopy = (row) => row.status === MessageStatus.moving &&
+    row.uid === 0 &&
+    typeof row.originalUid !== "number";
+/**
+ * The message a uid-0 copy was made from: its id derives from the Message-ID
+ * the copy's listing row carries, and the copy's own id derives from it.
+ */
+const copyRedriveFor = async (client, account, copy) => {
+    const listing = await client.threadMessage.findByMessageId(account.accountConfigId, copy.messageId);
+    if (!listing)
+        return { kind: "unresolvable", reason: "listing row missing" };
+    const header = listing.messageIdHeader;
+    if (!header || !isValidMessageId(header)) {
+        return { kind: "unresolvable", reason: "listing row has no Message-ID" };
+    }
+    const sourceId = deriveMessageId(account.accountId, header);
+    if (deriveCopyMessageId(sourceId, copy.mailboxId) !== copy.messageId) {
+        return {
+            kind: "unresolvable",
+            reason: "copy was not made from the message its Message-ID names",
+        };
+    }
+    const [source] = await client.message.get([sourceId]);
+    if (!source)
+        return { kind: "unresolvable", reason: "source row missing" };
+    if (source.status === MessageStatus.deleted) {
+        return { kind: "unresolvable", reason: "source row deleted" };
+    }
+    if (source.status !== MessageStatus.active)
+        return { kind: "wait" };
+    return {
+        kind: "redrive",
+        event: {
+            type: "MESSAGE_COPY",
+            schemaVersion: PATHLESS_MUTATION_EVENT_SCHEMA_VERSION,
+            accountId: account.accountId,
+            sourceMessageId: source.messageId,
+            newMessageId: copy.messageId,
+            sourceMailboxId: source.mailboxId,
+            destinationMailboxId: copy.mailboxId,
+            uid: source.uid,
+        },
+    };
+};
+/** A copy with no source to copy from has nothing to bind and nothing to hide. */
+const removeUnresolvableCopy = async (deps, account, row, reason, now) => {
+    const removed = await deps.client.message.deleteIfPlacement(row.messageId, {
+        status: MessageStatus.moving,
+        mailboxId: row.mailboxId,
+        uid: 0,
+    });
+    if (!removed)
+        return false;
+    deps.log.error({
+        alert: "stranded_copy_unresolvable",
+        accountId: account.accountId,
+        messageId: row.messageId,
+        mailboxId: row.mailboxId,
+        reason,
+        untouchedForMs: now - row.updatedAt,
+    }, "A copy stranded at uid 0 has no source to copy from; the copy row was removed");
+    return true;
+};
+const eventFor = async (client, account, row, trashMailboxId) => {
+    const { accountId, accountConfigId } = account;
+    const { messageId } = row;
+    if (row.status === MessageStatus.deleting) {
+        return {
+            type: "MESSAGE_DELETE",
+            schemaVersion: PATHLESS_MUTATION_EVENT_SCHEMA_VERSION,
+            accountId,
+            messageId,
+            mailboxId: row.mailboxId,
+            uid: row.uid,
+            operation: "permanent_delete",
+        };
+    }
+    if (typeof row.originalMailboxId !== "string" ||
+        typeof row.originalUid !== "number") {
+        return undefined;
+    }
+    const marker = await client.placementMove.find(messageId);
+    if (marker && marker.destinationMailboxId === row.mailboxId) {
+        return {
+            type: "PLACEMENT_MOVE_PUSH",
+            accountId,
+            accountConfigId,
+            messageId,
+        };
+    }
+    if (row.mailboxId === trashMailboxId) {
+        return {
+            type: "MESSAGE_DELETE",
+            schemaVersion: PATHLESS_MUTATION_EVENT_SCHEMA_VERSION,
+            accountId,
+            messageId,
+            mailboxId: row.originalMailboxId,
+            uid: row.originalUid,
+            operation: "move_to_trash",
+            destinationMailboxId: row.mailboxId,
+        };
+    }
+    return {
+        type: "MESSAGE_MOVE",
+        schemaVersion: PATHLESS_MUTATION_EVENT_SCHEMA_VERSION,
+        accountId,
+        messageId,
+        sourceMailboxId: row.originalMailboxId,
+        destinationMailboxId: row.mailboxId,
+        uid: row.originalUid,
+    };
+};
+/** The claim restarts the row's clock; a folder awaiting a cursor rebuild waits until it is normal. */
+export const redriveStrandedPlacements = async (deps, account, now) => {
+    const { client, emit, log } = deps;
+    const { accountId } = account;
+    const mailboxes = await client.mailbox.listAllByAccount(accountId);
+    const paused = new Set(mailboxes
+        .filter((mailbox) => isCursorRebuildNeeded(mailbox.cursorState))
+        .map((mailbox) => mailbox.mailboxId));
+    const stranded = (await client.message.listStrandedPlacements(mailboxes.map((mailbox) => mailbox.mailboxId), now - STRANDED_PLACEMENT_AFTER_MILLIS)).filter((row) => !paused.has(row.mailboxId) &&
+        !(row.originalMailboxId && paused.has(row.originalMailboxId)));
+    if (stranded.length === 0)
+        return 0;
+    const trash = trashMailboxAt(await client.mailboxSpecialUse.resolveTrashRole(accountId), "resolved");
+    const trashMailboxId = trash.allowed ? trash.mailbox.mailboxId : undefined;
+    let redriven = 0;
+    for (const row of stranded) {
+        const copy = isStrandedCopy(row)
+            ? await copyRedriveFor(client, account, row)
+            : undefined;
+        if (copy?.kind === "wait")
+            continue;
+        if (copy?.kind === "unresolvable") {
+            if (await removeUnresolvableCopy(deps, account, row, copy.reason, now)) {
+                redriven += 1;
+            }
+            continue;
+        }
+        const event = copy?.kind === "redrive"
+            ? copy.event
+            : await eventFor(client, account, row, trashMailboxId);
+        if (!event)
+            continue;
+        // A copy's earlier COPY may have landed with its answer lost, so the
+        // re-drive marks it `failed`: the copy handler then asks the destination
+        // before it copies again.
+        const claimed = await client.message.transitionPlacement(row.messageId, { status: row.status, mailboxId: row.mailboxId, uid: row.uid }, {
+            syncStatus: copy ? MessageSyncStatus.failed : MessageSyncStatus.pending,
+        });
+        if (!claimed)
+            continue;
+        await emit(event);
+        redriven += 1;
+        log.warn({
+            metric: "stranded_placement_redriven",
+            accountId,
+            messageId: row.messageId,
+            event: event.type,
+            syncStatus: row.syncStatus,
+            untouchedForMs: now - row.updatedAt,
+        }, "A move or delete had no event left to settle it; re-driven");
+    }
+    return redriven;
+};

package/dist/scheduler/tick.d.ts

@@ -0,0 +1,5 @@
+export { createEmitEvent, type EmitDeps, type EmitEvent } from "../emit.js";
+export { buildAttachmentSweep } from "./attachment-sweep.js";
+export { DEFAULT_OFFLINE_INTERVAL_MS, DEFAULT_TICK_INTERVAL_MS, } from "./config.js";
+export { type CalendarSubscriptionTally, type RunSchedulerTickDeps, runSchedulerTick, type SchedulerTickResult, } from "./run-tick.js";
+export { redriveStrandedPlacements, type StrandedPlacementEvent, type StrandedPlacementRedriveDeps, } from "./stranded-placement-redrive.js";

package/dist/scheduler/tick.js

@@ -0,0 +1,5 @@
+export { createEmitEvent } from "../emit.js";
+export { buildAttachmentSweep } from "./attachment-sweep.js";
+export { DEFAULT_OFFLINE_INTERVAL_MS, DEFAULT_TICK_INTERVAL_MS, } from "./config.js";
+export { runSchedulerTick, } from "./run-tick.js";
+export { redriveStrandedPlacements, } from "./stranded-placement-redrive.js";

package/dist/sqs-queues.d.ts

@@ -0,0 +1,4 @@
+import type { WorkerQueues } from "./queues.js";
+export type WorkerQueueUrls = Record<keyof WorkerQueues, string>;
+export declare const workerQueueUrlsFromEnv: () => WorkerQueueUrls;
+export declare const sqsWorkerQueues: (urls: WorkerQueueUrls) => WorkerQueues;

package/dist/sqs-queues.js

@@ -0,0 +1,22 @@
+import { createFifoQueueProducer, createStandardQueueProducer, } from "@remit/sqs-client/producer";
+import { env } from "expect-env";
+export const workerQueueUrlsFromEnv = () => ({
+    mailboxes: env.SQS_QUEUE_URL_MAILBOXES,
+    messages: env.SQS_QUEUE_URL_MESSAGES,
+    flags: env.SQS_QUEUE_URL_FLAGS,
+    body: env.SQS_QUEUE_URL_BODY,
+    mailboxManagement: env.SQS_QUEUE_URL_MAILBOX_MGMT,
+    messageManagement: env.SQS_QUEUE_URL_MESSAGE_MGMT,
+});
+export const sqsWorkerQueues = (urls) => ({
+    mailboxes: createFifoQueueProducer({ queueUrl: urls.mailboxes }),
+    messages: createFifoQueueProducer({ queueUrl: urls.messages }),
+    flags: createFifoQueueProducer({ queueUrl: urls.flags }),
+    body: createStandardQueueProducer({ queueUrl: urls.body }),
+    mailboxManagement: createStandardQueueProducer({
+        queueUrl: urls.mailboxManagement,
+    }),
+    messageManagement: createStandardQueueProducer({
+        queueUrl: urls.messageManagement,
+    }),
+});

package/dist/with-oauth-lifecycle-deps.d.ts

@@ -0,0 +1,5 @@
+import type { IAccountRepository } from "@remit/data-ports";
+import type { SecretsService } from "@remit/secrets-service";
+import type { TokenService } from "./context.js";
+import type { OAuthLifecycleDeps } from "./with-oauth-lifecycle.js";
+export declare const buildLifecycleDeps: (secrets: SecretsService, accountService: IAccountRepository, tokenService: TokenService) => OAuthLifecycleDeps;

package/dist/with-oauth-lifecycle-deps.js

@@ -0,0 +1,17 @@
+export const buildLifecycleDeps = (secrets, accountService, tokenService) => ({
+    secrets,
+    tokenService,
+    persistRotatedToken: async (accountId, encryptedHash, updatedAt) => {
+        await accountService.update(accountId, {
+            oauthRefreshTokenHash: encryptedHash,
+            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, state, lastError) => {
+        await accountService.update(accountId, { connectionState: state, lastError }, lastError === undefined ? ["lastError"] : undefined);
+    },
+});

package/dist/with-oauth-lifecycle.d.ts

@@ -0,0 +1,56 @@
+/**
+ * with-oauth-lifecycle.ts
+ *
+ * Centralizes the OAuth reauth/ACK contract shared by every IMAP handler.
+ *
+ * The contract (see issue #472):
+ *  - If the account already requires reauth, skip all IMAP traffic entirely.
+ *  - 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.
+ *    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).
+ *
+ * Tokens must NEVER appear in logs — only accountId / errorKind / errorCode.
+ */
+import type { AccountItem } from "@remit/data-ports";
+import type { Logger } from "@remit/logger";
+import { type AccountCredentialsDeps, type ConnectionStateValue, type CredentialResolution } from "@remit/mailbox-service/account-credentials";
+import { type MailCredentials } from "@remit/mailbox-service/types";
+export type { ConnectionStateValue };
+export interface OAuthLifecycleDeps extends AccountCredentialsDeps {
+    /**
+     * 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
+     * resolveConnectionCredentials; overridable for testing. Kept as the ONLY
+     * authType branch in the codebase (see account-credentials.ts).
+     */
+    resolveCredentials?: (account: AccountItem, deps: AccountCredentialsDeps) => Promise<CredentialResolution>;
+}
+/**
+ * Run `work` for an account under the shared OAuth reauth/ACK contract.
+ *
+ * `work` receives the resolved MailCredentials. Both credential resolution and
+ * `work` run inside the same try/catch.
+ */
+export declare const withOAuthLifecycle: (deps: OAuthLifecycleDeps, account: AccountItem, log: Logger, work: (credentials: MailCredentials) => Promise<void>) => Promise<void>;