@remit/imap-worker 0.0.90 → 0.0.92

package/dist/with-oauth-lifecycle.js

@@ -0,0 +1,92 @@
+/**
+ * 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 { AccountAuthType, ConnectionState } from "@remit/domain-enums";
+import { RefreshTokenError } from "@remit/mail-oauth-service";
+import { resolveConnectionCredentials, } from "@remit/mailbox-service/account-credentials";
+import { MailConnectionError, } from "@remit/mailbox-service/types";
+import { isAccountReauthRequired } from "./account-check.js";
+/**
+ * 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 const withOAuthLifecycle = async (deps, account, log, work) => {
+    // Skip all IMAP traffic for accounts that already require reauth.
+    if (isAccountReauthRequired(account, log)) {
+        return;
+    }
+    const resolve = deps.resolveCredentials ?? resolveConnectionCredentials;
+    try {
+        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) {
+            if (err.error.kind === "reauth-required") {
+                log.warn({
+                    accountId: account.accountId,
+                    errorKind: err.error.kind,
+                    errorCode: err.error.code,
+                }, "OAuth token revoked; marking account reauth_required");
+                await deps.updateConnectionState(account.accountId, ConnectionState.ReauthRequired);
+                return; // ACK — do not retry
+            }
+            // transient or config: let-it-crash (SQS retry / DLQ)
+            throw err;
+        }
+        // Terminal auth failure at the IMAP layer (bad credentials / expired token).
+        // Only OAuth accounts can recover via the re-auth flow; password accounts
+        // have no such path so we rethrow to preserve pre-PR batch-item-failure
+        // behaviour instead of permanently fencing the account.
+        if (err instanceof MailConnectionError && err.kind === "auth") {
+            if (account.authType !== AccountAuthType.OauthMicrosoft) {
+                throw err;
+            }
+            log.warn({
+                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
+        }
+        // Transient / network / unexpected: rethrow so SQS retries with backoff.
+        throw err;
+    }
+};

package/{src/worker-version.ts → dist/worker-version.d.ts}

@@ -9,5 +9,4 @@
  * CI-provided SHA, then to `dev`, so a local run is labelled honestly rather
  * than claiming a release it is not.
  */
-export const workerVersion = (): string =>
-	process.env.REMIT_WORKER_SHA || process.env.GITHUB_SHA || "dev";
+export declare const workerVersion: () => string;

package/dist/worker-version.js

@@ -0,0 +1,12 @@
+/**
+ * The build of this worker, stamped onto a quarantine record so a maintainer
+ * reading a filed report knows which commit failed to read the message.
+ *
+ * Deliberately not the client's `APP_SHA`: that is the web build, and pointing
+ * a maintainer at it for a backend parse failure sends them to the wrong
+ * commit. The container bundle replaces this read at build time (see
+ * `npm-scripts/docker-bundle.mjs`); outside an image build it falls back to the
+ * CI-provided SHA, then to `dev`, so a local run is labelled honestly rather
+ * than claiming a release it is not.
+ */
+export const workerVersion = () => process.env.REMIT_WORKER_SHA || process.env.GITHUB_SHA || "dev";

package/package.json

