@remit/mailbox-service 0.0.81 → 0.0.83

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/mailbox-service",
-  "version": "0.0.81",
+  "version": "0.0.83",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -16,6 +16,10 @@
     "./account-credentials": {
       "types": "./src/account-credentials.ts",
       "default": "./src/account-credentials.ts"
+    },
+    "./types": {
+      "types": "./src/types.ts",
+      "default": "./src/types.ts"
     }
   },
   "scripts": {

package/src/account-credentials.ts

@@ -19,6 +19,83 @@ import {
 } from "@remit/secrets-service";
 import type { MailCredentials } from "./types.js";
 
+/** ConnectionState is a const object (not a TS enum); this is its value type. */
+export type ConnectionStateValue =
+	(typeof ConnectionState)[keyof typeof ConnectionState];
+
+/**
+ * The fields that say whether an account holds a credential at all. Narrower
+ * than AccountItem so a caller holding only an account summary can ask.
+ */
+export type StoredCredentialFields = Partial<
+	Pick<AccountItem, "authType" | "passwordHash" | "oauthRefreshTokenHash">
+>;
+
+/**
+ * No credential of the kind this account's authType needs is stored. An
+ * imported account holds none by design until its owner types one, so this is
+ * a normal state of the world rather than a fault: no retry can change it, and
+ * it is distinct from a credential the mail server rejected.
+ *
+ * `terminalState` is the connectionState that describes the account while it
+ * stays this way, decided here so nothing downstream branches on authType.
+ */
+export interface MissingCredential {
+	readonly status: "missing";
+	readonly terminalState: ConnectionStateValue;
+	readonly reason: string;
+}
+
+export type CredentialResolution =
+	| { readonly status: "resolved"; readonly credentials: MailCredentials }
+	| MissingCredential;
+
+type StoredCredential =
+	| { readonly status: "password"; readonly passwordHash: string }
+	| { readonly status: "oauthMicrosoft"; readonly refreshTokenHash: string }
+	| MissingCredential;
+
+const readStoredCredential = (
+	account: StoredCredentialFields,
+): StoredCredential => {
+	const authType = account.authType ?? AccountAuthType.Password;
+
+	if (authType === AccountAuthType.OauthMicrosoft) {
+		if (!account.oauthRefreshTokenHash) {
+			return {
+				status: "missing",
+				terminalState: ConnectionState.ReauthRequired,
+				reason: "authType=oauthMicrosoft but no oauthRefreshTokenHash",
+			};
+		}
+		return {
+			status: "oauthMicrosoft",
+			refreshTokenHash: account.oauthRefreshTokenHash,
+		};
+	}
+
+	if (!account.passwordHash) {
+		return {
+			status: "missing",
+			terminalState: ConnectionState.CredentialsMissing,
+			reason: "authType=password but no passwordHash",
+		};
+	}
+	return { status: "password", passwordHash: account.passwordHash };
+};
+
+/**
+ * Whether the account holds the credential its authType requires.
+ *
+ * Keyed on the stored credential, never on `connectionState`: PATCH
+ * /accounts/{id} writes a password without clearing `credentials_missing` —
+ * only a successful connect clears it, via markAuthenticated — so a
+ * state-based check would go on skipping an account that can sync perfectly
+ * well.
+ */
+export const hasStoredCredential = (account: StoredCredentialFields): boolean =>
+	readStoredCredential(account).status !== "missing";
+
 export interface AccountCredentialsDeps {
 	secrets: Pick<SecretsService, "decrypt" | "encrypt">;
 	tokenService: Pick<MailOAuthService, "getAccessToken">;
@@ -42,6 +119,9 @@ export interface AccountCredentialsDeps {
  *   tokenService.  If the provider rotated the refresh token, persist the
  *   new token via `deps.persistRotatedToken` BEFORE returning credentials.
  *
+ * Returns `{ status: "missing" }` when the account stores no credential —
+ * an expected outcome every caller settles terminally, never retries.
+ *
  * Throws `RefreshTokenError` on OAuth failures; callers should handle:
  * - `kind === "reauth-required"` → set connectionState to reauth_required, ACK
  * - `kind === "transient"` → rethrow (SQS retry)
@@ -50,49 +130,55 @@ export interface AccountCredentialsDeps {
 export const resolveConnectionCredentials = async (
 	account: AccountItem,
 	deps: AccountCredentialsDeps,
-): Promise<MailCredentials> => {
-	const authType = account.authType ?? AccountAuthType.Password;
+): Promise<CredentialResolution> => {
+	const stored = readStoredCredential(account);
 
-	if (authType === AccountAuthType.OauthMicrosoft) {
-		return resolveOauthCredentials(account, deps);
+	if (stored.status === "missing") {
+		return stored;
+	}
+
+	if (stored.status === "oauthMicrosoft") {
+		return {
+			status: "resolved",
+			credentials: await resolveOauthCredentials(
+				account.accountId,
+				stored.refreshTokenHash,
+				deps,
+			),
+		};
 	}
 
-	// Default: password auth
-	return resolvePasswordCredentials(account, deps.secrets);
+	return {
+		status: "resolved",
+		credentials: await resolvePasswordCredentials(
+			stored.passwordHash,
+			deps.secrets,
+		),
+	};
 };
 
 const resolvePasswordCredentials = async (
-	account: AccountItem,
+	passwordHash: string,
 	secrets: Pick<SecretsService, "decrypt">,
 ): Promise<MailCredentials> => {
-	if (!account.passwordHash) {
-		throw new Error(
-			`Account ${account.accountId} has authType=password but no passwordHash`,
-		);
-	}
 	const password = await secrets.decrypt(
-		deserializeEncryptedPayload(JSON.parse(account.passwordHash)),
+		deserializeEncryptedPayload(JSON.parse(passwordHash)),
 	);
 	return { kind: "password", password };
 };
 
 const resolveOauthCredentials = async (
-	account: AccountItem,
+	accountId: string,
+	refreshTokenHash: string,
 	deps: AccountCredentialsDeps,
 ): Promise<MailCredentials> => {
-	if (!account.oauthRefreshTokenHash) {
-		throw new Error(
-			`Account ${account.accountId} has authType=oauthMicrosoft but no oauthRefreshTokenHash`,
-		);
-	}
-
 	const refreshToken = await deps.secrets.decrypt(
-		deserializeEncryptedPayload(JSON.parse(account.oauthRefreshTokenHash)),
+		deserializeEncryptedPayload(JSON.parse(refreshTokenHash)),
 	);
 
 	// getAccessToken throws RefreshTokenError on failure
 	const tokenSet = await deps.tokenService.getAccessToken(
-		account.accountId,
+		accountId,
 		refreshToken,
 	);
 
@@ -103,11 +189,7 @@ const resolveOauthCredentials = async (
 		const encryptedHash = JSON.stringify(
 			serializeEncryptedPayload(encryptedPayload),
 		);
-		await deps.persistRotatedToken(
-			account.accountId,
-			encryptedHash,
-			Date.now(),
-		);
+		await deps.persistRotatedToken(accountId, encryptedHash, Date.now());
 	}
 
 	return { kind: "accessToken", accessToken: tokenSet.accessToken };

package/src/index.ts

@@ -6,8 +6,13 @@
 
 export {
 	type AccountCredentialsDeps,
+	type ConnectionStateValue,
+	type CredentialResolution,
 	encryptRefreshToken,
+	hasStoredCredential,
+	type MissingCredential,
 	resolveConnectionCredentials,
+	type StoredCredentialFields,
 } from "./account-credentials.js";
 export {
 	hasChildren,

package/src/message-sync-repoint.test.ts

@@ -49,6 +49,12 @@ const JUNK = mailboxAt("INBOX/Rubbish");
 const TRASH = mailboxAt("Trash");
 const ALL_MAIL = mailboxAt("[Gmail]/All Mail", ["All"]);
 
+/**
+ * `pending` is what an ordinary inbound row carries: `upsertWithStatus` is
+ * called without a `syncStatus` and the repository defaults to it, and nothing
+ * on the sync path ever promotes it (#1096). The fixture states the reachable
+ * state, not the one the gate used to demand.
+ */
 const storedIn = (
 	mailbox: MailboxItem,
 	overrides: Partial<MessageItem> = {},
@@ -57,7 +63,7 @@ const storedIn = (
 		mailboxId: mailbox.mailboxId,
 		uid: 7,
 		status: MessageStatus.active,
-		syncStatus: MessageSyncStatus.synced,
+		syncStatus: MessageSyncStatus.pending,
 		...overrides,
 	}) as MessageItem;
 
@@ -310,6 +316,26 @@ describe("repointsOnSighting", () => {
 		);
 	});
 
+	it("accepts an ordinary inbound row the sync path left pending", () => {
+		assert.equal(
+			repointsOnSighting(
+				JUNK,
+				storedIn(INBOX, { syncStatus: MessageSyncStatus.pending }),
+			),
+			true,
+		);
+	});
+
+	it("accepts a row a settled mutation marked synced", () => {
+		assert.equal(
+			repointsOnSighting(
+				JUNK,
+				storedIn(INBOX, { syncStatus: MessageSyncStatus.synced }),
+			),
+			true,
+		);
+	});
+
 	it("refuses a row whose move failed and has not been re-tried", () => {
 		assert.equal(
 			repointsOnSighting(
@@ -319,4 +345,30 @@ describe("repointsOnSighting", () => {
 			false,
 		);
 	});
+
+	it("refuses a row whose own move is still in flight", () => {
+		assert.equal(
+			repointsOnSighting(
+				JUNK,
+				storedIn(INBOX, {
+					status: MessageStatus.moving,
+					syncStatus: MessageSyncStatus.pending,
+				}),
+			),
+			false,
+		);
+	});
+
+	it("refuses a row whose own delete is still in flight", () => {
+		assert.equal(
+			repointsOnSighting(
+				JUNK,
+				storedIn(INBOX, {
+					status: MessageStatus.deleting,
+					syncStatus: MessageSyncStatus.pending,
+				}),
+			),
+			false,
+		);
+	});
 });

package/src/message-sync.ts

@@ -145,8 +145,17 @@ export const addressSightingIn = (
  * filing locations; following one would empty every other folder's listing. And
  * a row whose own mutation has not settled is in flight, not stale
  * (imap-mutations R1): the server's answer predates the move reader is still
- * waiting on, so taking it would undo the optimistic write. That sighting is
- * reconciled by the next one after the mutation settles.
+ * waiting on, so taking it would undo the optimistic write. The sync path
+ * reconciles rather than waits (imap-mutations R2): it never blocks on a
+ * mutation, it re-reads the row on the next sighting after the move settles.
+ *
+ * In flight is read off `status`, never off `syncStatus` (#1096). Every
+ * outbound mutation writes `moving` or `deleting` and only settling returns the
+ * row to `active`, while an ordinary inbound row stays `pending` for its whole
+ * life because nothing on the sync path promotes it — so demanding `synced`
+ * here meant ordinary mail never re-pointed at all. `failed` is still refused:
+ * a mutation that gave up leaves it set on a row put back to `active`, and
+ * nothing routine settles that row afterwards.
  */
 export const repointsOnSighting = (
 	mailbox: MailboxItem,
@@ -154,10 +163,8 @@ export const repointsOnSighting = (
 ): boolean => {
 	if (message.mailboxId === mailbox.mailboxId) return false;
 	if (isVirtualCopyMailbox(mailbox)) return false;
-	return (
-		message.status === MessageStatus.active &&
-		message.syncStatus === MessageSyncStatus.synced
-	);
+	if (message.status !== MessageStatus.active) return false;
+	return message.syncStatus !== MessageSyncStatus.failed;
 };
 
 /**