@remit/mailbox-service 0.0.82 → 0.0.83

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/mailbox-service",
-  "version": "0.0.82",
+  "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,