@@ -1,71 +1,81 @@
 {
-  "name": "@remit/imap-worker",
-  "version": "0.0.90",
-  "type": "module",
-  "main": "dist/index.js",
-  "exports": {
-    ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
-    },
-    "./scheduler": {
-      "types": "./src/scheduler/handler.ts",
-      "default": "./src/scheduler/handler.ts"
-    },
-    "./mailbox-management": {
-      "types": "./src/handlers/mailbox-management.ts",
-      "default": "./src/handlers/mailbox-management.ts"
-    },
-    "./test-helpers/test-world": {
-      "types": "./src/test-helpers/test-world.ts",
-      "default": "./src/test-helpers/test-world.ts"
-    }
-  },
-  "bin": {
-    "remit-worker": "./dist/cli.js"
-  },
-  "scripts": {
-    "bundle": "esbuild src/index.ts --sourcemap --bundle --platform=node --format=esm --outfile=dist/index.js",
-    "cli": "node --env-file=../../localhost-dev-aws.env src/cli.ts",
-    "test:typecheck": "tsgo --noEmit",
-    "test:run": "node $NODE_TEST_FLAGS --env-file=../../localhost-test-unit.env --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=86 --test 'src/**/*.test.ts'",
-    "test": "npm run test:typecheck && npm run test:run",
-    "dev": "node --import tsx src/e2e-processor-shim.ts"
-  },
-  "devDependencies": {
-    "@remit/drizzle-service": "*",
-    "@remit/queue-sidecar": "*",
-    "@remit/storage-service": "*",
-    "aws-sdk-client-mock": "*",
-    "esbuild": "^0.28.1"
-  },
-  "dependencies": {
-    "@remit/logger": "*",
-    "@aws-sdk/client-s3": "^3.1055.0",
-    "@remit/config-transfer": "*",
-    "@remit/data-ports": "*",
-    "@remit/smtp-service": "*",
-    "@remit/logger-lambda": "*",
-    "@remit/mailbox-service": "*",
-    "@remit/sqs-client": "*",
-    "@remit/backend": "*",
-    "@remit/calendar-service": "*",
-    "@remit/domain-enums": "*",
-    "@remit/mail-oauth-service": "*",
-    "@remit/secrets-service": "*",
-    "@aws-sdk/client-sqs": "^3.1090.0",
-    "@aws-sdk/client-ssm": "^3.1090.0",
-    "expect-env": "^1.0.1",
-    "p-map": "^2.1.0",
-    "@types/aws-lambda": "^8.10.162"
-  },
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/remit-mail/reader.git",
-    "directory": "packages/imap-worker"
-  }
+	"name": "@remit/imap-worker",
+	"version": "0.0.92",
+	"type": "module",
+	"main": "dist/index.js",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./process": {
+			"types": "./dist/process.d.ts",
+			"default": "./dist/process.js"
+		},
+		"./scheduler": {
+			"types": "./dist/scheduler/handler.d.ts",
+			"default": "./dist/scheduler/handler.js"
+		},
+		"./scheduler-tick": {
+			"types": "./dist/scheduler/tick.d.ts",
+			"default": "./dist/scheduler/tick.js"
+		},
+		"./mailbox-management": {
+			"types": "./dist/handlers/mailbox-management.d.ts",
+			"default": "./dist/handlers/mailbox-management.js"
+		}
+	},
+	"bin": {
+		"remit-worker": "./dist/cli.js"
+	},
+	"scripts": {
+		"prepack": "node ../../npm-scripts/pack-dist.mjs prepack",
+		"postpack": "node ../../npm-scripts/pack-dist.mjs postpack",
+		"bundle": "esbuild src/index.ts --sourcemap --bundle --platform=node --format=esm --outfile=dist/index.js",
+		"cli": "node --env-file=../../localhost-dev-aws.env src/cli.ts",
+		"test:typecheck": "tsgo --noEmit",
+		"test:run": "node $NODE_TEST_FLAGS --env-file=../../localhost-test-unit.env --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=86 --test 'src/**/*.test.ts'",
+		"test": "npm run test:typecheck && npm run test:run",
+		"dev": "node --import tsx src/e2e-processor-shim.ts"
+	},
+	"devDependencies": {
+		"@remit/drizzle-service": "*",
+		"@remit/queue-sidecar": "*",
+		"@remit/storage-service": "*",
+		"aws-sdk-client-mock": "*",
+		"esbuild": "^0.28.1"
+	},
+	"dependencies": {
+		"@remit/logger": "*",
+		"@aws-sdk/client-s3": "^3.1055.0",
+		"@remit/config-transfer": "*",
+		"@remit/data-ports": "*",
+		"@remit/smtp-service": "*",
+		"@remit/logger-lambda": "*",
+		"@remit/mailbox-service": "*",
+		"@remit/sqs-client": "*",
+		"@remit/backend": "*",
+		"@remit/calendar-service": "*",
+		"@remit/domain-enums": "*",
+		"@remit/mail-oauth-service": "*",
+		"@remit/secrets-service": "*",
+		"@aws-sdk/client-sqs": "^3.1090.0",
+		"@aws-sdk/client-ssm": "^3.1090.0",
+		"expect-env": "^1.0.1",
+		"p-map": "^2.1.0",
+		"@types/aws-lambda": "^8.10.162"
+	},
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/remit-mail/reader.git",
+		"directory": "packages/imap-worker"
+	},
+	"types": "dist/index.d.ts",
+	"files": [
+		"dist"
+	]
 }

