feat(clerk-js,ui): Add OAuth transport support for external auth flows

.changeset/oauth-transport.md

@@ -0,0 +1,8 @@
+---
+'@clerk/shared': minor
+'@clerk/clerk-js': minor
+'@clerk/react': minor
+'@clerk/ui': minor
+---
+
+Add internal OAuth transport support for native desktop SDK wrappers to run Clerk's prebuilt OAuth flows through a system browser.

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -158,6 +158,41 @@ describe('Clerk singleton', () => {
  });
  });
 
+ describe('__internal_oauthTransport', () => {
+ it('defaults to null with no getter access errors', () => {
+ const sut = new Clerk(productionPublishableKey);
+
+ expect(sut.__internal_hasOAuthTransport).toBe(false);
+ expect(sut.__internal_oauthTransport).toBeNull();
+ });
+
+ it('exposes the transport registered via options after load', async () => {
+ const transport = {
+ getRedirectUrl: () => 'myapp://sso-callback',
+ open: async (_url: URL) => ({ callbackUrl: 'myapp://sso-callback' }),
+ };
+ const sut = new Clerk(productionPublishableKey);
+
+ await sut.load({ __internal_oauthTransport: transport });
+
+ expect(sut.__internal_hasOAuthTransport).toBe(true);
+ expect(sut.__internal_oauthTransport).toBe(transport);
+ });
+ });
+
+ describe('__internal_handleResourceCallback', () => {
+ it('handleGoogleOneTapCallback delegates to __internal_handleResourceCallback', async () => {
+ const clerk = new Clerk(productionPublishableKey);
+ await clerk.load();
+ const spy = vi.spyOn(clerk, '__internal_handleResourceCallback').mockResolvedValue(undefined);
+ const signInLike = { identifier: 'x' } as any;
+
+ await clerk.handleGoogleOneTapCallback(signInLike, { signInUrl: '/sign-in' });
+
+ expect(spy).toHaveBeenCalledWith(signInLike, { signInUrl: '/sign-in' }, undefined);
+ });
+ });
+
  describe('.setActive', () => {
  describe('with `active` session status', () => {
  const mockSession = {
@@ -1205,6 +1240,104 @@ describe('Clerk singleton', () => {
  });
  });
 
+ it('uses __internal_navigateOnSetActive for completed sign in callbacks', async () => {
+ const sessionId = 'sess_123';
+ const mockSession = { id: sessionId, currentTask: null };
+ mockEnvironmentFetch.mockReturnValue(
+ Promise.resolve({
+ authConfig: {},
+ userSettings: mockUserSettings,
+ displayConfig: mockDisplayConfig,
+ isSingleSession: () => false,
+ isProduction: () => false,
+ isDevelopmentOrStaging: () => true,
+ onWindowLocationHost: () => false,
+ }),
+ );
+ mockClientFetch.mockReturnValue(
+ Promise.resolve({
+ signedInSessions: [],
+ signIn: new SignIn({
+ status: 'complete',
+ created_session_id: sessionId,
+ } as any as SignInJSON),
+ signUp: new SignUp(null),
+ }),
+ );
+
+ const internalNavigateOnSetActive = vi.fn(async ({ session, redirectUrl, decorateUrl }) => {
+ expect(session).toBe(mockSession);
+ expect(redirectUrl).toBe('http://test.host/after-sign-in');
+ expect(decorateUrl('/decorated')).toBe('/decorated');
+ });
+ const mockSetActive = vi.fn(async ({ navigate }) => navigate({ session: mockSession }));
+
+ const sut = new Clerk(productionPublishableKey);
+ await sut.load(mockedLoadOptions);
+ sut.setActive = mockSetActive as any;
+
+ await sut.handleRedirectCallback({
+ signInForceRedirectUrl: '/after-sign-in',
+ __internal_navigateOnSetActive: internalNavigateOnSetActive,
+ });
+
+ expect(mockSetActive).toHaveBeenCalledWith({
+ session: sessionId,
+ navigate: expect.any(Function),
+ });
+ expect(internalNavigateOnSetActive).toHaveBeenCalledTimes(1);
+ expect(mockNavigate).not.toHaveBeenCalled();
+ });
+
+ it('uses __internal_navigateOnSetActive for completed sign up callbacks', async () => {
+ const sessionId = 'sess_123';
+ const mockSession = { id: sessionId, currentTask: null };
+ mockEnvironmentFetch.mockReturnValue(
+ Promise.resolve({
+ authConfig: {},
+ userSettings: mockUserSettings,
+ displayConfig: mockDisplayConfig,
+ isSingleSession: () => false,
+ isProduction: () => false,
+ isDevelopmentOrStaging: () => true,
+ onWindowLocationHost: () => false,
+ }),
+ );
+ mockClientFetch.mockReturnValue(
+ Promise.resolve({
+ signedInSessions: [],
+ signIn: new SignIn(null),
+ signUp: new SignUp({
+ status: 'complete',
+ created_session_id: sessionId,
+ } as any as SignUpJSON),
+ }),
+ );
+
+ const internalNavigateOnSetActive = vi.fn(async ({ session, redirectUrl, decorateUrl }) => {
+ expect(session).toBe(mockSession);
+ expect(redirectUrl).toBe('http://test.host/after-sign-up');
+ expect(decorateUrl('/decorated')).toBe('/decorated');
+ });
+ const mockSetActive = vi.fn(async ({ navigate }) => navigate({ session: mockSession }));
+
+ const sut = new Clerk(productionPublishableKey);
+ await sut.load(mockedLoadOptions);
+ sut.setActive = mockSetActive as any;
+
+ await sut.handleRedirectCallback({
+ signUpForceRedirectUrl: '/after-sign-up',
+ __internal_navigateOnSetActive: internalNavigateOnSetActive,
+ });
+
+ expect(mockSetActive).toHaveBeenCalledWith({
+ session: sessionId,
+ navigate: expect.any(Function),
+ });
+ expect(internalNavigateOnSetActive).toHaveBeenCalledTimes(1);
+ expect(mockNavigate).not.toHaveBeenCalled();
+ });
+
  it('does not initiate the transfer flow when transferable: false is passed', async () => {
  mockEnvironmentFetch.mockReturnValue(
  Promise.resolve({

packages/clerk-js/src/core/clerk.ts

@@ -98,6 +98,7 @@ import type {
  LoadedClerk,
  NavigateOptions,
  OAuthApplicationNamespace,
+ OAuthTransport,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -269,6 +270,7 @@ export class Clerk implements ClerkInterface {
  #listeners: Array<(emission: Resources) => void> = [];
  #navigationListeners: Array<() => void> = [];
  #options: ClerkOptions = {};
+ #oauthTransport: OAuthTransport | null = null;
  #pageLifecycle: ReturnType<typeof createPageLifecycle> | null = null;
  #touchThrottledUntil = 0;
  #publicEventBus = createClerkEventBus();
@@ -295,6 +297,14 @@ export class Clerk implements ClerkInterface {
  : undefined;
  }
 
+ get __internal_hasOAuthTransport(): boolean {
+ return this.#oauthTransport !== null;
+ }
+
+ get __internal_oauthTransport(): OAuthTransport | null {
+ return this.#oauthTransport;
+ }
+
  public __internal_getCachedResources:
  | (() => Promise<{ client: ClientJSONSnapshot | null; environment: EnvironmentJSONSnapshot | null }>)
  | undefined;
@@ -529,6 +539,7 @@ export class Clerk implements ClerkInterface {
  }
 
  this.#options = this.#initOptions(options);
+ this.#oauthTransport = this.#options.__internal_oauthTransport ?? null;
 
  // Initialize ClerkUI if it was provided
  if (this.#options.ui?.ClerkUI) {
@@ -2285,7 +2296,7 @@ export class Clerk implements ClerkInterface {
  return null;
  };
 
- public handleGoogleOneTapCallback = async (
+ public __internal_handleResourceCallback = async (
  signInOrUp: SignInResource | SignUpResource,
  params: HandleOAuthCallbackParams,
  customNavigate?: (to: string) => Promise<unknown>,
@@ -2310,6 +2321,14 @@ export class Clerk implements ClerkInterface {
  });
  };
 
+ public handleGoogleOneTapCallback = async (
+ signInOrUp: SignInResource | SignUpResource,
+ params: HandleOAuthCallbackParams,
+ customNavigate?: (to: string) => Promise<unknown>,
+ ): Promise<unknown> => {
+ return this.__internal_handleResourceCallback(signInOrUp, params, customNavigate);
+ };
+
  private _handleRedirectCallback = async (
  params: HandleOAuthCallbackParams,
  {
@@ -2421,6 +2440,7 @@ export class Clerk implements ClerkInterface {
 
  const signInUrl = params.signInUrl || displayConfig.signInUrl;
  const signUpUrl = params.signUpUrl || displayConfig.signUpUrl;
+ const internalNavigateOnSetActive = params.__internal_navigateOnSetActive;
 
  const setActiveNavigate = async ({
  session,
@@ -2431,6 +2451,15 @@ export class Clerk implements ClerkInterface {
  baseUrl: string;
  redirectUrl: string;
  }) => {
+ if (internalNavigateOnSetActive) {
+ await internalNavigateOnSetActive({
+ session,
+ redirectUrl,
+ decorateUrl: url => this.buildUrlWithAuth(url),
+ });
+ return;
+ }
+
  if (!session.currentTask) {
  await this.navigate(redirectUrl);
  return;
@@ -2446,7 +2475,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: si.sessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signInUrl, redirectUrl: redirectUrls.getAfterSignInUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signInUrl,
+ redirectUrl: redirectUrls.getAfterSignInUrl(),
+ });
  },
  });
  }
@@ -2461,7 +2494,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: res.createdSessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignInUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignInUrl(),
+ });
  },
  });
  case 'needs_first_factor':
@@ -2512,7 +2549,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: res.createdSessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignUpUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignUpUrl(),
+ });
  },
  });
  case 'missing_requirements':
@@ -2526,7 +2567,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: su.sessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignUpUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignUpUrl(),
+ });
  },
  });
  }

packages/clerk-js/src/core/resources/SignIn.ts

@@ -83,6 +83,7 @@ import {
  _futureAuthenticateWithPopup,
  wrapWithPopupRoutes,
 } from '../../utils/authenticateWithPopup';
+import { _authenticateWithTransport } from '../../utils/authenticateWithTransport';
 import { CaptchaChallenge } from '../../utils/captcha/CaptchaChallenge';
 import { runAsyncResourceTask } from '../../utils/runAsyncResourceTask';
 import { loadZxcvbn } from '../../utils/zxcvbn';
@@ -379,6 +380,18 @@ export class SignIn extends BaseResource implements SignInResource {
  };
 
  public authenticateWithRedirect = async (params: AuthenticateWithRedirectParams): Promise<void> => {
+ const transport = SignIn.clerk.__internal_oauthTransport;
+ if (transport) {
+ return _authenticateWithTransport({
+ clerk: SignIn.clerk,
+ transport,
+ resource: this,
+ authenticateMethod: this.authenticateWithRedirectOrPopup,
+ params,
+ callbackParams: params.__internal_callbackParams ?? {},
+ });
+ }
+
  return this.authenticateWithRedirectOrPopup(params, windowNavigate);
  };
 

packages/clerk-js/src/core/resources/SignUp.ts

@@ -54,6 +54,7 @@ import {
  _futureAuthenticateWithPopup,
  wrapWithPopupRoutes,
 } from '../../utils/authenticateWithPopup';
+import { _authenticateWithTransport } from '../../utils/authenticateWithTransport';
 import { CaptchaChallenge } from '../../utils/captcha/CaptchaChallenge';
 import { normalizeUnsafeMetadata } from '../../utils/resourceParams';
 import { runAsyncResourceTask } from '../../utils/runAsyncResourceTask';
@@ -449,6 +450,18 @@ export class SignUp extends BaseResource implements SignUpResource {
  unsafeMetadata?: SignUpUnsafeMetadata;
  },
  ): Promise<void> => {
+ const transport = SignUp.clerk.__internal_oauthTransport;
+ if (transport) {
+ return _authenticateWithTransport({
+ clerk: SignUp.clerk,
+ transport,
+ resource: this,
+ authenticateMethod: this.authenticateWithRedirectOrPopup,
+ params,
+ callbackParams: params.__internal_callbackParams ?? {},
+ });
+ }
+
  return this.authenticateWithRedirectOrPopup(params, windowNavigate);
  };
 

packages/clerk-js/src/core/resources/__tests__/SignIn.test.ts

@@ -34,6 +34,47 @@ describe('SignIn', () => {
  expect(snapshot).toBeDefined();
  });
 
