fix(clerk-js): Fix token cache refresh timer leak (clerk#8098)

Co-authored-by: Fredrik Höglund <fredrik@clerk.dev>

Author: jacekradko

.changeset/fix-token-cache-timer-leak.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Fix token cache refresh timer leak that caused accelerating token refresh requests after `session.touch()` or organization switching.

integration/tests/session-token-cache/multi-session.test.ts

@@ -226,5 +226,106 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withSessionTasks] })(
       expect(tab1FinalInfo.userId).toBe(user1SessionInfo.userId);
       expect(tab1FinalInfo.activeSessionId).toBe(user1SessionInfo.sessionId);
     });
+
+    /**
+     * Test Flow:
+     * 1. Tab1: Sign in as user1
+     * 2. Tab2: Inherits user1's session, then signs in as user2 (multi-session)
+     * 3. Tab1 has user1's active session; tab2 has user2's active session
+     * 4. Each tab's active session independently hydrates its token cache
+     * 5. Start counting /tokens requests, wait for both refresh timers to fire
+     * 6. Assert exactly 2 /tokens requests (one per session), with each session
+     *    represented exactly once
+     *
+     * Expected Behavior:
+     * - Two different sessions produce two independent refresh requests
+     * - BroadcastChannel does NOT deduplicate across sessions (different tokenIds)
+     * - Each session refreshes exactly once
+     *
+     * Note that this test does not currently assert in which tab the updates happen,
+     * this might be something we want to add in the future, but currently it is not
+     * deterministic.
+     */
+    test('multi-session scheduled refreshes produce one request per session', async ({ context }) => {
+      test.setTimeout(90_000);
+
+      const page1 = await context.newPage();
+      await page1.goto(app.serverUrl);
+      await page1.waitForFunction(() => (window as any).Clerk?.loaded);
+
+      const u1 = createTestUtils({ app, page: page1 });
+      await u1.po.signIn.goTo();
+      await u1.po.signIn.setIdentifier(fakeUser1.email);
+      await u1.po.signIn.continue();
+      await u1.po.signIn.setPassword(fakeUser1.password);
+      await u1.po.signIn.continue();
+      await u1.po.expect.toBeSignedIn();
+
+      const user1SessionId = await page1.evaluate(() => (window as any).Clerk?.session?.id);
+      expect(user1SessionId).toBeDefined();
+
+      const page2 = await context.newPage();
+      await page2.goto(app.serverUrl);
+      await page2.waitForFunction(() => (window as any).Clerk?.loaded);
+
+      // eslint-disable-next-line playwright/no-wait-for-timeout
+      await page2.waitForTimeout(1000);
+
+      const u2 = createTestUtils({ app, page: page2 });
+      await u2.po.expect.toBeSignedIn();
+
+      // Sign in as user2 on tab2, creating a second session
+      const signInResult = await page2.evaluate(
+        async ({ email, password }) => {
+          const clerk = (window as any).Clerk;
+          const signIn = await clerk.client.signIn.create({ identifier: email, password });
+          await clerk.setActive({ session: signIn.createdSessionId });
+          return {
+            sessionCount: clerk?.client?.sessions?.length || 0,
+            sessionId: clerk?.session?.id,
+            success: true,
+          };
+        },
+        { email: fakeUser2.email, password: fakeUser2.password },
+      );
+
+      expect(signInResult.success).toBe(true);
+      expect(signInResult.sessionCount).toBe(2);
+
+      const user2SessionId = signInResult.sessionId;
+      expect(user2SessionId).toBeDefined();
+      expect(user2SessionId).not.toBe(user1SessionId);
+
+      // Tab1 has user1's active session; tab2 has user2's active session.
+      // Start counting /tokens requests.
+      const refreshRequests: Array<{ sessionId: string; url: string }> = [];
+      await context.route('**/v1/client/sessions/*/tokens*', async route => {
+        const url = route.request().url();
+        const match = url.match(/sessions\/([^/]+)\/tokens/);
+        refreshRequests.push({ sessionId: match?.[1] || 'unknown', url });
+        await route.continue();
+      });
+
+      // Wait for proactive refresh timers to fire.
+      // Default token TTL is 60s; onRefresh fires at 60 - 15 - 2 = 43s from iat.
+      // Uses page.evaluate to avoid the global actionTimeout (10s) capping the wait.
+      await page1.evaluate(() => new Promise(resolve => setTimeout(resolve, 50_000)));
+
+      // Two different sessions should each produce exactly one refresh request.
+      // BroadcastChannel deduplication is per-tokenId, so different sessions refresh independently.
+      expect(refreshRequests.length).toBe(2);
+
+      const refreshedSessionIds = new Set(refreshRequests.map(r => r.sessionId));
+      expect(refreshedSessionIds.has(user1SessionId)).toBe(true);
+      expect(refreshedSessionIds.has(user2SessionId)).toBe(true);
+
+      // Both tabs should still have valid tokens after the refresh cycle
+      const page1Token = await page1.evaluate(() => (window as any).Clerk.session?.getToken());
+      const page2Token = await page2.evaluate(() => (window as any).Clerk.session?.getToken());
+
+      expect(page1Token).toBeTruthy();
+      expect(page2Token).toBeTruthy();
+      expect(page1Token).not.toBe(page2Token);
+    });
   },
 );

