Tighten entitlement and refresh-token identity matching

Author: ndycode

lib/entitlement-cache.ts

@@ -50,31 +50,27 @@ function normalizeEntitlementEmail(email: string | undefined): string | undefine
 /**
  * Derives a stable cache key for an entitlement account reference.
  *
- * Produces one of six deterministic keys:
+ * Produces one of five deterministic keys:
  * - `account:<trimmed accountId>::email:<lowercased trimmed email>` when both are present,
  * - `email:<lowercased trimmed email>` when only `email` is present,
  * - `account:<trimmed accountId>::idx:<non-negative integer>` when `accountId` is present without email,
  * - `account:<trimmed accountId>` when only `accountId` is present and no index is available,
- * - `refresh:<trimmed refreshToken>` when no accountId/email exists but a refresh token is available,
  * - `idx:<non-negative integer>` otherwise (index defaults to 0).
  *
- * This function is pure and concurrency-safe; it performs no I/O and is not affected by Windows filesystem semantics. It does not redact secrets or tokens — values are only trimmed and, for emails, lowercased.
+ * This function is pure and concurrency-safe; it performs no I/O and is not affected by Windows filesystem semantics. It never serializes refresh tokens or other secrets into the returned key.
  *
  * @param ref - Reference identifying an account (may include `accountId`, `email`, or `index`)
- * @returns A deterministic string key prefixed with `account:`, `email:`, `refresh:`, or `idx:` as described above
+ * @returns A deterministic string key prefixed with `account:`, `email:`, or `idx:` as described above
  */
 export function resolveEntitlementAccountKey(ref: EntitlementAccountRef): string {
 	const accountId = typeof ref.accountId === "string" ? ref.accountId.trim() : "";
 	const hasIndex = Number.isFinite(ref.index);
 	const index = hasIndex ? Math.max(0, Math.floor(ref.index ?? 0)) : 0;
 	const email = normalizeEntitlementEmail(ref.email);
-	const refreshToken =
-		typeof ref.refreshToken === "string" ? ref.refreshToken.trim() : "";
 	if (accountId && email) return `account:${accountId}::email:${email}`;
 	if (email) return `email:${email}`;
 	if (accountId && hasIndex) return `account:${accountId}::idx:${index}`;
 	if (accountId) return `account:${accountId}`;
-	if (refreshToken) return `refresh:${refreshToken}`;
 	return `idx:${index}`;
 }
 

lib/storage.ts

@@ -1131,6 +1131,51 @@ function findSafeEmailMatchIndex<T extends AccountLike>(
 	);
 }
 
+function findCompatibleRefreshTokenMatchIndex<T extends AccountLike>(
+	accounts: readonly T[],
+	candidateRef: AccountIdentityRef,
+): number | undefined {
+	if (!candidateRef.refreshToken) return undefined;
+	let matchingIndex: number | undefined;
+	let matchingAccount: T | null = null;
+
+	for (let i = 0; i < accounts.length; i += 1) {
+		const account = accounts[i];
+		if (!account) continue;
+		const ref = toAccountIdentityRef(account);
+		if (ref.refreshToken !== candidateRef.refreshToken) continue;
+		if (
+			(candidateRef.accountId &&
+				ref.accountId &&
+				ref.accountId !== candidateRef.accountId) ||
+			(candidateRef.emailKey &&
+				ref.emailKey &&
+				ref.emailKey !== candidateRef.emailKey)
+		) {
+			return undefined;
+		}
+		if (
+			matchingIndex !== undefined &&
+			!candidateRef.accountId &&
+			!candidateRef.emailKey
+		) {
+			return undefined;
+		}
+		if (matchingIndex === undefined || matchingAccount === null) {
+			matchingIndex = i;
+			matchingAccount = account;
+			continue;
+		}
+		const newest = selectNewestAccount(matchingAccount, account);
+		if (newest === account) {
+			matchingIndex = i;
+			matchingAccount = account;
+		}
+	}
+
+	return matchingIndex;
+}
+
 function findUniqueAccountIdMatchIndex<T extends AccountLike>(
 	accounts: readonly T[],
 	candidateRef: AccountIdentityRef,
@@ -1179,20 +1224,20 @@ export function findMatchingAccountIndex<
 ): number | undefined {
 	const candidateRef = toAccountIdentityRef(candidate);
 
-	if (candidateRef.refreshToken) {
-		const byRefresh = findNewestMatchingIndex(
-			accounts,
-			(ref) => ref.refreshToken === candidateRef.refreshToken,
-		);
-		if (byRefresh !== undefined) return byRefresh;
-	}
-
 	const byComposite = findCompositeAccountMatchIndex(accounts, candidateRef);
 	if (byComposite !== undefined) return byComposite;
 
 	const byEmail = findSafeEmailMatchIndex(accounts, candidateRef);
 	if (byEmail !== undefined) return byEmail;
 
+	if (candidateRef.refreshToken) {
+		const byRefresh = findCompatibleRefreshTokenMatchIndex(
+			accounts,
+			candidateRef,
+		);
+		if (byRefresh !== undefined) return byRefresh;
+	}
+
 	return findUniqueAccountIdMatchIndex(accounts, candidateRef, options);
 }
 