+ describe('authenticateWithRedirect with an OAuth transport', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ SignIn.clerk = {} as any;
+ });
+
+ it('routes through the transport instead of windowNavigate when one is registered', async () => {
+ const open = vi.fn().mockResolvedValue({ callbackUrl: 'myapp://sso-callback' });
+ const handleResourceCallback = vi.fn().mockResolvedValue(undefined);
+ SignIn.clerk = {
+ buildUrlWithAuth: vi.fn(u => u),
+ __internal_oauthTransport: { getRedirectUrl: () => 'myapp://sso-callback', open },
+ __internal_handleResourceCallback: handleResourceCallback,
+ __internal_environment: { displayConfig: { captchaOauthBypass: [] } },
+ } as any;
+
+ const mockFetch = vi.fn().mockResolvedValueOnce({
+ client: null,
+ response: {
+ id: 'signin_123',
+ first_factor_verification: {
+ status: 'unverified',
+ external_verification_redirect_url: 'https://provider.example/auth',
+ },
+ },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const signIn = new SignIn();
+ await signIn.authenticateWithRedirect({
+ strategy: 'oauth_google',
+ redirectUrl: '/sso-callback',
+ redirectUrlComplete: '/',
+ __internal_callbackParams: { signInUrl: '/sign-in' },
+ } as any);
+
+ expect(open).toHaveBeenCalledWith(new URL('https://provider.example/auth'));
+ expect(handleResourceCallback).toHaveBeenCalledWith(signIn, { signInUrl: '/sign-in' });
+ });
+ });
+
  describe('signIn.create', () => {
  afterEach(() => {
  vi.clearAllMocks();

.changeset/oauth-transport.md

@@ -0,0 +1,8 @@
+---
+'@clerk/shared': minor
+'@clerk/clerk-js': minor
+'@clerk/react': minor
+'@clerk/ui': minor
+---
+
+Add internal OAuth transport support for native desktop SDK wrappers to run Clerk's prebuilt OAuth flows through a system browser.

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -158,6 +158,41 @@ describe('Clerk singleton', () => {
  });
  });
 
+ describe('__internal_oauthTransport', () => {
+ it('defaults to null with no getter access errors', () => {
+ const sut = new Clerk(productionPublishableKey);
+
+ expect(sut.__internal_hasOAuthTransport).toBe(false);
+ expect(sut.__internal_oauthTransport).toBeNull();
+ });
+
+ it('exposes the transport registered via options after load', async () => {
+ const transport = {
+ getRedirectUrl: () => 'myapp://sso-callback',
+ open: async (_url: URL) => ({ callbackUrl: 'myapp://sso-callback' }),
+ };
+ const sut = new Clerk(productionPublishableKey);
+
+ await sut.load({ __internal_oauthTransport: transport });
+
+ expect(sut.__internal_hasOAuthTransport).toBe(true);
+ expect(sut.__internal_oauthTransport).toBe(transport);
+ });
+ });
+
+ describe('__internal_handleResourceCallback', () => {
+ it('handleGoogleOneTapCallback delegates to __internal_handleResourceCallback', async () => {
+ const clerk = new Clerk(productionPublishableKey);
+ await clerk.load();
+ const spy = vi.spyOn(clerk, '__internal_handleResourceCallback').mockResolvedValue(undefined);
+ const signInLike = { identifier: 'x' } as any;
+
+ await clerk.handleGoogleOneTapCallback(signInLike, { signInUrl: '/sign-in' });
+
+ expect(spy).toHaveBeenCalledWith(signInLike, { signInUrl: '/sign-in' }, undefined);
+ });
+ });
+
  describe('.setActive', () => {
  describe('with `active` session status', () => {
  const mockSession = {
@@ -1205,6 +1240,104 @@ describe('Clerk singleton', () => {
  });
  });
 
+ it('uses __internal_navigateOnSetActive for completed sign in callbacks', async () => {
+ const sessionId = 'sess_123';
+ const mockSession = { id: sessionId, currentTask: null };
+ mockEnvironmentFetch.mockReturnValue(
+ Promise.resolve({
+ authConfig: {},
+ userSettings: mockUserSettings,
+ displayConfig: mockDisplayConfig,
+ isSingleSession: () => false,
+ isProduction: () => false,
+ isDevelopmentOrStaging: () => true,
+ onWindowLocationHost: () => false,
+ }),
+ );
+ mockClientFetch.mockReturnValue(
+ Promise.resolve({
+ signedInSessions: [],
+ signIn: new SignIn({
+ status: 'complete',
+ created_session_id: sessionId,
+ } as any as SignInJSON),
+ signUp: new SignUp(null),
+ }),
+ );
+
+ const internalNavigateOnSetActive = vi.fn(async ({ session, redirectUrl, decorateUrl }) => {
+ expect(session).toBe(mockSession);
+ expect(redirectUrl).toBe('http://test.host/after-sign-in');
+ expect(decorateUrl('/decorated')).toBe('/decorated');
+ });
+ const mockSetActive = vi.fn(async ({ navigate }) => navigate({ session: mockSession }));
+
+ const sut = new Clerk(productionPublishableKey);
+ await sut.load(mockedLoadOptions);
+ sut.setActive = mockSetActive as any;
+
+ await sut.handleRedirectCallback({
+ signInForceRedirectUrl: '/after-sign-in',
+ __internal_navigateOnSetActive: internalNavigateOnSetActive,
+ });
+
+ expect(mockSetActive).toHaveBeenCalledWith({
+ session: sessionId,
+ navigate: expect.any(Function),
+ });
+ expect(internalNavigateOnSetActive).toHaveBeenCalledTimes(1);
+ expect(mockNavigate).not.toHaveBeenCalled();
+ });
+
+ it('uses __internal_navigateOnSetActive for completed sign up callbacks', async () => {
+ const sessionId = 'sess_123';
+ const mockSession = { id: sessionId, currentTask: null };
+ mockEnvironmentFetch.mockReturnValue(
+ Promise.resolve({
+ authConfig: {},
+ userSettings: mockUserSettings,
+ displayConfig: mockDisplayConfig,
+ isSingleSession: () => false,
+ isProduction: () => false,
+ isDevelopmentOrStaging: () => true,
+ onWindowLocationHost: () => false,
+ }),
+ );
+ mockClientFetch.mockReturnValue(
+ Promise.resolve({
+ signedInSessions: [],
+ signIn: new SignIn(null),
+ signUp: new SignUp({
+ status: 'complete',
+ created_session_id: sessionId,
+ } as any as SignUpJSON),
+ }),
+ );
+
+ const internalNavigateOnSetActive = vi.fn(async ({ session, redirectUrl, decorateUrl }) => {
+ expect(session).toBe(mockSession);
+ expect(redirectUrl).toBe('http://test.host/after-sign-up');
+ expect(decorateUrl('/decorated')).toBe('/decorated');
+ });
+ const mockSetActive = vi.fn(async ({ navigate }) => navigate({ session: mockSession }));
+
+ const sut = new Clerk(productionPublishableKey);
+ await sut.load(mockedLoadOptions);
+ sut.setActive = mockSetActive as any;
+
+ await sut.handleRedirectCallback({
+ signUpForceRedirectUrl: '/after-sign-up',
+ __internal_navigateOnSetActive: internalNavigateOnSetActive,
+ });
+
+ expect(mockSetActive).toHaveBeenCalledWith({
+ session: sessionId,
+ navigate: expect.any(Function),
+ });
+ expect(internalNavigateOnSetActive).toHaveBeenCalledTimes(1);
+ expect(mockNavigate).not.toHaveBeenCalled();
+ });
+
  it('does not initiate the transfer flow when transferable: false is passed', async () => {
  mockEnvironmentFetch.mockReturnValue(
  Promise.resolve({

packages/clerk-js/src/core/clerk.ts

@@ -98,6 +98,7 @@ import type {
  LoadedClerk,
  NavigateOptions,
  OAuthApplicationNamespace,
+ OAuthTransport,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -269,6 +270,7 @@ export class Clerk implements ClerkInterface {
  #listeners: Array<(emission: Resources) => void> = [];
  #navigationListeners: Array<() => void> = [];
  #options: ClerkOptions = {};
+ #oauthTransport: OAuthTransport | null = null;
  #pageLifecycle: ReturnType<typeof createPageLifecycle> | null = null;
  #touchThrottledUntil = 0;
  #publicEventBus = createClerkEventBus();
@@ -295,6 +297,14 @@ export class Clerk implements ClerkInterface {
  : undefined;
  }
 
+ get __internal_hasOAuthTransport(): boolean {
+ return this.#oauthTransport !== null;
+ }
+
+ get __internal_oauthTransport(): OAuthTransport | null {
+ return this.#oauthTransport;
+ }
+
  public __internal_getCachedResources:
  | (() => Promise<{ client: ClientJSONSnapshot | null; environment: EnvironmentJSONSnapshot | null }>)
  | undefined;
@@ -529,6 +539,7 @@ export class Clerk implements ClerkInterface {
  }
 
  this.#options = this.#initOptions(options);
+ this.#oauthTransport = this.#options.__internal_oauthTransport ?? null;
 
  // Initialize ClerkUI if it was provided
  if (this.#options.ui?.ClerkUI) {
@@ -2285,7 +2296,7 @@ export class Clerk implements ClerkInterface {
  return null;
  };
 
- public handleGoogleOneTapCallback = async (
+ public __internal_handleResourceCallback = async (
  signInOrUp: SignInResource | SignUpResource,
  params: HandleOAuthCallbackParams,
  customNavigate?: (to: string) => Promise<unknown>,
@@ -2310,6 +2321,14 @@ export class Clerk implements ClerkInterface {
  });
  };
 
+ public handleGoogleOneTapCallback = async (
+ signInOrUp: SignInResource | SignUpResource,
+ params: HandleOAuthCallbackParams,
+ customNavigate?: (to: string) => Promise<unknown>,
+ ): Promise<unknown> => {
+ return this.__internal_handleResourceCallback(signInOrUp, params, customNavigate);
+ };
+
  private _handleRedirectCallback = async (
  params: HandleOAuthCallbackParams,
  {
@@ -2421,6 +2440,7 @@ export class Clerk implements ClerkInterface {
 
  const signInUrl = params.signInUrl || displayConfig.signInUrl;
  const signUpUrl = params.signUpUrl || displayConfig.signUpUrl;
+ const internalNavigateOnSetActive = params.__internal_navigateOnSetActive;
 
  const setActiveNavigate = async ({
  session,
@@ -2431,6 +2451,15 @@ export class Clerk implements ClerkInterface {
  baseUrl: string;
  redirectUrl: string;
  }) => {
+ if (internalNavigateOnSetActive) {
+ await internalNavigateOnSetActive({
+ session,
+ redirectUrl,
+ decorateUrl: url => this.buildUrlWithAuth(url),
+ });
+ return;
+ }
+
  if (!session.currentTask) {
  await this.navigate(redirectUrl);
  return;
@@ -2446,7 +2475,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: si.sessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signInUrl, redirectUrl: redirectUrls.getAfterSignInUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signInUrl,
+ redirectUrl: redirectUrls.getAfterSignInUrl(),
+ });
  },
  });
  }
@@ -2461,7 +2494,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: res.createdSessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignInUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignInUrl(),
+ });
  },
  });
  case 'needs_first_factor':
@@ -2512,7 +2549,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: res.createdSessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignUpUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignUpUrl(),
+ });
  },
  });
  case 'missing_requirements':
@@ -2526,7 +2567,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: su.sessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignUpUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignUpUrl(),
+ });
  },
  });
  }

packages/clerk-js/src/core/resources/SignIn.ts

@@ -83,6 +83,7 @@ import {
  _futureAuthenticateWithPopup,
  wrapWithPopupRoutes,
 } from '../../utils/authenticateWithPopup';
+import { _authenticateWithTransport } from '../../utils/authenticateWithTransport';
 import { CaptchaChallenge } from '../../utils/captcha/CaptchaChallenge';
 import { runAsyncResourceTask } from '../../utils/runAsyncResourceTask';
 import { loadZxcvbn } from '../../utils/zxcvbn';
@@ -379,6 +380,18 @@ export class SignIn extends BaseResource implements SignInResource {
  };
 
  public authenticateWithRedirect = async (params: AuthenticateWithRedirectParams): Promise<void> => {
+ const transport = SignIn.clerk.__internal_oauthTransport;
+ if (transport) {
+ return _authenticateWithTransport({
+ clerk: SignIn.clerk,
+ transport,
+ resource: this,
+ authenticateMethod: this.authenticateWithRedirectOrPopup,
+ params,
+ callbackParams: params.__internal_callbackParams ?? {},
+ });
+ }
+
  return this.authenticateWithRedirectOrPopup(params, windowNavigate);
  };
 

packages/clerk-js/src/core/resources/SignUp.ts

@@ -54,6 +54,7 @@ import {
  _futureAuthenticateWithPopup,
  wrapWithPopupRoutes,
 } from '../../utils/authenticateWithPopup';
+import { _authenticateWithTransport } from '../../utils/authenticateWithTransport';
 import { CaptchaChallenge } from '../../utils/captcha/CaptchaChallenge';
 import { normalizeUnsafeMetadata } from '../../utils/resourceParams';
 import { runAsyncResourceTask } from '../../utils/runAsyncResourceTask';
@@ -449,6 +450,18 @@ export class SignUp extends BaseResource implements SignUpResource {
  unsafeMetadata?: SignUpUnsafeMetadata;
  },
  ): Promise<void> => {
+ const transport = SignUp.clerk.__internal_oauthTransport;
+ if (transport) {
+ return _authenticateWithTransport({
+ clerk: SignUp.clerk,
+ transport,
+ resource: this,
+ authenticateMethod: this.authenticateWithRedirectOrPopup,
+ params,
+ callbackParams: params.__internal_callbackParams ?? {},
+ });
+ }
+
  return this.authenticateWithRedirectOrPopup(params, windowNavigate);
  };
 

packages/clerk-js/src/core/resources/__tests__/SignIn.test.ts

@@ -34,6 +34,47 @@ describe('SignIn', () => {
  expect(snapshot).toBeDefined();
  });
 
