fix(expo): harden hosted auth completion

Author: mikepitre

.changeset/hosted-auth-expo.md

@@ -1,7 +1,5 @@
 ---
 '@clerk/expo': patch
-'@clerk/clerk-js': patch
-'@clerk/shared': patch
 ---
 
 Add `@clerk/expo/hosted-auth` for signing in or signing up through Account Portal from native Expo apps.

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

@@ -151,15 +151,6 @@ describe('buildUrl(options)', () => {
     );
   });
 
-  it('adds rotating token nonce', () => {
-    const url = fapiClient.buildUrl({
-      path: '/client',
-      rotatingTokenNonce: 'nonce_123',
-    });
-
-    expect(url.searchParams.get('rotating_token_nonce')).toBe('nonce_123');
-  });
-
   // The return value isn't as expected.
   // The buildUrl function converts an undefined value to the string 'undefined'
   // and includes it in the search parameters.

packages/expo/src/hooks/__tests__/useHostedAuth.test.ts

@@ -85,6 +85,7 @@ const mockCodeChallenge = 'mock-code-challenge-_';
 describe('useHostedAuth', () => {
   const mockClient = {
     lastActiveSessionId: null as string | null,
+    sessions: [] as Array<{ id: string }>,
     reload: vi.fn(),
     fromJSON: vi.fn(),
   };
@@ -128,8 +129,10 @@ describe('useHostedAuth', () => {
     mocks.platformOS = 'ios';
     mocks.expoConfig = undefined;
     mockClient.lastActiveSessionId = null;
+    mockClient.sessions = [];
     mockClient.fromJSON.mockImplementation((clientJSON: ClientJSON) => {
       mockClient.lastActiveSessionId = clientJSON.last_active_session_id;
+      mockClient.sessions = clientJSON.sessions.map(session => ({ id: session.id }));
       return mockClient;
     });
     mocks.makeRedirectUri.mockReturnValue('myapp:///hosted-auth-callback');
@@ -253,6 +256,28 @@ describe('useHostedAuth', () => {
     expect(mocks.makeRedirectUri).not.toHaveBeenCalled();
   });
 
+  test('uses Expo universal-link callbacks for HTTPS redirect URLs', async () => {
+    const redirectUrl = 'https://mobile.example.com/hosted-auth-callback';
+    mockHostedAuthResponse();
+    mocks.openAuthSessionAsync.mockResolvedValue({
+      type: 'success',
+      url: `${redirectUrl}?state=state-123&rotating_token_nonce=nonce-123&created_session_id=sess_123`,
+    });
+    mockHostedAuthRedeemResponse({ lastActiveSessionId: 'sess_123' });
+
+    const { result } = renderHook(() => useHostedAuth());
+    await result.current.startHostedAuth({
+      redirectUrl,
+      state: 'state-123',
+      authSessionOptions: { showInRecents: true },
+    });
+
+    expect(mocks.openAuthSessionAsync).toHaveBeenCalledWith('https://example.accounts.dev/sign-in', redirectUrl, {
+      preferUniversalLinks: true,
+      showInRecents: true,
+    });
+  });
+
   test('falls back to the reloaded client session when callback session id is absent', async () => {
     mockHostedAuthResponse();
     mocks.openAuthSessionAsync.mockResolvedValue({
@@ -270,7 +295,7 @@ describe('useHostedAuth', () => {
     expect(response.client).toBe(mockClient);
   });
 
-  test('does not activate a session when the callback does not return one', async () => {
+  test('rejects a redeemed client response without a created session', async () => {
     mockHostedAuthResponse();
     mocks.openAuthSessionAsync.mockResolvedValue({
       type: 'success',
@@ -279,15 +304,17 @@ describe('useHostedAuth', () => {
     mockHostedAuthRedeemResponse();
 
     const { result } = renderHook(() => useHostedAuth());
-    const response = await result.current.startHostedAuth({ state: 'state-123' });
+
+    await expect(result.current.startHostedAuth({ state: 'state-123' })).rejects.toThrow(
+      'Hosted auth completion did not include the created session.',
+    );
 
     expect(mockFapiRequest).toHaveBeenNthCalledWith(2, expect.objectContaining({ path: '/client' }));
     expect(mockUpdateClient).toHaveBeenCalledWith(mockClient);
     expect(mockSetActive).not.toHaveBeenCalled();
-    expect(response.createdSessionId).toBeNull();
   });
 
-  test('does not fall back to an existing active session when callback session params are missing', async () => {
+  test('rejects a successful callback without a rotating token nonce', async () => {
     mockClient.lastActiveSessionId = 'sess_existing';
     mockHostedAuthResponse();
     mocks.openAuthSessionAsync.mockResolvedValue({
@@ -296,11 +323,29 @@ describe('useHostedAuth', () => {
     });
 
     const { result } = renderHook(() => useHostedAuth());
-    const response = await result.current.startHostedAuth({ state: 'state-123' });
+
+    await expect(result.current.startHostedAuth({ state: 'state-123' })).rejects.toThrow(
+      'Hosted auth callback did not include a rotating token nonce.',
+    );
 
     expect(mockFapiRequest).toHaveBeenCalledTimes(1);
     expect(mockSetActive).not.toHaveBeenCalled();
-    expect(response.createdSessionId).toBeNull();
+  });
+
+  test('rejects a callback session that is absent from the redeemed client', async () => {
+    mockHostedAuthResponse();
+    mocks.openAuthSessionAsync.mockResolvedValue({
+      type: 'success',
+      url: 'myapp:///hosted-auth-callback?state=state-123&rotating_token_nonce=nonce-123&created_session_id=sess_other',
+    });
+    mockHostedAuthRedeemResponse({ lastActiveSessionId: 'sess_123' });
+
+    const { result } = renderHook(() => useHostedAuth());
+
+    await expect(result.current.startHostedAuth({ state: 'state-123' })).rejects.toThrow(
+      'Hosted auth completion did not include the created session.',
+    );
+    expect(mockSetActive).not.toHaveBeenCalled();
   });
 
   test('surfaces browser session open failures', async () => {
@@ -486,7 +531,13 @@ function mockHostedAuthResponse(url = 'https://example.accounts.dev/sign-in') {
   });
 }
 
-function mockHostedAuthRedeemResponse({ lastActiveSessionId = null }: { lastActiveSessionId?: string | null } = {}) {
+function mockHostedAuthRedeemResponse({
+  lastActiveSessionId = null,
+  sessionIds = lastActiveSessionId ? [lastActiveSessionId] : [],
+}: {
+  lastActiveSessionId?: string | null;
+  sessionIds?: string[];
+} = {}) {
   mockFapiRequest.mockResolvedValueOnce({
     ok: true,
     status: 200,
@@ -495,7 +546,7 @@ function mockHostedAuthRedeemResponse({ lastActiveSessionId = null }: { lastActi
       response: {
         object: 'client',
         id: 'client_123',
-        sessions: [],
+        sessions: sessionIds.map(id => ({ id })),
         sign_in: null,
         sign_up: null,
         last_active_session_id: lastActiveSessionId,

packages/expo/src/hooks/useHostedAuth.ts

@@ -18,10 +18,11 @@ export type HostedAuthMode = 'sign-in' | 'sign-up';
  */
 export type StartHostedAuthParams = {
   /**
-   * Native deep-link URL that Account Portal redirects to after auth completes.
+   * Native callback URL that Account Portal redirects to after auth completes.
    * Defaults to the canonical callback Clerk registers for the configured iOS
    * bundle identifier or Android package name. Expo Go and projects without a
    * configured application identifier fall back to `AuthSession.makeRedirectUri`.
+   * HTTPS callbacks use Expo's universal-link auth session support on iOS.
    */
   redirectUrl?: string;
   /**
@@ -36,9 +37,7 @@ export type StartHostedAuthParams = {
   /**
    * Options forwarded to `expo-web-browser` when opening the hosted auth session.
    */
-  authSessionOptions?: {
-    showInRecents?: boolean;
-  };
+  authSessionOptions?: WebBrowser.AuthSessionOpenOptions;
 };
 
 /**
@@ -57,7 +56,7 @@ export type StartHostedAuthReturnType = {
     url?: string | null;
   } | null;
   /**
-   * The current Clerk client after hosted auth completes.
+   * The current Clerk client after the hosted auth attempt.
    */
   client?: {
     id?: string;
@@ -120,10 +119,14 @@ export function useHostedAuth(): {
       clerk,
     );
 
+    const authSessionOptions =
+      Platform.OS === 'ios' && isHTTPSRedirectUrl(redirectUrl)
+        ? { preferUniversalLinks: true, ...params.authSessionOptions }
+        : params.authSessionOptions;
     const authSessionResult = await WebBrowserModule.openAuthSessionAsync(
       hostedAuth.url,
       redirectUrl,
-      params.authSessionOptions,
+      authSessionOptions,
     );
     if (authSessionResult.type !== 'success' || !authSessionResult.url) {
       return {
@@ -148,30 +151,30 @@ export function useHostedAuth(): {
       return errorThrower.throw('Hosted auth callback state did not match the initiated state.');
     }
 
-    let updatedClient: ClientResource | undefined;
-    let createdSessionId: string | null = null;
     const rotatingTokenNonce = callbackParams.get('rotating_token_nonce') ?? '';
-    if (rotatingTokenNonce) {
-      updatedClient = await redeemHostedAuth(
-        {
-          rotatingTokenNonce,
-          codeVerifier: pkce.codeVerifier,
-        },
-        clerk.client,
-        clerk,
-      );
-      if (updatedClient) {
-        getClientUpdater(clerk)?.(updatedClient);
-        createdSessionId = normalizeSessionId(
-          callbackParams.get('created_session_id') || updatedClient.lastActiveSessionId,
-        );
-      }
+    if (!rotatingTokenNonce) {
+      return errorThrower.throw('Hosted auth callback did not include a rotating token nonce.');
     }
-    if (createdSessionId) {
-      await clerk.setActive({
-        session: createdSessionId,
-      });
+
+    const updatedClient = await redeemHostedAuth(
+      {
+        rotatingTokenNonce,
+        codeVerifier: pkce.codeVerifier,
+      },
+      clerk.client,
+      clerk,
+    );
+    getClientUpdater(clerk)?.(updatedClient);
+
+    const createdSessionId = normalizeSessionId(
+      callbackParams.get('created_session_id') || updatedClient.lastActiveSessionId,
+    );
+    if (!createdSessionId || !updatedClient.sessions.some(session => session.id === createdSessionId)) {
+      return errorThrower.throw('Hosted auth completion did not include the created session.');
     }
+    await clerk.setActive({
+      session: createdSessionId,
+    });
 
     return {
       createdSessionId,
@@ -288,3 +291,11 @@ function callbackUrlMatchesRedirectUrl(callbackUrl: URL, redirectUrl: string): b
 
   return callbackUrl.pathname === expectedUrl.pathname;
 }
+
+function isHTTPSRedirectUrl(redirectUrl: string): boolean {
+  try {
+    return new URL(redirectUrl).protocol === 'https:';
+  } catch {
+    return false;
+  }
+}

packages/expo/src/provider/__tests__/ClerkProvider.nativeClientSync.test.tsx

@@ -1067,7 +1067,6 @@ describe('ClerkProvider native client sync', () => {
 
   test('ignores native client events that echo a JS-originated sync', async () => {
     mocks.tokenCache.getToken.mockResolvedValue(null);
-    mocks.getClientToken.mockResolvedValue(null);
 
     const { rerender } = render(
       <ClerkProvider

packages/expo/src/utils/hostedAuth.ts

@@ -171,8 +171,8 @@ function hasObjectType(payload: unknown, object: string): boolean {
 }
 
 function applyClientJSON(client: ClientResource, clientJSON: ClientJSON): ClientResource {
-  // Hosted auth gets the same /client payload as Client.reload(), but the verifier-bound
-  // exchange is Expo-specific. Apply it to the existing ClerkJS client instance here
+  // Hosted auth gets the same /client payload as Client.reload(), but its verifier-bound
+  // exchange uses a request body. Apply it to the existing ClerkJS client instance here
   // instead of adding a hosted-auth branch to every resource reload path.
   const mutableClient = client as ClientResource & {
     fromJSON?: (data: ClientJSON) => ClientResource;