chore: Add custom renderer origin support (#8816)

Author: wobsoriano

packages/electron/README.md

@@ -40,14 +40,40 @@ This package exposes entrypoints for Electron's distinct runtime contexts:
 
 ```ts
 // main.ts
+import { app, BrowserWindow, net, protocol } from 'electron';
 import { setupMain } from '@clerk/electron';
 import { storage } from '@clerk/electron/storage';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 setupMain({
   storage: storage(),
+  renderer: {
+    scheme: 'my-app',
+    host: 'renderer',
+  },
+});
+
+app.whenReady().then(() => {
+  protocol.handle('my-app', request => {
+    const url = new URL(request.url);
+    const file = url.pathname === '/' ? 'index.html' : url.pathname;
+
+    return net.fetch(pathToFileURL(join(__dirname, '../renderer', file)).toString());
+  });
+
+  const win = new BrowserWindow({
+    webPreferences: {
+      preload: join(__dirname, '../preload/index.js'),
+    },
+  });
+
+  win.loadURL('my-app://renderer/');
 });
 ```
 
+In `my-app://renderer/sign-in`, `my-app` is the scheme, `renderer` is the host, `my-app://renderer` is the origin, and `/sign-in` is the path. If your renderer uses path-based routing, serve every route from the same origin and fall back to your renderer entrypoint as needed.
+
 ```tsx
 // renderer.tsx
 import { ClerkProvider } from '@clerk/electron/react';

packages/electron/src/index.ts

@@ -1,2 +1 @@
 export { setupMain } from './main/setup-main';
-export type { TokenStorage } from './shared/types';

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

@@ -1,4 +1,4 @@
-import { ipcMain } from 'electron';
+import { ipcMain, protocol } from 'electron';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { TokenStorage } from '../../shared/types';
@@ -9,6 +9,9 @@ vi.mock('electron', () => ({
     handle: vi.fn(),
     removeHandler: vi.fn(),
   },
+  protocol: {
+    registerSchemesAsPrivileged: vi.fn(),
+  },
 }));
 
 describe('setupMain', () => {
@@ -33,6 +36,53 @@ describe('setupMain', () => {
     expect(ipcMain.handle).toHaveBeenCalledTimes(3);
   });
 
+  it('registers the configured renderer scheme as privileged before app ready', () => {
+    setupMain({
+      storage,
+      renderer: {
+        host: 'renderer',
+        scheme: 'my-app',
+      },
+    });
+
+    expect(protocol.registerSchemesAsPrivileged).toHaveBeenCalledWith([
+      {
+        scheme: 'my-app',
+        privileges: {
+          corsEnabled: true,
+          secure: true,
+          standard: true,
+          stream: true,
+          supportFetchAPI: true,
+        },
+      },
+    ]);
+  });
+
+  it('requires renderer.scheme to be a scheme name, not a URL', () => {
+    expect(() =>
+      setupMain({
+        storage,
+        renderer: {
+          host: 'renderer',
+          scheme: 'my-app://',
+        },
+      }),
+    ).toThrow('renderer.scheme must be a scheme name');
+  });
+
+  it('requires renderer.host to be a host name, not an origin', () => {
+    expect(() =>
+      setupMain({
+        storage,
+        renderer: {
+          host: 'my-app://renderer',
+          scheme: 'my-app',
+        },
+      }),
+    ).toThrow('renderer.host must be a host name');
+  });
+
   it('returns a cleanup function for registered handlers', () => {
     const clerk = setupMain({ storage });
 

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

@@ -1,6 +1,22 @@
+import { protocol } from 'electron';
+
 import type { SetupMainOptions, SetupMainReturn } from '../shared/types';
 import { setupTokenCacheIpcHandlers } from './ipc-handlers';
 
+function assertValidRendererOriginConfig(renderer: NonNullable<SetupMainOptions['renderer']>): void {
+  if (renderer.scheme.includes(':') || renderer.scheme.includes('/')) {
+    throw new Error(
+      'Clerk: renderer.scheme must be a scheme name like "my-app", not a URL or protocol like "my-app://".',
+    );
+  }
+
+  if (renderer.host.includes(':') || renderer.host.includes('/')) {
+    throw new Error(
+      'Clerk: renderer.host must be a host name like "renderer", not a URL or origin like "my-app://renderer".',
+    );
+  }
+}
+
 export function setupMain(options: SetupMainOptions): SetupMainReturn {
   if (!options.storage) {
     throw new Error(
@@ -10,6 +26,23 @@ export function setupMain(options: SetupMainOptions): SetupMainReturn {
 
   const cleanupTokenPersistence = setupTokenCacheIpcHandlers(options.storage);
 
+  if (options.renderer) {
+    assertValidRendererOriginConfig(options.renderer);
+
+    protocol.registerSchemesAsPrivileged([
+      {
+        scheme: options.renderer.scheme,
+        privileges: {
+          standard: true,
+          secure: true,
+          supportFetchAPI: true,
+          corsEnabled: true,
+          stream: true,
+        },
+      },
+    ]);
+  }
+
   return {
     cleanup() {
       cleanupTokenPersistence();

packages/electron/src/shared/types.ts

@@ -8,12 +8,27 @@ export type TokenStorage = {
 
 export type SetupMainOptions = {
   storage: TokenStorage;
+  /**
+   * Registers the custom scheme used to serve the Electron renderer from a stable origin.
+   */
+  renderer?: RendererSchemeOptions;
 };
 
 export type SetupMainReturn = {
   cleanup: () => void;
 };
 
+export type RendererSchemeOptions = {
+  /**
+   * Custom scheme used for the renderer origin.
+   */
+  scheme: string;
+  /**
+   * Custom host used for the renderer origin.
+   */
+  host: string;
+};
+
 export type TokenCache = {
   getToken: (key: string) => Promise<string | null>;
   saveToken: (key: string, value: string) => Promise<void>;