+ describe('authenticateWithRedirect with an OAuth transport', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ SignIn.clerk = {} as any;
+ });
+
+ it('routes through the transport instead of windowNavigate when one is registered', async () => {
+ const open = vi.fn().mockResolvedValue({ callbackUrl: 'myapp://sso-callback' });
+ const handleResourceCallback = vi.fn().mockResolvedValue(undefined);
+ SignIn.clerk = {
+ buildUrlWithAuth: vi.fn(u => u),
+ __internal_oauthTransport: { getRedirectUrl: () => 'myapp://sso-callback', open },
+ __internal_handleResourceCallback: handleResourceCallback,
+ __internal_environment: { displayConfig: { captchaOauthBypass: [] } },
+ } as any;
+
+ const mockFetch = vi.fn().mockResolvedValueOnce({
+ client: null,
+ response: {
+ id: 'signin_123',
+ first_factor_verification: {
+ status: 'unverified',
+ external_verification_redirect_url: 'https://provider.example/auth',
+ },
+ },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const signIn = new SignIn();
+ await signIn.authenticateWithRedirect({
+ strategy: 'oauth_google',
+ redirectUrl: '/sso-callback',
+ redirectUrlComplete: '/',
+ __internal_callbackParams: { signInUrl: '/sign-in' },
+ } as any);
+
+ expect(open).toHaveBeenCalledWith(new URL('https://provider.example/auth'));
+ expect(handleResourceCallback).toHaveBeenCalledWith(signIn, { signInUrl: '/sign-in' });
+ });
+ });
+
  describe('signIn.create', () => {
  afterEach(() => {
  vi.clearAllMocks();

.changeset/oauth-transport.md

@@ -0,0 +1,8 @@
+---
+'@clerk/shared': minor
+'@clerk/clerk-js': minor
+'@clerk/react': minor
+'@clerk/ui': minor
+---
+
+Add internal OAuth transport support for native desktop SDK wrappers to run Clerk's prebuilt OAuth flows through a system browser.

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -158,6 +158,41 @@ describe('Clerk singleton', () => {
  });
  });
 
+ describe('__internal_oauthTransport', () => {
+ it('defaults to null with no getter access errors', () => {
+ const sut = new Clerk(productionPublishableKey);
+
+ expect(sut.__internal_hasOAuthTransport).toBe(false);
+ expect(sut.__internal_oauthTransport).toBeNull();
+ });
+
+ it('exposes the transport registered via options after load', async () => {
+ const transport = {
+ getRedirectUrl: () => 'myapp://sso-callback',
+ open: async (_url: URL) => ({ callbackUrl: 'myapp://sso-callback' }),
+ };
+ const sut = new Clerk(productionPublishableKey);
+
+ await sut.load({ __internal_oauthTransport: transport });
+
+ expect(sut.__internal_hasOAuthTransport).toBe(true);
+ expect(sut.__internal_oauthTransport).toBe(transport);
+ });
+ });
+
+ describe('__internal_handleResourceCallback', () => {
+ it('handleGoogleOneTapCallback delegates to __internal_handleResourceCallback', async () => {
+ const clerk = new Clerk(productionPublishableKey);
+ await clerk.load();
+ const spy = vi.spyOn(clerk, '__internal_handleResourceCallback').mockResolvedValue(undefined);
+ const signInLike = { identifier: 'x' } as any;
+
+ await clerk.handleGoogleOneTapCallback(signInLike, { signInUrl: '/sign-in' });
+
+ expect(spy).toHaveBeenCalledWith(signInLike, { signInUrl: '/sign-in' }, undefined);
+ });
+ });
+
  describe('.setActive', () => {
  describe('with `active` session status', () => {
  const mockSession = {
@@ -1205,6 +1240,104 @@ describe('Clerk singleton', () => {
  });
  });
 
+ it('uses __internal_navigateOnSetActive for completed sign in callbacks', async () => {
+ const sessionId = 'sess_123';
+ const mockSession = { id: sessionId, currentTask: null };
+ mockEnvironmentFetch.mockReturnValue(
+ Promise.resolve({
+ authConfig: {},
+ userSettings: mockUserSettings,
+ displayConfig: mockDisplayConfig,
+ isSingleSession: () => false,
+ isProduction: () => false,
+ isDevelopmentOrStaging: () => true,
+ onWindowLocationHost: () => false,
+ }),
+ );
+ mockClientFetch.mockReturnValue(
+ Promise.resolve({
+ signedInSessions: [],
+ signIn: new SignIn({
+ status: 'complete',
+ created_session_id: sessionId,
+ } as any as SignInJSON),
+ signUp: new SignUp(null),
+ }),
+ );
+
+ const internalNavigateOnSetActive = vi.fn(async ({ session, redirectUrl, decorateUrl }) => {
+ expect(session).toBe(mockSession);
+ expect(redirectUrl).toBe('http://test.host/after-sign-in');
+ expect(decorateUrl('/decorated')).toBe('/decorated');
+ });
+ const mockSetActive = vi.fn(async ({ navigate }) => navigate({ session: mockSession }));
+
+ const sut = new Clerk(productionPublishableKey);
+ await sut.load(mockedLoadOptions);
+ sut.setActive = mockSetActive as any;
+
+ await sut.handleRedirectCallback({
+ signInForceRedirectUrl: '/after-sign-in',
+ __internal_navigateOnSetActive: internalNavigateOnSetActive,
+ });
+
+ expect(mockSetActive).toHaveBeenCalledWith({
+ session: sessionId,
+ navigate: expect.any(Function),
+ });
+ expect(internalNavigateOnSetActive).toHaveBeenCalledTimes(1);
+ expect(mockNavigate).not.toHaveBeenCalled();
+ });
+
+ it('uses __internal_navigateOnSetActive for completed sign up callbacks', async () => {
+ const sessionId = 'sess_123';
+ const mockSession = { id: sessionId, currentTask: null };
+ mockEnvironmentFetch.mockReturnValue(
+ Promise.resolve({
+ authConfig: {},
+ userSettings: mockUserSettings,
+ displayConfig: mockDisplayConfig,
+ isSingleSession: () => false,
+ isProduction: () => false,
+ isDevelopmentOrStaging: () => true,
+ onWindowLocationHost: () => false,
+ }),
+ );
+ mockClientFetch.mockReturnValue(
+ Promise.resolve({
+ signedInSessions: [],
+ signIn: new SignIn(null),
+ signUp: new SignUp({
+ status: 'complete',
+ created_session_id: sessionId,
+ } as any as SignUpJSON),
+ }),
+ );
+
+ const internalNavigateOnSetActive = vi.fn(async ({ session, redirectUrl, decorateUrl }) => {
+ expect(session).toBe(mockSession);
+ expect(redirectUrl).toBe('http://test.host/after-sign-up');
+ expect(decorateUrl('/decorated')).toBe('/decorated');
+ });
+ const mockSetActive = vi.fn(async ({ navigate }) => navigate({ session: mockSession }));
+
+ const sut = new Clerk(productionPublishableKey);
+ await sut.load(mockedLoadOptions);
+ sut.setActive = mockSetActive as any;
+
+ await sut.handleRedirectCallback({
+ signUpForceRedirectUrl: '/after-sign-up',
+ __internal_navigateOnSetActive: internalNavigateOnSetActive,
+ });
+
+ expect(mockSetActive).toHaveBeenCalledWith({
+ session: sessionId,
+ navigate: expect.any(Function),
+ });
+ expect(internalNavigateOnSetActive).toHaveBeenCalledTimes(1);
+ expect(mockNavigate).not.toHaveBeenCalled();
+ });
+
  it('does not initiate the transfer flow when transferable: false is passed', async () => {
  mockEnvironmentFetch.mockReturnValue(
  Promise.resolve({

packages/clerk-js/src/core/clerk.ts

@@ -98,6 +98,7 @@ import type {
  LoadedClerk,
  NavigateOptions,
  OAuthApplicationNamespace,
+ OAuthTransport,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -269,6 +270,7 @@ export class Clerk implements ClerkInterface {
  #listeners: Array<(emission: Resources) => void> = [];
  #navigationListeners: Array<() => void> = [];
  #options: ClerkOptions = {};
+ #oauthTransport: OAuthTransport | null = null;
  #pageLifecycle: ReturnType<typeof createPageLifecycle> | null = null;
  #touchThrottledUntil = 0;
  #publicEventBus = createClerkEventBus();
@@ -295,6 +297,14 @@ export class Clerk implements ClerkInterface {
  : undefined;
  }
 
+ get __internal_hasOAuthTransport(): boolean {
+ return this.#oauthTransport !== null;
+ }
+
+ get __internal_oauthTransport(): OAuthTransport | null {
+ return this.#oauthTransport;
+ }
+
  public __internal_getCachedResources:
  | (() => Promise<{ client: ClientJSONSnapshot | null; environment: EnvironmentJSONSnapshot | null }>)
  | undefined;
@@ -529,6 +539,7 @@ export class Clerk implements ClerkInterface {
  }
 
  this.#options = this.#initOptions(options);
+ this.#oauthTransport = this.#options.__internal_oauthTransport ?? null;
 
  // Initialize ClerkUI if it was provided
  if (this.#options.ui?.ClerkUI) {
@@ -2285,7 +2296,7 @@ export class Clerk implements ClerkInterface {
  return null;
  };
 
- public handleGoogleOneTapCallback = async (
+ public __internal_handleResourceCallback = async (
  signInOrUp: SignInResource | SignUpResource,
  params: HandleOAuthCallbackParams,
  customNavigate?: (to: string) => Promise<unknown>,
@@ -2310,6 +2321,14 @@ export class Clerk implements ClerkInterface {
  });
  };
 
+ public handleGoogleOneTapCallback = async (
+ signInOrUp: SignInResource | SignUpResource,
+ params: HandleOAuthCallbackParams,
+ customNavigate?: (to: string) => Promise<unknown>,
+ ): Promise<unknown> => {
+ return this.__internal_handleResourceCallback(signInOrUp, params, customNavigate);
+ };
+
  private _handleRedirectCallback = async (
  params: HandleOAuthCallbackParams,
  {
@@ -2421,6 +2440,7 @@ export class Clerk implements ClerkInterface {
 
  const signInUrl = params.signInUrl || displayConfig.signInUrl;
  const signUpUrl = params.signUpUrl || displayConfig.signUpUrl;
+ const internalNavigateOnSetActive = params.__internal_navigateOnSetActive;
 
  const setActiveNavigate = async ({
  session,
@@ -2431,6 +2451,15 @@ export class Clerk implements ClerkInterface {
  baseUrl: string;
  redirectUrl: string;
  }) => {
+ if (internalNavigateOnSetActive) {
+ await internalNavigateOnSetActive({
+ session,
+ redirectUrl,
+ decorateUrl: url => this.buildUrlWithAuth(url),
+ });
+ return;
+ }
+
  if (!session.currentTask) {
  await this.navigate(redirectUrl);
  return;
@@ -2446,7 +2475,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: si.sessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signInUrl, redirectUrl: redirectUrls.getAfterSignInUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signInUrl,
+ redirectUrl: redirectUrls.getAfterSignInUrl(),
+ });
  },
  });
  }
@@ -2461,7 +2494,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: res.createdSessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignInUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignInUrl(),
+ });
  },
  });
  case 'needs_first_factor':
@@ -2512,7 +2549,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: res.createdSessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignUpUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignUpUrl(),
+ });
  },
  });
  case 'missing_requirements':
@@ -2526,7 +2567,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: su.sessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignUpUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignUpUrl(),
+ });
  },
  });
  }

packages/clerk-js/src/core/resources/SignIn.ts

@@ -83,6 +83,7 @@ import {
  _futureAuthenticateWithPopup,
  wrapWithPopupRoutes,
 } from '../../utils/authenticateWithPopup';
+import { _authenticateWithTransport } from '../../utils/authenticateWithTransport';
 import { CaptchaChallenge } from '../../utils/captcha/CaptchaChallenge';
 import { runAsyncResourceTask } from '../../utils/runAsyncResourceTask';
 import { loadZxcvbn } from '../../utils/zxcvbn';
@@ -379,6 +380,18 @@ export class SignIn extends BaseResource implements SignInResource {
  };
 
  public authenticateWithRedirect = async (params: AuthenticateWithRedirectParams): Promise<void> => {
+ const transport = SignIn.clerk.__internal_oauthTransport;
+ if (transport) {
+ return _authenticateWithTransport({
+ clerk: SignIn.clerk,
+ transport,
+ resource: this,
+ authenticateMethod: this.authenticateWithRedirectOrPopup,
+ params,
+ callbackParams: params.__internal_callbackParams ?? {},
+ });
+ }
+
  return this.authenticateWithRedirectOrPopup(params, windowNavigate);
  };
 

packages/clerk-js/src/core/resources/SignUp.ts

@@ -54,6 +54,7 @@ import {
  _futureAuthenticateWithPopup,
  wrapWithPopupRoutes,
 } from '../../utils/authenticateWithPopup';
+import { _authenticateWithTransport } from '../../utils/authenticateWithTransport';
 import { CaptchaChallenge } from '../../utils/captcha/CaptchaChallenge';
 import { normalizeUnsafeMetadata } from '../../utils/resourceParams';
 import { runAsyncResourceTask } from '../../utils/runAsyncResourceTask';
@@ -449,6 +450,18 @@ export class SignUp extends BaseResource implements SignUpResource {
  unsafeMetadata?: SignUpUnsafeMetadata;
  },
  ): Promise<void> => {
+ const transport = SignUp.clerk.__internal_oauthTransport;
+ if (transport) {
+ return _authenticateWithTransport({
+ clerk: SignUp.clerk,
+ transport,
+ resource: this,
+ authenticateMethod: this.authenticateWithRedirectOrPopup,
+ params,
+ callbackParams: params.__internal_callbackParams ?? {},
+ });
+ }
+
  return this.authenticateWithRedirectOrPopup(params, windowNavigate);
  };
 

packages/clerk-js/src/core/resources/__tests__/SignIn.test.ts

@@ -34,6 +34,47 @@ describe('SignIn', () => {
  expect(snapshot).toBeDefined();
  });
 
