fix(electron,ui): Don't run passkey autofill as a modal prompt (#9500)

Author: jeremy-clerk

.changeset/rude-pianos-smoke.md

@@ -0,0 +1,6 @@
+---
+'@clerk/electron': patch
+'@clerk/ui': patch
+---
+
+Stop passkey autofill from opening a passkey prompt as soon as the sign-in form renders. Autofill now runs as a real background request when the window can service one (an `https` origin matching your RP ID), and is not attempted at all when it would route to the OS passkey dialog. Signing in with the explicit "Use passkey" action is unchanged.

packages/electron/README.md

@@ -212,6 +212,8 @@ Passkey support works in two modes, selected automatically per request:
 - **Renderer mode**: when your window loads content over `https://` from an origin that matches your passkey RP (Relying Party) ID, the renderer's built-in Chromium WebAuthn is used. Credentials are synced by the OS/browser ecosystem (Windows Hello works out of the box; Touch ID on macOS requires Electron ≥ 42 and [`app.configureWebAuthn`](https://www.electronjs.org/docs/latest/api/app#appconfigurewebauthnoptions-macos)).
 - **Native mode**: when your window loads a local bundle (e.g. `scheme://host`), WebAuthn's origin checks reject the request, so the ceremony is routed over IPC to the main process and serviced by the OS WebAuthn APIs (AuthenticationServices on macOS, `webauthn.dll` on Windows) via the optional [`@clerk/electron-passkeys`](https://github.com/clerk/javascript/tree/main/packages/electron-passkeys) native module.
 
+Passkey autofill relies on WebAuthn conditional mediation, which only the renderer can provide. In native mode passkeys are offered through the explicit "Use passkey" action instead; the sign-in form never opens a passkey prompt on its own.
+
 ### Setup
 
 Native mode requires the optional native module:

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

@@ -294,6 +294,60 @@ describe('createPasskeys', () => {
       expect(bridge.get).toHaveBeenCalled();
       expect(result.error).toBeNull();
     });
