feat(clerk-js): Dedupe getToken requests

.changeset/every-dryers-refuse.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': minor
+---
+
+When fetching a new Session token, broadcast the token value to other tabs so they can pre-warm their in-memory Session Token cache with the most recent token.

.changeset/slick-ducks-bet.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Introduce deprecation warning for LocalStorageBroadcastChannel

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -177,6 +177,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "shared/is-valid-browser.mdx",
   "shared/isomorphic-atob.mdx",
   "shared/load-clerk-js-script.mdx",
+  "shared/local-storage-broadcast-channel.mdx",
   "shared/pages-or-infinite-options.mdx",
   "shared/paginated-hook-config.mdx",
   "shared/paginated-resources.mdx",

integration/presets/envs.ts

@@ -42,6 +42,15 @@ const withEmailCodes = base
   .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', instanceKeys.get('with-email-codes').pk)
   .setEnvVariable('private', 'CLERK_ENCRYPTION_KEY', constants.E2E_CLERK_ENCRYPTION_KEY || 'a-key');
 
+const withBroadcastChannel = withEmailCodes
+  .clone()
+  .setId('withBroadcastChannel')
+  .setEnvVariable(
+    'public',
+    'CLERK_JS_URL',
+    constants.E2E_APP_CLERK_JS || 'http://localhost:18211/clerk.channel.browser.js',
+  );
+
 const sessionsProd1 = base
   .clone()
   .setId('sessionsProd1')
@@ -178,28 +187,29 @@ const withAPIKeys = base
 
 export const envs = {
   base,
-  withKeyless,
-  withEmailCodes,
-  withEmailCodes_destroy_client,
-  withEmailLinks,
-  withCustomRoles,
-  withReverification,
-  withEmailCodesQuickstart,
+  sessionsProd1,
+  withAPIKeys,
   withAPCore1ClerkLatest,
   withAPCore1ClerkV4,
   withAPCore2ClerkLatest,
   withAPCore2ClerkV4,
+  withBilling,
+  withBillingJwtV2,
+  withBroadcastChannel,
+  withCustomRoles,
   withDynamicKeys,
-  withRestrictedMode,
+  withEmailCodes,
+  withEmailCodes_destroy_client,
+  withEmailCodesQuickstart,
+  withEmailLinks,
+  withKeyless,
   withLegalConsent,
-  withWaitlistdMode,
-  withSignInOrUpFlow,
+  withRestrictedMode,
+  withReverification,
+  withSessionTasks,
   withSignInOrUpEmailLinksFlow,
+  withSignInOrUpFlow,
   withSignInOrUpwithRestrictedModeFlow,
-  withSessionTasks,
-  withBillingJwtV2,
-  withBilling,
+  withWaitlistdMode,
   withWhatsappPhoneCode,
-  sessionsProd1,
-  withAPIKeys,
 } as const;

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

