fix(clerk-js): refresh session cookie on visibilitychange in cross-origin iframes (#8923)

Co-authored-by: Kevin Wang <26389321+thiskevinwang@users.noreply.github.com>
Co-authored-by: wobsoriano <sorianorobertc@gmail.com>

Author: 3 people

.changeset/iframe-session-visibility-refresh.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Refresh the session cookie when a tab becomes visible again, not only on window `focus`. Apps embedded in a cross-origin iframe (for example a preview pane) never receive a `focus` event when their parent tab is re-activated, which could leave the session token stale and cause requests to fail with a 401 until the page was manually refreshed. clerk-js now also refreshes on `visibilitychange` (which does reach iframes) and allows a visible embedded frame to write the refreshed cookie.

packages/clerk-js/bundlewatch.config.json

@@ -4,7 +4,7 @@
     { "path": "./dist/clerk.browser.js", "maxSize": "74KB" },
     { "path": "./dist/clerk.legacy.browser.js", "maxSize": "114KB" },
     { "path": "./dist/clerk.no-rhc.js", "maxSize": "316KB" },
-    { "path": "./dist/clerk.native.js", "maxSize": "72KB" },
+    { "path": "./dist/clerk.native.js", "maxSize": "73KB" },
     { "path": "./dist/vendors*.js", "maxSize": "7KB" },
     { "path": "./dist/coinbase*.js", "maxSize": "36KB" },
     { "path": "./dist/base-account-sdk*.js", "maxSize": "207KB" },

packages/clerk-js/sandbox/integration/iframe-session-refresh.spec.ts

@@ -0,0 +1,67 @@
+import { expect, test } from '@playwright/test';
+
+const PORT = process.env.PORT || 4011;
+const HOST = `http://localhost:${PORT}`;
+
+type ProbeEvent = { type: string; visibility: string; hasFocus: boolean; t: number };
+
+/**
+ * Real-browser proof of the browser facts behind the embedded-app (e.g. Replit preview) session-refresh
+ * bug. clerk-js historically refreshed the session cookie only on the window `focus` event and gated the
+ * cookie write on `document.hasFocus()`. Both assume a top-level browsing context. This test demonstrates,
+ * in real Chromium, why that fails for a Clerk app running inside a cross-origin iframe:
+ *
+ *   - a VISIBLE cross-origin iframe reports `document.hasFocus() === false`
+ *   - focusing the parent document never delivers a `focus` event to the iframe (it stays unfocused)
+ *   - the iframe only receives `focus` when it is explicitly focused (clicked into)
+ *
+ * So an embedded app is "visible but unfocused" essentially all the time, which is exactly why the
+ * focus-only refresh never runs and the `!document.hasFocus()` write-gate blocks it. The fix adds a
+ * `visibilitychange` trigger (which does propagate into the iframe) and lets a visible cross-origin
+ * iframe write the cookie. clerk-js's response to `visibilitychange` is covered by the AuthCookieService
+ * unit test; here we verify the browser semantics the fix relies on.
+ */
+test.describe('cross-origin iframe focus semantics @iframe', () => {
+  test('a visible cross-origin iframe is unfocused and only receives focus when explicitly focused', async ({
+    page,
+  }) => {
+    await page.goto(`${HOST}/iframe-host.html?framePath=/iframe-probe.html`);
+
+    const handle = await page.waitForSelector('#f');
+    const frame = await handle.contentFrame();
+    if (!frame) {
+      throw new Error('iframe contentFrame() was null');
+    }
+
+    await frame.waitForFunction(() => Array.isArray((window as any).__events));
+
+    // We are genuinely cross-origin: parent on localhost, iframe on 127.0.0.1.
+    expect(page.url()).toContain('localhost');
+    expect(frame.url()).toContain('127.0.0.1');
+
+    const liveState = () => frame.evaluate(() => ({ vis: document.visibilityState, hasFocus: document.hasFocus() }));
+    const events = () => frame.evaluate(() => (window as any).__events as ProbeEvent[]);
+
+    // 1) The iframe is visible but does NOT have focus.
+    const initial = await liveState();
+    expect(initial.vis).toBe('visible');
+    expect(initial.hasFocus).toBe(false);
+
+    // 2) Focusing an element in the PARENT document does not focus the iframe.
+    await page.evaluate(() => {
+      const input = document.createElement('input');
+      document.body.appendChild(input);
+      input.focus();
+    });
+    const afterParentFocus = await liveState();
+    expect(afterParentFocus.vis).toBe('visible');
+    expect(afterParentFocus.hasFocus).toBe(false);
+    expect((await events()).some(e => e.type === 'window.focus')).toBe(false);
+
+    // 3) Explicitly focusing into the iframe (a real click) delivers `focus` and flips hasFocus.
+    await handle.click();
+    await frame.waitForFunction(() => (window as any).__events.some((e: ProbeEvent) => e.type === 'window.focus'));
+    const afterIframeFocus = await liveState();
+    expect(afterIframeFocus.hasFocus).toBe(true);
+  });
+});

packages/clerk-js/sandbox/public/iframe-host.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>iframe host (parent)</title>
+  </head>
+  <body>
+    <h1>iframe host</h1>
+    <p>Embeds a cross-origin iframe to reproduce the embedded-app (e.g. Replit preview) session-refresh scenario.</p>
+    <iframe
+      id="f"
+      style="width: 480px; height: 360px; border: 1px solid #ccc"
+    ></iframe>
+    <script>
+      // Build a cross-origin URL for the iframe by swapping localhost <-> 127.0.0.1 on the same dev server.
+      const params = new URLSearchParams(location.search);
+      const framePath = params.get('framePath') || '/iframe-probe.html';
+      const frameSearch = params.get('frameSearch') || '';
+      const u = new URL(location.href);
+      u.hostname = location.hostname === 'localhost' ? '127.0.0.1' : 'localhost';
+      u.pathname = framePath;
+      u.search = frameSearch;
+      u.hash = '';
+      window.__frameSrc = u.toString();
+      document.getElementById('f').src = window.__frameSrc;
+    </script>
+  </body>
+</html>

packages/clerk-js/sandbox/public/iframe-probe.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>iframe probe (no Clerk)</title>
+  </head>
+  <body>
+    <h1>iframe probe</h1>
+    <script>
+      // Records the events the embedded document actually receives, so a test can assert
+      // which of `focus` / `visibilitychange` fire on parent-tab re-activation.
+      window.__events = [];
+      const rec = type =>
+        window.__events.push({
+          type,
+          visibility: document.visibilityState,
+          hasFocus: document.hasFocus(),
+          t: Date.now(),
+        });
+      window.addEventListener('focus', () => rec('window.focus'));
+      window.addEventListener('blur', () => rec('window.blur'));
+      document.addEventListener('visibilitychange', () => rec('visibilitychange'));
+      rec('init');
+    </script>
+  </body>
+</html>

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -9,6 +9,7 @@ import {
   isNetworkError,
   isUnauthenticatedError,
 } from '@clerk/shared/error';
+import { inCrossOriginIframe } from '@clerk/shared/internal/clerk-js/runtime';
 import type { Clerk, InstanceType } from '@clerk/shared/types';
 import { noop } from '@clerk/shared/utils';
 
@@ -37,7 +38,7 @@ import { SessionCookiePoller } from './SessionCookiePoller';
  * and auth from the Clerk instance.
  * This service is responsible to:
  *   - refresh the session cookie using a poller
- *   - refresh the session cookie on tab visibility change
+ *   - refresh the session cookie on tab focus and visibility change
  *   - update the related cookies listening to the `token:update` event
  *   - initialize auth related cookies for development instances (eg __client_uat, __clerk_db_jwt)
  *   - cookie setup for production / development instances
@@ -156,7 +157,7 @@ export class AuthCookieService {
   }
 
   private refreshTokenOnFocus() {
-    window.addEventListener('focus', () => {
+    const refreshIfVisible = () => {
       if (document.visibilityState === 'visible') {
         // Certain data-fetching libraries that refetch on focus use setTimeout(cb, 0) to schedule a task on the event loop.
         // This gives us an opportunity to ensure the session cookie is updated with a fresh token before the fetch occurs, but it needs to
@@ -166,7 +167,15 @@ export class AuthCookieService {
         // While online `.schedule()` executes synchronously and immediately, ensuring the above mechanism will not break.
         void this.refreshSessionToken({ updateCookieImmediately: true });
       }
-    });
+    };
+
+    // `focus` covers top-level tabs (and the multi-tab active-organization handoff added in #3786), but it never fires
+    // inside a cross-origin iframe on tab re-activation unless the frame itself is clicked. `visibilitychange` does
+    // propagate into the iframe, so embedded apps (e.g. a preview pane) still get a fresh cookie before they refetch.
+    window.addEventListener('focus', refreshIfVisible);
+    if (typeof document !== 'undefined') {
+      document.addEventListener('visibilitychange', refreshIfVisible);
+    }
   }
 
   private async refreshSessionToken({
@@ -189,8 +198,10 @@ export class AuthCookieService {
   }
 
   private updateSessionCookie(token: string | null) {
-    // Only allow background tabs to update if both session and organization match
-    if (!document.hasFocus() && !this.isCurrentContextActive()) {
+    // Only allow background tabs to update if both session and organization match.
+    // A cross-origin iframe never reports focus even while visible, so treat a visible embedded
+    // frame as eligible to write; top-level multi-tab ownership still keys on `document.hasFocus()`.
+    if (!document.hasFocus() && !this.inVisibleCrossOriginIframe() && !this.isCurrentContextActive()) {
       return;
     }
 
@@ -258,6 +269,10 @@ export class AuthCookieService {
     }
   }
 
+  private inVisibleCrossOriginIframe() {
+    return inCrossOriginIframe() && document.visibilityState === 'visible';
+  }
+
   private isCurrentContextActive() {
     const activeContext = this.activeCookie.get();
     if (!activeContext) {

packages/clerk-js/src/core/auth/__tests__/AuthCookieService.test.ts

@@ -0,0 +1,139 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { eventBus, events } from '../../events';
+
+const mocks = vi.hoisted(() => ({
+  sessionCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn() },
+  clientUatCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn(() => 0) },
+  activeContextCookie: { set: vi.fn(), remove: vi.fn(), get: vi.fn<() => string | undefined>(() => undefined) },
+  inCrossOriginIframe: vi.fn(() => false),
+}));
+
+vi.mock('../cookies/session', () => ({ createSessionCookie: () => mocks.sessionCookie }));
+vi.mock('../cookies/clientUat', () => ({ createClientUatCookie: () => mocks.clientUatCookie }));
+vi.mock('../cookies/activeContext', () => ({ createActiveContextCookie: () => mocks.activeContextCookie }));
+vi.mock('../cookieSuffix', () => ({ getCookieSuffix: vi.fn(() => Promise.resolve('suffix')) }));
+vi.mock('../devBrowser', () => ({
+  createDevBrowser: () => ({
+    clear: vi.fn(),
+    setup: vi.fn(() => Promise.resolve()),
+    getDevBrowser: vi.fn(() => 'deadbeef'),
+    refreshCookies: vi.fn(),
+  }),
+}));
+vi.mock('@clerk/shared/internal/clerk-js/runtime', async importOriginal => {
+  const actual = await importOriginal<Record<string, unknown>>();
+  return { ...actual, inCrossOriginIframe: () => mocks.inCrossOriginIframe() };
+});
+
+import { AuthCookieService } from '../AuthCookieService';
+
+const setFocus = (hasFocus: boolean) =>
+  Object.defineProperty(document, 'hasFocus', { value: () => hasFocus, configurable: true });
+const setVisibility = (state: DocumentVisibilityState) =>
+  Object.defineProperty(document, 'visibilityState', { value: state, configurable: true });
+
+describe('AuthCookieService session cookie refresh', () => {
+  const getToken = vi.fn(() => Promise.resolve('fresh-jwt'));
+  const clerkStub = {
+    publishableKey: 'pk_test_Y2xlcmsuYWJjZWYuMTIzNDUuZGV2LmxjbGNsZXJrLmNvbSQ',
+    frontendApi: 'clerk.abcef.12345.dev.lclclerk.com',
+    loaded: true,
+    session: { id: 'sess_active', getToken },
+    organization: null,
+    user: {},
+    client: {},
+    handleUnauthenticated: vi.fn(),
+  } as any;
+  const clerkEventBusStub = { emit: vi.fn(), on: vi.fn(), prioritizedOn: vi.fn() } as any;
+
+  const createService = () => AuthCookieService.create(clerkStub, {} as any, 'production', clerkEventBusStub);
+  const emitTokenUpdate = (raw: string) =>
+    eventBus.emit(events.TokenUpdate, { token: { getRawString: () => raw } as any });
+
+  let service: Awaited<ReturnType<typeof createService>> | undefined;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.inCrossOriginIframe.mockReturnValue(false);
+    mocks.activeContextCookie.get.mockReturnValue(undefined);
+    getToken.mockResolvedValue('fresh-jwt');
+    setFocus(true);
+    setVisibility('visible');
+  });
+
+  afterEach(() => {
+    service?.stopPollingForToken();
+    service = undefined;
+    // The service registers listeners on the shared event bus on construction.
+    eventBus.off(events.TokenUpdate);
+    eventBus.off(events.UserSignOut);
+    eventBus.off(events.EnvironmentUpdate);
+  });
+
+  it('registers both focus and visibilitychange listeners', async () => {
+    const windowSpy = vi.spyOn(window, 'addEventListener');
+    const documentSpy = vi.spyOn(document, 'addEventListener');
+
+    service = await createService();
+
+    expect(windowSpy).toHaveBeenCalledWith('focus', expect.any(Function));
+    expect(documentSpy).toHaveBeenCalledWith('visibilitychange', expect.any(Function));
+  });
+
+  it('writes the session cookie on token:update when the tab is focused', async () => {
+    service = await createService();
+
+    emitTokenUpdate('jwt-focused');
+
+    expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-focused');
+  });
+
+  it('does not write when unfocused, outside an iframe, and the active context does not match', async () => {
+    mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+    service = await createService();
+    setFocus(false);
+
+    emitTokenUpdate('jwt-blocked');
+
+    expect(mocks.sessionCookie.set).not.toHaveBeenCalledWith('jwt-blocked');
+  });
+
+  it('writes when unfocused but in a visible cross-origin iframe, even if the active context does not match', async () => {
+    mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+    mocks.inCrossOriginIframe.mockReturnValue(true);
+    service = await createService();
+    setFocus(false);
+    setVisibility('visible');
+
+    emitTokenUpdate('jwt-iframe');
+
+    expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-iframe');
+  });
+
+  it('does not write in a cross-origin iframe while it is hidden', async () => {
+    mocks.activeContextCookie.get.mockReturnValue('sess_other:');
+    mocks.inCrossOriginIframe.mockReturnValue(true);
+    service = await createService();
+    setFocus(false);
+    setVisibility('hidden');
+
+    emitTokenUpdate('jwt-hidden');
+
+    expect(mocks.sessionCookie.set).not.toHaveBeenCalledWith('jwt-hidden');
+  });
+
+  it('refreshes the session cookie when an unfocused iframe becomes visible (visibilitychange)', async () => {
+    mocks.inCrossOriginIframe.mockReturnValue(true);
+    service = await createService();
+    setFocus(false);
+    setVisibility('visible');
+    getToken.mockResolvedValue('jwt-on-visible');
+    mocks.sessionCookie.set.mockClear();
+
+    document.dispatchEvent(new Event('visibilitychange'));
+    await vi.waitFor(() => expect(mocks.sessionCookie.set).toHaveBeenCalledWith('jwt-on-visible'));
+
+    expect(getToken).toHaveBeenCalled();
+  });
+});