+ describe('authenticateWithRedirect with an OAuth transport', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ SignIn.clerk = {} as any;
+ });
+
+ it('routes through the transport instead of windowNavigate when one is registered', async () => {
+ const open = vi.fn().mockResolvedValue({ callbackUrl: 'myapp://sso-callback' });
+ const handleResourceCallback = vi.fn().mockResolvedValue(undefined);
+ SignIn.clerk = {
+ buildUrlWithAuth: vi.fn(u => u),
+ __internal_oauthTransport: { getRedirectUrl: () => 'myapp://sso-callback', open },
+ __internal_handleResourceCallback: handleResourceCallback,
+ __internal_environment: { displayConfig: { captchaOauthBypass: [] } },
+ } as any;
+
+ const mockFetch = vi.fn().mockResolvedValueOnce({
+ client: null,
+ response: {
+ id: 'signin_123',
+ first_factor_verification: {
+ status: 'unverified',
+ external_verification_redirect_url: 'https://provider.example/auth',
+ },
+ },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const signIn = new SignIn();
+ await signIn.authenticateWithRedirect({
+ strategy: 'oauth_google',
+ redirectUrl: '/sso-callback',
+ redirectUrlComplete: '/',
+ __internal_callbackParams: { signInUrl: '/sign-in' },
+ } as any);
+
+ expect(open).toHaveBeenCalledWith(new URL('https://provider.example/auth'));
+ expect(handleResourceCallback).toHaveBeenCalledWith(signIn, { signInUrl: '/sign-in' });
+ });
+ });
+
  describe('signIn.create', () => {
  afterEach(() => {
  vi.clearAllMocks();

.changeset/oauth-transport.md

@@ -0,0 +1,8 @@
+---
+'@clerk/shared': minor
+'@clerk/clerk-js': minor
+'@clerk/react': minor
+'@clerk/ui': minor
+---
+
+Add internal OAuth transport support for native desktop SDK wrappers to run Clerk's prebuilt OAuth flows through a system browser.

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -158,6 +158,41 @@ describe('Clerk singleton', () => {
  });
  });
 
+ describe('__internal_oauthTransport', () => {
+ it('defaults to null with no getter access errors', () => {
+ const sut = new Clerk(productionPublishableKey);
+
+ expect(sut.__internal_hasOAuthTransport).toBe(false);
+ expect(sut.__internal_oauthTransport).toBeNull();
+ });
+
+ it('exposes the transport registered via options after load', async () => {
+ const transport = {
+ getRedirectUrl: () => 'myapp://sso-callback',
+ open: async (_url: URL) => ({ callbackUrl: 'myapp://sso-callback' }),
+ };
+ const sut = new Clerk(productionPublishableKey);
+
+ await sut.load({ __internal_oauthTransport: transport });
+
+ expect(sut.__internal_hasOAuthTransport).toBe(true);
+ expect(sut.__internal_oauthTransport).toBe(transport);
+ });
+ });
+
+ describe('__internal_handleResourceCallback', () => {
+ it('handleGoogleOneTapCallback delegates to __internal_handleResourceCallback', async () => {
+ const clerk = new Clerk(productionPublishableKey);
+ await clerk.load();
+ const spy = vi.spyOn(clerk, '__internal_handleResourceCallback').mockResolvedValue(undefined);
+ const signInLike = { identifier: 'x' } as any;
+
+ await clerk.handleGoogleOneTapCallback(signInLike, { signInUrl: '/sign-in' });
+
+ expect(spy).toHaveBeenCalledWith(signInLike, { signInUrl: '/sign-in' }, undefined);
+ });
+ });
+
  describe('.setActive', () => {
  describe('with `active` session status', () => {
  const mockSession = {
@@ -1205,6 +1240,104 @@ describe('Clerk singleton', () => {
  });
  });
 
+ it('uses __internal_navigateOnSetActive for completed sign in callbacks', async () => {
+ const sessionId = 'sess_123';
+ const mockSession = { id: sessionId, currentTask: null };
+ mockEnvironmentFetch.mockReturnValue(
+ Promise.resolve({
+ authConfig: {},
+ userSettings: mockUserSettings,
+ displayConfig: mockDisplayConfig,
+ isSingleSession: () => false,
+ isProduction: () => false,
+ isDevelopmentOrStaging: () => true,
+ onWindowLocationHost: () => false,
+ }),
+ );
+ mockClientFetch.mockReturnValue(
+ Promise.resolve({
+ signedInSessions: [],
+ signIn: new SignIn({
+ status: 'complete',
+ created_session_id: sessionId,
+ } as any as SignInJSON),
+ signUp: new SignUp(null),
+ }),
+ );
+
+ const internalNavigateOnSetActive = vi.fn(async ({ session, redirectUrl, decorateUrl }) => {
+ expect(session).toBe(mockSession);
+ expect(redirectUrl).toBe('http://test.host/after-sign-in');
+ expect(decorateUrl('/decorated')).toBe('/decorated');
+ });
+ const mockSetActive = vi.fn(async ({ navigate }) => navigate({ session: mockSession }));
+
+ const sut = new Clerk(productionPublishableKey);
+ await sut.load(mockedLoadOptions);
+ sut.setActive = mockSetActive as any;
+
+ await sut.handleRedirectCallback({
+ signInForceRedirectUrl: '/after-sign-in',
+ __internal_navigateOnSetActive: internalNavigateOnSetActive,
+ });
+
+ expect(mockSetActive).toHaveBeenCalledWith({
+ session: sessionId,
+ navigate: expect.any(Function),
+ });
+ expect(internalNavigateOnSetActive).toHaveBeenCalledTimes(1);
+ expect(mockNavigate).not.toHaveBeenCalled();
+ });
+
+ it('uses __internal_navigateOnSetActive for completed sign up callbacks', async () => {
+ const sessionId = 'sess_123';
+ const mockSession = { id: sessionId, currentTask: null };
+ mockEnvironmentFetch.mockReturnValue(
+ Promise.resolve({
+ authConfig: {},
+ userSettings: mockUserSettings,
+ displayConfig: mockDisplayConfig,
+ isSingleSession: () => false,
+ isProduction: () => false,
+ isDevelopmentOrStaging: () => true,
+ onWindowLocationHost: () => false,
+ }),
+ );
+ mockClientFetch.mockReturnValue(
+ Promise.resolve({
+ signedInSessions: [],
+ signIn: new SignIn(null),
+ signUp: new SignUp({
+ status: 'complete',
+ created_session_id: sessionId,
+ } as any as SignUpJSON),
+ }),
+ );
+
+ const internalNavigateOnSetActive = vi.fn(async ({ session, redirectUrl, decorateUrl }) => {
+ expect(session).toBe(mockSession);
+ expect(redirectUrl).toBe('http://test.host/after-sign-up');
+ expect(decorateUrl('/decorated')).toBe('/decorated');
+ });
+ const mockSetActive = vi.fn(async ({ navigate }) => navigate({ session: mockSession }));
+
+ const sut = new Clerk(productionPublishableKey);
+ await sut.load(mockedLoadOptions);
+ sut.setActive = mockSetActive as any;
+
+ await sut.handleRedirectCallback({
+ signUpForceRedirectUrl: '/after-sign-up',
+ __internal_navigateOnSetActive: internalNavigateOnSetActive,
+ });
+
+ expect(mockSetActive).toHaveBeenCalledWith({
+ session: sessionId,
+ navigate: expect.any(Function),
+ });
+ expect(internalNavigateOnSetActive).toHaveBeenCalledTimes(1);
+ expect(mockNavigate).not.toHaveBeenCalled();
+ });
+
  it('does not initiate the transfer flow when transferable: false is passed', async () => {
  mockEnvironmentFetch.mockReturnValue(
  Promise.resolve({

packages/clerk-js/src/core/clerk.ts

@@ -98,6 +98,7 @@ import type {
  LoadedClerk,
  NavigateOptions,
  OAuthApplicationNamespace,
+ OAuthTransport,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -269,6 +270,7 @@ export class Clerk implements ClerkInterface {
  #listeners: Array<(emission: Resources) => void> = [];
  #navigationListeners: Array<() => void> = [];
  #options: ClerkOptions = {};
+ #oauthTransport: OAuthTransport | null = null;
  #pageLifecycle: ReturnType<typeof createPageLifecycle> | null = null;
  #touchThrottledUntil = 0;
  #publicEventBus = createClerkEventBus();
@@ -295,6 +297,14 @@ export class Clerk implements ClerkInterface {
  : undefined;
  }
 
+ get __internal_hasOAuthTransport(): boolean {
+ return this.#oauthTransport !== null;
+ }
+
+ get __internal_oauthTransport(): OAuthTransport | null {
+ return this.#oauthTransport;
+ }
+
  public __internal_getCachedResources:
  | (() => Promise<{ client: ClientJSONSnapshot | null; environment: EnvironmentJSONSnapshot | null }>)
  | undefined;
@@ -529,6 +539,7 @@ export class Clerk implements ClerkInterface {
  }
 
  this.#options = this.#initOptions(options);
+ this.#oauthTransport = this.#options.__internal_oauthTransport ?? null;
 
  // Initialize ClerkUI if it was provided
  if (this.#options.ui?.ClerkUI) {
@@ -2285,7 +2296,7 @@ export class Clerk implements ClerkInterface {
  return null;
  };
 
- public handleGoogleOneTapCallback = async (
+ public __internal_handleResourceCallback = async (
  signInOrUp: SignInResource | SignUpResource,
  params: HandleOAuthCallbackParams,
  customNavigate?: (to: string) => Promise<unknown>,
@@ -2310,6 +2321,14 @@ export class Clerk implements ClerkInterface {
  });
  };
 
+ public handleGoogleOneTapCallback = async (
+ signInOrUp: SignInResource | SignUpResource,
+ params: HandleOAuthCallbackParams,
+ customNavigate?: (to: string) => Promise<unknown>,
+ ): Promise<unknown> => {
+ return this.__internal_handleResourceCallback(signInOrUp, params, customNavigate);
+ };
+
  private _handleRedirectCallback = async (
  params: HandleOAuthCallbackParams,
  {
@@ -2421,6 +2440,7 @@ export class Clerk implements ClerkInterface {
 
  const signInUrl = params.signInUrl || displayConfig.signInUrl;
  const signUpUrl = params.signUpUrl || displayConfig.signUpUrl;
+ const internalNavigateOnSetActive = params.__internal_navigateOnSetActive;
 
  const setActiveNavigate = async ({
  session,
@@ -2431,6 +2451,15 @@ export class Clerk implements ClerkInterface {
  baseUrl: string;
  redirectUrl: string;
  }) => {
+ if (internalNavigateOnSetActive) {
+ await internalNavigateOnSetActive({
+ session,
+ redirectUrl,
+ decorateUrl: url => this.buildUrlWithAuth(url),
+ });
+ return;
+ }
+
  if (!session.currentTask) {
  await this.navigate(redirectUrl);
  return;
@@ -2446,7 +2475,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: si.sessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signInUrl, redirectUrl: redirectUrls.getAfterSignInUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signInUrl,
+ redirectUrl: redirectUrls.getAfterSignInUrl(),
+ });
  },
  });
  }
@@ -2461,7 +2494,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: res.createdSessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignInUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignInUrl(),
+ });
  },
  });
  case 'needs_first_factor':
@@ -2512,7 +2549,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: res.createdSessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignUpUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignUpUrl(),
+ });
  },
  });
  case 'missing_requirements':
@@ -2526,7 +2567,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: su.sessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignUpUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignUpUrl(),
+ });
  },
  });
  }

packages/clerk-js/src/core/resources/SignIn.ts

@@ -83,6 +83,7 @@ import {
  _futureAuthenticateWithPopup,
  wrapWithPopupRoutes,
 } from '../../utils/authenticateWithPopup';
+import { _authenticateWithTransport } from '../../utils/authenticateWithTransport';
 import { CaptchaChallenge } from '../../utils/captcha/CaptchaChallenge';
 import { runAsyncResourceTask } from '../../utils/runAsyncResourceTask';
 import { loadZxcvbn } from '../../utils/zxcvbn';
@@ -379,6 +380,18 @@ export class SignIn extends BaseResource implements SignInResource {
  };
 
  public authenticateWithRedirect = async (params: AuthenticateWithRedirectParams): Promise<void> => {
+ const transport = SignIn.clerk.__internal_oauthTransport;
+ if (transport) {
+ return _authenticateWithTransport({
+ clerk: SignIn.clerk,
+ transport,
+ resource: this,
+ authenticateMethod: this.authenticateWithRedirectOrPopup,
+ params,
+ callbackParams: params.__internal_callbackParams ?? {},
+ });
+ }
+
  return this.authenticateWithRedirectOrPopup(params, windowNavigate);
  };
 

packages/clerk-js/src/core/resources/SignUp.ts

@@ -54,6 +54,7 @@ import {
  _futureAuthenticateWithPopup,
  wrapWithPopupRoutes,
 } from '../../utils/authenticateWithPopup';
+import { _authenticateWithTransport } from '../../utils/authenticateWithTransport';
 import { CaptchaChallenge } from '../../utils/captcha/CaptchaChallenge';
 import { normalizeUnsafeMetadata } from '../../utils/resourceParams';
 import { runAsyncResourceTask } from '../../utils/runAsyncResourceTask';
@@ -449,6 +450,18 @@ export class SignUp extends BaseResource implements SignUpResource {
  unsafeMetadata?: SignUpUnsafeMetadata;
  },
  ): Promise<void> => {
+ const transport = SignUp.clerk.__internal_oauthTransport;
+ if (transport) {
+ return _authenticateWithTransport({
+ clerk: SignUp.clerk,
+ transport,
+ resource: this,
+ authenticateMethod: this.authenticateWithRedirectOrPopup,
+ params,
+ callbackParams: params.__internal_callbackParams ?? {},
+ });
+ }
+
  return this.authenticateWithRedirectOrPopup(params, windowNavigate);
  };
 

packages/clerk-js/src/core/resources/__tests__/SignIn.test.ts

@@ -34,6 +34,47 @@ describe('SignIn', () => {
  expect(snapshot).toBeDefined();
  });
 
