feat(electron): Add deep link and native OAuth IPC handling

packages/electron/src/global.d.ts

@@ -1,4 +1,4 @@
-import type { TokenCache } from './shared/types';
+import type { OAuthTransport, TokenCache } from './shared/types';
 
 declare const PACKAGE_NAME: string;
 declare const PACKAGE_VERSION: string;
@@ -8,6 +8,7 @@ declare global {
  interface Window {
  __clerk_internal_electron?: {
  tokenCache: TokenCache;
+ oauthTransport: OAuthTransport;
  };
  }
 }

packages/electron/src/main/__tests__/setup-main.test.ts

@@ -1,17 +1,26 @@
-import { ipcMain, protocol } from 'electron';
+import { app, ipcMain, protocol, shell } from 'electron';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { OAUTH_TRANSPORT_CHANNELS } from '../../shared/ipc';
 import type { TokenStorage } from '../../shared/types';
 import { setupMain } from '../setup-main';
 
 vi.mock('electron', () => ({
+ app: {
+ on: vi.fn(),
+ removeListener: vi.fn(),
+ setAsDefaultProtocolClient: vi.fn(),
+ },
  ipcMain: {
  handle: vi.fn(),
  removeHandler: vi.fn(),
  },
  protocol: {
  registerSchemesAsPrivileged: vi.fn(),
  },
+ shell: {
+ openExternal: vi.fn(),
+ },
 }));
 
 describe('setupMain', () => {
@@ -90,4 +99,76 @@ describe('setupMain', () => {
 
  expect(ipcMain.removeHandler).toHaveBeenCalledTimes(3);
  });
+
+ it('cleans up OAuth transport handlers when renderer origin is configured', () => {
+ const clerk = setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ clerk.cleanup();
+
+ expect(ipcMain.removeHandler).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ expect(ipcMain.removeHandler).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.open);
+ expect(app.removeListener).toHaveBeenCalledWith('open-url', expect.any(Function));
+ expect(app.removeListener).toHaveBeenCalledWith('second-instance', expect.any(Function));
+ });
+
+ it('sets up OAuth transport IPC handlers when renderer origin is configured', () => {
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ expect(ipcMain.handle).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl, expect.any(Function));
+ expect(ipcMain.handle).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.open, expect.any(Function));
+ expect(app.setAsDefaultProtocolClient).toHaveBeenCalledWith('my-app');
+ });
+
+ it('derives the OAuth callback URL from the renderer origin', () => {
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ const getRedirectUrlHandler = vi.mocked(ipcMain.handle).mock.calls.find(([channel]) => {
+ return channel === OAUTH_TRANSPORT_CHANNELS.getRedirectUrl;
+ })?.[1];
+
+ expect(getRedirectUrlHandler?.({} as Electron.IpcMainInvokeEvent)).toBe('my-app://renderer/');
+ });
+
+ it('opens OAuth URLs externally and resolves with the matching deep-link callback URL', async () => {
+ vi.mocked(shell.openExternal).mockResolvedValue(undefined);
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ 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 openUrlListener = vi.mocked(app.on).mock.calls.find(([event]) => event === 'open-url')?.[1] as (
+ event: Electron.Event,
+ url: string,
+ ) => void;
+
+ openUrlListener({ preventDefault: vi.fn() } as unknown as Electron.Event, 'my-app://renderer/?code=123');
+
+ await expect(openPromise).resolves.toEqual({ callbackUrl: 'my-app://renderer/?code=123' });
+ expect(shell.openExternal).toHaveBeenCalledWith('https://accounts.example.com/oauth');
+ });
 });

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

@@ -0,0 +1,130 @@
+import { app, ipcMain, shell } from 'electron';
+
+import { OAUTH_TRANSPORT_CHANNELS } from '../shared/ipc';
+import type { RendererSchemeOptions } from '../shared/types';
+
+const CALLBACK_TIMEOUT_MS = 3 * 60 * 1000;
+
+type PendingOAuthFlow = {
+ resolve: (value: { callbackUrl: string }) => void;
+ reject: (reason: Error) => void;
+ timeout: NodeJS.Timeout;
+};
+
+type OAuthTransportOptions = {
+ renderer: RendererSchemeOptions;
+};
+
+function buildRedirectUrl(options: OAuthTransportOptions): string {
+ return `${options.renderer.scheme}://${options.renderer.host}/`;
+}
+
+function isMatchingCallbackUrl(url: string, redirectUrl: string): boolean {
+ try {
+ const callback = new URL(url);
+ const expected = new URL(redirectUrl);
+
+ return (
+ callback.protocol === expected.protocol &&
+ callback.host === expected.host &&
+ callback.pathname === expected.pathname
+ );
+ } catch {
+ return false;
+ }
+}
+
+function assertExternalOAuthUrl(url: string): void {
+ const parsedUrl = new URL(url);
+
+ if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+ throw new TypeError(`Clerk: refusing to open unsupported OAuth URL protocol: ${parsedUrl.protocol}`);
+ }
+}
+
+export function setupOAuthTransportIpcHandlers(options: OAuthTransportOptions): () => void {
+ const redirectUrl = buildRedirectUrl(options);
+ let pendingOAuthFlow: PendingOAuthFlow | null = null;
+
+ const disposePendingOAuthFlow = (reason?: Error): void => {
+ if (!pendingOAuthFlow) {
+ return;
+ }
+
+ const pending = pendingOAuthFlow;
+ clearTimeout(pendingOAuthFlow.timeout);
+ pendingOAuthFlow = null;
+
+ if (reason) {
+ pending.reject(reason);
+ }
+ };
+
+ const handleCallbackUrl = (url: string): void => {
+ if (!pendingOAuthFlow || !isMatchingCallbackUrl(url, redirectUrl)) {
+ return;
+ }
+
+ const pending = pendingOAuthFlow;
+ disposePendingOAuthFlow();
+ pending.resolve({ callbackUrl: url });
+ };
+
+ const openUrlListener = (event: Electron.Event, url: string): void => {
+ if (!isMatchingCallbackUrl(url, redirectUrl)) {
+ return;
+ }
+
+ event.preventDefault();
+ handleCallbackUrl(url);
+ };
+
+ const secondInstanceListener = (_event: Electron.Event, argv: string[]): void => {
+ const callbackUrl = argv.find(url => isMatchingCallbackUrl(url, redirectUrl));
+
+ if (callbackUrl) {
+ handleCallbackUrl(callbackUrl);
+ }
+ };
+
+ app.setAsDefaultProtocolClient(options.renderer.scheme);
+ app.on('open-url', openUrlListener);
+ app.on('second-instance', secondInstanceListener);
+
+ ipcMain.handle(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl, () => {
+ return redirectUrl;
+ });
+
+ ipcMain.handle(OAUTH_TRANSPORT_CHANNELS.open, async (_event, url: string) => {
+ if (pendingOAuthFlow) {
+ throw new Error('Clerk: an OAuth flow is already pending.');
+ }
+
+ assertExternalOAuthUrl(url);
+
+ const callbackPromise = new Promise<{ callbackUrl: string }>((resolve, reject) => {
+ const timeout = setTimeout(() => {
+ disposePendingOAuthFlow();
+ reject(new Error('Clerk: OAuth callback timed out.'));
+ }, CALLBACK_TIMEOUT_MS);
+
+ pendingOAuthFlow = { resolve, reject, timeout };
+ });
+
+ try {
+ await shell.openExternal(url);
+ } catch (err) {
+ disposePendingOAuthFlow(err instanceof Error ? err : new Error(String(err)));
+ }
+
+ return callbackPromise;
+ });
+
+ return () => {
+ disposePendingOAuthFlow(new Error('Clerk: OAuth flow was cancelled.'));
+ app.removeListener('open-url', openUrlListener);
+ app.removeListener('second-instance', secondInstanceListener);
+ ipcMain.removeHandler(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ ipcMain.removeHandler(OAUTH_TRANSPORT_CHANNELS.open);
+ };
+}

packages/electron/src/main/setup-main.ts

@@ -2,6 +2,7 @@ import { protocol } from 'electron';
 
 import type { SetupMainOptions, SetupMainReturn } from '../shared/types';
 import { setupTokenCacheIpcHandlers } from './ipc-handlers';
+import { setupOAuthTransportIpcHandlers } from './oauth-transport';
 
 function assertValidRendererOriginConfig(renderer: NonNullable<SetupMainOptions['renderer']>): void {
  if (renderer.scheme.includes(':') || renderer.scheme.includes('/')) {
@@ -25,6 +26,7 @@ export function setupMain(options: SetupMainOptions): SetupMainReturn {
  }
 
  const cleanupTokenPersistence = setupTokenCacheIpcHandlers(options.storage);
+ let cleanupOAuthTransport: (() => void) | undefined;
 
  if (options.renderer) {
  assertValidRendererOriginConfig(options.renderer);
@@ -41,11 +43,16 @@ export function setupMain(options: SetupMainOptions): SetupMainReturn {
  },
  },
  ]);
+
+ cleanupOAuthTransport = setupOAuthTransportIpcHandlers({
+ renderer: options.renderer,
+ });
  }
 
  return {
  cleanup() {
  cleanupTokenPersistence();
+ cleanupOAuthTransport?.();
  },
  };
 }

packages/electron/src/preload/__tests__/index.test.ts

@@ -1,7 +1,7 @@
 import { contextBridge, ipcRenderer } from 'electron';
 import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-import { TOKEN_CACHE_CHANNELS } from '../../shared/ipc';
+import { OAUTH_TRANSPORT_CHANNELS, TOKEN_CACHE_CHANNELS } from '../../shared/ipc';
 import { setupPreload } from '../index';
 
 vi.mock('electron', () => ({
@@ -39,6 +39,10 @@ describe('setupPreload', () => {
  saveToken: expect.any(Function),
  clearToken: expect.any(Function),
  },
+ oauthTransport: {
+ getRedirectUrl: expect.any(Function),
+ open: expect.any(Function),
+ },
  });
  });
 
@@ -52,6 +56,10 @@ describe('setupPreload', () => {
  saveToken: expect.any(Function),
  clearToken: expect.any(Function),
  });
+ expect(window.__clerk_internal_electron?.oauthTransport).toEqual({
+ getRedirectUrl: expect.any(Function),
+ open: expect.any(Function),
+ });
  });
 
  it('forwards token cache calls over IPC', async () => {
@@ -68,4 +76,20 @@ describe('setupPreload', () => {
  expect(ipcRenderer.invoke).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.saveToken, 'token-key', 'jwt');
  expect(ipcRenderer.invoke).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.clearToken, 'token-key');
  });
+
+ it('forwards OAuth transport calls over IPC', async () => {
+ setupPreload();
+
+ const bridge = vi.mocked(contextBridge.exposeInMainWorld).mock
+ .calls[0][1] as typeof window.__clerk_internal_electron;
+
+ await bridge?.oauthTransport.getRedirectUrl();
+ await bridge?.oauthTransport.open('https://accounts.example.com/oauth');
+
+ expect(ipcRenderer.invoke).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ expect(ipcRenderer.invoke).toHaveBeenCalledWith(
+ OAUTH_TRANSPORT_CHANNELS.open,
+ 'https://accounts.example.com/oauth',
+ );
+ });
 });

packages/electron/src/preload/index.ts

@@ -1,18 +1,23 @@
 import { contextBridge, ipcRenderer } from 'electron';
 
-import { TOKEN_CACHE_CHANNELS } from '../shared/ipc';
-import type { TokenCache } from '../shared/types';
+import { OAUTH_TRANSPORT_CHANNELS, TOKEN_CACHE_CHANNELS } from '../shared/ipc';
+import type { OAuthTransport, TokenCache } from '../shared/types';
 
 export function setupPreload(): void {
  const tokenCache: TokenCache = {
  getToken: key => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.getToken, key),
  saveToken: (key, value) => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.saveToken, key, value),
  clearToken: key => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.clearToken, key),
  };
+ const oauthTransport: OAuthTransport = {
+ getRedirectUrl: () => ipcRenderer.invoke(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl),
+ open: url => ipcRenderer.invoke(OAUTH_TRANSPORT_CHANNELS.open, url),
+ };
+ const bridge = { tokenCache, oauthTransport };
 
  if (process.contextIsolated) {
- contextBridge.exposeInMainWorld('__clerk_internal_electron', { tokenCache });
+ contextBridge.exposeInMainWorld('__clerk_internal_electron', bridge);
  } else {
- window.__clerk_internal_electron = { tokenCache };
+ window.__clerk_internal_electron = bridge;
  }
 }

