feat(electron): Introduce Electron SDK

.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

.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

.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

.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

.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

.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

.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