fix(electron): validate IPC sender frame for token-cache and OAuth handlers (#9167)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dominic-clerk

.changeset/fine-results-crash.md

@@ -0,0 +1,5 @@
+---
+'@clerk/electron': patch
+---
+
+Validate that token-cache and OAuth-transport IPC requests originate from a top-level window's main frame. This prevents untrusted content in subframes or `<webview>`s that share the Clerk preload from reading the persisted client JWT or driving the OAuth transport.

packages/electron/src/main/__tests__/create-clerk-bridge.test.ts

@@ -34,6 +34,11 @@ vi.mock('@clerk/electron-passkeys', () => ({
   },
 }));
 
+const mainFrame = {};
+const windowSender = { mainFrame, getType: () => 'window' };
+const mainFrameEvent = { sender: windowSender, senderFrame: mainFrame } as unknown as Electron.IpcMainInvokeEvent;
+const subframeEvent = { sender: windowSender, senderFrame: {} } as unknown as Electron.IpcMainInvokeEvent;
+
 describe('createClerkBridge', () => {
   const missingStorage = {} as Parameters<typeof createClerkBridge>[0];
   const storage: TokenStorage = {
@@ -264,7 +269,52 @@ describe('createClerkBridge', () => {
       return channel === OAUTH_TRANSPORT_CHANNELS.getRedirectUrl;
     })?.[1];
 
-    expect(getRedirectUrlHandler?.({} as Electron.IpcMainInvokeEvent)).toBe('my-app://renderer/');
+    expect(getRedirectUrlHandler?.(mainFrameEvent)).toBe('my-app://renderer/');
+  });
+
+  it('rejects OAuth transport requests that do not originate from the main frame', async () => {
+    vi.mocked(shell.openExternal).mockResolvedValue(undefined);
+    createClerkBridge({
+      storage,
+      renderer: {
+        host: 'renderer',
+        scheme: 'my-app',
+      },
+    });
+
+    const findHandler = (channel: string) =>
+      vi.mocked(ipcMain.handle).mock.calls.find(([registered]) => registered === channel)?.[1];
+
+    expect(() => findHandler(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl)?.(subframeEvent)).toThrow('main frame');
+    await expect(
+      findHandler(OAUTH_TRANSPORT_CHANNELS.open)?.(subframeEvent, 'https://accounts.example.com/oauth'),
+    ).rejects.toThrow('main frame');
+    expect(shell.openExternal).not.toHaveBeenCalled();
+  });
+
+  it('rejects OAuth transport requests from a <webview> whose top frame mimics the main frame', async () => {
+    vi.mocked(shell.openExternal).mockResolvedValue(undefined);
+    createClerkBridge({
+      storage,
+      renderer: {
+        host: 'renderer',
+        scheme: 'my-app',
+      },
+    });
+
+    const findHandler = (channel: string) =>
+      vi.mocked(ipcMain.handle).mock.calls.find(([registered]) => registered === channel)?.[1];
+
+    const webviewEvent = {
+      sender: { mainFrame, getType: () => 'webview' },
+      senderFrame: mainFrame,
+    } as unknown as Electron.IpcMainInvokeEvent;
+
+    expect(() => findHandler(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl)?.(webviewEvent)).toThrow('main frame');
+    await expect(
+      findHandler(OAUTH_TRANSPORT_CHANNELS.open)?.(webviewEvent, 'https://accounts.example.com/oauth'),
+    ).rejects.toThrow('main frame');
+    expect(shell.openExternal).not.toHaveBeenCalled();
   });
 
   it('opens OAuth URLs externally and resolves with the matching deep-link callback URL', async () => {
@@ -280,7 +330,7 @@ describe('createClerkBridge', () => {
     const openHandler = vi.mocked(ipcMain.handle).mock.calls.find(([channel]) => {
       return channel === OAUTH_TRANSPORT_CHANNELS.open;
     })?.[1];
-    const openPromise = openHandler?.({} as Electron.IpcMainInvokeEvent, 'https://accounts.example.com/oauth');
+    const openPromise = openHandler?.(mainFrameEvent, 'https://accounts.example.com/oauth');
     const openUrlListener = vi.mocked(app.on).mock.calls.find(([event]) => event === 'open-url')?.[1] as (
       event: Electron.Event,
       url: string,

packages/electron/src/main/__tests__/ipc-handlers.test.ts

@@ -5,7 +5,15 @@ import { TOKEN_CACHE_CHANNELS } from '../../shared/ipc';
 import type { TokenStorage } from '../../shared/types';
 import { setupTokenCacheIpcHandlers } from '../ipc-handlers';
 
-const ipcEvent = {} as Electron.IpcMainInvokeEvent;
+const mainFrame = {};
+const windowSender = { mainFrame, getType: () => 'window' };
+const ipcEvent = { sender: windowSender, senderFrame: mainFrame } as unknown as Electron.IpcMainInvokeEvent;
+const subframeEvent = { sender: windowSender, senderFrame: {} } as unknown as Electron.IpcMainInvokeEvent;
+// A <webview> is a separate WebContents whose top document satisfies senderFrame === mainFrame.
+const webviewEvent = {
+  sender: { mainFrame, getType: () => 'webview' },
+  senderFrame: mainFrame,
+} as unknown as Electron.IpcMainInvokeEvent;
 
 vi.mock('electron', () => ({
   ipcMain: {
@@ -51,6 +59,38 @@ describe('setupTokenCacheIpcHandlers', () => {
     expect(storage.removeItem).toHaveBeenCalledWith('token-key');
   });
 
+  it('rejects token operations that do not originate from the main frame', () => {
+    setupTokenCacheIpcHandlers(storage);
+
+    const getTokenHandler = vi.mocked(ipcMain.handle).mock.calls[0][1];
+    const saveTokenHandler = vi.mocked(ipcMain.handle).mock.calls[1][1];
+    const clearTokenHandler = vi.mocked(ipcMain.handle).mock.calls[2][1];
+
+    expect(() => getTokenHandler(subframeEvent, 'token-key')).toThrow('main frame');
+    expect(() => saveTokenHandler(subframeEvent, 'token-key', 'jwt')).toThrow('main frame');
+    expect(() => clearTokenHandler(subframeEvent, 'token-key')).toThrow('main frame');
+
+    expect(storage.getItem).not.toHaveBeenCalled();
+    expect(storage.setItem).not.toHaveBeenCalled();
+    expect(storage.removeItem).not.toHaveBeenCalled();
+  });
+
+  it('rejects token operations from a <webview> whose top frame mimics the main frame', () => {
+    setupTokenCacheIpcHandlers(storage);
+
+    const getTokenHandler = vi.mocked(ipcMain.handle).mock.calls[0][1];
+    const saveTokenHandler = vi.mocked(ipcMain.handle).mock.calls[1][1];
+    const clearTokenHandler = vi.mocked(ipcMain.handle).mock.calls[2][1];
+
+    expect(() => getTokenHandler(webviewEvent, 'token-key')).toThrow('main frame');
+    expect(() => saveTokenHandler(webviewEvent, 'token-key', 'jwt')).toThrow('main frame');
+    expect(() => clearTokenHandler(webviewEvent, 'token-key')).toThrow('main frame');
+
+    expect(storage.getItem).not.toHaveBeenCalled();
+    expect(storage.setItem).not.toHaveBeenCalled();
+    expect(storage.removeItem).not.toHaveBeenCalled();
+  });
+
   it('removes registered handlers on cleanup', () => {
     const cleanup = setupTokenCacheIpcHandlers(storage);
 

packages/electron/src/main/__tests__/passkey-handlers.test.ts

@@ -36,7 +36,10 @@ const getHandler = (channel: string): Handler => {
 
 const windowHandle = Buffer.from([1, 2, 3, 4]);
 const mainFrame = {};
-const event = { sender: { mainFrame }, senderFrame: mainFrame } as unknown as IpcMainInvokeEvent;
+const event = {
+  sender: { mainFrame, getType: () => 'window' },
+  senderFrame: mainFrame,
+} as unknown as IpcMainInvokeEvent;
 
 const creationOptions = { challenge: 'abc', rp: { id: 'example.com', name: 'Example' } };
 const registrationJSON = { id: 'cred', rawId: 'cred', type: 'public-key', response: {} };
@@ -98,7 +101,10 @@ describe('setupPasskeysMain', () => {
   it('rejects requests that do not originate from the main frame', async () => {
     setupPasskeysMain();
 
-    const subframeEvent = { sender: { mainFrame }, senderFrame: {} } as unknown as IpcMainInvokeEvent;
+    const subframeEvent = {
+      sender: { mainFrame, getType: () => 'window' },
+      senderFrame: {},
+    } as unknown as IpcMainInvokeEvent;
     const result = await getHandler(PASSKEY_CHANNELS.create)(subframeEvent, creationOptions);
 
     expect(result).toMatchObject({ ok: false, error: { code: 'unknown' } });

packages/electron/src/main/ipc-handlers.ts

@@ -1,18 +1,29 @@
+import type { IpcMainInvokeEvent } from 'electron';
 import { ipcMain } from 'electron';
 
 import { TOKEN_CACHE_CHANNELS } from '../shared/ipc';
 import type { TokenStorage } from '../shared/types';
+import { isMainFrameEvent } from './validate-sender';
+
+function assertMainFrameSender(event: IpcMainInvokeEvent): void {
+  if (!isMainFrameEvent(event)) {
+    throw new Error("Clerk: token-cache request did not originate from a window's main frame.");
+  }
+}
 
 export function setupTokenCacheIpcHandlers(storage: TokenStorage): () => void {
-  ipcMain.handle(TOKEN_CACHE_CHANNELS.getToken, (_event, key: string) => {
+  ipcMain.handle(TOKEN_CACHE_CHANNELS.getToken, (event, key: string) => {
+    assertMainFrameSender(event);
     return storage.getItem(key);
   });
 
-  ipcMain.handle(TOKEN_CACHE_CHANNELS.saveToken, (_event, key: string, value: string) => {
+  ipcMain.handle(TOKEN_CACHE_CHANNELS.saveToken, (event, key: string, value: string) => {
+    assertMainFrameSender(event);
     return storage.setItem(key, value);
   });
 
-  ipcMain.handle(TOKEN_CACHE_CHANNELS.clearToken, (_event, key: string) => {
+  ipcMain.handle(TOKEN_CACHE_CHANNELS.clearToken, (event, key: string) => {
+    assertMainFrameSender(event);
     return storage.removeItem(key);
   });
 

packages/electron/src/main/oauth-transport.ts

@@ -2,6 +2,7 @@ import { app, ipcMain, shell } from 'electron';
 
 import { OAUTH_TRANSPORT_CHANNELS } from '../shared/ipc';
 import type { RendererSchemeOptions } from '../shared/types';
+import { isMainFrameEvent } from './validate-sender';
 
 const CALLBACK_TIMEOUT_MS = 3 * 60 * 1000;
 
@@ -91,11 +92,18 @@ export function setupOAuthTransportIpcHandlers(options: OAuthTransportOptions):
   app.on('open-url', openUrlListener);
   app.on('second-instance', secondInstanceListener);
 
-  ipcMain.handle(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl, () => {
+  ipcMain.handle(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl, event => {
+    if (!isMainFrameEvent(event)) {
+      throw new Error("Clerk: OAuth request did not originate from a window's main frame.");
+    }
     return redirectUrl;
   });
 
-  ipcMain.handle(OAUTH_TRANSPORT_CHANNELS.open, async (_event, url: string) => {
+  ipcMain.handle(OAUTH_TRANSPORT_CHANNELS.open, async (event, url: string) => {
+    if (!isMainFrameEvent(event)) {
+      throw new Error("Clerk: OAuth request did not originate from a window's main frame.");
+    }
+
     if (pendingOAuthFlow) {
       throw new Error('Clerk: an OAuth flow is already pending.');
     }

packages/electron/src/main/passkey-handlers.ts

@@ -12,6 +12,7 @@ import type {
   SerializedPublicKeyCredentialRequestOptions,
   SetupPasskeysMainReturn,
 } from '../shared/types';
+import { isMainFrameEvent } from './validate-sender';
 
 /**
  * Optional native module. Ceremony failures resolve as JSON envelopes so error
@@ -77,7 +78,7 @@ async function invokeNative<T>(
 
   // Subframes and webviews can host third-party content that must not be able
   // to run credential ceremonies for the app's RP ID.
-  if (!event.senderFrame || event.senderFrame !== event.sender.mainFrame) {
+  if (!isMainFrameEvent(event)) {
     return {
       ok: false,
       error: { code: 'unknown', message: "The passkey request did not originate from a window's main frame." },

packages/electron/src/main/validate-sender.ts

@@ -0,0 +1,10 @@
+import type { IpcMainInvokeEvent } from 'electron';
+
+// Restricts privileged IPC to a top-level BrowserWindow's main frame. The frame check alone
+// only proves the sender is the top document of *its own* WebContents, so a <webview> (a separate
+// WebContents) sharing the Clerk preload would still pass; requiring getType() === 'window' rejects
+// <webview> guests and BrowserViews, and the frame check rejects in-page iframes.
+export function isMainFrameEvent(event: IpcMainInvokeEvent): boolean {
+  const { sender, senderFrame } = event;
+  return sender.getType() === 'window' && Boolean(senderFrame) && senderFrame === sender.mainFrame;
+}