packages/electron/src/global.d.ts

@@ -1,4 +1,4 @@
-import type { TokenCache } from './shared/types';
+import type { OAuthTransport, TokenCache } from './shared/types';
 
 declare const PACKAGE_NAME: string;
 declare const PACKAGE_VERSION: string;
@@ -8,6 +8,7 @@ declare global {
  interface Window {
  __clerk_internal_electron?: {
  tokenCache: TokenCache;
+ oauthTransport: OAuthTransport;
  };
  }
 }

packages/electron/src/main/__tests__/setup-main.test.ts

@@ -1,17 +1,26 @@
-import { ipcMain, protocol } from 'electron';
+import { app, ipcMain, protocol, shell } from 'electron';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { OAUTH_TRANSPORT_CHANNELS } from '../../shared/ipc';
 import type { TokenStorage } from '../../shared/types';
 import { setupMain } from '../setup-main';
 
 vi.mock('electron', () => ({
+ app: {
+ on: vi.fn(),
+ removeListener: vi.fn(),
+ setAsDefaultProtocolClient: vi.fn(),
+ },
  ipcMain: {
  handle: vi.fn(),
  removeHandler: vi.fn(),
  },
  protocol: {
  registerSchemesAsPrivileged: vi.fn(),
  },
+ shell: {
+ openExternal: vi.fn(),
+ },
 }));
 
 describe('setupMain', () => {
@@ -90,4 +99,76 @@ describe('setupMain', () => {
 
  expect(ipcMain.removeHandler).toHaveBeenCalledTimes(3);
  });
+
+ it('cleans up OAuth transport handlers when renderer origin is configured', () => {
+ const clerk = setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ clerk.cleanup();
+
+ expect(ipcMain.removeHandler).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ expect(ipcMain.removeHandler).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.open);
+ expect(app.removeListener).toHaveBeenCalledWith('open-url', expect.any(Function));
+ expect(app.removeListener).toHaveBeenCalledWith('second-instance', expect.any(Function));
+ });
+
+ it('sets up OAuth transport IPC handlers when renderer origin is configured', () => {
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ expect(ipcMain.handle).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl, expect.any(Function));
+ expect(ipcMain.handle).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.open, expect.any(Function));
+ expect(app.setAsDefaultProtocolClient).toHaveBeenCalledWith('my-app');
+ });
+
+ it('derives the OAuth callback URL from the renderer origin', () => {
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ const getRedirectUrlHandler = vi.mocked(ipcMain.handle).mock.calls.find(([channel]) => {
+ return channel === OAUTH_TRANSPORT_CHANNELS.getRedirectUrl;
+ })?.[1];
+
+ expect(getRedirectUrlHandler?.({} as Electron.IpcMainInvokeEvent)).toBe('my-app://renderer/');
+ });
+
+ it('opens OAuth URLs externally and resolves with the matching deep-link callback URL', async () => {
+ vi.mocked(shell.openExternal).mockResolvedValue(undefined);
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ 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 openUrlListener = vi.mocked(app.on).mock.calls.find(([event]) => event === 'open-url')?.[1] as (
+ event: Electron.Event,
+ url: string,
+ ) => void;
+
+ openUrlListener({ preventDefault: vi.fn() } as unknown as Electron.Event, 'my-app://renderer/?code=123');
+
+ await expect(openPromise).resolves.toEqual({ callbackUrl: 'my-app://renderer/?code=123' });
+ expect(shell.openExternal).toHaveBeenCalledWith('https://accounts.example.com/oauth');
+ });
 });

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

@@ -0,0 +1,130 @@
+import { app, ipcMain, shell } from 'electron';
+
+import { OAUTH_TRANSPORT_CHANNELS } from '../shared/ipc';
+import type { RendererSchemeOptions } from '../shared/types';
+
+const CALLBACK_TIMEOUT_MS = 3 * 60 * 1000;
+
+type PendingOAuthFlow = {
+ resolve: (value: { callbackUrl: string }) => void;
+ reject: (reason: Error) => void;
+ timeout: NodeJS.Timeout;
+};
+
+type OAuthTransportOptions = {
+ renderer: RendererSchemeOptions;
+};
+
+function buildRedirectUrl(options: OAuthTransportOptions): string {
+ return `${options.renderer.scheme}://${options.renderer.host}/`;
+}
+
+function isMatchingCallbackUrl(url: string, redirectUrl: string): boolean {
+ try {
+ const callback = new URL(url);
+ const expected = new URL(redirectUrl);
+
+ return (
+ callback.protocol === expected.protocol &&
+ callback.host === expected.host &&
+ callback.pathname === expected.pathname
+ );
+ } catch {
+ return false;
+ }
+}
+
+function assertExternalOAuthUrl(url: string): void {
+ const parsedUrl = new URL(url);
+
+ if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+ throw new TypeError(`Clerk: refusing to open unsupported OAuth URL protocol: ${parsedUrl.protocol}`);
+ }
+}
+
+export function setupOAuthTransportIpcHandlers(options: OAuthTransportOptions): () => void {
+ const redirectUrl = buildRedirectUrl(options);
+ let pendingOAuthFlow: PendingOAuthFlow | null = null;
+
+ const disposePendingOAuthFlow = (reason?: Error): void => {
+ if (!pendingOAuthFlow) {
+ return;
+ }
+
+ const pending = pendingOAuthFlow;
+ clearTimeout(pendingOAuthFlow.timeout);
+ pendingOAuthFlow = null;
+
+ if (reason) {
+ pending.reject(reason);
+ }
+ };
+
+ const handleCallbackUrl = (url: string): void => {
+ if (!pendingOAuthFlow || !isMatchingCallbackUrl(url, redirectUrl)) {
+ return;
+ }
+
+ const pending = pendingOAuthFlow;
+ disposePendingOAuthFlow();
+ pending.resolve({ callbackUrl: url });
+ };
+
+ const openUrlListener = (event: Electron.Event, url: string): void => {
+ if (!isMatchingCallbackUrl(url, redirectUrl)) {
+ return;
+ }
+
+ event.preventDefault();
+ handleCallbackUrl(url);
+ };
+
+ const secondInstanceListener = (_event: Electron.Event, argv: string[]): void => {
+ const callbackUrl = argv.find(url => isMatchingCallbackUrl(url, redirectUrl));
+
+ if (callbackUrl) {
+ handleCallbackUrl(callbackUrl);
+ }
+ };
+
+ app.setAsDefaultProtocolClient(options.renderer.scheme);
+ app.on('open-url', openUrlListener);
+ app.on('second-instance', secondInstanceListener);
+
+ ipcMain.handle(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl, () => {
+ return redirectUrl;
+ });
+
+ ipcMain.handle(OAUTH_TRANSPORT_CHANNELS.open, async (_event, url: string) => {
+ if (pendingOAuthFlow) {
+ throw new Error('Clerk: an OAuth flow is already pending.');
+ }
+
+ assertExternalOAuthUrl(url);
+
+ const callbackPromise = new Promise<{ callbackUrl: string }>((resolve, reject) => {
+ const timeout = setTimeout(() => {
+ disposePendingOAuthFlow();
+ reject(new Error('Clerk: OAuth callback timed out.'));
+ }, CALLBACK_TIMEOUT_MS);
+
+ pendingOAuthFlow = { resolve, reject, timeout };
+ });
+
+ try {
+ await shell.openExternal(url);
+ } catch (err) {
+ disposePendingOAuthFlow(err instanceof Error ? err : new Error(String(err)));
+ }
+
+ return callbackPromise;
+ });
+
+ return () => {
+ disposePendingOAuthFlow(new Error('Clerk: OAuth flow was cancelled.'));
+ app.removeListener('open-url', openUrlListener);
+ app.removeListener('second-instance', secondInstanceListener);
+ ipcMain.removeHandler(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ ipcMain.removeHandler(OAUTH_TRANSPORT_CHANNELS.open);
+ };
+}

packages/electron/src/main/setup-main.ts

@@ -2,6 +2,7 @@ import { protocol } from 'electron';
 
 import type { SetupMainOptions, SetupMainReturn } from '../shared/types';
 import { setupTokenCacheIpcHandlers } from './ipc-handlers';
+import { setupOAuthTransportIpcHandlers } from './oauth-transport';
 
 function assertValidRendererOriginConfig(renderer: NonNullable<SetupMainOptions['renderer']>): void {
  if (renderer.scheme.includes(':') || renderer.scheme.includes('/')) {
@@ -25,6 +26,7 @@ export function setupMain(options: SetupMainOptions): SetupMainReturn {
  }
 
  const cleanupTokenPersistence = setupTokenCacheIpcHandlers(options.storage);
+ let cleanupOAuthTransport: (() => void) | undefined;
 
  if (options.renderer) {
  assertValidRendererOriginConfig(options.renderer);
@@ -41,11 +43,16 @@ export function setupMain(options: SetupMainOptions): SetupMainReturn {
  },
  },
  ]);
+
+ cleanupOAuthTransport = setupOAuthTransportIpcHandlers({
+ renderer: options.renderer,
+ });
  }
 
  return {
  cleanup() {
  cleanupTokenPersistence();
+ cleanupOAuthTransport?.();
  },
  };
 }

packages/electron/src/preload/__tests__/index.test.ts

@@ -1,7 +1,7 @@
 import { contextBridge, ipcRenderer } from 'electron';
 import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-import { TOKEN_CACHE_CHANNELS } from '../../shared/ipc';
+import { OAUTH_TRANSPORT_CHANNELS, TOKEN_CACHE_CHANNELS } from '../../shared/ipc';
 import { setupPreload } from '../index';
 
 vi.mock('electron', () => ({
@@ -39,6 +39,10 @@ describe('setupPreload', () => {
  saveToken: expect.any(Function),
  clearToken: expect.any(Function),
  },
+ oauthTransport: {
+ getRedirectUrl: expect.any(Function),
+ open: expect.any(Function),
+ },
  });
  });
 
@@ -52,6 +56,10 @@ describe('setupPreload', () => {
  saveToken: expect.any(Function),
  clearToken: expect.any(Function),
  });
+ expect(window.__clerk_internal_electron?.oauthTransport).toEqual({
+ getRedirectUrl: expect.any(Function),
+ open: expect.any(Function),
+ });
  });
 
  it('forwards token cache calls over IPC', async () => {
@@ -68,4 +76,20 @@ describe('setupPreload', () => {
  expect(ipcRenderer.invoke).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.saveToken, 'token-key', 'jwt');
  expect(ipcRenderer.invoke).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.clearToken, 'token-key');
  });
+
+ it('forwards OAuth transport calls over IPC', async () => {
+ setupPreload();
+
+ const bridge = vi.mocked(contextBridge.exposeInMainWorld).mock
+ .calls[0][1] as typeof window.__clerk_internal_electron;
+
+ await bridge?.oauthTransport.getRedirectUrl();
+ await bridge?.oauthTransport.open('https://accounts.example.com/oauth');
+
+ expect(ipcRenderer.invoke).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ expect(ipcRenderer.invoke).toHaveBeenCalledWith(
+ OAUTH_TRANSPORT_CHANNELS.open,
+ 'https://accounts.example.com/oauth',
+ );
+ });
 });

packages/electron/src/preload/index.ts

@@ -1,18 +1,23 @@
 import { contextBridge, ipcRenderer } from 'electron';
 
-import { TOKEN_CACHE_CHANNELS } from '../shared/ipc';
-import type { TokenCache } from '../shared/types';
+import { OAUTH_TRANSPORT_CHANNELS, TOKEN_CACHE_CHANNELS } from '../shared/ipc';
+import type { OAuthTransport, TokenCache } from '../shared/types';
 
 export function setupPreload(): void {
  const tokenCache: TokenCache = {
  getToken: key => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.getToken, key),
  saveToken: (key, value) => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.saveToken, key, value),
  clearToken: key => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.clearToken, key),
  };
+ const oauthTransport: OAuthTransport = {
+ getRedirectUrl: () => ipcRenderer.invoke(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl),
+ open: url => ipcRenderer.invoke(OAUTH_TRANSPORT_CHANNELS.open, url),
+ };
+ const bridge = { tokenCache, oauthTransport };
 
  if (process.contextIsolated) {
- contextBridge.exposeInMainWorld('__clerk_internal_electron', { tokenCache });
+ contextBridge.exposeInMainWorld('__clerk_internal_electron', bridge);
  } else {
- window.__clerk_internal_electron = { tokenCache };
+ window.__clerk_internal_electron = bridge;
  }
 }

packages/electron/src/global.d.ts