+ describe('authenticateWithRedirect with an OAuth transport', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ SignIn.clerk = {} as any;
+ });
+
+ it('routes through the transport instead of windowNavigate when one is registered', async () => {
+ const open = vi.fn().mockResolvedValue({ callbackUrl: 'myapp://sso-callback' });
+ const handleResourceCallback = vi.fn().mockResolvedValue(undefined);
+ SignIn.clerk = {
+ buildUrlWithAuth: vi.fn(u => u),
+ __internal_oauthTransport: { getRedirectUrl: () => 'myapp://sso-callback', open },
+ __internal_handleResourceCallback: handleResourceCallback,
+ __internal_environment: { displayConfig: { captchaOauthBypass: [] } },
+ } as any;
+
+ const mockFetch = vi.fn().mockResolvedValueOnce({
+ client: null,
+ response: {
+ id: 'signin_123',
+ first_factor_verification: {
+ status: 'unverified',
+ external_verification_redirect_url: 'https://provider.example/auth',
+ },
+ },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const signIn = new SignIn();
+ await signIn.authenticateWithRedirect({
+ strategy: 'oauth_google',
+ redirectUrl: '/sso-callback',
+ redirectUrlComplete: '/',
+ __internal_callbackParams: { signInUrl: '/sign-in' },
+ } as any);
+
+ expect(open).toHaveBeenCalledWith(new URL('https://provider.example/auth'));
+ expect(handleResourceCallback).toHaveBeenCalledWith(signIn, { signInUrl: '/sign-in' });
+ });
+ });
+
  describe('signIn.create', () => {
  afterEach(() => {
  vi.clearAllMocks();

.changeset/oauth-transport.md

@@ -0,0 +1,8 @@
+---
+'@clerk/shared': minor
+'@clerk/clerk-js': minor
+'@clerk/react': minor
+'@clerk/ui': minor
+---
+
+Add internal OAuth transport support for native desktop SDK wrappers to run Clerk's prebuilt OAuth flows through a system browser.

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -158,6 +158,41 @@ describe('Clerk singleton', () => {
  });
  });
 
+ describe('__internal_oauthTransport', () => {
+ it('defaults to null with no getter access errors', () => {
+ const sut = new Clerk(productionPublishableKey);
+
+ expect(sut.__internal_hasOAuthTransport).toBe(false);
+ expect(sut.__internal_oauthTransport).toBeNull();
+ });
+
+ it('exposes the transport registered via options after load', async () => {
+ const transport = {
+ getRedirectUrl: () => 'myapp://sso-callback',
+ open: async (_url: URL) => ({ callbackUrl: 'myapp://sso-callback' }),
+ };
+ const sut = new Clerk(productionPublishableKey);
+
+ await sut.load({ __internal_oauthTransport: transport });
+
+ expect(sut.__internal_hasOAuthTransport).toBe(true);
+ expect(sut.__internal_oauthTransport).toBe(transport);
+ });
+ });
+
+ describe('__internal_handleResourceCallback', () => {
+ it('handleGoogleOneTapCallback delegates to __internal_handleResourceCallback', async () => {
+ const clerk = new Clerk(productionPublishableKey);
+ await clerk.load();
+ const spy = vi.spyOn(clerk, '__internal_handleResourceCallback').mockResolvedValue(undefined);
+ const signInLike = { identifier: 'x' } as any;
+
+ await clerk.handleGoogleOneTapCallback(signInLike, { signInUrl: '/sign-in' });
+
+ expect(spy).toHaveBeenCalledWith(signInLike, { signInUrl: '/sign-in' }, undefined);
+ });
+ });
+
  describe('.setActive', () => {
  describe('with `active` session status', () => {
  const mockSession = {
@@ -1205,6 +1240,104 @@ describe('Clerk singleton', () => {
  });
  });
 
+ it('uses __internal_navigateOnSetActive for completed sign in callbacks', async () => {
+ const sessionId = 'sess_123';
+ const mockSession = { id: sessionId, currentTask: null };
+ mockEnvironmentFetch.mockReturnValue(
+ Promise.resolve({
+ authConfig: {},
+ userSettings: mockUserSettings,
+ displayConfig: mockDisplayConfig,
+ isSingleSession: () => false,
+ isProduction: () => false,
+ isDevelopmentOrStaging: () => true,
+ onWindowLocationHost: () => false,
+ }),
+ );
+ mockClientFetch.mockReturnValue(
+ Promise.resolve({
+ signedInSessions: [],
+ signIn: new SignIn({
+ status: 'complete',
+ created_session_id: sessionId,
+ } as any as SignInJSON),
+ signUp: new SignUp(null),
+ }),
+ );
+
+ const internalNavigateOnSetActive = vi.fn(async ({ session, redirectUrl, decorateUrl }) => {
+ expect(session).toBe(mockSession);
+ expect(redirectUrl).toBe('http://test.host/after-sign-in');
+ expect(decorateUrl('/decorated')).toBe('/decorated');
+ });
+ const mockSetActive = vi.fn(async ({ navigate }) => navigate({ session: mockSession }));
+
+ const sut = new Clerk(productionPublishableKey);
+ await sut.load(mockedLoadOptions);
+ sut.setActive = mockSetActive as any;
+
+ await sut.handleRedirectCallback({
+ signInForceRedirectUrl: '/after-sign-in',
+ __internal_navigateOnSetActive: internalNavigateOnSetActive,
+ });
+
+ expect(mockSetActive).toHaveBeenCalledWith({
+ session: sessionId,
+ navigate: expect.any(Function),
+ });
+ expect(internalNavigateOnSetActive).toHaveBeenCalledTimes(1);
+ expect(mockNavigate).not.toHaveBeenCalled();
+ });
+
+ it('uses __internal_navigateOnSetActive for completed sign up callbacks', async () => {
+ const sessionId = 'sess_123';
+ const mockSession = { id: sessionId, currentTask: null };
+ mockEnvironmentFetch.mockReturnValue(
+ Promise.resolve({
+ authConfig: {},
+ userSettings: mockUserSettings,
+ displayConfig: mockDisplayConfig,
+ isSingleSession: () => false,
+ isProduction: () => false,
+ isDevelopmentOrStaging: () => true,
+ onWindowLocationHost: () => false,
+ }),
+ );
+ mockClientFetch.mockReturnValue(
+ Promise.resolve({
+ signedInSessions: [],
+ signIn: new SignIn(null),
+ signUp: new SignUp({
+ status: 'complete',
+ created_session_id: sessionId,
+ } as any as SignUpJSON),
+ }),
+ );
+
+ const internalNavigateOnSetActive = vi.fn(async ({ session, redirectUrl, decorateUrl }) => {
+ expect(session).toBe(mockSession);
+ expect(redirectUrl).toBe('http://test.host/after-sign-up');
+ expect(decorateUrl('/decorated')).toBe('/decorated');
+ });
+ const mockSetActive = vi.fn(async ({ navigate }) => navigate({ session: mockSession }));
+
+ const sut = new Clerk(productionPublishableKey);
+ await sut.load(mockedLoadOptions);
+ sut.setActive = mockSetActive as any;
+
+ await sut.handleRedirectCallback({
+ signUpForceRedirectUrl: '/after-sign-up',
+ __internal_navigateOnSetActive: internalNavigateOnSetActive,
+ });
+
+ expect(mockSetActive).toHaveBeenCalledWith({
+ session: sessionId,
+ navigate: expect.any(Function),
+ });
+ expect(internalNavigateOnSetActive).toHaveBeenCalledTimes(1);
+ expect(mockNavigate).not.toHaveBeenCalled();
+ });
+
  it('does not initiate the transfer flow when transferable: false is passed', async () => {
  mockEnvironmentFetch.mockReturnValue(
  Promise.resolve({

packages/clerk-js/src/core/clerk.ts

@@ -98,6 +98,7 @@ import type {
  LoadedClerk,
  NavigateOptions,
  OAuthApplicationNamespace,
+ OAuthTransport,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -269,6 +270,7 @@ export class Clerk implements ClerkInterface {
  #listeners: Array<(emission: Resources) => void> = [];
  #navigationListeners: Array<() => void> = [];
  #options: ClerkOptions = {};
+ #oauthTransport: OAuthTransport | null = null;
  #pageLifecycle: ReturnType<typeof createPageLifecycle> | null = null;
  #touchThrottledUntil = 0;
  #publicEventBus = createClerkEventBus();
@@ -295,6 +297,14 @@ export class Clerk implements ClerkInterface {
  : undefined;
  }
 
+ get __internal_hasOAuthTransport(): boolean {
+ return this.#oauthTransport !== null;
+ }
+
+ get __internal_oauthTransport(): OAuthTransport | null {
+ return this.#oauthTransport;
+ }
+
  public __internal_getCachedResources:
  | (() => Promise<{ client: ClientJSONSnapshot | null; environment: EnvironmentJSONSnapshot | null }>)
  | undefined;
@@ -529,6 +539,7 @@ export class Clerk implements ClerkInterface {
  }
 
  this.#options = this.#initOptions(options);
+ this.#oauthTransport = this.#options.__internal_oauthTransport ?? null;
 
  // Initialize ClerkUI if it was provided
  if (this.#options.ui?.ClerkUI) {
@@ -2285,7 +2296,7 @@ export class Clerk implements ClerkInterface {
  return null;
  };
 
- public handleGoogleOneTapCallback = async (
+ public __internal_handleResourceCallback = async (
  signInOrUp: SignInResource | SignUpResource,
  params: HandleOAuthCallbackParams,
  customNavigate?: (to: string) => Promise<unknown>,
@@ -2310,6 +2321,14 @@ export class Clerk implements ClerkInterface {
  });
  };
 
+ public handleGoogleOneTapCallback = async (
+ signInOrUp: SignInResource | SignUpResource,
+ params: HandleOAuthCallbackParams,
+ customNavigate?: (to: string) => Promise<unknown>,
+ ): Promise<unknown> => {
+ return this.__internal_handleResourceCallback(signInOrUp, params, customNavigate);
+ };
+
  private _handleRedirectCallback = async (
  params: HandleOAuthCallbackParams,
  {
@@ -2421,6 +2440,7 @@ export class Clerk implements ClerkInterface {
 
  const signInUrl = params.signInUrl || displayConfig.signInUrl;
  const signUpUrl = params.signUpUrl || displayConfig.signUpUrl;
+ const internalNavigateOnSetActive = params.__internal_navigateOnSetActive;
 
  const setActiveNavigate = async ({
  session,
@@ -2431,6 +2451,15 @@ export class Clerk implements ClerkInterface {
  baseUrl: string;
  redirectUrl: string;
  }) => {
+ if (internalNavigateOnSetActive) {
+ await internalNavigateOnSetActive({
+ session,
+ redirectUrl,
+ decorateUrl: url => this.buildUrlWithAuth(url),
+ });
+ return;
+ }
+
  if (!session.currentTask) {
  await this.navigate(redirectUrl);
  return;
@@ -2446,7 +2475,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: si.sessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signInUrl, redirectUrl: redirectUrls.getAfterSignInUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signInUrl,
+ redirectUrl: redirectUrls.getAfterSignInUrl(),
+ });
  },
  });
  }
@@ -2461,7 +2494,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: res.createdSessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignInUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignInUrl(),
+ });
  },
  });
  case 'needs_first_factor':
@@ -2512,7 +2549,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: res.createdSessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignUpUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignUpUrl(),
+ });
  },
  });
  case 'missing_requirements':
@@ -2526,7 +2567,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: su.sessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignUpUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignUpUrl(),
+ });
  },
  });
  }

packages/clerk-js/src/core/resources/SignIn.ts

@@ -83,6 +83,7 @@ import {
  _futureAuthenticateWithPopup,
  wrapWithPopupRoutes,
 } from '../../utils/authenticateWithPopup';
+import { _authenticateWithTransport } from '../../utils/authenticateWithTransport';
 import { CaptchaChallenge } from '../../utils/captcha/CaptchaChallenge';
 import { runAsyncResourceTask } from '../../utils/runAsyncResourceTask';
 import { loadZxcvbn } from '../../utils/zxcvbn';
@@ -379,6 +380,18 @@ export class SignIn extends BaseResource implements SignInResource {
  };
 
  public authenticateWithRedirect = async (params: AuthenticateWithRedirectParams): Promise<void> => {
+ const transport = SignIn.clerk.__internal_oauthTransport;
+ if (transport) {
+ return _authenticateWithTransport({
+ clerk: SignIn.clerk,
+ transport,
+ resource: this,
+ authenticateMethod: this.authenticateWithRedirectOrPopup,
+ params,
+ callbackParams: params.__internal_callbackParams ?? {},
+ });
+ }
+
  return this.authenticateWithRedirectOrPopup(params, windowNavigate);
  };
 

packages/clerk-js/src/core/resources/SignUp.ts

@@ -54,6 +54,7 @@ import {
  _futureAuthenticateWithPopup,
  wrapWithPopupRoutes,
 } from '../../utils/authenticateWithPopup';
+import { _authenticateWithTransport } from '../../utils/authenticateWithTransport';
 import { CaptchaChallenge } from '../../utils/captcha/CaptchaChallenge';
 import { normalizeUnsafeMetadata } from '../../utils/resourceParams';
 import { runAsyncResourceTask } from '../../utils/runAsyncResourceTask';
@@ -449,6 +450,18 @@ export class SignUp extends BaseResource implements SignUpResource {
  unsafeMetadata?: SignUpUnsafeMetadata;
  },
  ): Promise<void> => {
+ const transport = SignUp.clerk.__internal_oauthTransport;
+ if (transport) {
+ return _authenticateWithTransport({
+ clerk: SignUp.clerk,
+ transport,
+ resource: this,
+ authenticateMethod: this.authenticateWithRedirectOrPopup,
+ params,
+ callbackParams: params.__internal_callbackParams ?? {},
+ });
+ }
+
  return this.authenticateWithRedirectOrPopup(params, windowNavigate);
  };
 

packages/clerk-js/src/core/resources/__tests__/SignIn.test.ts

@@ -34,6 +34,47 @@ describe('SignIn', () => {
  expect(snapshot).toBeDefined();
  });
 