test/entitlement-cache.test.ts

@@ -148,10 +148,19 @@ describe("entitlement cache", () => {
     expect(
       resolveEntitlementAccountKey({ email: "  Person@Example.com  " }),
     ).toBe("email:person@example.com");
+    expect(resolveEntitlementAccountKey({ index: Number.NaN })).toBe("idx:0");
+  });
+
+  it("never serializes refresh tokens into entitlement keys", () => {
+    expect(
+      resolveEntitlementAccountKey({
+        refreshToken: "  refresh-token  ",
+        index: 4,
+      }),
+    ).toBe("idx:4");
     expect(
       resolveEntitlementAccountKey({ refreshToken: "  refresh-token  " }),
-    ).toBe("refresh:refresh-token");
-    expect(resolveEntitlementAccountKey({ index: Number.NaN })).toBe("idx:0");
+    ).toBe("idx:0");
   });
 
   it("ignores invalid mark/clear/isBlocked inputs", () => {

test/storage.test.ts

@@ -151,7 +151,7 @@ describe("storage", () => {
 			expect(deduped[0]?.lastUsed).toBe(now);
 		});
 
-		it("prefers refresh token matches over composite and email matches", () => {
+		it("prefers composite and email matches over refresh token matches", () => {
 			const accounts = [
 				{
 					accountId: "workspace-a",
@@ -176,9 +176,56 @@ describe("storage", () => {
 				refreshToken: "token-refresh",
 			});
 
+			expect(matchIndex).toBe(1);
+		});
+
+		it("uses a unique refresh token match when no safer identifier exists", () => {
+			const accounts = [
+				{
+					accountId: "workspace-a",
+					email: "alpha@example.com",
+					refreshToken: "token-refresh",
+				},
+				{
+					accountId: "workspace-b",
+					email: "match@example.com",
+					refreshToken: "token-composite",
+				},
+			];
+
+			const matchIndex = findMatchingAccountIndex(accounts, {
+				refreshToken: "token-refresh",
+			});
+
 			expect(matchIndex).toBe(0);
 		});
 
+		it("falls back to composite matching when refresh tokens are ambiguous", () => {
+			const accounts = [
+				{
+					accountId: "workspace-a",
+					email: "alpha@example.com",
+					refreshToken: "shared-refresh",
+					lastUsed: 100,
+				},
+				{
+					accountId: "workspace-b",
+					email: "match@example.com",
+					refreshToken: "shared-refresh",
+					lastUsed: 200,
+				},
+			];
+
+			const matchIndex = findMatchingAccountIndex(accounts, {
+				accountId: "workspace-b",
+				email: "match@example.com",
+				refreshToken: "shared-refresh",
+			});
+
+			expect(matchIndex).toBe(1);
+			expect(deduplicateAccounts(accounts)).toHaveLength(2);
+		});
+
 		it("prefers composite accountId plus email matches over safe-email fallbacks", () => {
 			const accounts = [
 				{