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();