feat(electron): Introduce Electron SDK (#8786)

Co-authored-by: Jeremy Wright <jeremy@clerk.dev>

Author: wobsoriano

.changeset/electron-package-scaffold.md

@@ -0,0 +1,5 @@
+---
+'@clerk/electron': patch
+---
+
+Introduce `@clerk/electron` package.

.changeset/native-oauth-errors.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Display native OAuth callback errors in the UI.

.changeset/native-oauth-localizations.md

@@ -0,0 +1,7 @@
+---
+'@clerk/localizations': patch
+'@clerk/shared': patch
+'@clerk/ui': patch
+---
+
+Add localization support for OAuth access denied errors.

packages/clerk-js/src/utils/__tests__/authenticateWithTransport.test.ts

@@ -14,7 +14,10 @@ describe('_authenticateWithTransport', () => {
       getRedirectUrl: vi.fn().mockResolvedValue('myapp://sso-callback'),
       open: vi.fn().mockResolvedValue({ callbackUrl: 'myapp://sso-callback?rotating_token_nonce=abc' }),
     };
-    const resource = { reload: vi.fn().mockResolvedValue(undefined) } as any;
+    const resource = {
+      reload: vi.fn().mockResolvedValue(undefined),
+      create: vi.fn().mockResolvedValue(undefined),
+    } as any;
     const authenticateMethod = vi.fn(async (_params, navigate) => {
       navigate(new URL('https://provider.example/auth'));
     });
@@ -36,6 +39,7 @@ describe('_authenticateWithTransport', () => {
     expect(transport.open).toHaveBeenCalledWith(new URL('https://provider.example/auth'));
     expect(resource.reload).toHaveBeenCalledWith({ rotatingTokenNonce: 'abc' });
     expect(clerk.__internal_handleResourceCallback).toHaveBeenCalledWith(resource, callbackParams);
+    expect(resource.create).not.toHaveBeenCalled();
   });
 
   it('reloads without a nonce when the callback URL has no nonce', async () => {
@@ -60,6 +64,104 @@ describe('_authenticateWithTransport', () => {
     expect(clerk.__internal_handleResourceCallback).toHaveBeenCalledWith(resource, {});
   });
 
+  it('rejects with a localizable error without reloading when the native callback reports OAuth failure', async () => {
+    const clerk = makeClerk();
+    const transport = {
+      getRedirectUrl: vi.fn().mockResolvedValue('myapp://sso-callback'),
+      open: vi.fn().mockResolvedValue({
+        callbackUrl: 'myapp://sso-callback?__clerk_status=failed&__clerk_error_code=oauth_access_denied',
+      }),
+    };
+    const resource = {
+      reload: vi.fn().mockResolvedValue(undefined),
+      create: vi.fn().mockResolvedValue(undefined),
+    } as any;
+    const authenticateMethod = vi.fn(async (_params, navigate) => navigate('https://provider.example/auth'));
+
+    await expect(
+      _authenticateWithTransport({
+        clerk: clerk as any,
+        transport,
+        resource,
+        authenticateMethod,
+        params: {} as any,
+        callbackParams: {},
+      }),
+    ).rejects.toMatchObject({
+      code: 'oauth_access_denied',
+      clerkRuntimeError: true,
+    } satisfies Partial<ClerkRuntimeError>);
+
+    expect(resource.create).toHaveBeenCalledWith({});
+    expect(resource.reload).not.toHaveBeenCalled();
+    expect(clerk.__internal_handleResourceCallback).not.toHaveBeenCalled();
+  });
+
+  it('uses a generic error code for unknown native OAuth callback failure codes', async () => {
+    const clerk = makeClerk();
+    const transport = {
+      getRedirectUrl: vi.fn().mockResolvedValue('myapp://sso-callback'),
+      open: vi.fn().mockResolvedValue({
+        callbackUrl: 'myapp://sso-callback?__clerk_status=failed&__clerk_error_code=reverification_cancelled',
+      }),
+    };
+    const resource = {
+      reload: vi.fn().mockResolvedValue(undefined),
+      create: vi.fn().mockResolvedValue(undefined),
+    } as any;
+    const authenticateMethod = vi.fn(async (_params, navigate) => navigate('https://provider.example/auth'));
+
+    await expect(
+      _authenticateWithTransport({
+        clerk: clerk as any,
+        transport,
+        resource,
+        authenticateMethod,
+        params: {} as any,
+        callbackParams: {},
+      }),
+    ).rejects.toMatchObject({
+      code: 'oauth_callback_failed',
+      clerkRuntimeError: true,
+    } satisfies Partial<ClerkRuntimeError>);
+
+    expect(resource.create).toHaveBeenCalledWith({});
+    expect(resource.reload).not.toHaveBeenCalled();
+    expect(clerk.__internal_handleResourceCallback).not.toHaveBeenCalled();
+  });
+
+  it('still surfaces the OAuth failure when resetting the attempt fails', async () => {
+    const clerk = makeClerk();
+    const transport = {
+      getRedirectUrl: vi.fn().mockResolvedValue('myapp://sso-callback'),
+      open: vi.fn().mockResolvedValue({
+        callbackUrl: 'myapp://sso-callback?__clerk_status=failed&__clerk_error_code=oauth_access_denied',
+      }),
+    };
+    const resource = {
+      reload: vi.fn().mockResolvedValue(undefined),
+      create: vi.fn().mockRejectedValue(new Error('network down')),
+    } as any;
+    const authenticateMethod = vi.fn(async (_params, navigate) => navigate('https://provider.example/auth'));
+
+    await expect(
+      _authenticateWithTransport({
+        clerk: clerk as any,
+        transport,
+        resource,
+        authenticateMethod,
+        params: {} as any,
+        callbackParams: {},
+      }),
+    ).rejects.toMatchObject({
+      code: 'oauth_access_denied',
+      clerkRuntimeError: true,
+    } satisfies Partial<ClerkRuntimeError>);
+
+    expect(resource.create).toHaveBeenCalledWith({});
+    expect(clerk.__internal_handleResourceCallback).not.toHaveBeenCalled();
+  });
+
   it('propagates transport.open rejection and does not complete the callback', async () => {
     const clerk = makeClerk();
     const transport = {

packages/clerk-js/src/utils/authenticateWithTransport.ts

@@ -19,6 +19,38 @@ type ClerkWithResourceCallback = {
   ) => Promise<unknown>;
 };
 
+const NATIVE_OAUTH_FAILED_STATUS = 'failed';
+const NATIVE_OAUTH_ERROR_FALLBACK_CODE = 'oauth_callback_failed';
+const NATIVE_OAUTH_ERROR_MESSAGES: Record<string, string> = {
+  oauth_access_denied: 'You did not grant access to your account.',
+};
+
+function getNativeOAuthCallbackFailure(callbackUrl: string): { code: string; message: string } | null {
+  const searchParams = new URL(callbackUrl).searchParams;
+  const status = searchParams.get('__clerk_status');
+
+  if (status !== NATIVE_OAUTH_FAILED_STATUS) {
+    return null;
+  }
+
+  const unsafeCode = searchParams.get('__clerk_error_code') || NATIVE_OAUTH_ERROR_FALLBACK_CODE;
+  const code = NATIVE_OAUTH_ERROR_MESSAGES[unsafeCode] ? unsafeCode : NATIVE_OAUTH_ERROR_FALLBACK_CODE;
+
+  return {
+    code,
+    message: NATIVE_OAUTH_ERROR_MESSAGES[code] || 'OAuth callback failed.',
+  };
+}
+
+async function resetFailedAttempt(resource: SignInResource | SignUpResource): Promise<void> {
+  try {
+    // Both resources accept `{}` to reset the attempt, but their `create` param types differ.
+    await (resource.create as (params: Record<string, never>) => Promise<unknown>)({});
+  } catch {
+    // Best-effort: the OAuth failure is still thrown, so a failed reset just keeps the prior behavior.
+  }
+}
+
 export async function _authenticateWithTransport(opts: {
   clerk: ClerkWithResourceCallback;
   transport: OAuthTransport;
@@ -41,6 +73,15 @@ export async function _authenticateWithTransport(opts: {
   }
 
   const { callbackUrl } = await opts.transport.open(new URL(verificationUrl.toString()));
+  const failure = getNativeOAuthCallbackFailure(callbackUrl);
+
+  if (failure) {
+    // The failed verification persists on the client and would resurface on the next reload (the native
+    // flow never navigates away from the card), so reset the attempt before surfacing the error.
+    await resetFailedAttempt(opts.resource);
+    throw new ClerkRuntimeError(failure.message, { code: failure.code });
+  }
+
   const nonce = new URL(callbackUrl).searchParams.get('rotating_token_nonce');
 
   if (nonce) {

packages/electron-passkeys/.gitignore

@@ -0,0 +1,6 @@
+target/
+*.node
+artifacts/
+# napi-generated type defs for the raw native binding (the public surface is
+# the hand-written index.js/index.d.ts loader)
+native.d.ts