integration/tests/session-token-cache/refresh-timer-cleanup.test.ts

@@ -0,0 +1,79 @@
+import { expect, test } from '@playwright/test';
+
+import { appConfigs } from '../../presets';
+import type { FakeUser } from '../../testUtils';
+import { createTestUtils, testAgainstRunningApps } from '../../testUtils';
+
+/**
+ * Tests that the token cache's proactive refresh timer does not accumulate
+ * orphaned timers across set() calls.
+ *
+ * Background: Every API response that piggybacks client data triggers _updateClient,
+ * which reconstructs Session objects and calls #hydrateCache → SessionTokenCache.set().
+ * Without proper timer cleanup, each set() call would leave the previous refresh timer
+ * running, causing the effective polling rate to accelerate over time.
+ */
+testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodes] })(
+  'Token refresh timer cleanup @generic',
+  ({ app }) => {
+    test.describe.configure({ mode: 'serial' });
+
+    let fakeUser: FakeUser;
+
+    test.beforeAll(async () => {
+      const u = createTestUtils({ app });
+      fakeUser = u.services.users.createFakeUser();
+      await u.services.users.createBapiUser(fakeUser);
+    });
+
+    test.afterAll(async () => {
+      await fakeUser.deleteIfExists();
+      await app.teardown();
+    });
+
+    test('touch does not cause clustered token refresh requests', async ({ page, context }) => {
+      test.setTimeout(120_000);
+      const u = createTestUtils({ app, page, context });
+
+      await u.po.signIn.goTo();
+      await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeUser.email, password: fakeUser.password });
+      await u.po.expect.toBeSignedIn();
+
+      // Track token fetch requests with timestamps
+      const tokenRequests: number[] = [];
+      await page.route('**/v1/client/sessions/*/tokens**', async route => {
+        tokenRequests.push(Date.now());
+        await route.continue();
+      });
+
+      // Trigger multiple touch() calls — each causes _updateClient → Session constructor
+      // → #hydrateCache → set(), which previously leaked orphaned refresh timers.
+      // Note: This works because the test instance is multi-session, so it doesn't
+      // hit the 5s single-session touch throttle.
+      for (let i = 0; i < 5; i++) {
+        await page.evaluate(async () => {
+          await (window as any).Clerk?.session?.touch();
+        });
+      }
+
+      // Wait 50s — enough for one refresh cycle (~43s) but not two
+      // eslint-disable-next-line playwright/no-wait-for-timeout
+      await page.waitForTimeout(50_000);
+
+      await page.unrouteAll();
+
+      // With the fix: at most 1-2 refresh requests (one cycle at ~43s)
+      // Without the fix: 5+ requests from orphaned timers all firing at different offsets
+      expect(tokenRequests.length).toBeLessThanOrEqual(3);
+
+      // If multiple requests occurred, verify they aren't clustered together
+      // (clustering = orphaned timers firing near-simultaneously)
+      if (tokenRequests.length >= 2) {
+        for (let i = 1; i < tokenRequests.length; i++) {
+          const gap = tokenRequests[i] - tokenRequests[i - 1];
+          expect(gap).toBeGreaterThan(10_000);
+        }
+      }
+    });
+  },
+);