+ describe('authenticateWithRedirect with an OAuth transport', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ SignIn.clerk = {} as any;
+ });
+
+ it('routes through the transport instead of windowNavigate when one is registered', async () => {
+ const open = vi.fn().mockResolvedValue({ callbackUrl: 'myapp://sso-callback' });
+ const handleResourceCallback = vi.fn().mockResolvedValue(undefined);
+ SignIn.clerk = {
+ buildUrlWithAuth: vi.fn(u => u),
+ __internal_oauthTransport: { getRedirectUrl: () => 'myapp://sso-callback', open },
+ __internal_handleResourceCallback: handleResourceCallback,
+ __internal_environment: { displayConfig: { captchaOauthBypass: [] } },
+ } as any;
+
+ const mockFetch = vi.fn().mockResolvedValueOnce({
+ client: null,
+ response: {
+ id: 'signin_123',
+ first_factor_verification: {
+ status: 'unverified',
+ external_verification_redirect_url: 'https://provider.example/auth',
+ },
+ },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const signIn = new SignIn();
+ await signIn.authenticateWithRedirect({
+ strategy: 'oauth_google',
+ redirectUrl: '/sso-callback',
+ redirectUrlComplete: '/',
+ __internal_callbackParams: { signInUrl: '/sign-in' },
+ } as any);
+
+ expect(open).toHaveBeenCalledWith(new URL('https://provider.example/auth'));
+ expect(handleResourceCallback).toHaveBeenCalledWith(signIn, { signInUrl: '/sign-in' });
+ });
+ });
+
  describe('signIn.create', () => {
  afterEach(() => {
  vi.clearAllMocks();

.changeset/oauth-transport.md

@@ -0,0 +1,8 @@
+---
+'@clerk/shared': minor
+'@clerk/clerk-js': minor
+'@clerk/react': minor
+'@clerk/ui': minor
+---
+
+Add internal OAuth transport support for native desktop SDK wrappers to run Clerk's prebuilt OAuth flows through a system browser.

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -158,6 +158,41 @@ describe('Clerk singleton', () => {
  });
  });
 
+ describe('__internal_oauthTransport', () => {
+ it('defaults to null with no getter access errors', () => {
+ const sut = new Clerk(productionPublishableKey);
+
+ expect(sut.__internal_hasOAuthTransport).toBe(false);
+ expect(sut.__internal_oauthTransport).toBeNull();
+ });
+
+ it('exposes the transport registered via options after load', async () => {
+ const transport = {
+ getRedirectUrl: () => 'myapp://sso-callback',
+ open: async (_url: URL) => ({ callbackUrl: 'myapp://sso-callback' }),
+ };
+ const sut = new Clerk(productionPublishableKey);
+
+ await sut.load({ __internal_oauthTransport: transport });
+
+ expect(sut.__internal_hasOAuthTransport).toBe(true);
+ expect(sut.__internal_oauthTransport).toBe(transport);
+ });
+ });
+
+ describe('__internal_handleResourceCallback', () => {
+ it('handleGoogleOneTapCallback delegates to __internal_handleResourceCallback', async () => {
+ const clerk = new Clerk(productionPublishableKey);
+ await clerk.load();
+ const spy = vi.spyOn(clerk, '__internal_handleResourceCallback').mockResolvedValue(undefined);
+ const signInLike = { identifier: 'x' } as any;
+
+ await clerk.handleGoogleOneTapCallback(signInLike, { signInUrl: '/sign-in' });
+
+ expect(spy).toHaveBeenCalledWith(signInLike, { signInUrl: '/sign-in' }, undefined);
+ });
+ });
+
  describe('.setActive', () => {
  describe('with `active` session status', () => {
  const mockSession = {
@@ -1205,6 +1240,104 @@ describe('Clerk singleton', () => {
  });
  });
 
+ it('uses __internal_navigateOnSetActive for completed sign in callbacks', async () => {
+ const sessionId = 'sess_123';
+ const mockSession = { id: sessionId, currentTask: null };
+ mockEnvironmentFetch.mockReturnValue(
+ Promise.resolve({
+ authConfig: {},
+ userSettings: mockUserSettings,
+ displayConfig: mockDisplayConfig,
+ isSingleSession: () => false,
+ isProduction: () => false,
+ isDevelopmentOrStaging: () => true,
+ onWindowLocationHost: () => false,
+ }),
+ );
+ mockClientFetch.mockReturnValue(
+ Promise.resolve({
+ signedInSessions: [],
+ signIn: new SignIn({
+ status: 'complete',
+ created_session_id: sessionId,
+ } as any as SignInJSON),
+ signUp: new SignUp(null),
+ }),
+ );
+
+ const internalNavigateOnSetActive = vi.fn(async ({ session, redirectUrl, decorateUrl }) => {
+ expect(session).toBe(mockSession);
+ expect(redirectUrl).toBe('http://test.host/after-sign-in');
+ expect(decorateUrl('/decorated')).toBe('/decorated');
+ });
+ const mockSetActive = vi.fn(async ({ navigate }) => navigate({ session: mockSession }));
+
+ const sut = new Clerk(productionPublishableKey);
+ await sut.load(mockedLoadOptions);
+ sut.setActive = mockSetActive as any;
+
+ await sut.handleRedirectCallback({
+ signInForceRedirectUrl: '/after-sign-in',
+ __internal_navigateOnSetActive: internalNavigateOnSetActive,
+ });
+
+ expect(mockSetActive).toHaveBeenCalledWith({
+ session: sessionId,
+ navigate: expect.any(Function),
+ });
+ expect(internalNavigateOnSetActive).toHaveBeenCalledTimes(1);
+ expect(mockNavigate).not.toHaveBeenCalled();
+ });
+
+ it('uses __internal_navigateOnSetActive for completed sign up callbacks', async () => {
+ const sessionId = 'sess_123';
+ const mockSession = { id: sessionId, currentTask: null };
+ mockEnvironmentFetch.mockReturnValue(
+ Promise.resolve({
+ authConfig: {},
+ userSettings: mockUserSettings,
+ displayConfig: mockDisplayConfig,
+ isSingleSession: () => false,
+ isProduction: () => false,
+ isDevelopmentOrStaging: () => true,
+ onWindowLocationHost: () => false,
+ }),
+ );
+ mockClientFetch.mockReturnValue(
+ Promise.resolve({
+ signedInSessions: [],
+ signIn: new SignIn(null),
+ signUp: new SignUp({
+ status: 'complete',
+ created_session_id: sessionId,
+ } as any as SignUpJSON),
+ }),
+ );
+
+ const internalNavigateOnSetActive = vi.fn(async ({ session, redirectUrl, decorateUrl }) => {
+ expect(session).toBe(mockSession);
+ expect(redirectUrl).toBe('http://test.host/after-sign-up');
+ expect(decorateUrl('/decorated')).toBe('/decorated');
+ });
+ const mockSetActive = vi.fn(async ({ navigate }) => navigate({ session: mockSession }));
+
+ const sut = new Clerk(productionPublishableKey);
+ await sut.load(mockedLoadOptions);
+ sut.setActive = mockSetActive as any;
+
+ await sut.handleRedirectCallback({
+ signUpForceRedirectUrl: '/after-sign-up',
+ __internal_navigateOnSetActive: internalNavigateOnSetActive,
+ });
+
+ expect(mockSetActive).toHaveBeenCalledWith({
+ session: sessionId,
+ navigate: expect.any(Function),
+ });
+ expect(internalNavigateOnSetActive).toHaveBeenCalledTimes(1);
+ expect(mockNavigate).not.toHaveBeenCalled();
+ });
+
  it('does not initiate the transfer flow when transferable: false is passed', async () => {
  mockEnvironmentFetch.mockReturnValue(
  Promise.resolve({

packages/clerk-js/src/core/clerk.ts

@@ -98,6 +98,7 @@ import type {
  LoadedClerk,
  NavigateOptions,
  OAuthApplicationNamespace,
+ OAuthTransport,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -269,6 +270,7 @@ export class Clerk implements ClerkInterface {
  #listeners: Array<(emission: Resources) => void> = [];
  #navigationListeners: Array<() => void> = [];
  #options: ClerkOptions = {};
+ #oauthTransport: OAuthTransport | null = null;
  #pageLifecycle: ReturnType<typeof createPageLifecycle> | null = null;
  #touchThrottledUntil = 0;
  #publicEventBus = createClerkEventBus();
@@ -295,6 +297,14 @@ export class Clerk implements ClerkInterface {
  : undefined;
  }
 
+ get __internal_hasOAuthTransport(): boolean {
+ return this.#oauthTransport !== null;
+ }
+
+ get __internal_oauthTransport(): OAuthTransport | null {
+ return this.#oauthTransport;
+ }
+
  public __internal_getCachedResources:
  | (() => Promise<{ client: ClientJSONSnapshot | null; environment: EnvironmentJSONSnapshot | null }>)
  | undefined;
@@ -529,6 +539,7 @@ export class Clerk implements ClerkInterface {
  }
 
  this.#options = this.#initOptions(options);
+ this.#oauthTransport = this.#options.__internal_oauthTransport ?? null;
 
  // Initialize ClerkUI if it was provided
  if (this.#options.ui?.ClerkUI) {
@@ -2285,7 +2296,7 @@ export class Clerk implements ClerkInterface {
  return null;
  };
 
- public handleGoogleOneTapCallback = async (
+ public __internal_handleResourceCallback = async (
  signInOrUp: SignInResource | SignUpResource,
  params: HandleOAuthCallbackParams,
  customNavigate?: (to: string) => Promise<unknown>,
@@ -2310,6 +2321,14 @@ export class Clerk implements ClerkInterface {
  });
  };
 
+ public handleGoogleOneTapCallback = async (
+ signInOrUp: SignInResource | SignUpResource,
+ params: HandleOAuthCallbackParams,
+ customNavigate?: (to: string) => Promise<unknown>,
+ ): Promise<unknown> => {
+ return this.__internal_handleResourceCallback(signInOrUp, params, customNavigate);
+ };
+
  private _handleRedirectCallback = async (
  params: HandleOAuthCallbackParams,
  {
@@ -2421,6 +2440,7 @@ export class Clerk implements ClerkInterface {
 
  const signInUrl = params.signInUrl || displayConfig.signInUrl;
  const signUpUrl = params.signUpUrl || displayConfig.signUpUrl;
+ const internalNavigateOnSetActive = params.__internal_navigateOnSetActive;
 
  const setActiveNavigate = async ({
  session,
@@ -2431,6 +2451,15 @@ export class Clerk implements ClerkInterface {
  baseUrl: string;
  redirectUrl: string;
  }) => {
+ if (internalNavigateOnSetActive) {
+ await internalNavigateOnSetActive({
+ session,
+ redirectUrl,
+ decorateUrl: url => this.buildUrlWithAuth(url),
+ });
+ return;
+ }
+
  if (!session.currentTask) {
  await this.navigate(redirectUrl);
  return;
@@ -2446,7 +2475,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: si.sessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signInUrl, redirectUrl: redirectUrls.getAfterSignInUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signInUrl,
+ redirectUrl: redirectUrls.getAfterSignInUrl(),
+ });
  },
  });
  }
@@ -2461,7 +2494,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: res.createdSessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignInUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignInUrl(),
+ });
  },
  });
  case 'needs_first_factor':
@@ -2512,7 +2549,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: res.createdSessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignUpUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignUpUrl(),
+ });
  },
  });
  case 'missing_requirements':
@@ -2526,7 +2567,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: su.sessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignUpUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignUpUrl(),
+ });
  },
  });
  }

packages/clerk-js/src/core/resources/SignIn.ts

@@ -83,6 +83,7 @@ import {
  _futureAuthenticateWithPopup,
  wrapWithPopupRoutes,
 } from '../../utils/authenticateWithPopup';
+import { _authenticateWithTransport } from '../../utils/authenticateWithTransport';
 import { CaptchaChallenge } from '../../utils/captcha/CaptchaChallenge';
 import { runAsyncResourceTask } from '../../utils/runAsyncResourceTask';
 import { loadZxcvbn } from '../../utils/zxcvbn';
@@ -379,6 +380,18 @@ export class SignIn extends BaseResource implements SignInResource {
  };
 
  public authenticateWithRedirect = async (params: AuthenticateWithRedirectParams): Promise<void> => {
+ const transport = SignIn.clerk.__internal_oauthTransport;
+ if (transport) {
+ return _authenticateWithTransport({
+ clerk: SignIn.clerk,
+ transport,
+ resource: this,
+ authenticateMethod: this.authenticateWithRedirectOrPopup,
+ params,
+ callbackParams: params.__internal_callbackParams ?? {},
+ });
+ }
+
  return this.authenticateWithRedirectOrPopup(params, windowNavigate);
  };
 

packages/clerk-js/src/core/resources/SignUp.ts

@@ -54,6 +54,7 @@ import {
  _futureAuthenticateWithPopup,
  wrapWithPopupRoutes,
 } from '../../utils/authenticateWithPopup';
+import { _authenticateWithTransport } from '../../utils/authenticateWithTransport';
 import { CaptchaChallenge } from '../../utils/captcha/CaptchaChallenge';
 import { normalizeUnsafeMetadata } from '../../utils/resourceParams';
 import { runAsyncResourceTask } from '../../utils/runAsyncResourceTask';
@@ -449,6 +450,18 @@ export class SignUp extends BaseResource implements SignUpResource {
  unsafeMetadata?: SignUpUnsafeMetadata;
  },
  ): Promise<void> => {
+ const transport = SignUp.clerk.__internal_oauthTransport;
+ if (transport) {
+ return _authenticateWithTransport({
+ clerk: SignUp.clerk,
+ transport,
+ resource: this,
+ authenticateMethod: this.authenticateWithRedirectOrPopup,
+ params,
+ callbackParams: params.__internal_callbackParams ?? {},
+ });
+ }
+
  return this.authenticateWithRedirectOrPopup(params, windowNavigate);
  };
 

packages/clerk-js/src/core/resources/__tests__/SignIn.test.ts

@@ -34,6 +34,47 @@ describe('SignIn', () => {
  expect(snapshot).toBeDefined();
  });
 