package/src/account-check.test.ts

@@ -1,149 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import type { AccountItem } from "@remit/data-ports";
-import {
-	isAccountDeleted,
-	isAccountReauthRequired,
-	isMailSyncDisabled,
-	isReservedHost,
-	isUnsyncableHost,
-} from "./account-check.js";
-
-const log = {
-	info: () => {},
-	warn: () => {},
-	error: () => {},
-	debug: () => {},
-} as unknown as Parameters<typeof isAccountDeleted>[1];
-
-const buildAccount = (overrides: Partial<AccountItem> = {}): AccountItem =>
-	({
-		accountId: "acct-1",
-		connectionState: "authenticated",
-		...overrides,
-	}) as unknown as AccountItem;
-
-describe("isAccountDeleted", () => {
-	it("returns false when deletedAt is absent", () => {
-		assert.equal(isAccountDeleted(buildAccount(), log), false);
-	});
-
-	it("returns true when deletedAt is set", () => {
-		assert.equal(
-			isAccountDeleted(buildAccount({ deletedAt: Date.now() }), log),
-			true,
-		);
-	});
-});
-
-describe("isReservedHost", () => {
-	const reserved = [
-		"invalid",
-		"example",
-		"imap.invalid",
-		"foo.invalid",
-		"server.invalid",
-		"SERVER.INVALID",
-		"mail.example",
-		"foo.example",
-		"  imap.invalid  ",
-	];
-	for (const host of reserved) {
-		it(`returns true for reserved host ${JSON.stringify(host)}`, () => {
-			assert.equal(isReservedHost(host), true);
-		});
-	}
-
-	// localhost / .localhost / .test are legitimately used by local & e2e envs,
-	// so they must NOT be skipped (issue #835 follow-up).
-	const real = [
-		"imap.hostnet.nl",
-		"imap.gmail.com",
-		"localhost",
-		"foo.localhost",
-		"foo.test",
-		"notlocalhost",
-		"invalid.com",
-		"example.com",
-		"test.org",
-	];
-	for (const host of real) {
-		it(`returns false for real host ${JSON.stringify(host)}`, () => {
-			assert.equal(isReservedHost(host), false);
-		});
-	}
-});
-
-describe("isUnsyncableHost", () => {
-	it("returns false for a resolvable host", () => {
-		assert.equal(
-			isUnsyncableHost(buildAccount({ imapHost: "imap.gmail.com" }), log),
-			false,
-		);
-	});
-
-	it("returns true for a reserved host", () => {
-		assert.equal(
-			isUnsyncableHost(buildAccount({ imapHost: "imap.invalid" }), log),
-			true,
-		);
-	});
-});
-
-describe("isAccountReauthRequired", () => {
-	it("returns false for authenticated accounts", () => {
-		assert.equal(
-			isAccountReauthRequired(
-				buildAccount({ connectionState: "authenticated" }),
-				log,
-			),
-			false,
-		);
-	});
-
-	it("returns false for not_authenticated accounts", () => {
-		assert.equal(
-			isAccountReauthRequired(
-				buildAccount({ connectionState: "not_authenticated" }),
-				log,
-			),
-			false,
-		);
-	});
-
-	it("returns true when connectionState is reauth_required", () => {
-		assert.equal(
-			isAccountReauthRequired(
-				buildAccount({ connectionState: "reauth_required" }),
-				log,
-			),
-			true,
-		);
-	});
-});
-
-describe("isMailSyncDisabled", () => {
-	it("returns false for a mail-only account", () => {
-		assert.equal(
-			isMailSyncDisabled(buildAccount({ syncedServices: ["Mail"] }), log),
-			false,
-		);
-	});
-
-	it("returns false for an account syncing mail and calendar", () => {
-		assert.equal(
-			isMailSyncDisabled(
-				buildAccount({ syncedServices: ["Mail", "Calendar"] }),
-				log,
-			),
-			false,
-		);
-	});
-
-	it("returns true for a calendar-only account", () => {
-		assert.equal(
-			isMailSyncDisabled(buildAccount({ syncedServices: ["Calendar"] }), log),
-			true,
-		);
-	});
-});