+
+    it('forwards conditional UI to the renderer path', async () => {
+      stubEnvironment({ bridge: makeBridge() });
+      const rendererResult = { publicKeyCredential: {} as never, error: null };
+      vi.mocked(webAuthnGetCredential).mockResolvedValue(rendererResult);
+
+      const result = await createPasskeys().get({ publicKeyOptions: requestOptions(), conditionalUI: true });
+
+      expect(webAuthnGetCredential).toHaveBeenCalledWith({
+        publicKeyOptions: expect.anything(),
+        conditionalUI: true,
+      });
+      expect(result).toBe(rendererResult);
+    });
+
+    it('aborts a conditional request instead of prompting through the native path', async () => {
+      const bridge = makeBridge();
+      stubEnvironment({ protocol: 'clerk:', hostname: 'app', bridge });
+
+      const result = await createPasskeys().get({ publicKeyOptions: requestOptions(), conditionalUI: true });
+
+      expect(bridge.get).not.toHaveBeenCalled();
+      expect(webAuthnGetCredential).not.toHaveBeenCalled();
+      expect(result.publicKeyCredential).toBeNull();
+      expect(result.error).toMatchObject({ code: 'passkey_operation_aborted' });
+    });
+
+    it('aborts a conditional request rather than reporting it as unsupported', async () => {
+      stubEnvironment({ protocol: 'clerk:', hostname: 'app' });
+
+      const result = await createPasskeys().get({ publicKeyOptions: requestOptions(), conditionalUI: true });
+
+      expect(result.error).toMatchObject({ code: 'passkey_operation_aborted' });
+    });
+
+    it('does not retry natively when a conditional renderer request fails', async () => {
+      const bridge = makeBridge();
+      stubEnvironment({ protocol: 'http:', hostname: 'localhost', bridge });
+      const rendererResult = {
+        publicKeyCredential: null,
+        error: Object.assign(new Error('The user agent does not support public key credentials.'), {
+          name: 'NotSupportedError',
+        }),
+      };
+      vi.mocked(webAuthnGetCredential).mockResolvedValue(rendererResult as never);
+
+      const result = await createPasskeys().get({
+        publicKeyOptions: requestOptionsForRpId('localhost'),
+        conditionalUI: true,
+      });
+
+      expect(bridge.get).not.toHaveBeenCalled();
+      expect(result).toBe(rendererResult);
+    });
   });
 
   describe('capability checks', () => {
@@ -308,6 +362,14 @@ describe('createPasskeys', () => {
       expect(createPasskeys().isSupported()).toBe(true);
     });
 
+    it('isSupported is false when every request would resolve to unsupported', () => {
+      stubEnvironment({ protocol: 'clerk:', hostname: 'app' });
+      expect(createPasskeys().isSupported()).toBe(false);
+
+      stubEnvironment({ protocol: 'clerk:', hostname: 'app', bridge: makeBridge() });
+      expect(createPasskeys().isSupported()).toBe(true);
+    });
+
     it('isAutoFillSupported is false in native mode', async () => {
       stubEnvironment({ bridge: makeBridge() });
 
@@ -316,6 +378,16 @@ describe('createPasskeys', () => {
       expect(isWebAuthnAutofillSupported).toHaveBeenCalledTimes(1);
     });
 
+    it('isAutoFillSupported is false when requests cannot take the renderer path', async () => {
+      stubEnvironment({ protocol: 'clerk:', hostname: 'app', bridge: makeBridge() });
+      await expect(createPasskeys().isAutoFillSupported()).resolves.toBe(false);
+
+      stubEnvironment({ bridge: makeBridge({ electronMajor: 39 }) });
+      await expect(createPasskeys().isAutoFillSupported()).resolves.toBe(false);
+
+      expect(isWebAuthnAutofillSupported).not.toHaveBeenCalled();
+    });
+
     it('isPlatformAuthenticatorSupported prefers native capabilities when available', async () => {
       const bridge = makeBridge();
       stubEnvironment({ bridge });

packages/electron/src/passkeys/__tests__/strategy.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
 import type { StrategyEnv } from '../renderer/strategy';
-import { decidePath, originSatisfiesRpId } from '../renderer/strategy';
+import { canUseRendererPath, decidePath, originSatisfiesRpId } from '../renderer/strategy';
 
 const RP_ID = 'example.com';
 
@@ -117,3 +117,45 @@ describe('decidePath', () => {
     });
   });
 });
+
+describe('canUseRendererPath', () => {
+  it('is false without renderer WebAuthn', () => {
+    expect(canUseRendererPath('auto', env({ hasWebAuthn: false }))).toBe(false);
+    expect(canUseRendererPath('renderer', env({ hasWebAuthn: false }))).toBe(false);
+  });
+
+  it('is false in native mode', () => {
+    expect(canUseRendererPath('native', env())).toBe(false);
+  });
+
+  it('is true in renderer mode regardless of origin', () => {
+    expect(canUseRendererPath('renderer', env({ protocol: 'app:', hostname: 'bundle' }))).toBe(true);
+  });
+
+  describe('auto mode', () => {
+    it.each([
+      ['https:', 'example.com', true],
+      ['http:', 'localhost', true],
+      ['http:', '127.0.0.1', true],
+      ['http:', '[::1]', true],
+      ['http:', 'example.com', false],
+      ['file:', '', false],
+      ['app:', 'bundle', false],
+      ['clerk:', 'app', false],
+    ])('%s//%s -> %s', (protocol, hostname, expected) => {
+      expect(canUseRendererPath('auto', env({ protocol, hostname }))).toBe(expected);
+    });
+
+    it('is true for an https origin that does not match any particular RP ID', () => {
+      expect(canUseRendererPath('auto', env({ hostname: 'other.com' }))).toBe(true);
+    });
+
+    it('is false on macOS before Electron 42, where the request routes native', () => {
+      expect(canUseRendererPath('auto', env({ electronMajor: 39 }))).toBe(false);
+    });
+
+    it('is true on macOS before Electron 42 when native is unavailable', () => {
+      expect(canUseRendererPath('auto', env({ electronMajor: 39, nativeAvailable: false }))).toBe(true);
+    });
+  });
+});

packages/electron/src/passkeys/index.ts

@@ -11,7 +11,7 @@ import { isWebAuthnAutofillSupported, isWebAuthnPlatformAuthenticatorSupported }
 
 import { getPasskeyBridge, nativeCreateCredential, nativeGetCredential } from './renderer/native-bridge';
 import type { PasskeyMode, StrategyEnv } from './renderer/strategy';
-import { decidePath } from './renderer/strategy';
+import { canUseRendererPath, decidePath } from './renderer/strategy';
 
 export type { PasskeyMode, PasskeyPath, StrategyEnv } from './renderer/strategy';
 
@@ -29,6 +29,7 @@ export type PasskeySupport = {
   ) => Promise<CredentialReturn<PublicKeyCredentialWithAuthenticatorAttestationResponse>>;
   get: (args: {
     publicKeyOptions: PublicKeyCredentialRequestOptionsWithoutExtensions;
+    conditionalUI?: boolean;
   }) => Promise<CredentialReturn<PublicKeyCredentialWithAuthenticatorAssertionResponse>>;
   isSupported: () => boolean;
   isAutoFillSupported: () => Promise<boolean>;
@@ -67,6 +68,14 @@ const unsupportedReturn = <T>(): CredentialReturn<T> =>
     ),
   }) as CredentialReturn<T>;
 