@@ -1,4 +1,4 @@
-import type { TokenCache } from './shared/types';
+import type { OAuthTransport, TokenCache } from './shared/types';
 
 declare const PACKAGE_NAME: string;
 declare const PACKAGE_VERSION: string;
@@ -8,6 +8,7 @@ declare global {
  interface Window {
  __clerk_internal_electron?: {
  tokenCache: TokenCache;
+ oauthTransport: OAuthTransport;
  };
  }
 }

packages/electron/src/main/__tests__/setup-main.test.ts

@@ -1,17 +1,26 @@
-import { ipcMain, protocol } from 'electron';
+import { app, ipcMain, protocol, shell } from 'electron';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { OAUTH_TRANSPORT_CHANNELS } from '../../shared/ipc';
 import type { TokenStorage } from '../../shared/types';
 import { setupMain } from '../setup-main';
 
 vi.mock('electron', () => ({
+ app: {
+ on: vi.fn(),
+ removeListener: vi.fn(),
+ setAsDefaultProtocolClient: vi.fn(),
+ },
  ipcMain: {
  handle: vi.fn(),
  removeHandler: vi.fn(),
  },
  protocol: {
  registerSchemesAsPrivileged: vi.fn(),
  },
+ shell: {
+ openExternal: vi.fn(),
+ },
 }));
 
 describe('setupMain', () => {
@@ -90,4 +99,76 @@ describe('setupMain', () => {
 
  expect(ipcMain.removeHandler).toHaveBeenCalledTimes(3);
  });
+
+ it('cleans up OAuth transport handlers when renderer origin is configured', () => {
+ const clerk = setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ clerk.cleanup();
+
+ expect(ipcMain.removeHandler).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ expect(ipcMain.removeHandler).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.open);
+ expect(app.removeListener).toHaveBeenCalledWith('open-url', expect.any(Function));
+ expect(app.removeListener).toHaveBeenCalledWith('second-instance', expect.any(Function));
+ });
+
+ it('sets up OAuth transport IPC handlers when renderer origin is configured', () => {
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ expect(ipcMain.handle).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl, expect.any(Function));
+ expect(ipcMain.handle).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.open, expect.any(Function));
+ expect(app.setAsDefaultProtocolClient).toHaveBeenCalledWith('my-app');
+ });
+
+ it('derives the OAuth callback URL from the renderer origin', () => {
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ const getRedirectUrlHandler = vi.mocked(ipcMain.handle).mock.calls.find(([channel]) => {
+ return channel === OAUTH_TRANSPORT_CHANNELS.getRedirectUrl;
+ })?.[1];
+
+ expect(getRedirectUrlHandler?.({} as Electron.IpcMainInvokeEvent)).toBe('my-app://renderer/');
+ });
+
+ it('opens OAuth URLs externally and resolves with the matching deep-link callback URL', async () => {
+ vi.mocked(shell.openExternal).mockResolvedValue(undefined);
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ 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 openUrlListener = vi.mocked(app.on).mock.calls.find(([event]) => event === 'open-url')?.[1] as (
+ event: Electron.Event,
+ url: string,
+ ) => void;
+
+ openUrlListener({ preventDefault: vi.fn() } as unknown as Electron.Event, 'my-app://renderer/?code=123');
+
+ await expect(openPromise).resolves.toEqual({ callbackUrl: 'my-app://renderer/?code=123' });
+ expect(shell.openExternal).toHaveBeenCalledWith('https://accounts.example.com/oauth');
+ });
 });

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

@@ -0,0 +1,130 @@
+import { app, ipcMain, shell } from 'electron';
+
+import { OAUTH_TRANSPORT_CHANNELS } from '../shared/ipc';
+import type { RendererSchemeOptions } from '../shared/types';
+
+const CALLBACK_TIMEOUT_MS = 3 * 60 * 1000;
+
+type PendingOAuthFlow = {
+ resolve: (value: { callbackUrl: string }) => void;
+ reject: (reason: Error) => void;
+ timeout: NodeJS.Timeout;
+};
+
+type OAuthTransportOptions = {
+ renderer: RendererSchemeOptions;
+};
+
+function buildRedirectUrl(options: OAuthTransportOptions): string {
+ return `${options.renderer.scheme}://${options.renderer.host}/`;
+}
+
+function isMatchingCallbackUrl(url: string, redirectUrl: string): boolean {
+ try {
+ const callback = new URL(url);
+ const expected = new URL(redirectUrl);
+
+ return (
+ callback.protocol === expected.protocol &&
+ callback.host === expected.host &&
+ callback.pathname === expected.pathname
+ );
+ } catch {
+ return false;
+ }
+}
+
+function assertExternalOAuthUrl(url: string): void {
+ const parsedUrl = new URL(url);
+
+ if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+ throw new TypeError(`Clerk: refusing to open unsupported OAuth URL protocol: ${parsedUrl.protocol}`);
+ }
+}
+
+export function setupOAuthTransportIpcHandlers(options: OAuthTransportOptions): () => void {
+ const redirectUrl = buildRedirectUrl(options);
+ let pendingOAuthFlow: PendingOAuthFlow | null = null;
+
+ const disposePendingOAuthFlow = (reason?: Error): void => {
+ if (!pendingOAuthFlow) {
+ return;
+ }
+
+ const pending = pendingOAuthFlow;
+ clearTimeout(pendingOAuthFlow.timeout);
+ pendingOAuthFlow = null;
+
+ if (reason) {
+ pending.reject(reason);
+ }
+ };
+
+ const handleCallbackUrl = (url: string): void => {
+ if (!pendingOAuthFlow || !isMatchingCallbackUrl(url, redirectUrl)) {
+ return;
+ }
+
+ const pending = pendingOAuthFlow;
+ disposePendingOAuthFlow();
+ pending.resolve({ callbackUrl: url });
+ };
+
+ const openUrlListener = (event: Electron.Event, url: string): void => {
+ if (!isMatchingCallbackUrl(url, redirectUrl)) {
+ return;
+ }
+
+ event.preventDefault();
+ handleCallbackUrl(url);
+ };
+
+ const secondInstanceListener = (_event: Electron.Event, argv: string[]): void => {
+ const callbackUrl = argv.find(url => isMatchingCallbackUrl(url, redirectUrl));
+
+ if (callbackUrl) {
+ handleCallbackUrl(callbackUrl);
+ }
+ };
+
+ app.setAsDefaultProtocolClient(options.renderer.scheme);
+ app.on('open-url', openUrlListener);
+ app.on('second-instance', secondInstanceListener);
+
+ ipcMain.handle(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl, () => {
+ return redirectUrl;
+ });
+
+ ipcMain.handle(OAUTH_TRANSPORT_CHANNELS.open, async (_event, url: string) => {
+ if (pendingOAuthFlow) {
+ throw new Error('Clerk: an OAuth flow is already pending.');
+ }
+
+ assertExternalOAuthUrl(url);
+
+ const callbackPromise = new Promise<{ callbackUrl: string }>((resolve, reject) => {
+ const timeout = setTimeout(() => {
+ disposePendingOAuthFlow();
+ reject(new Error('Clerk: OAuth callback timed out.'));
+ }, CALLBACK_TIMEOUT_MS);
+
+ pendingOAuthFlow = { resolve, reject, timeout };
+ });
+
+ try {
+ await shell.openExternal(url);
+ } catch (err) {
+ disposePendingOAuthFlow(err instanceof Error ? err : new Error(String(err)));
+ }
+
+ return callbackPromise;
+ });
+
+ return () => {
+ disposePendingOAuthFlow(new Error('Clerk: OAuth flow was cancelled.'));
+ app.removeListener('open-url', openUrlListener);
+ app.removeListener('second-instance', secondInstanceListener);
+ ipcMain.removeHandler(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ ipcMain.removeHandler(OAUTH_TRANSPORT_CHANNELS.open);
+ };
+}

packages/electron/src/main/setup-main.ts

@@ -2,6 +2,7 @@ import { protocol } from 'electron';
 
 import type { SetupMainOptions, SetupMainReturn } from '../shared/types';
 import { setupTokenCacheIpcHandlers } from './ipc-handlers';
+import { setupOAuthTransportIpcHandlers } from './oauth-transport';
 
 function assertValidRendererOriginConfig(renderer: NonNullable<SetupMainOptions['renderer']>): void {
  if (renderer.scheme.includes(':') || renderer.scheme.includes('/')) {
@@ -25,6 +26,7 @@ export function setupMain(options: SetupMainOptions): SetupMainReturn {
  }
 
  const cleanupTokenPersistence = setupTokenCacheIpcHandlers(options.storage);
+ let cleanupOAuthTransport: (() => void) | undefined;
 
  if (options.renderer) {
  assertValidRendererOriginConfig(options.renderer);
@@ -41,11 +43,16 @@ export function setupMain(options: SetupMainOptions): SetupMainReturn {
  },
  },
  ]);
+
+ cleanupOAuthTransport = setupOAuthTransportIpcHandlers({
+ renderer: options.renderer,
+ });
  }
 
  return {
  cleanup() {
  cleanupTokenPersistence();
+ cleanupOAuthTransport?.();
  },
  };
 }

packages/electron/src/preload/__tests__/index.test.ts

@@ -1,7 +1,7 @@
 import { contextBridge, ipcRenderer } from 'electron';
 import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-import { TOKEN_CACHE_CHANNELS } from '../../shared/ipc';
+import { OAUTH_TRANSPORT_CHANNELS, TOKEN_CACHE_CHANNELS } from '../../shared/ipc';
 import { setupPreload } from '../index';
 
 vi.mock('electron', () => ({
@@ -39,6 +39,10 @@ describe('setupPreload', () => {
  saveToken: expect.any(Function),
  clearToken: expect.any(Function),
  },
+ oauthTransport: {
+ getRedirectUrl: expect.any(Function),
+ open: expect.any(Function),
+ },
  });
  });
 
@@ -52,6 +56,10 @@ describe('setupPreload', () => {
  saveToken: expect.any(Function),
  clearToken: expect.any(Function),
  });
+ expect(window.__clerk_internal_electron?.oauthTransport).toEqual({
+ getRedirectUrl: expect.any(Function),
+ open: expect.any(Function),
+ });
  });
 
  it('forwards token cache calls over IPC', async () => {
@@ -68,4 +76,20 @@ describe('setupPreload', () => {
  expect(ipcRenderer.invoke).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.saveToken, 'token-key', 'jwt');
  expect(ipcRenderer.invoke).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.clearToken, 'token-key');
  });
+
+ it('forwards OAuth transport calls over IPC', async () => {
+ setupPreload();
+
+ const bridge = vi.mocked(contextBridge.exposeInMainWorld).mock
+ .calls[0][1] as typeof window.__clerk_internal_electron;
+
+ await bridge?.oauthTransport.getRedirectUrl();
+ await bridge?.oauthTransport.open('https://accounts.example.com/oauth');
+
+ expect(ipcRenderer.invoke).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ expect(ipcRenderer.invoke).toHaveBeenCalledWith(
+ OAUTH_TRANSPORT_CHANNELS.open,
+ 'https://accounts.example.com/oauth',
+ );
+ });
 });

packages/electron/src/preload/index.ts

@@ -1,18 +1,23 @@
 import { contextBridge, ipcRenderer } from 'electron';
 
-import { TOKEN_CACHE_CHANNELS } from '../shared/ipc';
-import type { TokenCache } from '../shared/types';
+import { OAUTH_TRANSPORT_CHANNELS, TOKEN_CACHE_CHANNELS } from '../shared/ipc';
+import type { OAuthTransport, TokenCache } from '../shared/types';
 
 export function setupPreload(): void {
  const tokenCache: TokenCache = {
  getToken: key => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.getToken, key),
  saveToken: (key, value) => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.saveToken, key, value),
  clearToken: key => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.clearToken, key),
  };
+ const oauthTransport: OAuthTransport = {
+ getRedirectUrl: () => ipcRenderer.invoke(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl),
+ open: url => ipcRenderer.invoke(OAUTH_TRANSPORT_CHANNELS.open, url),
+ };
+ const bridge = { tokenCache, oauthTransport };
 
  if (process.contextIsolated) {
- contextBridge.exposeInMainWorld('__clerk_internal_electron', { tokenCache });
+ contextBridge.exposeInMainWorld('__clerk_internal_electron', bridge);
  } else {
- window.__clerk_internal_electron = { tokenCache };
+ window.__clerk_internal_electron = bridge;
  }
 }

packages/electron/src/global.d.ts