package/src/account-check.ts

@@ -1,101 +0,0 @@
-import type { AccountItem } from "@remit/data-ports";
-import { AccountService } from "@remit/domain-enums";
-import type { Logger } from "@remit/logger";
-
-/**
- * RFC 2606 reserved placeholder namespaces that are guaranteed never to resolve
- * and are not used by any local/dev/e2e environment: `.invalid` (the actual
- * smoke-test placeholder) and `.example`. An account pointed at one of these can
- * never connect, so syncing it would retry and dead-letter forever — we skip it.
- *
- * `localhost`/`.localhost` and `.test` are deliberately NOT skipped: the e2e and
- * mailfuzz suites run their IMAP server on `localhost`, and `.test` is commonly
- * used for local testing.
- */
-const RESERVED_NAMES = ["invalid", "example"] as const;
-const RESERVED_HOST_SUFFIXES = RESERVED_NAMES.map((name) => `.${name}`);
-
-/**
- * True when `host` is a reserved placeholder name that can never resolve.
- *
- * Matches the bare `invalid`/`example` and any subdomain of those namespaces
- * (`mail.example`, `foo.invalid`, …). Suffix matching is anchored on the dot so
- * real hosts like `invalid.com` or `imap.gmail.com` are NOT treated as reserved.
- */
-export const isReservedHost = (host: string): boolean => {
-	const normalized = host.trim().toLowerCase();
-	if (RESERVED_NAMES.includes(normalized as (typeof RESERVED_NAMES)[number])) {
-		return true;
-	}
-	return RESERVED_HOST_SUFFIXES.some((suffix) => normalized.endsWith(suffix));
-};
-
-/**
- * Check if an account's IMAP host can never resolve (reserved TLD).
- * Returns true if the account should be skipped cleanly — no connection
- * attempt, no thrown error, so the event is acked rather than dead-lettered.
- */
-export const isUnsyncableHost = (
-	account: AccountItem,
-	log: Logger,
-): boolean => {
-	if (isReservedHost(account.imapHost)) {
-		log.warn(
-			{ accountId: account.accountId, imapHost: account.imapHost },
-			"Skipping account: IMAP host is a reserved, never-resolvable name",
-		);
-		return true;
-	}
-	return false;
-};
-
-/**
- * Check if an account is deleted (tombstone pattern).
- * Returns true if the account should be skipped.
- */
-export const isAccountDeleted = (
-	account: AccountItem,
-	log: Logger,
-): boolean => {
-	if (account.deletedAt) {
-		log.info(
-			{ accountId: account.accountId, deletedAt: account.deletedAt },
-			"Skipping deleted account",
-		);
-		return true;
-	}
-	return false;
-};
-
-/**
- * Check if an account requires re-authentication (e.g. OAuth token revoked).
- * Returns true if the account should be skipped until the user re-auths.
- */
-export const isAccountReauthRequired = (
-	account: AccountItem,
-	log: Logger,
-): boolean => {
-	if (account.connectionState === "reauth_required") {
-		log.info(
-			{
-				accountId: account.accountId,
-				connectionState: account.connectionState,
-			},
-			"Skipping account: reauth required",
-		);
-		return true;
-	}
-	return false;
-};
-
-export const isMailSyncDisabled = (
-	account: AccountItem,
-	log: Logger,
-): boolean => {
-	if (account.syncedServices.includes(AccountService.Mail)) return false;
-	log.info(
-		{ accountId: account.accountId, syncedServices: account.syncedServices },
-		"Skipping account: mail sync is off",
-	);
-	return true;
-};