+ describe('authenticateWithRedirect with an OAuth transport', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ SignIn.clerk = {} as any;
+ });
+
+ it('routes through the transport instead of windowNavigate when one is registered', async () => {
+ const open = vi.fn().mockResolvedValue({ callbackUrl: 'myapp://sso-callback' });
+ const handleResourceCallback = vi.fn().mockResolvedValue(undefined);
+ SignIn.clerk = {
+ buildUrlWithAuth: vi.fn(u => u),
+ __internal_oauthTransport: { getRedirectUrl: () => 'myapp://sso-callback', open },
+ __internal_handleResourceCallback: handleResourceCallback,
+ __internal_environment: { displayConfig: { captchaOauthBypass: [] } },
+ } as any;
+
+ const mockFetch = vi.fn().mockResolvedValueOnce({
+ client: null,
+ response: {
+ id: 'signin_123',
+ first_factor_verification: {
+ status: 'unverified',
+ external_verification_redirect_url: 'https://provider.example/auth',
+ },
+ },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const signIn = new SignIn();
+ await signIn.authenticateWithRedirect({
+ strategy: 'oauth_google',
+ redirectUrl: '/sso-callback',
+ redirectUrlComplete: '/',
+ __internal_callbackParams: { signInUrl: '/sign-in' },
+ } as any);
+
+ expect(open).toHaveBeenCalledWith(new URL('https://provider.example/auth'));
+ expect(handleResourceCallback).toHaveBeenCalledWith(signIn, { signInUrl: '/sign-in' });
+ });
+ });
+
  describe('signIn.create', () => {
  afterEach(() => {
  vi.clearAllMocks();

.changeset/oauth-transport.md

@@ -0,0 +1,8 @@
+---
+'@clerk/shared': minor
+'@clerk/clerk-js': minor
+'@clerk/react': minor
+'@clerk/ui': minor
+---
+
+Add internal OAuth transport support for native desktop SDK wrappers to run Clerk's prebuilt OAuth flows through a system browser.

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -158,6 +158,41 @@ describe('Clerk singleton', () => {
  });
  });
 
+ describe('__internal_oauthTransport', () => {
+ it('defaults to null with no getter access errors', () => {
+ const sut = new Clerk(productionPublishableKey);
+
+ expect(sut.__internal_hasOAuthTransport).toBe(false);
+ expect(sut.__internal_oauthTransport).toBeNull();
+ });
+
+ it('exposes the transport registered via options after load', async () => {
+ const transport = {
+ getRedirectUrl: () => 'myapp://sso-callback',
+ open: async (_url: URL) => ({ callbackUrl: 'myapp://sso-callback' }),
+ };
+ const sut = new Clerk(productionPublishableKey);
+
+ await sut.load({ __internal_oauthTransport: transport });
+
+ expect(sut.__internal_hasOAuthTransport).toBe(true);
+ expect(sut.__internal_oauthTransport).toBe(transport);
+ });
+ });
+
+ describe('__internal_handleResourceCallback', () => {
+ it('handleGoogleOneTapCallback delegates to __internal_handleResourceCallback', async () => {
+ const clerk = new Clerk(productionPublishableKey);
+ await clerk.load();
+ const spy = vi.spyOn(clerk, '__internal_handleResourceCallback').mockResolvedValue(undefined);
+ const signInLike = { identifier: 'x' } as any;
+
+ await clerk.handleGoogleOneTapCallback(signInLike, { signInUrl: '/sign-in' });
+
+ expect(spy).toHaveBeenCalledWith(signInLike, { signInUrl: '/sign-in' }, undefined);
+ });
+ });
+
  describe('.setActive', () => {
  describe('with `active` session status', () => {
  const mockSession = {
@@ -1205,6 +1240,104 @@ describe('Clerk singleton', () => {
  });
  });
 
+ it('uses __internal_navigateOnSetActive for completed sign in callbacks', async () => {
+ const sessionId = 'sess_123';
+ const mockSession = { id: sessionId, currentTask: null };
+ mockEnvironmentFetch.mockReturnValue(
+ Promise.resolve({
+ authConfig: {},
+ userSettings: mockUserSettings,
+ displayConfig: mockDisplayConfig,
+ isSingleSession: () => false,
+ isProduction: () => false,
+ isDevelopmentOrStaging: () => true,
+ onWindowLocationHost: () => false,
+ }),
+ );
+ mockClientFetch.mockReturnValue(
+ Promise.resolve({
+ signedInSessions: [],
+ signIn: new SignIn({
+ status: 'complete',
+ created_session_id: sessionId,
+ } as any as SignInJSON),
+ signUp: new SignUp(null),
+ }),
+ );
+
+ const internalNavigateOnSetActive = vi.fn(async ({ session, redirectUrl, decorateUrl }) => {
+ expect(session).toBe(mockSession);
+ expect(redirectUrl).toBe('http://test.host/after-sign-in');
+ expect(decorateUrl('/decorated')).toBe('/decorated');
+ });
+ const mockSetActive = vi.fn(async ({ navigate }) => navigate({ session: mockSession }));
+
+ const sut = new Clerk(productionPublishableKey);
+ await sut.load(mockedLoadOptions);
+ sut.setActive = mockSetActive as any;
+
+ await sut.handleRedirectCallback({
+ signInForceRedirectUrl: '/after-sign-in',
+ __internal_navigateOnSetActive: internalNavigateOnSetActive,
+ });
+
+ expect(mockSetActive).toHaveBeenCalledWith({
+ session: sessionId,
+ navigate: expect.any(Function),
+ });
+ expect(internalNavigateOnSetActive).toHaveBeenCalledTimes(1);
+ expect(mockNavigate).not.toHaveBeenCalled();
+ });
+
+ it('uses __internal_navigateOnSetActive for completed sign up callbacks', async () => {
+ const sessionId = 'sess_123';
+ const mockSession = { id: sessionId, currentTask: null };
+ mockEnvironmentFetch.mockReturnValue(
+ Promise.resolve({
+ authConfig: {},
+ userSettings: mockUserSettings,
+ displayConfig: mockDisplayConfig,
+ isSingleSession: () => false,
+ isProduction: () => false,
+ isDevelopmentOrStaging: () => true,
+ onWindowLocationHost: () => false,
+ }),
+ );
+ mockClientFetch.mockReturnValue(
+ Promise.resolve({
+ signedInSessions: [],
+ signIn: new SignIn(null),
+ signUp: new SignUp({
+ status: 'complete',
+ created_session_id: sessionId,
+ } as any as SignUpJSON),
+ }),
+ );
+
+ const internalNavigateOnSetActive = vi.fn(async ({ session, redirectUrl, decorateUrl }) => {
+ expect(session).toBe(mockSession);
+ expect(redirectUrl).toBe('http://test.host/after-sign-up');
+ expect(decorateUrl('/decorated')).toBe('/decorated');
+ });
+ const mockSetActive = vi.fn(async ({ navigate }) => navigate({ session: mockSession }));
+
+ const sut = new Clerk(productionPublishableKey);
+ await sut.load(mockedLoadOptions);
+ sut.setActive = mockSetActive as any;
+
+ await sut.handleRedirectCallback({
+ signUpForceRedirectUrl: '/after-sign-up',
+ __internal_navigateOnSetActive: internalNavigateOnSetActive,
+ });
+
+ expect(mockSetActive).toHaveBeenCalledWith({
+ session: sessionId,
+ navigate: expect.any(Function),
+ });
+ expect(internalNavigateOnSetActive).toHaveBeenCalledTimes(1);
+ expect(mockNavigate).not.toHaveBeenCalled();
+ });
+
  it('does not initiate the transfer flow when transferable: false is passed', async () => {
  mockEnvironmentFetch.mockReturnValue(
  Promise.resolve({

packages/clerk-js/src/core/clerk.ts

@@ -98,6 +98,7 @@ import type {
  LoadedClerk,
  NavigateOptions,
  OAuthApplicationNamespace,
+ OAuthTransport,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -269,6 +270,7 @@ export class Clerk implements ClerkInterface {
  #listeners: Array<(emission: Resources) => void> = [];
  #navigationListeners: Array<() => void> = [];
  #options: ClerkOptions = {};
+ #oauthTransport: OAuthTransport | null = null;
  #pageLifecycle: ReturnType<typeof createPageLifecycle> | null = null;
  #touchThrottledUntil = 0;
  #publicEventBus = createClerkEventBus();
@@ -295,6 +297,14 @@ export class Clerk implements ClerkInterface {
  : undefined;
  }
 
+ get __internal_hasOAuthTransport(): boolean {
+ return this.#oauthTransport !== null;
+ }
+
+ get __internal_oauthTransport(): OAuthTransport | null {
+ return this.#oauthTransport;
+ }
+
  public __internal_getCachedResources:
  | (() => Promise<{ client: ClientJSONSnapshot | null; environment: EnvironmentJSONSnapshot | null }>)
  | undefined;
@@ -529,6 +539,7 @@ export class Clerk implements ClerkInterface {
  }
 
  this.#options = this.#initOptions(options);
+ this.#oauthTransport = this.#options.__internal_oauthTransport ?? null;
 
  // Initialize ClerkUI if it was provided
  if (this.#options.ui?.ClerkUI) {
@@ -2285,7 +2296,7 @@ export class Clerk implements ClerkInterface {
  return null;
  };
 
- public handleGoogleOneTapCallback = async (
+ public __internal_handleResourceCallback = async (
  signInOrUp: SignInResource | SignUpResource,
  params: HandleOAuthCallbackParams,
  customNavigate?: (to: string) => Promise<unknown>,
@@ -2310,6 +2321,14 @@ export class Clerk implements ClerkInterface {
  });
  };
 
+ public handleGoogleOneTapCallback = async (
+ signInOrUp: SignInResource | SignUpResource,
+ params: HandleOAuthCallbackParams,
+ customNavigate?: (to: string) => Promise<unknown>,
+ ): Promise<unknown> => {
+ return this.__internal_handleResourceCallback(signInOrUp, params, customNavigate);
+ };
+
  private _handleRedirectCallback = async (
  params: HandleOAuthCallbackParams,
  {
@@ -2421,6 +2440,7 @@ export class Clerk implements ClerkInterface {
 
  const signInUrl = params.signInUrl || displayConfig.signInUrl;
  const signUpUrl = params.signUpUrl || displayConfig.signUpUrl;
+ const internalNavigateOnSetActive = params.__internal_navigateOnSetActive;
 
  const setActiveNavigate = async ({
  session,
@@ -2431,6 +2451,15 @@ export class Clerk implements ClerkInterface {
  baseUrl: string;
  redirectUrl: string;
  }) => {
+ if (internalNavigateOnSetActive) {
+ await internalNavigateOnSetActive({
+ session,
+ redirectUrl,
+ decorateUrl: url => this.buildUrlWithAuth(url),
+ });
+ return;
+ }
+
  if (!session.currentTask) {
  await this.navigate(redirectUrl);
  return;
@@ -2446,7 +2475,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: si.sessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signInUrl, redirectUrl: redirectUrls.getAfterSignInUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signInUrl,
+ redirectUrl: redirectUrls.getAfterSignInUrl(),
+ });
  },
  });
  }
@@ -2461,7 +2494,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: res.createdSessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignInUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignInUrl(),
+ });
  },
  });
  case 'needs_first_factor':
@@ -2512,7 +2549,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: res.createdSessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignUpUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignUpUrl(),
+ });
  },
  });
  case 'missing_requirements':
@@ -2526,7 +2567,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: su.sessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignUpUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignUpUrl(),
+ });
  },
  });
  }

packages/clerk-js/src/core/resources/SignIn.ts

@@ -83,6 +83,7 @@ import {
  _futureAuthenticateWithPopup,
  wrapWithPopupRoutes,
 } from '../../utils/authenticateWithPopup';
+import { _authenticateWithTransport } from '../../utils/authenticateWithTransport';
 import { CaptchaChallenge } from '../../utils/captcha/CaptchaChallenge';
 import { runAsyncResourceTask } from '../../utils/runAsyncResourceTask';
 import { loadZxcvbn } from '../../utils/zxcvbn';
@@ -379,6 +380,18 @@ export class SignIn extends BaseResource implements SignInResource {
  };
 
  public authenticateWithRedirect = async (params: AuthenticateWithRedirectParams): Promise<void> => {
+ const transport = SignIn.clerk.__internal_oauthTransport;
+ if (transport) {
+ return _authenticateWithTransport({
+ clerk: SignIn.clerk,
+ transport,
+ resource: this,
+ authenticateMethod: this.authenticateWithRedirectOrPopup,
+ params,
+ callbackParams: params.__internal_callbackParams ?? {},
+ });
+ }
+
  return this.authenticateWithRedirectOrPopup(params, windowNavigate);
  };
 

packages/clerk-js/src/core/resources/SignUp.ts

@@ -54,6 +54,7 @@ import {
  _futureAuthenticateWithPopup,
  wrapWithPopupRoutes,
 } from '../../utils/authenticateWithPopup';
+import { _authenticateWithTransport } from '../../utils/authenticateWithTransport';
 import { CaptchaChallenge } from '../../utils/captcha/CaptchaChallenge';
 import { normalizeUnsafeMetadata } from '../../utils/resourceParams';
 import { runAsyncResourceTask } from '../../utils/runAsyncResourceTask';
@@ -449,6 +450,18 @@ export class SignUp extends BaseResource implements SignUpResource {
  unsafeMetadata?: SignUpUnsafeMetadata;
  },
  ): Promise<void> => {
+ const transport = SignUp.clerk.__internal_oauthTransport;
+ if (transport) {
+ return _authenticateWithTransport({
+ clerk: SignUp.clerk,
+ transport,
+ resource: this,
+ authenticateMethod: this.authenticateWithRedirectOrPopup,
+ params,
+ callbackParams: params.__internal_callbackParams ?? {},
+ });
+ }
+
  return this.authenticateWithRedirectOrPopup(params, windowNavigate);
  };
 

packages/clerk-js/src/core/resources/__tests__/SignIn.test.ts

@@ -34,6 +34,47 @@ describe('SignIn', () => {
  expect(snapshot).toBeDefined();
  });
 