@@ -1,4 +1,4 @@
-import type { TokenCache } from './shared/types';
+import type { OAuthTransport, TokenCache } from './shared/types';
 
 declare const PACKAGE_NAME: string;
 declare const PACKAGE_VERSION: string;
@@ -8,6 +8,7 @@ declare global {
  interface Window {
  __clerk_internal_electron?: {
  tokenCache: TokenCache;
+ oauthTransport: OAuthTransport;
  };
  }
 }

packages/electron/src/main/__tests__/setup-main.test.ts

@@ -1,17 +1,26 @@
-import { ipcMain, protocol } from 'electron';
+import { app, ipcMain, protocol, shell } from 'electron';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { OAUTH_TRANSPORT_CHANNELS } from '../../shared/ipc';
 import type { TokenStorage } from '../../shared/types';
 import { setupMain } from '../setup-main';
 
 vi.mock('electron', () => ({
+ app: {
+ on: vi.fn(),
+ removeListener: vi.fn(),
+ setAsDefaultProtocolClient: vi.fn(),
+ },
  ipcMain: {
  handle: vi.fn(),
  removeHandler: vi.fn(),
  },
  protocol: {
  registerSchemesAsPrivileged: vi.fn(),
  },
+ shell: {
+ openExternal: vi.fn(),
+ },
 }));
 
 describe('setupMain', () => {
@@ -90,4 +99,76 @@ describe('setupMain', () => {
 
  expect(ipcMain.removeHandler).toHaveBeenCalledTimes(3);
  });
+
+ it('cleans up OAuth transport handlers when renderer origin is configured', () => {
+ const clerk = setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ clerk.cleanup();
+
+ expect(ipcMain.removeHandler).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ expect(ipcMain.removeHandler).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.open);
+ expect(app.removeListener).toHaveBeenCalledWith('open-url', expect.any(Function));
+ expect(app.removeListener).toHaveBeenCalledWith('second-instance', expect.any(Function));
+ });
+
+ it('sets up OAuth transport IPC handlers when renderer origin is configured', () => {
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ expect(ipcMain.handle).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl, expect.any(Function));
+ expect(ipcMain.handle).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.open, expect.any(Function));
+ expect(app.setAsDefaultProtocolClient).toHaveBeenCalledWith('my-app');
+ });
+
+ it('derives the OAuth callback URL from the renderer origin', () => {
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ const getRedirectUrlHandler = vi.mocked(ipcMain.handle).mock.calls.find(([channel]) => {
+ return channel === OAUTH_TRANSPORT_CHANNELS.getRedirectUrl;
+ })?.[1];
+
+ expect(getRedirectUrlHandler?.({} as Electron.IpcMainInvokeEvent)).toBe('my-app://renderer/');
+ });
+
+ it('opens OAuth URLs externally and resolves with the matching deep-link callback URL', async () => {
+ vi.mocked(shell.openExternal).mockResolvedValue(undefined);
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ 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 openUrlListener = vi.mocked(app.on).mock.calls.find(([event]) => event === 'open-url')?.[1] as (
+ event: Electron.Event,
+ url: string,
+ ) => void;
+
+ openUrlListener({ preventDefault: vi.fn() } as unknown as Electron.Event, 'my-app://renderer/?code=123');
+
+ await expect(openPromise).resolves.toEqual({ callbackUrl: 'my-app://renderer/?code=123' });
+ expect(shell.openExternal).toHaveBeenCalledWith('https://accounts.example.com/oauth');
+ });
 });

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

@@ -0,0 +1,130 @@
+import { app, ipcMain, shell } from 'electron';
+
+import { OAUTH_TRANSPORT_CHANNELS } from '../shared/ipc';
+import type { RendererSchemeOptions } from '../shared/types';
+
+const CALLBACK_TIMEOUT_MS = 3 * 60 * 1000;
+
+type PendingOAuthFlow = {
+ resolve: (value: { callbackUrl: string }) => void;
+ reject: (reason: Error) => void;
+ timeout: NodeJS.Timeout;
+};
+
+type OAuthTransportOptions = {
+ renderer: RendererSchemeOptions;
+};
+
+function buildRedirectUrl(options: OAuthTransportOptions): string {
+ return `${options.renderer.scheme}://${options.renderer.host}/`;
+}
+
+function isMatchingCallbackUrl(url: string, redirectUrl: string): boolean {
+ try {
+ const callback = new URL(url);
+ const expected = new URL(redirectUrl);
+
+ return (
+ callback.protocol === expected.protocol &&
+ callback.host === expected.host &&
+ callback.pathname === expected.pathname
+ );
+ } catch {
+ return false;
+ }
+}
+
+function assertExternalOAuthUrl(url: string): void {
+ const parsedUrl = new URL(url);
+
+ if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+ throw new TypeError(`Clerk: refusing to open unsupported OAuth URL protocol: ${parsedUrl.protocol}`);
+ }
+}
+
+export function setupOAuthTransportIpcHandlers(options: OAuthTransportOptions): () => void {
+ const redirectUrl = buildRedirectUrl(options);
+ let pendingOAuthFlow: PendingOAuthFlow | null = null;
+
+ const disposePendingOAuthFlow = (reason?: Error): void => {
+ if (!pendingOAuthFlow) {
+ return;
+ }
+
+ const pending = pendingOAuthFlow;
+ clearTimeout(pendingOAuthFlow.timeout);
+ pendingOAuthFlow = null;
+
+ if (reason) {
+ pending.reject(reason);
+ }
+ };
+
+ const handleCallbackUrl = (url: string): void => {
+ if (!pendingOAuthFlow || !isMatchingCallbackUrl(url, redirectUrl)) {
+ return;
+ }
+
+ const pending = pendingOAuthFlow;
+ disposePendingOAuthFlow();
+ pending.resolve({ callbackUrl: url });
+ };
+
+ const openUrlListener = (event: Electron.Event, url: string): void => {
+ if (!isMatchingCallbackUrl(url, redirectUrl)) {
+ return;
+ }
+
+ event.preventDefault();
+ handleCallbackUrl(url);
+ };
+
+ const secondInstanceListener = (_event: Electron.Event, argv: string[]): void => {
+ const callbackUrl = argv.find(url => isMatchingCallbackUrl(url, redirectUrl));
+
+ if (callbackUrl) {
+ handleCallbackUrl(callbackUrl);
+ }
+ };
+
+ app.setAsDefaultProtocolClient(options.renderer.scheme);
+ app.on('open-url', openUrlListener);
+ app.on('second-instance', secondInstanceListener);
+
+ ipcMain.handle(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl, () => {
+ return redirectUrl;
+ });
+
+ ipcMain.handle(OAUTH_TRANSPORT_CHANNELS.open, async (_event, url: string) => {
+ if (pendingOAuthFlow) {
+ throw new Error('Clerk: an OAuth flow is already pending.');
+ }
+
+ assertExternalOAuthUrl(url);
+
+ const callbackPromise = new Promise<{ callbackUrl: string }>((resolve, reject) => {
+ const timeout = setTimeout(() => {
+ disposePendingOAuthFlow();
+ reject(new Error('Clerk: OAuth callback timed out.'));
+ }, CALLBACK_TIMEOUT_MS);
+
+ pendingOAuthFlow = { resolve, reject, timeout };
+ });
+
+ try {
+ await shell.openExternal(url);
+ } catch (err) {
+ disposePendingOAuthFlow(err instanceof Error ? err : new Error(String(err)));
+ }
+
+ return callbackPromise;
+ });
+
+ return () => {
+ disposePendingOAuthFlow(new Error('Clerk: OAuth flow was cancelled.'));
+ app.removeListener('open-url', openUrlListener);
+ app.removeListener('second-instance', secondInstanceListener);
+ ipcMain.removeHandler(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ ipcMain.removeHandler(OAUTH_TRANSPORT_CHANNELS.open);
+ };
+}

packages/electron/src/main/setup-main.ts

@@ -2,6 +2,7 @@ import { protocol } from 'electron';
 
 import type { SetupMainOptions, SetupMainReturn } from '../shared/types';
 import { setupTokenCacheIpcHandlers } from './ipc-handlers';
+import { setupOAuthTransportIpcHandlers } from './oauth-transport';
 
 function assertValidRendererOriginConfig(renderer: NonNullable<SetupMainOptions['renderer']>): void {
  if (renderer.scheme.includes(':') || renderer.scheme.includes('/')) {
@@ -25,6 +26,7 @@ export function setupMain(options: SetupMainOptions): SetupMainReturn {
  }
 
  const cleanupTokenPersistence = setupTokenCacheIpcHandlers(options.storage);
+ let cleanupOAuthTransport: (() => void) | undefined;
 
  if (options.renderer) {
  assertValidRendererOriginConfig(options.renderer);
@@ -41,11 +43,16 @@ export function setupMain(options: SetupMainOptions): SetupMainReturn {
  },
  },
  ]);
+
+ cleanupOAuthTransport = setupOAuthTransportIpcHandlers({
+ renderer: options.renderer,
+ });
  }
 
  return {
  cleanup() {
  cleanupTokenPersistence();
+ cleanupOAuthTransport?.();
  },
  };
 }

packages/electron/src/preload/__tests__/index.test.ts

@@ -1,7 +1,7 @@
 import { contextBridge, ipcRenderer } from 'electron';
 import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-import { TOKEN_CACHE_CHANNELS } from '../../shared/ipc';
+import { OAUTH_TRANSPORT_CHANNELS, TOKEN_CACHE_CHANNELS } from '../../shared/ipc';
 import { setupPreload } from '../index';
 
 vi.mock('electron', () => ({
@@ -39,6 +39,10 @@ describe('setupPreload', () => {
  saveToken: expect.any(Function),
  clearToken: expect.any(Function),
  },
+ oauthTransport: {
+ getRedirectUrl: expect.any(Function),
+ open: expect.any(Function),
+ },
  });
  });
 
@@ -52,6 +56,10 @@ describe('setupPreload', () => {
  saveToken: expect.any(Function),
  clearToken: expect.any(Function),
  });
+ expect(window.__clerk_internal_electron?.oauthTransport).toEqual({
+ getRedirectUrl: expect.any(Function),
+ open: expect.any(Function),
+ });
  });
 
  it('forwards token cache calls over IPC', async () => {
@@ -68,4 +76,20 @@ describe('setupPreload', () => {
  expect(ipcRenderer.invoke).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.saveToken, 'token-key', 'jwt');
  expect(ipcRenderer.invoke).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.clearToken, 'token-key');
  });
+
+ it('forwards OAuth transport calls over IPC', async () => {
+ setupPreload();
+
+ const bridge = vi.mocked(contextBridge.exposeInMainWorld).mock
+ .calls[0][1] as typeof window.__clerk_internal_electron;
+
+ await bridge?.oauthTransport.getRedirectUrl();
+ await bridge?.oauthTransport.open('https://accounts.example.com/oauth');
+
+ expect(ipcRenderer.invoke).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ expect(ipcRenderer.invoke).toHaveBeenCalledWith(
+ OAUTH_TRANSPORT_CHANNELS.open,
+ 'https://accounts.example.com/oauth',
+ );
+ });
 });

packages/electron/src/preload/index.ts

@@ -1,18 +1,23 @@
 import { contextBridge, ipcRenderer } from 'electron';
 
-import { TOKEN_CACHE_CHANNELS } from '../shared/ipc';
-import type { TokenCache } from '../shared/types';
+import { OAUTH_TRANSPORT_CHANNELS, TOKEN_CACHE_CHANNELS } from '../shared/ipc';
+import type { OAuthTransport, TokenCache } from '../shared/types';
 
 export function setupPreload(): void {
  const tokenCache: TokenCache = {
  getToken: key => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.getToken, key),
  saveToken: (key, value) => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.saveToken, key, value),
  clearToken: key => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.clearToken, key),
  };
+ const oauthTransport: OAuthTransport = {
+ getRedirectUrl: () => ipcRenderer.invoke(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl),
+ open: url => ipcRenderer.invoke(OAUTH_TRANSPORT_CHANNELS.open, url),
+ };
+ const bridge = { tokenCache, oauthTransport };
 
  if (process.contextIsolated) {
- contextBridge.exposeInMainWorld('__clerk_internal_electron', { tokenCache });
+ contextBridge.exposeInMainWorld('__clerk_internal_electron', bridge);
  } else {
- window.__clerk_internal_electron = { tokenCache };
+ window.__clerk_internal_electron = bridge;
  }
 }

packages/electron/src/global.d.ts

@@ -1,4 +1,4 @@
-import type { TokenCache } from './shared/types';
+import type { OAuthTransport, TokenCache } from './shared/types';
 
 declare const PACKAGE_NAME: string;
 declare const PACKAGE_VERSION: string;