@@ -0,0 +1,230 @@
+import { expect, test } from '@playwright/test';
+
+import { appConfigs } from '../../presets';
+import type { FakeUser } from '../../testUtils';
+import { createTestUtils, testAgainstRunningApps } from '../../testUtils';
+
+/**
+ * Tests MemoryTokenCache session isolation in multi-session scenarios
+ *
+ * This suite validates that when multiple user sessions exist simultaneously,
+ * each session maintains its own isolated token cache. Tokens are not shared
+ * between different sessions, even within the same tab, ensuring proper
+ * security boundaries between users.
+ */
+testAgainstRunningApps({ withEnv: [appConfigs.envs.withSessionTasks] })(
+  'MemoryTokenCache Multi-Session Integration @nextjs',
+  ({ app }) => {
+    test.describe.configure({ mode: 'serial' });
+
+    let fakeUser1: FakeUser;
+    let fakeUser2: FakeUser;
+
+    test.beforeAll(async () => {
+      const u = createTestUtils({ app });
+      fakeUser1 = u.services.users.createFakeUser();
+      fakeUser2 = u.services.users.createFakeUser();
+      await u.services.users.createBapiUser(fakeUser1);
+      await u.services.users.createBapiUser(fakeUser2);
+    });
+
+    test.afterAll(async () => {
+      await fakeUser1.deleteIfExists();
+      await fakeUser2.deleteIfExists();
+      await app.teardown();
+    });
+
+    /**
+     * Test Flow:
+     * 1. Tab1: Sign in as user1, fetch and cache their token
+     * 2. Tab2: Opens and inherits user1's session via cookies
+     * 3. Tab2: Sign in as user2 using programmatic sign-in (preserves both sessions)
+     * 4. Tab2: Now has two active sessions (user1 and user2)
+     * 5. Tab2: Switch between sessions and fetch tokens for each
+     * 6. Verify no network requests occur (tokens served from cache)
+     * 7. Tab1: Verify it still has user1 as active session (tab independence)
+     *
+     * Expected Behavior:
+     * - Each session has its own isolated token cache
+     * - Switching sessions in tab2 returns different tokens
+     * - Both tokens are served from cache (no network requests)
+     * - Tab1 remains unaffected by tab2's session changes
+     * - Multi-session state is properly maintained per-tab
+     */
+    test('MemoryTokenCache multi-session - multiple users in different tabs with separate token caches', async ({
+      context,
+    }) => {
+      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 user1SessionInfo = await page1.evaluate(() => {
+        const clerk = (window as any).Clerk;
+        return {
+          sessionId: clerk?.session?.id,
+          userId: clerk?.user?.id,
+        };
+      });
+
+      expect(user1SessionInfo.sessionId).toBeDefined();
+      expect(user1SessionInfo.userId).toBeDefined();
+
+      const user1Token = await page1.evaluate(async () => {
+        const clerk = (window as any).Clerk;
+        return await clerk.session?.getToken({ skipCache: true });
+      });
+
+      expect(user1Token).toBeTruthy();
+
+      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();
+
+      const page2User1SessionInfo = await page2.evaluate(() => {
+        const clerk = (window as any).Clerk;
+        return {
+          sessionId: clerk?.session?.id,
+          userId: clerk?.user?.id,
+        };
+      });
+
+      expect(page2User1SessionInfo.userId).toBe(user1SessionInfo.userId);
+      expect(page2User1SessionInfo.sessionId).toBe(user1SessionInfo.sessionId);
+
+      // Use clerk.client.signIn.create() instead of navigating to /sign-in
+      // because navigating replaces the session by default (transferable: true)
+      const signInResult = await page2.evaluate(
+        async ({ email, password }) => {
+          const clerk = (window as any).Clerk;
+
+          try {
+            const signIn = await clerk.client.signIn.create({
+              identifier: email,
+              password: password,
+            });
+
+            await clerk.setActive({
+              session: signIn.createdSessionId,
+            });
+
+            return {
+              allSessions: clerk?.client?.sessions?.map((s: any) => ({ id: s.id, userId: s.userId })) || [],
+              sessionCount: clerk?.client?.sessions?.length || 0,
+              success: true,
+            };
+          } catch (error: any) {
+            return {
+              error: error.message || String(error),
+              success: false,
+            };
+          }
+        },
+        { email: fakeUser2.email, password: fakeUser2.password },
+      );
+
+      expect(signInResult.success).toBe(true);
+      expect(signInResult.sessionCount).toBe(2);
+
+      await u2.po.expect.toBeSignedIn();
+
+      const user2SessionInfo = await page2.evaluate(() => {
+        const clerk = (window as any).Clerk;
+        return {
+          allSessions: clerk?.client?.sessions?.map((s: any) => ({ id: s.id, userId: s.userId })) || [],
+          sessionCount: clerk?.client?.sessions?.length || 0,
+          sessionId: clerk?.session?.id,
+          userId: clerk?.user?.id,
+        };
+      });
+
+      expect(user2SessionInfo.sessionId).toBeDefined();
+      expect(user2SessionInfo.userId).toBeDefined();
+      expect(user2SessionInfo.sessionId).not.toBe(user1SessionInfo.sessionId);
+      expect(user2SessionInfo.userId).not.toBe(user1SessionInfo.userId);
+
+      const user2Token = await page2.evaluate(async () => {
+        const clerk = (window as any).Clerk;
+        return await clerk.session?.getToken({ skipCache: true });
+      });
+
+      expect(user2Token).toBeTruthy();
+      expect(user2Token).not.toBe(user1Token);
+
+      const page2MultiSessionInfo = await page2.evaluate(() => {
+        const clerk = (window as any).Clerk;
+        return {
+          activeSessionId: clerk?.session?.id,
+          allSessionIds: clerk?.client?.sessions?.map((s: any) => s.id) || [],
+          sessionCount: clerk?.client?.sessions?.length || 0,
+        };
+      });
+
+      expect(page2MultiSessionInfo.sessionCount).toBe(2);
+      expect(page2MultiSessionInfo.allSessionIds).toContain(user1SessionInfo.sessionId);
+      expect(page2MultiSessionInfo.allSessionIds).toContain(user2SessionInfo.sessionId);
+      expect(page2MultiSessionInfo.activeSessionId).toBe(user2SessionInfo.sessionId);
+
+      const tokenFetchRequests: Array<{ sessionId: string; url: string }> = [];
+      await context.route('**/v1/client/sessions/*/tokens*', async route => {
+        const url = route.request().url();
+        const sessionIdMatch = url.match(/sessions\/([^/]+)\/tokens/);
+        const sessionId = sessionIdMatch?.[1] || 'unknown';
+        tokenFetchRequests.push({ sessionId, url });
+        await route.continue();
+      });
+
+      const tokenIsolation = await page2.evaluate(
+        async ({ user1SessionId, user2SessionId }) => {
+          const clerk = (window as any).Clerk;
+
+          await clerk.setActive({ session: user1SessionId });
+          const user1Token = await clerk.session?.getToken();
+
+          await clerk.setActive({ session: user2SessionId });
+          const user2Token = await clerk.session?.getToken();
+
+          return {
+            tokensAreDifferent: user1Token !== user2Token,
+            user1Token,
+            user2Token,
+          };
+        },
+        { user1SessionId: user1SessionInfo.sessionId, user2SessionId: user2SessionInfo.sessionId },
+      );
+
+      expect(tokenIsolation.tokensAreDifferent).toBe(true);
+      expect(tokenIsolation.user1Token).toBeTruthy();
+      expect(tokenIsolation.user2Token).toBeTruthy();
+      expect(tokenFetchRequests.length).toBe(0);
+
+      await context.unroute('**/v1/client/sessions/*/tokens*');
+
+      // In multi-session apps, each tab can have a different active session
+      const tab1FinalInfo = await page1.evaluate(() => {
+        const clerk = (window as any).Clerk;
+        return {
+          activeSessionId: clerk?.session?.id,
+          userId: clerk?.user?.id,
+        };
+      });
+
+      // Tab1 should STILL have user1 as the active session (independent per tab)
+      expect(tab1FinalInfo.userId).toBe(user1SessionInfo.userId);
+      expect(tab1FinalInfo.activeSessionId).toBe(user1SessionInfo.sessionId);
+    });
+  },
+);