integration/tests/session-token-cache/single-session.test.ts

@@ -46,7 +46,7 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodes] })(
      * - Only ONE network request is made (from tab1)
      * - Tab2 gets the token via BroadcastChannel, proving cross-tab cache sharing
      */
-    test('MemoryTokenCache multi-tab token sharing', async ({ context }) => {
+    test('multi-tab token sharing works when clearing the cache', async ({ context }) => {
       const page1 = await context.newPage();
       const page2 = await context.newPage();
 
@@ -128,5 +128,75 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodes] })(
       // Verify only one token fetch happened (page1), proving page2 got it from BroadcastChannel
       expect(tokenRequests.length).toBe(1);
     });
+
+    /**
+     * Test Flow:
+     * 1. Open two tabs with the same browser context (shared cookies)
+     * 2. Sign in on tab1, reload tab2 to pick up the session
+     * 3. Both tabs hydrate their token cache with the session token
+     * 4. Start counting /tokens requests, then wait for the timers to fire
+     * 5. Assert only 1 /tokens request was made (not 2)
+     */
+    test('multi-tab scheduled refreshes are deduped to a single request', async ({ context }) => {
+      test.setTimeout(90_000);
+
+      const page1 = await context.newPage();
+      const page2 = await context.newPage();
+
+      await page1.goto(app.serverUrl);
+      await page2.goto(app.serverUrl);
+
+      await page1.waitForFunction(() => (window as any).Clerk?.loaded);
+      await page2.waitForFunction(() => (window as any).Clerk?.loaded);
+
+      const u1 = createTestUtils({ app, page: page1 });
+      await u1.po.signIn.goTo();
+      await u1.po.signIn.setIdentifier(fakeUser.email);
+      await u1.po.signIn.continue();
+      await u1.po.signIn.setPassword(fakeUser.password);
+      await u1.po.signIn.continue();
+      await u1.po.expect.toBeSignedIn();
+
+      // eslint-disable-next-line playwright/no-wait-for-timeout
+      await page1.waitForTimeout(1000);
+
+      await page2.reload();
+      await page2.waitForFunction(() => (window as any).Clerk?.loaded);
+
+      const u2 = createTestUtils({ app, page: page2 });
+      await u2.po.expect.toBeSignedIn();
+
+      // Both tabs are now signed in and have hydrated their token caches
+      // via Session constructor -> #hydrateCache, each with an independent
+      // onRefresh timer that fires at ~43s (TTL 60s - 15s leeway - 2s lead).
+      // Start counting /tokens requests from this point.
+      const refreshRequests: string[] = [];
+      await context.route('**/v1/client/sessions/*/tokens*', async route => {
+        refreshRequests.push(route.request().url());
+        await route.continue();
+      });
+
+      // Wait for proactive refresh timers to fire.
+      // Default token TTL is 60s; onRefresh fires at 60 - 15 - 2 = 43s from iat.
+      // We wait 50s to give comfortable buffer, this includes the broadcast delay.
+      //
+      // Uses page.evaluate instead of page.waitForTimeout to avoid
+      // the global actionTimeout (10s) silently capping the wait.
+      await page1.evaluate(() => new Promise(resolve => setTimeout(resolve, 50_000)));
+
+      // Only one tab should have made a /tokens request; the other tab should have
+      // received the refreshed token via BroadcastChannel.
+      expect(refreshRequests.length).toBe(1);
+
+      // Both tabs should still have valid tokens after the refresh cycle
+      const [page1Token, page2Token] = await Promise.all([
+        page1.evaluate(() => (window as any).Clerk.session?.getToken()),
+        page2.evaluate(() => (window as any).Clerk.session?.getToken()),
+      ]);
+
+      expect(page1Token).toBeTruthy();
+      expect(page2Token).toBeTruthy();
+      expect(page1Token).toBe(page2Token);
+    });
   },
 );