@@ -8,6 +8,7 @@ declare global {
  interface Window {
  __clerk_internal_electron?: {
  tokenCache: TokenCache;
+ oauthTransport: OAuthTransport;
  };
  }
 }

packages/electron/src/main/__tests__/setup-main.test.ts

@@ -1,17 +1,26 @@
-import { ipcMain, protocol } from 'electron';
+import { app, ipcMain, protocol, shell } from 'electron';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { OAUTH_TRANSPORT_CHANNELS } from '../../shared/ipc';
 import type { TokenStorage } from '../../shared/types';
 import { setupMain } from '../setup-main';
 
 vi.mock('electron', () => ({
+ app: {
+ on: vi.fn(),
+ removeListener: vi.fn(),
+ setAsDefaultProtocolClient: vi.fn(),
+ },
  ipcMain: {
  handle: vi.fn(),
  removeHandler: vi.fn(),
  },
  protocol: {
  registerSchemesAsPrivileged: vi.fn(),
  },
+ shell: {
+ openExternal: vi.fn(),
+ },
 }));
 
 describe('setupMain', () => {
@@ -90,4 +99,76 @@ describe('setupMain', () => {
 
  expect(ipcMain.removeHandler).toHaveBeenCalledTimes(3);
  });
+
+ it('cleans up OAuth transport handlers when renderer origin is configured', () => {
+ const clerk = setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ clerk.cleanup();
+
+ expect(ipcMain.removeHandler).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ expect(ipcMain.removeHandler).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.open);
+ expect(app.removeListener).toHaveBeenCalledWith('open-url', expect.any(Function));
+ expect(app.removeListener).toHaveBeenCalledWith('second-instance', expect.any(Function));
+ });
+
+ it('sets up OAuth transport IPC handlers when renderer origin is configured', () => {
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ expect(ipcMain.handle).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl, expect.any(Function));
+ expect(ipcMain.handle).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.open, expect.any(Function));
+ expect(app.setAsDefaultProtocolClient).toHaveBeenCalledWith('my-app');
+ });
+
+ it('derives the OAuth callback URL from the renderer origin', () => {
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ const getRedirectUrlHandler = vi.mocked(ipcMain.handle).mock.calls.find(([channel]) => {
+ return channel === OAUTH_TRANSPORT_CHANNELS.getRedirectUrl;
+ })?.[1];
+
+ expect(getRedirectUrlHandler?.({} as Electron.IpcMainInvokeEvent)).toBe('my-app://renderer/');
+ });
+
+ it('opens OAuth URLs externally and resolves with the matching deep-link callback URL', async () => {
+ vi.mocked(shell.openExternal).mockResolvedValue(undefined);
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ 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 openUrlListener = vi.mocked(app.on).mock.calls.find(([event]) => event === 'open-url')?.[1] as (
+ event: Electron.Event,
+ url: string,
+ ) => void;
+
+ openUrlListener({ preventDefault: vi.fn() } as unknown as Electron.Event, 'my-app://renderer/?code=123');
+
+ await expect(openPromise).resolves.toEqual({ callbackUrl: 'my-app://renderer/?code=123' });
+ expect(shell.openExternal).toHaveBeenCalledWith('https://accounts.example.com/oauth');
+ });
 });

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

@@ -0,0 +1,130 @@
+import { app, ipcMain, shell } from 'electron';
+
+import { OAUTH_TRANSPORT_CHANNELS } from '../shared/ipc';
+import type { RendererSchemeOptions } from '../shared/types';
+
+const CALLBACK_TIMEOUT_MS = 3 * 60 * 1000;
+
+type PendingOAuthFlow = {
+ resolve: (value: { callbackUrl: string }) => void;
+ reject: (reason: Error) => void;
+ timeout: NodeJS.Timeout;
+};
+
+type OAuthTransportOptions = {
+ renderer: RendererSchemeOptions;
+};
+
+function buildRedirectUrl(options: OAuthTransportOptions): string {
+ return `${options.renderer.scheme}://${options.renderer.host}/`;
+}
+
+function isMatchingCallbackUrl(url: string, redirectUrl: string): boolean {
+ try {
+ const callback = new URL(url);
+ const expected = new URL(redirectUrl);
+
+ return (
+ callback.protocol === expected.protocol &&
+ callback.host === expected.host &&
+ callback.pathname === expected.pathname
+ );
+ } catch {
+ return false;
+ }
+}
+
+function assertExternalOAuthUrl(url: string): void {
+ const parsedUrl = new URL(url);
+
+ if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+ throw new TypeError(`Clerk: refusing to open unsupported OAuth URL protocol: ${parsedUrl.protocol}`);
+ }
+}
+
+export function setupOAuthTransportIpcHandlers(options: OAuthTransportOptions): () => void {
+ const redirectUrl = buildRedirectUrl(options);
+ let pendingOAuthFlow: PendingOAuthFlow | null = null;
+
+ const disposePendingOAuthFlow = (reason?: Error): void => {
+ if (!pendingOAuthFlow) {
+ return;
+ }
+
+ const pending = pendingOAuthFlow;
+ clearTimeout(pendingOAuthFlow.timeout);
+ pendingOAuthFlow = null;
+
+ if (reason) {
+ pending.reject(reason);
+ }
+ };
+
+ const handleCallbackUrl = (url: string): void => {
+ if (!pendingOAuthFlow || !isMatchingCallbackUrl(url, redirectUrl)) {
+ return;
+ }
+
+ const pending = pendingOAuthFlow;
+ disposePendingOAuthFlow();
+ pending.resolve({ callbackUrl: url });
+ };
+
+ const openUrlListener = (event: Electron.Event, url: string): void => {
+ if (!isMatchingCallbackUrl(url, redirectUrl)) {
+ return;
+ }
+
+ event.preventDefault();
+ handleCallbackUrl(url);
+ };
+
+ const secondInstanceListener = (_event: Electron.Event, argv: string[]): void => {
+ const callbackUrl = argv.find(url => isMatchingCallbackUrl(url, redirectUrl));
+
+ if (callbackUrl) {
+ handleCallbackUrl(callbackUrl);
+ }
+ };
+
+ app.setAsDefaultProtocolClient(options.renderer.scheme);
+ app.on('open-url', openUrlListener);
+ app.on('second-instance', secondInstanceListener);
+
+ ipcMain.handle(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl, () => {
+ return redirectUrl;
+ });
+
+ ipcMain.handle(OAUTH_TRANSPORT_CHANNELS.open, async (_event, url: string) => {
+ if (pendingOAuthFlow) {
+ throw new Error('Clerk: an OAuth flow is already pending.');
+ }
+
+ assertExternalOAuthUrl(url);
+
+ const callbackPromise = new Promise<{ callbackUrl: string }>((resolve, reject) => {
+ const timeout = setTimeout(() => {
+ disposePendingOAuthFlow();
+ reject(new Error('Clerk: OAuth callback timed out.'));
+ }, CALLBACK_TIMEOUT_MS);
+
+ pendingOAuthFlow = { resolve, reject, timeout };
+ });
+
+ try {
+ await shell.openExternal(url);
+ } catch (err) {
+ disposePendingOAuthFlow(err instanceof Error ? err : new Error(String(err)));
+ }
+
+ return callbackPromise;
+ });
+
+ return () => {
+ disposePendingOAuthFlow(new Error('Clerk: OAuth flow was cancelled.'));
+ app.removeListener('open-url', openUrlListener);
+ app.removeListener('second-instance', secondInstanceListener);
+ ipcMain.removeHandler(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ ipcMain.removeHandler(OAUTH_TRANSPORT_CHANNELS.open);
+ };
+}

packages/electron/src/main/setup-main.ts

@@ -2,6 +2,7 @@ import { protocol } from 'electron';
 
 import type { SetupMainOptions, SetupMainReturn } from '../shared/types';
 import { setupTokenCacheIpcHandlers } from './ipc-handlers';
+import { setupOAuthTransportIpcHandlers } from './oauth-transport';
 
 function assertValidRendererOriginConfig(renderer: NonNullable<SetupMainOptions['renderer']>): void {
  if (renderer.scheme.includes(':') || renderer.scheme.includes('/')) {
@@ -25,6 +26,7 @@ export function setupMain(options: SetupMainOptions): SetupMainReturn {
  }
 
  const cleanupTokenPersistence = setupTokenCacheIpcHandlers(options.storage);
+ let cleanupOAuthTransport: (() => void) | undefined;
 
  if (options.renderer) {
  assertValidRendererOriginConfig(options.renderer);
@@ -41,11 +43,16 @@ export function setupMain(options: SetupMainOptions): SetupMainReturn {
  },
  },
  ]);
+
+ cleanupOAuthTransport = setupOAuthTransportIpcHandlers({
+ renderer: options.renderer,
+ });
  }
 
  return {
  cleanup() {
  cleanupTokenPersistence();
+ cleanupOAuthTransport?.();
  },
  };
 }

packages/electron/src/preload/__tests__/index.test.ts

@@ -1,7 +1,7 @@
 import { contextBridge, ipcRenderer } from 'electron';
 import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-import { TOKEN_CACHE_CHANNELS } from '../../shared/ipc';
+import { OAUTH_TRANSPORT_CHANNELS, TOKEN_CACHE_CHANNELS } from '../../shared/ipc';
 import { setupPreload } from '../index';
 
 vi.mock('electron', () => ({
@@ -39,6 +39,10 @@ describe('setupPreload', () => {
  saveToken: expect.any(Function),
  clearToken: expect.any(Function),
  },
+ oauthTransport: {
+ getRedirectUrl: expect.any(Function),
+ open: expect.any(Function),
+ },
  });
  });
 
@@ -52,6 +56,10 @@ describe('setupPreload', () => {
  saveToken: expect.any(Function),
  clearToken: expect.any(Function),
  });
+ expect(window.__clerk_internal_electron?.oauthTransport).toEqual({
+ getRedirectUrl: expect.any(Function),
+ open: expect.any(Function),
+ });
  });
 
  it('forwards token cache calls over IPC', async () => {
@@ -68,4 +76,20 @@ describe('setupPreload', () => {
  expect(ipcRenderer.invoke).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.saveToken, 'token-key', 'jwt');
  expect(ipcRenderer.invoke).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.clearToken, 'token-key');
  });
+
+ it('forwards OAuth transport calls over IPC', async () => {
+ setupPreload();
+
+ const bridge = vi.mocked(contextBridge.exposeInMainWorld).mock
+ .calls[0][1] as typeof window.__clerk_internal_electron;
+
+ await bridge?.oauthTransport.getRedirectUrl();
+ await bridge?.oauthTransport.open('https://accounts.example.com/oauth');
+
+ expect(ipcRenderer.invoke).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ expect(ipcRenderer.invoke).toHaveBeenCalledWith(
+ OAUTH_TRANSPORT_CHANNELS.open,
+ 'https://accounts.example.com/oauth',
+ );
+ });
 });

packages/electron/src/preload/index.ts

@@ -1,18 +1,23 @@
 import { contextBridge, ipcRenderer } from 'electron';
 
-import { TOKEN_CACHE_CHANNELS } from '../shared/ipc';
-import type { TokenCache } from '../shared/types';
+import { OAUTH_TRANSPORT_CHANNELS, TOKEN_CACHE_CHANNELS } from '../shared/ipc';
+import type { OAuthTransport, TokenCache } from '../shared/types';
 
 export function setupPreload(): void {
  const tokenCache: TokenCache = {
  getToken: key => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.getToken, key),
  saveToken: (key, value) => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.saveToken, key, value),
  clearToken: key => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.clearToken, key),
  };
+ const oauthTransport: OAuthTransport = {
+ getRedirectUrl: () => ipcRenderer.invoke(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl),
+ open: url => ipcRenderer.invoke(OAUTH_TRANSPORT_CHANNELS.open, url),
+ };
+ const bridge = { tokenCache, oauthTransport };
 
  if (process.contextIsolated) {
- contextBridge.exposeInMainWorld('__clerk_internal_electron', { tokenCache });
+ contextBridge.exposeInMainWorld('__clerk_internal_electron', bridge);
  } else {
- window.__clerk_internal_electron = { tokenCache };
+ window.__clerk_internal_electron = bridge;
  }
 }

packages/electron/src/global.d.ts

@@ -1,4 +1,4 @@
-import type { TokenCache } from './shared/types';
+import type { OAuthTransport, TokenCache } from './shared/types';
 
 declare const PACKAGE_NAME: string;
 declare const PACKAGE_VERSION: string;
