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

.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;
+}

.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;
+}

.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;
+}

.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;
+}

.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;
+}

.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;
+}

.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;
+}

.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;
+}