+const abortedReturn = <T>(): CredentialReturn<T> =>
+  ({
+    publicKeyCredential: null,
+    error: new ClerkWebAuthnError('Clerk: Conditional passkey requests require the renderer WebAuthn path.', {
+      code: 'passkey_operation_aborted',
+    }),
+  }) as CredentialReturn<T>;
+
 const shouldRetryNativeAfterRendererError = (error: unknown): boolean => {
   if (!error || typeof error !== 'object') {
     return false;
@@ -102,19 +111,30 @@ export function createPasskeys(options?: CreatePasskeysOptions): PasskeySupport
     return result;
   };
 
-  const get: PasskeySupport['get'] = async ({ publicKeyOptions }) => {
+  const get: PasskeySupport['get'] = async ({ publicKeyOptions, conditionalUI = false }) => {
     const env = getEnv();
     const path = decidePath(publicKeyOptions.rpId ?? '', mode, env);
 
+    // Conditional runs without user intent, don't fall through to opening a prompt.
+    if (conditionalUI && path !== 'renderer') {
+      return abortedReturn();
+    }
+
     if (path === 'unsupported') {
       return unsupportedReturn();
     }
     if (path === 'native') {
       return nativeGetCredential(publicKeyOptions);
     }
 
-    const result = await webAuthnGetCredential({ publicKeyOptions, conditionalUI: false });
-    if (result.error && shouldRetryNativeAfterRendererError(result.error) && mode === 'auto' && env.nativeAvailable) {
+    const result = await webAuthnGetCredential({ publicKeyOptions, conditionalUI });
+    if (
+      !conditionalUI &&
+      result.error &&
+      shouldRetryNativeAfterRendererError(result.error) &&
+      mode === 'auto' &&
+      env.nativeAvailable
+    ) {
       return nativeGetCredential(publicKeyOptions);
     }
     return result;
@@ -128,11 +148,11 @@ export function createPasskeys(options?: CreatePasskeysOptions): PasskeySupport
     if (mode === 'native') {
       return env.nativeAvailable;
     }
-    return env.hasWebAuthn || env.nativeAvailable;
+    return canUseRendererPath(mode, env) || env.nativeAvailable;
   };
 
-  const isAutoFillSupported: PasskeySupport['isAutoFillSupported'] = () => {
-    return mode === 'native' ? Promise.resolve(false) : isWebAuthnAutofillSupported();
+  const isAutoFillSupported: PasskeySupport['isAutoFillSupported'] = async () => {
+    return canUseRendererPath(mode, getEnv()) && isWebAuthnAutofillSupported();
   };
 
   const isPlatformAuthenticatorSupported: PasskeySupport['isPlatformAuthenticatorSupported'] = async () => {

packages/electron/src/passkeys/renderer/strategy.ts

@@ -31,6 +31,15 @@ export function originSatisfiesRpId(env: Pick<StrategyEnv, 'protocol' | 'hostnam
   return env.hostname === rpId || env.hostname.endsWith(`.${rpId}`);
 }
 
+/** Whether the origin could satisfy some RP ID, without knowing which one is requested. */
+function originCanSatisfyRpId(env: Pick<StrategyEnv, 'protocol' | 'hostname'>): boolean {
+  return env.protocol === 'https:' || (env.protocol === 'http:' && isLoopbackHostname(env.hostname));
+}
+
+function prefersNativeOnLegacyDarwin(env: StrategyEnv): boolean {
+  return env.platform === 'darwin' && env.electronMajor > 0 && env.electronMajor < 42 && env.nativeAvailable;
+}
+
 /**
  * Prefer Chromium WebAuthn when the page origin can satisfy the RP ID.
  * Local bundles and older macOS Electron builds use the native bridge when available.
@@ -44,11 +53,23 @@ export function decidePath(rpId: string, mode: PasskeyMode, env: StrategyEnv): P
   }
 
   if (env.hasWebAuthn && originSatisfiesRpId(env, rpId)) {
-    if (env.platform === 'darwin' && env.electronMajor > 0 && env.electronMajor < 42 && env.nativeAvailable) {
-      return 'native';
-    }
-    return 'renderer';
+    return prefersNativeOnLegacyDarwin(env) ? 'native' : 'renderer';
   }
 
   return env.nativeAvailable ? 'native' : 'unsupported';
 }
+
+/**
+ * Whether a request can take the renderer path, evaluated without RP ID.
+ * More loose than originSatisfiesRpId as we don't have an RP ID yet.
+ * This informs if Chromium *can* service a request rather than *will service*
+ */
+export function canUseRendererPath(mode: PasskeyMode, env: StrategyEnv): boolean {
+  if (!env.hasWebAuthn || mode === 'native') {
+    return false;
+  }
+  if (mode === 'renderer') {
+    return true;
+  }
+  return originCanSatisfyRpId(env) && !prefersNativeOnLegacyDarwin(env);
+}

packages/ui/src/components/SignIn/SignInStart.tsx

@@ -60,10 +60,12 @@ const useAutoFillPasskey = () => {
   const authenticateWithPasskey = useHandleAuthenticateWithPasskey(onSecondFactor, 'protect-check');
   const { userSettings } = useEnvironment();
   const { passkeySettings, attributes } = userSettings;
+  // @ts-expect-error - This is not a public API
+  const { __internal_isWebAuthnAutofillSupported } = useClerk();
 
   useEffect(() => {
     async function runAutofillPasskey() {
-      const _isSupported = await isWebAuthnAutofillSupported();
+      const _isSupported = await (__internal_isWebAuthnAutofillSupported ?? isWebAuthnAutofillSupported)();
       setIsSupported(_isSupported);
       if (!_isSupported) {
         return;
@@ -105,7 +107,9 @@ function SignInStartInternal(): JSX.Element {
   const { isWebAuthnAutofillSupported } = useAutoFillPasskey();
   const onSecondFactor = () => navigate('factor-two');
   const authenticateWithPasskey = useHandleAuthenticateWithPasskey(onSecondFactor, 'protect-check');
-  const isWebSupported = isWebAuthnSupported();
+  // @ts-expect-error - This is not a public API
+  const { __internal_isWebAuthnSupported } = clerk;
+  const isWebSupported = (__internal_isWebAuthnSupported ?? isWebAuthnSupported)();
 
   const onlyPhoneNumberInitialValueExists =
     !!ctx.initialValues?.phoneNumber && !(ctx.initialValues.emailAddress || ctx.initialValues.username);