+ describe('authenticateWithRedirect with an OAuth transport', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ SignIn.clerk = {} as any;
+ });
+
+ it('routes through the transport instead of windowNavigate when one is registered', async () => {
+ const open = vi.fn().mockResolvedValue({ callbackUrl: 'myapp://sso-callback' });
+ const handleResourceCallback = vi.fn().mockResolvedValue(undefined);
+ SignIn.clerk = {
+ buildUrlWithAuth: vi.fn(u => u),
+ __internal_oauthTransport: { getRedirectUrl: () => 'myapp://sso-callback', open },
+ __internal_handleResourceCallback: handleResourceCallback,
+ __internal_environment: { displayConfig: { captchaOauthBypass: [] } },
+ } as any;
+
+ const mockFetch = vi.fn().mockResolvedValueOnce({
+ client: null,
+ response: {
+ id: 'signin_123',
+ first_factor_verification: {
+ status: 'unverified',
+ external_verification_redirect_url: 'https://provider.example/auth',
+ },
+ },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const signIn = new SignIn();
+ await signIn.authenticateWithRedirect({
+ strategy: 'oauth_google',
+ redirectUrl: '/sso-callback',
+ redirectUrlComplete: '/',
+ __internal_callbackParams: { signInUrl: '/sign-in' },
+ } as any);
+
+ expect(open).toHaveBeenCalledWith(new URL('https://provider.example/auth'));
+ expect(handleResourceCallback).toHaveBeenCalledWith(signIn, { signInUrl: '/sign-in' });
+ });
+ });
+
  describe('signIn.create', () => {
  afterEach(() => {
  vi.clearAllMocks();

.changeset/oauth-transport.md

@@ -0,0 +1,8 @@
+---
+'@clerk/shared': minor
+'@clerk/clerk-js': minor
+'@clerk/react': minor
+'@clerk/ui': minor
+---
+
+Add internal OAuth transport support for native desktop SDK wrappers to run Clerk's prebuilt OAuth flows through a system browser.

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -158,6 +158,41 @@ describe('Clerk singleton', () => {
  });
  });
 
+ describe('__internal_oauthTransport', () => {
+ it('defaults to null with no getter access errors', () => {
+ const sut = new Clerk(productionPublishableKey);
+
+ expect(sut.__internal_hasOAuthTransport).toBe(false);
+ expect(sut.__internal_oauthTransport).toBeNull();
+ });
+
+ it('exposes the transport registered via options after load', async () => {
+ const transport = {
+ getRedirectUrl: () => 'myapp://sso-callback',
+ open: async (_url: URL) => ({ callbackUrl: 'myapp://sso-callback' }),
+ };
+ const sut = new Clerk(productionPublishableKey);
+
+ await sut.load({ __internal_oauthTransport: transport });
+
+ expect(sut.__internal_hasOAuthTransport).toBe(true);
+ expect(sut.__internal_oauthTransport).toBe(transport);
+ });
+ });
+
+ describe('__internal_handleResourceCallback', () => {
+ it('handleGoogleOneTapCallback delegates to __internal_handleResourceCallback', async () => {
+ const clerk = new Clerk(productionPublishableKey);
+ await clerk.load();
+ const spy = vi.spyOn(clerk, '__internal_handleResourceCallback').mockResolvedValue(undefined);
+ const signInLike = { identifier: 'x' } as any;
+
+ await clerk.handleGoogleOneTapCallback(signInLike, { signInUrl: '/sign-in' });
+
+ expect(spy).toHaveBeenCalledWith(signInLike, { signInUrl: '/sign-in' }, undefined);
+ });
+ });
+
  describe('.setActive', () => {
  describe('with `active` session status', () => {
  const mockSession = {
@@ -1205,6 +1240,104 @@ describe('Clerk singleton', () => {
  });
  });
 
+ it('uses __internal_navigateOnSetActive for completed sign in callbacks', async () => {
+ const sessionId = 'sess_123';
+ const mockSession = { id: sessionId, currentTask: null };
+ mockEnvironmentFetch.mockReturnValue(
+ Promise.resolve({
+ authConfig: {},
+ userSettings: mockUserSettings,
+ displayConfig: mockDisplayConfig,
+ isSingleSession: () => false,
+ isProduction: () => false,
+ isDevelopmentOrStaging: () => true,
+ onWindowLocationHost: () => false,
+ }),
+ );
+ mockClientFetch.mockReturnValue(
+ Promise.resolve({
+ signedInSessions: [],
+ signIn: new SignIn({
+ status: 'complete',
+ created_session_id: sessionId,
+ } as any as SignInJSON),
+ signUp: new SignUp(null),
+ }),
+ );
+
+ const internalNavigateOnSetActive = vi.fn(async ({ session, redirectUrl, decorateUrl }) => {
+ expect(session).toBe(mockSession);
+ expect(redirectUrl).toBe('http://test.host/after-sign-in');
+ expect(decorateUrl('/decorated')).toBe('/decorated');
+ });
+ const mockSetActive = vi.fn(async ({ navigate }) => navigate({ session: mockSession }));
+
+ const sut = new Clerk(productionPublishableKey);
+ await sut.load(mockedLoadOptions);
+ sut.setActive = mockSetActive as any;
+
+ await sut.handleRedirectCallback({
+ signInForceRedirectUrl: '/after-sign-in',
+ __internal_navigateOnSetActive: internalNavigateOnSetActive,
+ });
+
+ expect(mockSetActive).toHaveBeenCalledWith({
+ session: sessionId,
+ navigate: expect.any(Function),
+ });
+ expect(internalNavigateOnSetActive).toHaveBeenCalledTimes(1);
+ expect(mockNavigate).not.toHaveBeenCalled();
+ });
+
+ it('uses __internal_navigateOnSetActive for completed sign up callbacks', async () => {
+ const sessionId = 'sess_123';
+ const mockSession = { id: sessionId, currentTask: null };
+ mockEnvironmentFetch.mockReturnValue(
+ Promise.resolve({
+ authConfig: {},
+ userSettings: mockUserSettings,
+ displayConfig: mockDisplayConfig,
+ isSingleSession: () => false,
+ isProduction: () => false,
+ isDevelopmentOrStaging: () => true,
+ onWindowLocationHost: () => false,
+ }),
+ );
+ mockClientFetch.mockReturnValue(
+ Promise.resolve({
+ signedInSessions: [],
+ signIn: new SignIn(null),
+ signUp: new SignUp({
+ status: 'complete',
+ created_session_id: sessionId,
+ } as any as SignUpJSON),
+ }),
+ );
+
+ const internalNavigateOnSetActive = vi.fn(async ({ session, redirectUrl, decorateUrl }) => {
+ expect(session).toBe(mockSession);
+ expect(redirectUrl).toBe('http://test.host/after-sign-up');
+ expect(decorateUrl('/decorated')).toBe('/decorated');
+ });
+ const mockSetActive = vi.fn(async ({ navigate }) => navigate({ session: mockSession }));
+
+ const sut = new Clerk(productionPublishableKey);
+ await sut.load(mockedLoadOptions);
+ sut.setActive = mockSetActive as any;
+
+ await sut.handleRedirectCallback({
+ signUpForceRedirectUrl: '/after-sign-up',
+ __internal_navigateOnSetActive: internalNavigateOnSetActive,
+ });
+
+ expect(mockSetActive).toHaveBeenCalledWith({
+ session: sessionId,
+ navigate: expect.any(Function),
+ });
+ expect(internalNavigateOnSetActive).toHaveBeenCalledTimes(1);
+ expect(mockNavigate).not.toHaveBeenCalled();
+ });
+
  it('does not initiate the transfer flow when transferable: false is passed', async () => {
  mockEnvironmentFetch.mockReturnValue(
  Promise.resolve({

packages/clerk-js/src/core/clerk.ts

@@ -98,6 +98,7 @@ import type {
  LoadedClerk,
  NavigateOptions,
  OAuthApplicationNamespace,
+ OAuthTransport,
  OrganizationListProps,
  OrganizationProfileProps,
  OrganizationResource,
@@ -269,6 +270,7 @@ export class Clerk implements ClerkInterface {
  #listeners: Array<(emission: Resources) => void> = [];
  #navigationListeners: Array<() => void> = [];
  #options: ClerkOptions = {};
+ #oauthTransport: OAuthTransport | null = null;
  #pageLifecycle: ReturnType<typeof createPageLifecycle> | null = null;
  #touchThrottledUntil = 0;
  #publicEventBus = createClerkEventBus();
@@ -295,6 +297,14 @@ export class Clerk implements ClerkInterface {
  : undefined;
  }
 
+ get __internal_hasOAuthTransport(): boolean {
+ return this.#oauthTransport !== null;
+ }
+
+ get __internal_oauthTransport(): OAuthTransport | null {
+ return this.#oauthTransport;
+ }
+
  public __internal_getCachedResources:
  | (() => Promise<{ client: ClientJSONSnapshot | null; environment: EnvironmentJSONSnapshot | null }>)
  | undefined;
@@ -529,6 +539,7 @@ export class Clerk implements ClerkInterface {
  }
 
  this.#options = this.#initOptions(options);
+ this.#oauthTransport = this.#options.__internal_oauthTransport ?? null;
 
  // Initialize ClerkUI if it was provided
  if (this.#options.ui?.ClerkUI) {
@@ -2285,7 +2296,7 @@ export class Clerk implements ClerkInterface {
  return null;
  };
 
- public handleGoogleOneTapCallback = async (
+ public __internal_handleResourceCallback = async (
  signInOrUp: SignInResource | SignUpResource,
  params: HandleOAuthCallbackParams,
  customNavigate?: (to: string) => Promise<unknown>,
@@ -2310,6 +2321,14 @@ export class Clerk implements ClerkInterface {
  });
  };
 
+ public handleGoogleOneTapCallback = async (
+ signInOrUp: SignInResource | SignUpResource,
+ params: HandleOAuthCallbackParams,
+ customNavigate?: (to: string) => Promise<unknown>,
+ ): Promise<unknown> => {
+ return this.__internal_handleResourceCallback(signInOrUp, params, customNavigate);
+ };
+
  private _handleRedirectCallback = async (
  params: HandleOAuthCallbackParams,
  {
@@ -2421,6 +2440,7 @@ export class Clerk implements ClerkInterface {
 
  const signInUrl = params.signInUrl || displayConfig.signInUrl;
  const signUpUrl = params.signUpUrl || displayConfig.signUpUrl;
+ const internalNavigateOnSetActive = params.__internal_navigateOnSetActive;
 
  const setActiveNavigate = async ({
  session,
@@ -2431,6 +2451,15 @@ export class Clerk implements ClerkInterface {
  baseUrl: string;
  redirectUrl: string;
  }) => {
+ if (internalNavigateOnSetActive) {
+ await internalNavigateOnSetActive({
+ session,
+ redirectUrl,
+ decorateUrl: url => this.buildUrlWithAuth(url),
+ });
+ return;
+ }
+
  if (!session.currentTask) {
  await this.navigate(redirectUrl);
  return;
@@ -2446,7 +2475,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: si.sessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signInUrl, redirectUrl: redirectUrls.getAfterSignInUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signInUrl,
+ redirectUrl: redirectUrls.getAfterSignInUrl(),
+ });
  },
  });
  }
@@ -2461,7 +2494,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: res.createdSessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignInUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignInUrl(),
+ });
  },
  });
  case 'needs_first_factor':
@@ -2512,7 +2549,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: res.createdSessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignUpUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignUpUrl(),
+ });
  },
  });
  case 'missing_requirements':
@@ -2526,7 +2567,11 @@ export class Clerk implements ClerkInterface {
  return this.setActive({
  session: su.sessionId,
  navigate: async ({ session }) => {
- await setActiveNavigate({ session, baseUrl: signUpUrl, redirectUrl: redirectUrls.getAfterSignUpUrl() });
+ await setActiveNavigate({
+ session,
+ baseUrl: signUpUrl,
+ redirectUrl: redirectUrls.getAfterSignUpUrl(),
+ });
  },
  });
  }

packages/clerk-js/src/core/resources/SignIn.ts

@@ -83,6 +83,7 @@ import {
  _futureAuthenticateWithPopup,
  wrapWithPopupRoutes,
 } from '../../utils/authenticateWithPopup';
+import { _authenticateWithTransport } from '../../utils/authenticateWithTransport';
 import { CaptchaChallenge } from '../../utils/captcha/CaptchaChallenge';
 import { runAsyncResourceTask } from '../../utils/runAsyncResourceTask';
 import { loadZxcvbn } from '../../utils/zxcvbn';
@@ -379,6 +380,18 @@ export class SignIn extends BaseResource implements SignInResource {
  };
 
  public authenticateWithRedirect = async (params: AuthenticateWithRedirectParams): Promise<void> => {
+ const transport = SignIn.clerk.__internal_oauthTransport;
+ if (transport) {
+ return _authenticateWithTransport({
+ clerk: SignIn.clerk,
+ transport,
+ resource: this,
+ authenticateMethod: this.authenticateWithRedirectOrPopup,
+ params,
+ callbackParams: params.__internal_callbackParams ?? {},
+ });
+ }
+
  return this.authenticateWithRedirectOrPopup(params, windowNavigate);
  };
 

packages/clerk-js/src/core/resources/SignUp.ts

@@ -54,6 +54,7 @@ import {
  _futureAuthenticateWithPopup,
  wrapWithPopupRoutes,
 } from '../../utils/authenticateWithPopup';
+import { _authenticateWithTransport } from '../../utils/authenticateWithTransport';
 import { CaptchaChallenge } from '../../utils/captcha/CaptchaChallenge';
 import { normalizeUnsafeMetadata } from '../../utils/resourceParams';
 import { runAsyncResourceTask } from '../../utils/runAsyncResourceTask';
@@ -449,6 +450,18 @@ export class SignUp extends BaseResource implements SignUpResource {
  unsafeMetadata?: SignUpUnsafeMetadata;
  },
  ): Promise<void> => {
+ const transport = SignUp.clerk.__internal_oauthTransport;
+ if (transport) {
+ return _authenticateWithTransport({
+ clerk: SignUp.clerk,
+ transport,
+ resource: this,
+ authenticateMethod: this.authenticateWithRedirectOrPopup,
+ params,
+ callbackParams: params.__internal_callbackParams ?? {},
+ });
+ }
+
  return this.authenticateWithRedirectOrPopup(params, windowNavigate);
  };
 

packages/clerk-js/src/core/resources/__tests__/SignIn.test.ts

@@ -34,6 +34,47 @@ describe('SignIn', () => {
  expect(snapshot).toBeDefined();
  });
 
+ describe('authenticateWithRedirect with an OAuth transport', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ SignIn.clerk = {} as any;
+ });
+
+ it('routes through the transport instead of windowNavigate when one is registered', async () => {
+ const open = vi.fn().mockResolvedValue({ callbackUrl: 'myapp://sso-callback' });
+ const handleResourceCallback = vi.fn().mockResolvedValue(undefined);
+ SignIn.clerk = {
+ buildUrlWithAuth: vi.fn(u => u),
+ __internal_oauthTransport: { getRedirectUrl: () => 'myapp://sso-callback', open },
+ __internal_handleResourceCallback: handleResourceCallback,
+ __internal_environment: { displayConfig: { captchaOauthBypass: [] } },
+ } as any;
+
+ const mockFetch = vi.fn().mockResolvedValueOnce({
+ client: null,
+ response: {
+ id: 'signin_123',
+ first_factor_verification: {
+ status: 'unverified',
+ external_verification_redirect_url: 'https://provider.example/auth',
+ },
+ },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const signIn = new SignIn();
+ await signIn.authenticateWithRedirect({
+ strategy: 'oauth_google',
+ redirectUrl: '/sso-callback',
+ redirectUrlComplete: '/',
+ __internal_callbackParams: { signInUrl: '/sign-in' },
+ } as any);
+
+ expect(open).toHaveBeenCalledWith(new URL('https://provider.example/auth'));
+ expect(handleResourceCallback).toHaveBeenCalledWith(signIn, { signInUrl: '/sign-in' });
+ });
+ });
+
  describe('signIn.create', () => {
  afterEach(() => {
  vi.clearAllMocks();