@@ -8,6 +8,7 @@ declare global {
  interface Window {
  __clerk_internal_electron?: {
  tokenCache: TokenCache;
+ oauthTransport: OAuthTransport;
  };
  }
 }

packages/electron/src/main/__tests__/setup-main.test.ts

@@ -1,17 +1,26 @@
-import { ipcMain, protocol } from 'electron';
+import { app, ipcMain, protocol, shell } from 'electron';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { OAUTH_TRANSPORT_CHANNELS } from '../../shared/ipc';
 import type { TokenStorage } from '../../shared/types';
 import { setupMain } from '../setup-main';
 
 vi.mock('electron', () => ({
+ app: {
+ on: vi.fn(),
+ removeListener: vi.fn(),
+ setAsDefaultProtocolClient: vi.fn(),
+ },
  ipcMain: {
  handle: vi.fn(),
  removeHandler: vi.fn(),
  },
  protocol: {
  registerSchemesAsPrivileged: vi.fn(),
  },
+ shell: {
+ openExternal: vi.fn(),
+ },
 }));
 
 describe('setupMain', () => {
@@ -90,4 +99,76 @@ describe('setupMain', () => {
 
  expect(ipcMain.removeHandler).toHaveBeenCalledTimes(3);
  });
+
+ it('cleans up OAuth transport handlers when renderer origin is configured', () => {
+ const clerk = setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ clerk.cleanup();
+
+ expect(ipcMain.removeHandler).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ expect(ipcMain.removeHandler).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.open);
+ expect(app.removeListener).toHaveBeenCalledWith('open-url', expect.any(Function));
+ expect(app.removeListener).toHaveBeenCalledWith('second-instance', expect.any(Function));
+ });
+
+ it('sets up OAuth transport IPC handlers when renderer origin is configured', () => {
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ expect(ipcMain.handle).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl, expect.any(Function));
+ expect(ipcMain.handle).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.open, expect.any(Function));
+ expect(app.setAsDefaultProtocolClient).toHaveBeenCalledWith('my-app');
+ });
+
+ it('derives the OAuth callback URL from the renderer origin', () => {
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ const getRedirectUrlHandler = vi.mocked(ipcMain.handle).mock.calls.find(([channel]) => {
+ return channel === OAUTH_TRANSPORT_CHANNELS.getRedirectUrl;
+ })?.[1];
+
+ expect(getRedirectUrlHandler?.({} as Electron.IpcMainInvokeEvent)).toBe('my-app://renderer/');
+ });
+
+ it('opens OAuth URLs externally and resolves with the matching deep-link callback URL', async () => {
+ vi.mocked(shell.openExternal).mockResolvedValue(undefined);
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ 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 openUrlListener = vi.mocked(app.on).mock.calls.find(([event]) => event === 'open-url')?.[1] as (
+ event: Electron.Event,
+ url: string,
+ ) => void;
+
+ openUrlListener({ preventDefault: vi.fn() } as unknown as Electron.Event, 'my-app://renderer/?code=123');
+
+ await expect(openPromise).resolves.toEqual({ callbackUrl: 'my-app://renderer/?code=123' });
+ expect(shell.openExternal).toHaveBeenCalledWith('https://accounts.example.com/oauth');
+ });
 });

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

@@ -0,0 +1,130 @@
+import { app, ipcMain, shell } from 'electron';
+
+import { OAUTH_TRANSPORT_CHANNELS } from '../shared/ipc';
+import type { RendererSchemeOptions } from '../shared/types';
+
+const CALLBACK_TIMEOUT_MS = 3 * 60 * 1000;
+
+type PendingOAuthFlow = {
+ resolve: (value: { callbackUrl: string }) => void;
+ reject: (reason: Error) => void;
+ timeout: NodeJS.Timeout;
+};
+
+type OAuthTransportOptions = {
+ renderer: RendererSchemeOptions;
+};
+
+function buildRedirectUrl(options: OAuthTransportOptions): string {
+ return `${options.renderer.scheme}://${options.renderer.host}/`;
+}
+
+function isMatchingCallbackUrl(url: string, redirectUrl: string): boolean {
+ try {
+ const callback = new URL(url);
+ const expected = new URL(redirectUrl);
+
+ return (
+ callback.protocol === expected.protocol &&
+ callback.host === expected.host &&
+ callback.pathname === expected.pathname
+ );
+ } catch {
+ return false;
+ }
+}
+
+function assertExternalOAuthUrl(url: string): void {
+ const parsedUrl = new URL(url);
+
+ if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+ throw new TypeError(`Clerk: refusing to open unsupported OAuth URL protocol: ${parsedUrl.protocol}`);
+ }
+}
+
+export function setupOAuthTransportIpcHandlers(options: OAuthTransportOptions): () => void {
+ const redirectUrl = buildRedirectUrl(options);
+ let pendingOAuthFlow: PendingOAuthFlow | null = null;
+
+ const disposePendingOAuthFlow = (reason?: Error): void => {
+ if (!pendingOAuthFlow) {
+ return;
+ }
+
+ const pending = pendingOAuthFlow;
+ clearTimeout(pendingOAuthFlow.timeout);
+ pendingOAuthFlow = null;
+
+ if (reason) {
+ pending.reject(reason);
+ }
+ };
+
+ const handleCallbackUrl = (url: string): void => {
+ if (!pendingOAuthFlow || !isMatchingCallbackUrl(url, redirectUrl)) {
+ return;
+ }
+
+ const pending = pendingOAuthFlow;
+ disposePendingOAuthFlow();
+ pending.resolve({ callbackUrl: url });
+ };
+
+ const openUrlListener = (event: Electron.Event, url: string): void => {
+ if (!isMatchingCallbackUrl(url, redirectUrl)) {
+ return;
+ }
+
+ event.preventDefault();
+ handleCallbackUrl(url);
+ };
+
+ const secondInstanceListener = (_event: Electron.Event, argv: string[]): void => {
+ const callbackUrl = argv.find(url => isMatchingCallbackUrl(url, redirectUrl));
+
+ if (callbackUrl) {
+ handleCallbackUrl(callbackUrl);
+ }
+ };
+
+ app.setAsDefaultProtocolClient(options.renderer.scheme);
+ app.on('open-url', openUrlListener);
+ app.on('second-instance', secondInstanceListener);
+
+ ipcMain.handle(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl, () => {
+ return redirectUrl;
+ });
+
+ ipcMain.handle(OAUTH_TRANSPORT_CHANNELS.open, async (_event, url: string) => {
+ if (pendingOAuthFlow) {
+ throw new Error('Clerk: an OAuth flow is already pending.');
+ }
+
+ assertExternalOAuthUrl(url);
+
+ const callbackPromise = new Promise<{ callbackUrl: string }>((resolve, reject) => {
+ const timeout = setTimeout(() => {
+ disposePendingOAuthFlow();
+ reject(new Error('Clerk: OAuth callback timed out.'));
+ }, CALLBACK_TIMEOUT_MS);
+
+ pendingOAuthFlow = { resolve, reject, timeout };
+ });
+
+ try {
+ await shell.openExternal(url);
+ } catch (err) {
+ disposePendingOAuthFlow(err instanceof Error ? err : new Error(String(err)));
+ }
+
+ return callbackPromise;
+ });
+
+ return () => {
+ disposePendingOAuthFlow(new Error('Clerk: OAuth flow was cancelled.'));
+ app.removeListener('open-url', openUrlListener);
+ app.removeListener('second-instance', secondInstanceListener);
+ ipcMain.removeHandler(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ ipcMain.removeHandler(OAUTH_TRANSPORT_CHANNELS.open);
+ };
+}

packages/electron/src/main/setup-main.ts

@@ -2,6 +2,7 @@ import { protocol } from 'electron';
 
 import type { SetupMainOptions, SetupMainReturn } from '../shared/types';
 import { setupTokenCacheIpcHandlers } from './ipc-handlers';
+import { setupOAuthTransportIpcHandlers } from './oauth-transport';
 
 function assertValidRendererOriginConfig(renderer: NonNullable<SetupMainOptions['renderer']>): void {
  if (renderer.scheme.includes(':') || renderer.scheme.includes('/')) {
@@ -25,6 +26,7 @@ export function setupMain(options: SetupMainOptions): SetupMainReturn {
  }
 
  const cleanupTokenPersistence = setupTokenCacheIpcHandlers(options.storage);
+ let cleanupOAuthTransport: (() => void) | undefined;
 
  if (options.renderer) {
  assertValidRendererOriginConfig(options.renderer);
@@ -41,11 +43,16 @@ export function setupMain(options: SetupMainOptions): SetupMainReturn {
  },
  },
  ]);
+
+ cleanupOAuthTransport = setupOAuthTransportIpcHandlers({
+ renderer: options.renderer,
+ });
  }
 
  return {
  cleanup() {
  cleanupTokenPersistence();
+ cleanupOAuthTransport?.();
  },
  };
 }

packages/electron/src/preload/__tests__/index.test.ts

@@ -1,7 +1,7 @@
 import { contextBridge, ipcRenderer } from 'electron';
 import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-import { TOKEN_CACHE_CHANNELS } from '../../shared/ipc';
+import { OAUTH_TRANSPORT_CHANNELS, TOKEN_CACHE_CHANNELS } from '../../shared/ipc';
 import { setupPreload } from '../index';
 
 vi.mock('electron', () => ({
@@ -39,6 +39,10 @@ describe('setupPreload', () => {
  saveToken: expect.any(Function),
  clearToken: expect.any(Function),
  },
+ oauthTransport: {
+ getRedirectUrl: expect.any(Function),
+ open: expect.any(Function),
+ },
  });
  });
 
@@ -52,6 +56,10 @@ describe('setupPreload', () => {
  saveToken: expect.any(Function),
  clearToken: expect.any(Function),
  });
+ expect(window.__clerk_internal_electron?.oauthTransport).toEqual({
+ getRedirectUrl: expect.any(Function),
+ open: expect.any(Function),
+ });
  });
 
  it('forwards token cache calls over IPC', async () => {
@@ -68,4 +76,20 @@ describe('setupPreload', () => {
  expect(ipcRenderer.invoke).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.saveToken, 'token-key', 'jwt');
  expect(ipcRenderer.invoke).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.clearToken, 'token-key');
  });
+
+ it('forwards OAuth transport calls over IPC', async () => {
+ setupPreload();
+
+ const bridge = vi.mocked(contextBridge.exposeInMainWorld).mock
+ .calls[0][1] as typeof window.__clerk_internal_electron;
+
+ await bridge?.oauthTransport.getRedirectUrl();
+ await bridge?.oauthTransport.open('https://accounts.example.com/oauth');
+
+ expect(ipcRenderer.invoke).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ expect(ipcRenderer.invoke).toHaveBeenCalledWith(
+ OAUTH_TRANSPORT_CHANNELS.open,
+ 'https://accounts.example.com/oauth',
+ );
+ });
 });

packages/electron/src/preload/index.ts

@@ -1,18 +1,23 @@
 import { contextBridge, ipcRenderer } from 'electron';
 
-import { TOKEN_CACHE_CHANNELS } from '../shared/ipc';
-import type { TokenCache } from '../shared/types';
+import { OAUTH_TRANSPORT_CHANNELS, TOKEN_CACHE_CHANNELS } from '../shared/ipc';
+import type { OAuthTransport, TokenCache } from '../shared/types';
 
 export function setupPreload(): void {
  const tokenCache: TokenCache = {
  getToken: key => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.getToken, key),
  saveToken: (key, value) => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.saveToken, key, value),
  clearToken: key => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.clearToken, key),
  };
+ const oauthTransport: OAuthTransport = {
+ getRedirectUrl: () => ipcRenderer.invoke(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl),
+ open: url => ipcRenderer.invoke(OAUTH_TRANSPORT_CHANNELS.open, url),
+ };
+ const bridge = { tokenCache, oauthTransport };
 
  if (process.contextIsolated) {
- contextBridge.exposeInMainWorld('__clerk_internal_electron', { tokenCache });
+ contextBridge.exposeInMainWorld('__clerk_internal_electron', bridge);
  } else {
- window.__clerk_internal_electron = { tokenCache };
+ window.__clerk_internal_electron = bridge;
  }
 }

packages/electron/src/global.d.ts

@@ -1,4 +1,4 @@
-import type { TokenCache } from './shared/types';
+import type { OAuthTransport, TokenCache } from './shared/types';
 
 declare const PACKAGE_NAME: string;
 declare const PACKAGE_VERSION: string;
