@@ -57,7 +57,7 @@ jobs:
 
       - name: Smoke test (host-native targets only)
         if: matrix.settings.target == 'aarch64-apple-darwin' || matrix.settings.target == 'x86_64-pc-windows-msvc'
-        run: node -e "const m = require('./index.js'); console.log('isAvailable:', m.isAvailable(), 'capabilities:', JSON.stringify(m.capabilities()))"
+        run: node -e "const m = require('./index.js'); console.log('isAvailable:', m.isAvailable(), 'capabilities:', JSON.stringify(m.capabilities())); if (!m.isAvailable()) throw new Error('the loader did not find the freshly built native binary');"
 
       - uses: actions/upload-artifact@v4
         with:
 
@@ -37,6 +37,7 @@ objc2-authentication-services = { version = "0.3", default-features = false, fea
   "std",
   "ASFoundation",
   "ASAuthorization",
+  "ASAuthorizationError",
   "ASAuthorizationController",
   "ASAuthorizationCredential",
   "ASAuthorizationRequest",
@@ -55,6 +56,12 @@ objc2-authentication-services = { version = "0.3", default-features = false, fea
   "ASAuthorizationPublicKeyCredentialParameters",
 ] }
 
+# NSDictionary is only needed to build NSError fixtures in unit tests.
+[target.'cfg(target_os = "macos")'.dev-dependencies]
+objc2-foundation = { version = "0.3", default-features = false, features = [
+  "NSDictionary",
+] }
+
 [target.'cfg(target_os = "windows")'.dependencies]
 windows = { version = "0.61", features = [
   "Win32_Foundation",
 
@@ -5,7 +5,7 @@ Native passkey (WebAuthn) support for [`@clerk/electron`](https://github.com/cle
 > [!WARNING]
 > This package is under active development and is not yet ready for production use.
 
-This package is a napi-rs native module loaded in the Electron **main** process by `setupPasskeysMain()` from `@clerk/electron`. You should not need to call it directly.
+This package is a napi-rs native module loaded in the Electron **main** process by `createClerkBridge({ passkeys: true })` from `@clerk/electron`. You should not need to call it directly.
 
 | Platform         | Backend                                              | Authenticators                           |
 | ---------------- | ---------------------------------------------------- | ---------------------------------------- |
 
@@ -11,8 +11,10 @@ const PLATFORM_PACKAGES = {
 function loadNative() {
   const key = `${process.platform}-${process.arch}`;
 
-  // Local napi builds land next to this file.
-  const localBinary = join(__dirname, `electron-passkeys.${key}.node`);
+  // Local napi builds land next to this file; napi appends the ABI to the
+  // filename on Windows (e.g. electron-passkeys.win32-x64-msvc.node).
+  const localKey = process.platform === 'win32' ? `${key}-msvc` : key;
+  const localBinary = join(__dirname, `electron-passkeys.${localKey}.node`);
   if (existsSync(localBinary)) {
     return require(localBinary);
   }
 
@@ -15,7 +15,7 @@ use objc2::{
 use objc2_app_kit::{NSView, NSWindow};
 use objc2_authentication_services::{
     ASAuthorization, ASAuthorizationController, ASAuthorizationControllerDelegate,
-    ASAuthorizationControllerPresentationContextProviding,
+    ASAuthorizationControllerPresentationContextProviding, ASAuthorizationError, ASAuthorizationErrorDomain,
     ASAuthorizationPlatformPublicKeyCredentialDescriptor, ASAuthorizationPlatformPublicKeyCredentialProvider,
     ASAuthorizationPublicKeyCredentialParameters, ASAuthorizationRequest,
     ASAuthorizationSecurityKeyPublicKeyCredentialDescriptor,
@@ -170,20 +170,21 @@ impl CeremonyDelegate {
 }
 
 fn map_nserror(error: &NSError) -> (String, String) {
-    let domain = error.domain().to_string();
-    let code = error.code();
+    let domain = error.domain();
+    let code = ASAuthorizationError(error.code());
     let message = error.localizedDescription().to_string();
     let lowered = message.to_lowercase();
 
     let mapped = if lowered.contains("timed out") || lowered.contains("timeout") {
         "timeout"
-    } else if domain == "ASAuthorizationError" {
+    } else if &*domain == unsafe { ASAuthorizationErrorDomain } {
         match code {
-            // ASAuthorizationError.canceled
-            1001 => "cancelled",
+            ASAuthorizationError::Canceled => "cancelled",
             // ASAuthorizationError.failed also covers RP ID / associated-domain
             // mismatches, so use the localized description for classification.
-            1004 if lowered.contains("not associated") || lowered.contains("associated domain") => {
+            ASAuthorizationError::Failed
+                if lowered.contains("not associated") || lowered.contains("associated domain") =>
+            {
                 "invalid_rp"
             }
             _ => "unknown",
@@ -613,3 +614,52 @@ pub(crate) async fn create_credential(handle: usize, options: CreationOptions) -
 pub(crate) async fn get_credential(handle: usize, options: RequestOptions) -> String {
     run_ceremony(handle, move || build_get_requests(&options)).await
 }
+
+#[cfg(test)]
+mod tests {
+    use objc2::rc::Retained;
+    use objc2::runtime::AnyObject;
+    use objc2_authentication_services::{ASAuthorizationError, ASAuthorizationErrorDomain};
+    use objc2_foundation::{NSDictionary, NSError, NSLocalizedDescriptionKey, NSString};
+
+    use super::map_nserror;
+
+    fn authorization_error(code: ASAuthorizationError, description: Option<&str>) -> Retained<NSError> {
+        let user_info = description.map(|text| {
+            let value = NSString::from_str(text);
+            let object: &AnyObject = &value;
+            NSDictionary::from_slices(&[unsafe { NSLocalizedDescriptionKey }], &[object])
+        });
+        unsafe {
+            NSError::errorWithDomain_code_userInfo(ASAuthorizationErrorDomain, code.0, user_info.as_deref())
+        }
+    }
+
+    #[test]
+    fn maps_user_cancellation_to_cancelled() {
+        let error = authorization_error(ASAuthorizationError::Canceled, None);
+        assert_eq!(map_nserror(&error).0, "cancelled");
+    }
+
+    #[test]
+    fn maps_domain_association_failures_to_invalid_rp() {
+        let error = authorization_error(
+            ASAuthorizationError::Failed,
+            Some("Application with identifier ABC.com.example is not associated with domain example.com"),
+        );
+        assert_eq!(map_nserror(&error).0, "invalid_rp");
+    }
+
+    #[test]
+    fn maps_other_authorization_failures_to_unknown() {
+        let error = authorization_error(ASAuthorizationError::Unknown, None);
+        assert_eq!(map_nserror(&error).0, "unknown");
+    }
+
+    #[test]
+    fn maps_foreign_domains_to_unknown() {
+        let domain = NSString::from_str("com.example.SomeOtherDomain");
+        let error = unsafe { NSError::errorWithDomain_code_userInfo(&domain, 1001, None) };
+        assert_eq!(map_nserror(&error).0, "unknown");
+    }
+}
@@ -42,7 +42,7 @@ This package exposes entrypoints for Electron's distinct runtime contexts:
 ```ts
 // main.ts
 import { app, BrowserWindow, net, protocol } from 'electron';
-import { createClerkBridge, setupPasskeysMain } from '@clerk/electron';
+import { createClerkBridge } from '@clerk/electron';
 import { storage } from '@clerk/electron/storage';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -53,10 +53,9 @@ createClerkBridge({
     scheme: 'my-app',
     host: 'renderer',
   },
+  passkeys: true,
 });
 
-setupPasskeysMain();
-
 app.whenReady().then(() => {
   protocol.handle('my-app', request => {
     const url = new URL(request.url);
@@ -79,17 +78,22 @@ In `my-app://renderer/sign-in`, `my-app` is the scheme, `renderer` is the host,
 
 ```ts
 // preload.ts
-import { exposeClerkBridge, setupPasskeysPreload } from '@clerk/electron/preload';
+import { exposeClerkBridge } from '@clerk/electron/preload';
 
-exposeClerkBridge();
-setupPasskeysPreload();
+exposeClerkBridge({ passkeys: true });
 ```
 
 ```tsx
 // renderer.tsx
 import { ClerkProvider } from '@clerk/electron/react';
-
-<ClerkProvider publishableKey={import.meta.env.VITE_CLERK_PUBLISHABLE_KEY}>{/* ... */}</ClerkProvider>;
+import { passkeys } from '@clerk/electron/passkeys';
+
+<ClerkProvider
+  publishableKey={import.meta.env.VITE_CLERK_PUBLISHABLE_KEY}
+  passkeys={passkeys}
+>
+  {/* ... */}
+</ClerkProvider>;
 ```
 
 ## Passkeys
@@ -109,28 +113,41 @@ pnpm add @clerk/electron-passkeys
 
 ```ts
 // main process
-import { createClerkBridge, setupPasskeysMain } from '@clerk/electron';
+import { createClerkBridge } from '@clerk/electron';
 import { storage } from '@clerk/electron/storage';
 
-createClerkBridge({ storage: storage() });
-setupPasskeysMain();
+createClerkBridge({ storage: storage(), passkeys: true });
 ```
 
 ```ts
 // preload script
-import { exposeClerkBridge, setupPasskeysPreload } from '@clerk/electron/preload';
+import { exposeClerkBridge } from '@clerk/electron/preload';
 
-exposeClerkBridge();
-setupPasskeysPreload();
+exposeClerkBridge({ passkeys: true });
 ```
 
+```tsx
+// renderer process (React)
+import { ClerkProvider } from '@clerk/electron/react';
+import { passkeys } from '@clerk/electron/passkeys';
+
+<ClerkProvider
+  publishableKey={publishableKey}
+  passkeys={passkeys}
+>
+  {/* ... */}
+</ClerkProvider>;
+```
+
+Passkey code is only bundled and initialized when you pass the `passkeys` prop. If you manage the Clerk instance yourself instead of using `ClerkProvider`, wire it up before `clerk.load()`:
+
 ```ts
-// renderer process
+// renderer process (vanilla)
 import { Clerk } from '@clerk/clerk-js';
 import { createPasskeyProvider } from '@clerk/electron/passkeys';
 
 const clerk = new Clerk(publishableKey);
-createPasskeyProvider(clerk); // optionally { mode: 'auto' | 'renderer' | 'native' }
+createPasskeyProvider(clerk);
 await clerk.load();
 ```
 
 
@@ -1,3 +1,3 @@
 export { createClerkBridge } from './main/create-clerk-bridge';
 export { setupPasskeysMain } from './main/passkey-handlers';
-export type { ClerkBridge, CreateClerkBridgeOptions, TokenStorage } from './shared/types';
+export type { ClerkBridge, CreateClerkBridgeOptions, ExposeClerkBridgeOptions, TokenStorage } from './shared/types';
@@ -1,7 +1,7 @@
 import { app, ipcMain, protocol, shell } from 'electron';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
-import { OAUTH_TRANSPORT_CHANNELS } from '../../shared/ipc';
+import { OAUTH_TRANSPORT_CHANNELS, PASSKEY_CHANNELS } from '../../shared/ipc';
 import type { TokenStorage } from '../../shared/types';
 import { createClerkBridge } from '../create-clerk-bridge';
 
@@ -23,6 +23,15 @@ vi.mock('electron', () => ({
   },
 }));
 
+vi.mock('@clerk/electron-passkeys', () => ({
+  default: {
+    isAvailable: () => true,
+    capabilities: () => ({ platformAuthenticator: true, securityKeys: true }),
+    createCredential: vi.fn(),
+    getCredential: vi.fn(),
+  },
+}));
+
 describe('createClerkBridge', () => {
   const missingStorage = {} as Parameters<typeof createClerkBridge>[0];
   const storage: TokenStorage = {
@@ -100,6 +109,32 @@ describe('createClerkBridge', () => {
     expect(ipcMain.removeHandler).toHaveBeenCalledTimes(3);
   });
 
+  it('does not register passkey IPC handlers by default', () => {
+    createClerkBridge({ storage });
+
+    const channels = vi.mocked(ipcMain.handle).mock.calls.map(([channel]) => channel);
+    expect(channels).not.toContain(PASSKEY_CHANNELS.create);
+    expect(channels).not.toContain(PASSKEY_CHANNELS.get);
+    expect(channels).not.toContain(PASSKEY_CHANNELS.capabilities);
+  });
+
+  it('registers passkey IPC handlers when passkeys are enabled', () => {
+    createClerkBridge({ storage, passkeys: true });
+
+    const channels = vi.mocked(ipcMain.handle).mock.calls.map(([channel]) => channel);
+    expect(channels).toContain(PASSKEY_CHANNELS.create);
+    expect(channels).toContain(PASSKEY_CHANNELS.get);
+    expect(channels).toContain(PASSKEY_CHANNELS.capabilities);
+  });
+
+  it('cleans up passkey handlers together with the token handlers', () => {
+    const clerk = createClerkBridge({ storage, passkeys: true });
+
+    clerk.cleanup();
+
+    expect(ipcMain.removeHandler).toHaveBeenCalledTimes(6);
+  });
+
   it('cleans up OAuth transport handlers when renderer origin is configured', () => {
     const clerk = createClerkBridge({
       storage,
 
@@ -35,7 +35,8 @@ const getHandler = (channel: string): Handler => {
 };
 
 const windowHandle = Buffer.from([1, 2, 3, 4]);
-const event = { sender: {} } as IpcMainInvokeEvent;
+const mainFrame = {};
+const event = { sender: { mainFrame }, senderFrame: mainFrame } as unknown as IpcMainInvokeEvent;
 
 const creationOptions = { challenge: 'abc', rp: { id: 'example.com', name: 'Example' } };
 const registrationJSON = { id: 'cred', rawId: 'cred', type: 'public-key', response: {} };
@@ -94,6 +95,16 @@ describe('setupPasskeysMain', () => {
     expect(native.createCredential).not.toHaveBeenCalled();
   });
 
+  it('rejects requests that do not originate from the main frame', async () => {
+    setupPasskeysMain();
+
+    const subframeEvent = { sender: { mainFrame }, senderFrame: {} } as unknown as IpcMainInvokeEvent;
+    const result = await getHandler(PASSKEY_CHANNELS.create)(subframeEvent, creationOptions);
+
+    expect(result).toMatchObject({ ok: false, error: { code: 'unknown' } });
+    expect(native.createCredential).not.toHaveBeenCalled();
+  });
+
   it('returns an error when the request does not originate from a window', async () => {
     vi.mocked(BrowserWindow.fromWebContents).mockReturnValue(null);
     setupPasskeysMain();
 
@@ -3,6 +3,7 @@ import { protocol } from 'electron';
 import type { ClerkBridge, CreateClerkBridgeOptions } from '../shared/types';
 import { setupTokenCacheIpcHandlers } from './ipc-handlers';
 import { setupOAuthTransportIpcHandlers } from './oauth-transport';
+import { setupPasskeysMain } from './passkey-handlers';
 
 function assertValidRendererOriginConfig(renderer: NonNullable<CreateClerkBridgeOptions['renderer']>): void {
   if (renderer.scheme.includes(':') || renderer.scheme.includes('/')) {
@@ -34,6 +35,7 @@ export function createClerkBridge(options: CreateClerkBridgeOptions): ClerkBridg
 
   const cleanupTokenPersistence = setupTokenCacheIpcHandlers(options.storage);
   let cleanupOAuthTransport: (() => void) | undefined;
+  const passkeys = options.passkeys ? setupPasskeysMain() : null;
 
   if (options.renderer) {
     assertValidRendererOriginConfig(options.renderer);
@@ -60,6 +62,7 @@ export function createClerkBridge(options: CreateClerkBridgeOptions): ClerkBridg
     cleanup() {
       cleanupTokenPersistence();
       cleanupOAuthTransport?.();
+      passkeys?.cleanup();
     },
   };
 }