@@ -8,6 +8,7 @@ declare global {
  interface Window {
  __clerk_internal_electron?: {
  tokenCache: TokenCache;
+ oauthTransport: OAuthTransport;
  };
  }
 }

packages/electron/src/main/__tests__/setup-main.test.ts

@@ -1,17 +1,26 @@
-import { ipcMain, protocol } from 'electron';
+import { app, ipcMain, protocol, shell } from 'electron';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { OAUTH_TRANSPORT_CHANNELS } from '../../shared/ipc';
 import type { TokenStorage } from '../../shared/types';
 import { setupMain } from '../setup-main';
 
 vi.mock('electron', () => ({
+ app: {
+ on: vi.fn(),
+ removeListener: vi.fn(),
+ setAsDefaultProtocolClient: vi.fn(),
+ },
  ipcMain: {
  handle: vi.fn(),
  removeHandler: vi.fn(),
  },
  protocol: {
  registerSchemesAsPrivileged: vi.fn(),
  },
+ shell: {
+ openExternal: vi.fn(),
+ },
 }));
 
 describe('setupMain', () => {
@@ -90,4 +99,76 @@ describe('setupMain', () => {
 
  expect(ipcMain.removeHandler).toHaveBeenCalledTimes(3);
  });
+
+ it('cleans up OAuth transport handlers when renderer origin is configured', () => {
+ const clerk = setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ clerk.cleanup();
+
+ expect(ipcMain.removeHandler).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ expect(ipcMain.removeHandler).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.open);
+ expect(app.removeListener).toHaveBeenCalledWith('open-url', expect.any(Function));
+ expect(app.removeListener).toHaveBeenCalledWith('second-instance', expect.any(Function));
+ });
+
+ it('sets up OAuth transport IPC handlers when renderer origin is configured', () => {
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ expect(ipcMain.handle).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl, expect.any(Function));
+ expect(ipcMain.handle).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.open, expect.any(Function));
+ expect(app.setAsDefaultProtocolClient).toHaveBeenCalledWith('my-app');
+ });
+
+ it('derives the OAuth callback URL from the renderer origin', () => {
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ const getRedirectUrlHandler = vi.mocked(ipcMain.handle).mock.calls.find(([channel]) => {
+ return channel === OAUTH_TRANSPORT_CHANNELS.getRedirectUrl;
+ })?.[1];
+
+ expect(getRedirectUrlHandler?.({} as Electron.IpcMainInvokeEvent)).toBe('my-app://renderer/');
+ });
+
+ it('opens OAuth URLs externally and resolves with the matching deep-link callback URL', async () => {
+ vi.mocked(shell.openExternal).mockResolvedValue(undefined);
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ 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 openUrlListener = vi.mocked(app.on).mock.calls.find(([event]) => event === 'open-url')?.[1] as (
+ event: Electron.Event,
+ url: string,
+ ) => void;
+
+ openUrlListener({ preventDefault: vi.fn() } as unknown as Electron.Event, 'my-app://renderer/?code=123');
+
+ await expect(openPromise).resolves.toEqual({ callbackUrl: 'my-app://renderer/?code=123' });
+ expect(shell.openExternal).toHaveBeenCalledWith('https://accounts.example.com/oauth');
+ });
 });

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

@@ -0,0 +1,130 @@
+import { app, ipcMain, shell } from 'electron';
+
+import { OAUTH_TRANSPORT_CHANNELS } from '../shared/ipc';
+import type { RendererSchemeOptions } from '../shared/types';
+
+const CALLBACK_TIMEOUT_MS = 3 * 60 * 1000;
+
+type PendingOAuthFlow = {
+ resolve: (value: { callbackUrl: string }) => void;
+ reject: (reason: Error) => void;
+ timeout: NodeJS.Timeout;
+};
+
+type OAuthTransportOptions = {
+ renderer: RendererSchemeOptions;
+};
+
+function buildRedirectUrl(options: OAuthTransportOptions): string {
+ return `${options.renderer.scheme}://${options.renderer.host}/`;
+}
+
+function isMatchingCallbackUrl(url: string, redirectUrl: string): boolean {
+ try {
+ const callback = new URL(url);
+ const expected = new URL(redirectUrl);
+
+ return (
+ callback.protocol === expected.protocol &&
+ callback.host === expected.host &&
+ callback.pathname === expected.pathname
+ );
+ } catch {
+ return false;
+ }
+}
+
+function assertExternalOAuthUrl(url: string): void {
+ const parsedUrl = new URL(url);
+
+ if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+ throw new TypeError(`Clerk: refusing to open unsupported OAuth URL protocol: ${parsedUrl.protocol}`);
+ }
+}
+
+export function setupOAuthTransportIpcHandlers(options: OAuthTransportOptions): () => void {
+ const redirectUrl = buildRedirectUrl(options);
+ let pendingOAuthFlow: PendingOAuthFlow | null = null;
+
+ const disposePendingOAuthFlow = (reason?: Error): void => {
+ if (!pendingOAuthFlow) {
+ return;
+ }
+
+ const pending = pendingOAuthFlow;
+ clearTimeout(pendingOAuthFlow.timeout);
+ pendingOAuthFlow = null;
+
+ if (reason) {
+ pending.reject(reason);
+ }
+ };
+
+ const handleCallbackUrl = (url: string): void => {
+ if (!pendingOAuthFlow || !isMatchingCallbackUrl(url, redirectUrl)) {
+ return;
+ }
+
+ const pending = pendingOAuthFlow;
+ disposePendingOAuthFlow();
+ pending.resolve({ callbackUrl: url });
+ };
+
+ const openUrlListener = (event: Electron.Event, url: string): void => {
+ if (!isMatchingCallbackUrl(url, redirectUrl)) {
+ return;
+ }
+
+ event.preventDefault();
+ handleCallbackUrl(url);
+ };
+
+ const secondInstanceListener = (_event: Electron.Event, argv: string[]): void => {
+ const callbackUrl = argv.find(url => isMatchingCallbackUrl(url, redirectUrl));
+
+ if (callbackUrl) {
+ handleCallbackUrl(callbackUrl);
+ }
+ };
+
+ app.setAsDefaultProtocolClient(options.renderer.scheme);
+ app.on('open-url', openUrlListener);
+ app.on('second-instance', secondInstanceListener);
+
+ ipcMain.handle(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl, () => {
+ return redirectUrl;
+ });
+
+ ipcMain.handle(OAUTH_TRANSPORT_CHANNELS.open, async (_event, url: string) => {
+ if (pendingOAuthFlow) {
+ throw new Error('Clerk: an OAuth flow is already pending.');
+ }
+
+ assertExternalOAuthUrl(url);
+
+ const callbackPromise = new Promise<{ callbackUrl: string }>((resolve, reject) => {
+ const timeout = setTimeout(() => {
+ disposePendingOAuthFlow();
+ reject(new Error('Clerk: OAuth callback timed out.'));
+ }, CALLBACK_TIMEOUT_MS);
+
+ pendingOAuthFlow = { resolve, reject, timeout };
+ });
+
+ try {
+ await shell.openExternal(url);
+ } catch (err) {
+ disposePendingOAuthFlow(err instanceof Error ? err : new Error(String(err)));
+ }
+
+ return callbackPromise;
+ });
+
+ return () => {
+ disposePendingOAuthFlow(new Error('Clerk: OAuth flow was cancelled.'));
+ app.removeListener('open-url', openUrlListener);
+ app.removeListener('second-instance', secondInstanceListener);
+ ipcMain.removeHandler(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ ipcMain.removeHandler(OAUTH_TRANSPORT_CHANNELS.open);
+ };
+}

packages/electron/src/main/setup-main.ts

@@ -2,6 +2,7 @@ import { protocol } from 'electron';
 
 import type { SetupMainOptions, SetupMainReturn } from '../shared/types';
 import { setupTokenCacheIpcHandlers } from './ipc-handlers';
+import { setupOAuthTransportIpcHandlers } from './oauth-transport';
 
 function assertValidRendererOriginConfig(renderer: NonNullable<SetupMainOptions['renderer']>): void {
  if (renderer.scheme.includes(':') || renderer.scheme.includes('/')) {
@@ -25,6 +26,7 @@ export function setupMain(options: SetupMainOptions): SetupMainReturn {
  }
 
  const cleanupTokenPersistence = setupTokenCacheIpcHandlers(options.storage);
+ let cleanupOAuthTransport: (() => void) | undefined;
 
  if (options.renderer) {
  assertValidRendererOriginConfig(options.renderer);
@@ -41,11 +43,16 @@ export function setupMain(options: SetupMainOptions): SetupMainReturn {
  },
  },
  ]);
+
+ cleanupOAuthTransport = setupOAuthTransportIpcHandlers({
+ renderer: options.renderer,
+ });
  }
 
  return {
  cleanup() {
  cleanupTokenPersistence();
+ cleanupOAuthTransport?.();
  },
  };
 }

packages/electron/src/preload/__tests__/index.test.ts

@@ -1,7 +1,7 @@
 import { contextBridge, ipcRenderer } from 'electron';
 import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-import { TOKEN_CACHE_CHANNELS } from '../../shared/ipc';
+import { OAUTH_TRANSPORT_CHANNELS, TOKEN_CACHE_CHANNELS } from '../../shared/ipc';
 import { setupPreload } from '../index';
 
 vi.mock('electron', () => ({
@@ -39,6 +39,10 @@ describe('setupPreload', () => {
  saveToken: expect.any(Function),
  clearToken: expect.any(Function),
  },
+ oauthTransport: {
+ getRedirectUrl: expect.any(Function),
+ open: expect.any(Function),
+ },
  });
  });
 
@@ -52,6 +56,10 @@ describe('setupPreload', () => {
  saveToken: expect.any(Function),
  clearToken: expect.any(Function),
  });
+ expect(window.__clerk_internal_electron?.oauthTransport).toEqual({
+ getRedirectUrl: expect.any(Function),
+ open: expect.any(Function),
+ });
  });
 
  it('forwards token cache calls over IPC', async () => {
@@ -68,4 +76,20 @@ describe('setupPreload', () => {
  expect(ipcRenderer.invoke).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.saveToken, 'token-key', 'jwt');
  expect(ipcRenderer.invoke).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.clearToken, 'token-key');
  });
+
+ it('forwards OAuth transport calls over IPC', async () => {
+ setupPreload();
+
+ const bridge = vi.mocked(contextBridge.exposeInMainWorld).mock
+ .calls[0][1] as typeof window.__clerk_internal_electron;
+
+ await bridge?.oauthTransport.getRedirectUrl();
+ await bridge?.oauthTransport.open('https://accounts.example.com/oauth');
+
+ expect(ipcRenderer.invoke).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ expect(ipcRenderer.invoke).toHaveBeenCalledWith(
+ OAUTH_TRANSPORT_CHANNELS.open,
+ 'https://accounts.example.com/oauth',
+ );
+ });
 });

packages/electron/src/preload/index.ts

@@ -1,18 +1,23 @@
 import { contextBridge, ipcRenderer } from 'electron';
 
-import { TOKEN_CACHE_CHANNELS } from '../shared/ipc';
-import type { TokenCache } from '../shared/types';
+import { OAUTH_TRANSPORT_CHANNELS, TOKEN_CACHE_CHANNELS } from '../shared/ipc';
+import type { OAuthTransport, TokenCache } from '../shared/types';
 
 export function setupPreload(): void {
  const tokenCache: TokenCache = {
  getToken: key => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.getToken, key),
  saveToken: (key, value) => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.saveToken, key, value),
  clearToken: key => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.clearToken, key),
  };
+ const oauthTransport: OAuthTransport = {
+ getRedirectUrl: () => ipcRenderer.invoke(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl),
+ open: url => ipcRenderer.invoke(OAUTH_TRANSPORT_CHANNELS.open, url),
+ };
+ const bridge = { tokenCache, oauthTransport };
 
  if (process.contextIsolated) {
- contextBridge.exposeInMainWorld('__clerk_internal_electron', { tokenCache });
+ contextBridge.exposeInMainWorld('__clerk_internal_electron', bridge);
  } else {
- window.__clerk_internal_electron = { tokenCache };
+ window.__clerk_internal_electron = bridge;
  }
 }

packages/electron/src/global.d.ts

@@ -1,4 +1,4 @@
-import type { TokenCache } from './shared/types';
+import type { OAuthTransport, TokenCache } from './shared/types';
 
 declare const PACKAGE_NAME: string;
 declare const PACKAGE_VERSION: string;
@@ -8,6 +8,7 @@ declare global {
  interface Window {
  __clerk_internal_electron?: {
  tokenCache: TokenCache;
+ oauthTransport: OAuthTransport;
  };
  }
 }

packages/electron/src/main/__tests__/setup-main.test.ts

@@ -1,17 +1,26 @@
-import { ipcMain, protocol } from 'electron';
+import { app, ipcMain, protocol, shell } from 'electron';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { OAUTH_TRANSPORT_CHANNELS } from '../../shared/ipc';
 import type { TokenStorage } from '../../shared/types';
 import { setupMain } from '../setup-main';
 
 vi.mock('electron', () => ({
+ app: {
+ on: vi.fn(),
+ removeListener: vi.fn(),
+ setAsDefaultProtocolClient: vi.fn(),
+ },
  ipcMain: {
  handle: vi.fn(),
  removeHandler: vi.fn(),
  },
  protocol: {
  registerSchemesAsPrivileged: vi.fn(),
  },
+ shell: {
+ openExternal: vi.fn(),
+ },
 }));
 
 describe('setupMain', () => {
@@ -90,4 +99,76 @@ describe('setupMain', () => {
 
  expect(ipcMain.removeHandler).toHaveBeenCalledTimes(3);
  });
+
+ it('cleans up OAuth transport handlers when renderer origin is configured', () => {
+ const clerk = setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ clerk.cleanup();
+
+ expect(ipcMain.removeHandler).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ expect(ipcMain.removeHandler).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.open);
+ expect(app.removeListener).toHaveBeenCalledWith('open-url', expect.any(Function));
+ expect(app.removeListener).toHaveBeenCalledWith('second-instance', expect.any(Function));
+ });
+
+ it('sets up OAuth transport IPC handlers when renderer origin is configured', () => {
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ expect(ipcMain.handle).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl, expect.any(Function));
+ expect(ipcMain.handle).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.open, expect.any(Function));
+ expect(app.setAsDefaultProtocolClient).toHaveBeenCalledWith('my-app');
+ });
+
+ it('derives the OAuth callback URL from the renderer origin', () => {
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ const getRedirectUrlHandler = vi.mocked(ipcMain.handle).mock.calls.find(([channel]) => {
+ return channel === OAUTH_TRANSPORT_CHANNELS.getRedirectUrl;
+ })?.[1];
+
+ expect(getRedirectUrlHandler?.({} as Electron.IpcMainInvokeEvent)).toBe('my-app://renderer/');
+ });
+
+ it('opens OAuth URLs externally and resolves with the matching deep-link callback URL', async () => {
+ vi.mocked(shell.openExternal).mockResolvedValue(undefined);
+ setupMain({
+ storage,
+ renderer: {
+ host: 'renderer',
+ scheme: 'my-app',
+ },
+ });
+
+ 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 openUrlListener = vi.mocked(app.on).mock.calls.find(([event]) => event === 'open-url')?.[1] as (
+ event: Electron.Event,
+ url: string,
+ ) => void;
+
+ openUrlListener({ preventDefault: vi.fn() } as unknown as Electron.Event, 'my-app://renderer/?code=123');
+
+ await expect(openPromise).resolves.toEqual({ callbackUrl: 'my-app://renderer/?code=123' });
+ expect(shell.openExternal).toHaveBeenCalledWith('https://accounts.example.com/oauth');
+ });
 });

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

@@ -0,0 +1,130 @@
+import { app, ipcMain, shell } from 'electron';
+
+import { OAUTH_TRANSPORT_CHANNELS } from '../shared/ipc';
+import type { RendererSchemeOptions } from '../shared/types';
+
+const CALLBACK_TIMEOUT_MS = 3 * 60 * 1000;
+
+type PendingOAuthFlow = {
+ resolve: (value: { callbackUrl: string }) => void;
+ reject: (reason: Error) => void;
+ timeout: NodeJS.Timeout;
+};
+
+type OAuthTransportOptions = {
+ renderer: RendererSchemeOptions;
+};
+
+function buildRedirectUrl(options: OAuthTransportOptions): string {
+ return `${options.renderer.scheme}://${options.renderer.host}/`;
+}
+
+function isMatchingCallbackUrl(url: string, redirectUrl: string): boolean {
+ try {
+ const callback = new URL(url);
+ const expected = new URL(redirectUrl);
+
+ return (
+ callback.protocol === expected.protocol &&
+ callback.host === expected.host &&
+ callback.pathname === expected.pathname
+ );
+ } catch {
+ return false;
+ }
+}
+
+function assertExternalOAuthUrl(url: string): void {
+ const parsedUrl = new URL(url);
+
+ if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+ throw new TypeError(`Clerk: refusing to open unsupported OAuth URL protocol: ${parsedUrl.protocol}`);
+ }
+}
+
+export function setupOAuthTransportIpcHandlers(options: OAuthTransportOptions): () => void {
+ const redirectUrl = buildRedirectUrl(options);
+ let pendingOAuthFlow: PendingOAuthFlow | null = null;
+
+ const disposePendingOAuthFlow = (reason?: Error): void => {
+ if (!pendingOAuthFlow) {
+ return;
+ }
+
+ const pending = pendingOAuthFlow;
+ clearTimeout(pendingOAuthFlow.timeout);
+ pendingOAuthFlow = null;
+
+ if (reason) {
+ pending.reject(reason);
+ }
+ };
+
+ const handleCallbackUrl = (url: string): void => {
+ if (!pendingOAuthFlow || !isMatchingCallbackUrl(url, redirectUrl)) {
+ return;
+ }
+
+ const pending = pendingOAuthFlow;
+ disposePendingOAuthFlow();
+ pending.resolve({ callbackUrl: url });
+ };
+
+ const openUrlListener = (event: Electron.Event, url: string): void => {
+ if (!isMatchingCallbackUrl(url, redirectUrl)) {
+ return;
+ }
+
+ event.preventDefault();
+ handleCallbackUrl(url);
+ };
+
+ const secondInstanceListener = (_event: Electron.Event, argv: string[]): void => {
+ const callbackUrl = argv.find(url => isMatchingCallbackUrl(url, redirectUrl));
+
+ if (callbackUrl) {
+ handleCallbackUrl(callbackUrl);
+ }
+ };
+
+ app.setAsDefaultProtocolClient(options.renderer.scheme);
+ app.on('open-url', openUrlListener);
+ app.on('second-instance', secondInstanceListener);
+
+ ipcMain.handle(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl, () => {
+ return redirectUrl;
+ });
+
+ ipcMain.handle(OAUTH_TRANSPORT_CHANNELS.open, async (_event, url: string) => {
+ if (pendingOAuthFlow) {
+ throw new Error('Clerk: an OAuth flow is already pending.');
+ }
+
+ assertExternalOAuthUrl(url);
+
+ const callbackPromise = new Promise<{ callbackUrl: string }>((resolve, reject) => {
+ const timeout = setTimeout(() => {
+ disposePendingOAuthFlow();
+ reject(new Error('Clerk: OAuth callback timed out.'));
+ }, CALLBACK_TIMEOUT_MS);
+
+ pendingOAuthFlow = { resolve, reject, timeout };
+ });
+
+ try {
+ await shell.openExternal(url);
+ } catch (err) {
+ disposePendingOAuthFlow(err instanceof Error ? err : new Error(String(err)));
+ }
+
+ return callbackPromise;
+ });
+
+ return () => {
+ disposePendingOAuthFlow(new Error('Clerk: OAuth flow was cancelled.'));
+ app.removeListener('open-url', openUrlListener);
+ app.removeListener('second-instance', secondInstanceListener);
+ ipcMain.removeHandler(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ ipcMain.removeHandler(OAUTH_TRANSPORT_CHANNELS.open);
+ };
+}

packages/electron/src/main/setup-main.ts

@@ -2,6 +2,7 @@ import { protocol } from 'electron';
 
 import type { SetupMainOptions, SetupMainReturn } from '../shared/types';
 import { setupTokenCacheIpcHandlers } from './ipc-handlers';
+import { setupOAuthTransportIpcHandlers } from './oauth-transport';
 
 function assertValidRendererOriginConfig(renderer: NonNullable<SetupMainOptions['renderer']>): void {
  if (renderer.scheme.includes(':') || renderer.scheme.includes('/')) {
@@ -25,6 +26,7 @@ export function setupMain(options: SetupMainOptions): SetupMainReturn {
  }
 
  const cleanupTokenPersistence = setupTokenCacheIpcHandlers(options.storage);
+ let cleanupOAuthTransport: (() => void) | undefined;
 
  if (options.renderer) {
  assertValidRendererOriginConfig(options.renderer);
@@ -41,11 +43,16 @@ export function setupMain(options: SetupMainOptions): SetupMainReturn {
  },
  },
  ]);
+
+ cleanupOAuthTransport = setupOAuthTransportIpcHandlers({
+ renderer: options.renderer,
+ });
  }
 
  return {
  cleanup() {
  cleanupTokenPersistence();
+ cleanupOAuthTransport?.();
  },
  };
 }

packages/electron/src/preload/__tests__/index.test.ts

@@ -1,7 +1,7 @@
 import { contextBridge, ipcRenderer } from 'electron';
 import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-import { TOKEN_CACHE_CHANNELS } from '../../shared/ipc';
+import { OAUTH_TRANSPORT_CHANNELS, TOKEN_CACHE_CHANNELS } from '../../shared/ipc';
 import { setupPreload } from '../index';
 
 vi.mock('electron', () => ({
@@ -39,6 +39,10 @@ describe('setupPreload', () => {
  saveToken: expect.any(Function),
  clearToken: expect.any(Function),
  },
+ oauthTransport: {
+ getRedirectUrl: expect.any(Function),
+ open: expect.any(Function),
+ },
  });
  });
 
@@ -52,6 +56,10 @@ describe('setupPreload', () => {
  saveToken: expect.any(Function),
  clearToken: expect.any(Function),
  });
+ expect(window.__clerk_internal_electron?.oauthTransport).toEqual({
+ getRedirectUrl: expect.any(Function),
+ open: expect.any(Function),
+ });
  });
 
  it('forwards token cache calls over IPC', async () => {
@@ -68,4 +76,20 @@ describe('setupPreload', () => {
  expect(ipcRenderer.invoke).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.saveToken, 'token-key', 'jwt');
  expect(ipcRenderer.invoke).toHaveBeenCalledWith(TOKEN_CACHE_CHANNELS.clearToken, 'token-key');
  });
+
+ it('forwards OAuth transport calls over IPC', async () => {
+ setupPreload();
+
+ const bridge = vi.mocked(contextBridge.exposeInMainWorld).mock
+ .calls[0][1] as typeof window.__clerk_internal_electron;
+
+ await bridge?.oauthTransport.getRedirectUrl();
+ await bridge?.oauthTransport.open('https://accounts.example.com/oauth');
+
+ expect(ipcRenderer.invoke).toHaveBeenCalledWith(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl);
+ expect(ipcRenderer.invoke).toHaveBeenCalledWith(
+ OAUTH_TRANSPORT_CHANNELS.open,
+ 'https://accounts.example.com/oauth',
+ );
+ });
 });

packages/electron/src/preload/index.ts

@@ -1,18 +1,23 @@
 import { contextBridge, ipcRenderer } from 'electron';
 
-import { TOKEN_CACHE_CHANNELS } from '../shared/ipc';
-import type { TokenCache } from '../shared/types';
+import { OAUTH_TRANSPORT_CHANNELS, TOKEN_CACHE_CHANNELS } from '../shared/ipc';
+import type { OAuthTransport, TokenCache } from '../shared/types';
 
 export function setupPreload(): void {
  const tokenCache: TokenCache = {
  getToken: key => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.getToken, key),
  saveToken: (key, value) => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.saveToken, key, value),
  clearToken: key => ipcRenderer.invoke(TOKEN_CACHE_CHANNELS.clearToken, key),
  };
+ const oauthTransport: OAuthTransport = {
+ getRedirectUrl: () => ipcRenderer.invoke(OAUTH_TRANSPORT_CHANNELS.getRedirectUrl),
+ open: url => ipcRenderer.invoke(OAUTH_TRANSPORT_CHANNELS.open, url),
+ };
+ const bridge = { tokenCache, oauthTransport };
 
  if (process.contextIsolated) {
- contextBridge.exposeInMainWorld('__clerk_internal_electron', { tokenCache });
+ contextBridge.exposeInMainWorld('__clerk_internal_electron', bridge);
  } else {
- window.__clerk_internal_electron = { tokenCache };
+ window.__clerk_internal_electron = bridge;
  }
 }