feat(expo): add experimental useSSO with new hooks

.changeset/bright-taxis-sing.md

@@ -0,0 +1,15 @@
+---
+'@clerk/expo': minor
+---
+
+Add an experimental `useSSO()` hook at `@clerk/expo/experimental` that uses future auth resources and activates completed SSO sessions automatically.
+
+```tsx
+import { useSSO } from '@clerk/expo/experimental';
+
+const { startSSOFlow } = useSSO();
+
+await startSSOFlow({
+  strategy: 'oauth_google',
+});
+```

packages/expo/src/experimental.ts

@@ -1 +1 @@
-export {};
+export * from './hooks/useSSO.experimental';

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

@@ -0,0 +1,33 @@
+import Module from 'node:module';
+
+import { describe, expect, test, vi } from 'vitest';
+
+import { loadSSODependencies } from '../ssoDependencies';
+
+const moduleWithLoad = Module as unknown as {
+  _load: (request: string, parent?: unknown, isMain?: boolean) => unknown;
+};
+const originalModuleLoad = moduleWithLoad._load;
+
+vi.mock('react-native', () => {
+  return {
+    Platform: {
+      OS: 'ios',
+    },
+  };
+});
+
+describe('loadSSODependencies', () => {
+  test('throws install guidance when an optional dependency cannot be loaded', () => {
+    const loadSpy = vi.spyOn(moduleWithLoad, '_load').mockImplementation((request, parent, isMain) => {
+      if (request === 'expo-auth-session') {
+        throw new Error('Cannot find module expo-auth-session');
+      }
+
+      return originalModuleLoad(request, parent, isMain);
+    });
+
+    expect(() => loadSSODependencies()).toThrow(/npx expo install expo-auth-session expo-web-browser/);
+    loadSpy.mockRestore();
+  });
+});

packages/expo/src/hooks/__tests__/useSSO.experimental.test.ts

@@ -0,0 +1,335 @@
+import { renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { useSSO as experimentalUseSSO } from '../../experimental';
+import { useSSO } from '../useSSO.experimental';
+
+const mocks = vi.hoisted(() => {
+  return {
+    useClerk: vi.fn(),
+    useSignIn: vi.fn(),
+    useSignUp: vi.fn(),
+    makeRedirectUri: vi.fn(),
+    openAuthSessionAsync: vi.fn(),
+    loadSSODependencies: vi.fn(),
+  };
+});
+
+vi.mock('@clerk/react', () => {
+  return {
+    useClerk: mocks.useClerk,
+    useSignIn: mocks.useSignIn,
+    useSignUp: mocks.useSignUp,
+  };
+});
+
+vi.mock('../ssoDependencies', () => {
+  return {
+    loadSSODependencies: mocks.loadSSODependencies,
+  };
+});
+
+vi.mock('react-native', () => {
+  return {
+    Platform: {
+      OS: 'ios',
+    },
+  };
+});
+
+describe('experimental useSSO', () => {
+  const mockSetActive = vi.fn();
+  const mockClientSignIn = {
+    reload: vi.fn(),
+  };
+  const mockSignIn = {
+    create: vi.fn(),
+    finalize: vi.fn(),
+    createdSessionId: null as string | null,
+    existingSession: null as { sessionId: string } | null,
+    firstFactorVerification: {
+      externalVerificationRedirectURL: new URL('https://accounts.example.com/sso'),
+      status: 'unverified' as string | null,
+    },
+  };
+  const mockSignUp = {
+    create: vi.fn(),
+    finalize: vi.fn(),
+    createdSessionId: null as string | null,
+    existingSession: null as { sessionId: string } | null,
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    mocks.makeRedirectUri.mockReturnValue('myapp://sso-callback');
+    mocks.openAuthSessionAsync.mockResolvedValue({
+      type: 'success',
+      url: 'myapp://sso-callback?rotating_token_nonce=nonce_123',
+    });
+    mocks.loadSSODependencies.mockReturnValue({
+      AuthSession: {
+        makeRedirectUri: mocks.makeRedirectUri,
+      },
+      WebBrowser: {
+        openAuthSessionAsync: mocks.openAuthSessionAsync,
+      },
+    });
+
+    mockSignIn.createdSessionId = null;
+    mockSignIn.existingSession = null;
+    mockSignIn.firstFactorVerification.externalVerificationRedirectURL = new URL('https://accounts.example.com/sso');
+    mockSignIn.firstFactorVerification.status = 'unverified';
+    mockSignIn.create.mockResolvedValue({ error: null });
+    mockSignIn.finalize.mockResolvedValue({ error: null });
+    mockClientSignIn.reload.mockImplementation(({ rotatingTokenNonce }) => {
+      if (rotatingTokenNonce === 'nonce_123') {
+        mockSignIn.firstFactorVerification.status = 'verified';
+        mockSignIn.createdSessionId = 'sess_123';
+      }
+
+      return Promise.resolve({ __internal_future: mockSignIn });
+    });
+
+    mockSignUp.createdSessionId = null;
+    mockSignUp.existingSession = null;
+    mockSignUp.create.mockResolvedValue({ error: null });
+    mockSignUp.finalize.mockResolvedValue({ error: null });
+
+    mocks.useClerk.mockReturnValue({
+      loaded: true,
+      setActive: mockSetActive,
+      client: {
+        signIn: mockClientSignIn,
+      },
+    });
+    mocks.useSignIn.mockReturnValue({
+      signIn: mockSignIn,
+      fetchStatus: 'idle',
+      errors: {},
+    });
+    mocks.useSignUp.mockReturnValue({
+      signUp: mockSignUp,
+      fetchStatus: 'idle',
+      errors: {},
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test('exports useSSO from the experimental entrypoint', () => {
+    expect(experimentalUseSSO).toBe(useSSO);
+  });
+
+  test('returns the startSSOFlow function', () => {
+    const { result } = renderHook(() => useSSO());
+
+    expect(typeof result.current.startSSOFlow).toBe('function');
+    expect(mocks.useSignIn).toHaveBeenCalled();
+    expect(mocks.useSignUp).toHaveBeenCalled();
+  });
+
+  test('returns early without starting the flow when Clerk is not loaded', async () => {
+    mocks.useClerk.mockReturnValue({
+      loaded: false,
+      setActive: mockSetActive,
+      client: null,
+    });
+
+    const { result } = renderHook(() => useSSO());
+
+    const response = await result.current.startSSOFlow({ strategy: 'oauth_google' });
+
+    expect(mockSignIn.create).not.toHaveBeenCalled();
+    expect(mocks.openAuthSessionAsync).not.toHaveBeenCalled();
+    expect(response.createdSessionId).toBe(null);
+    expect(response.signIn).toBe(mockSignIn);
+    expect(response.signUp).toBe(mockSignUp);
+    expect(response).not.toHaveProperty('setActive');
+  });
+
+  test('starts OAuth SSO with future sign-in hooks and reloads the underlying client with the callback nonce', async () => {
+    const { result } = renderHook(() => useSSO());
+
+    const response = await result.current.startSSOFlow({
+      strategy: 'oauth_google',
+      authSessionOptions: { showInRecents: true },
+    });
+
+    expect(mockSignIn.create).toHaveBeenCalledWith({
+      strategy: 'oauth_google',
+      redirectUrl: 'myapp://sso-callback',
+    });
+    expect(mocks.openAuthSessionAsync).toHaveBeenCalledWith(
+      'https://accounts.example.com/sso',
+      'myapp://sso-callback',
+      { showInRecents: true },
+    );
+    expect(mockClientSignIn.reload).toHaveBeenCalledWith({ rotatingTokenNonce: 'nonce_123' });
+    expect(mockSignIn.finalize).toHaveBeenCalledOnce();
+    expect(response).toMatchObject({
+      createdSessionId: 'sess_123',
+      authSessionResult: {
+        type: 'success',
+        url: 'myapp://sso-callback?rotating_token_nonce=nonce_123',
+      },
+      signIn: mockSignIn,
+      signUp: mockSignUp,
+    });
+    expect(response).not.toHaveProperty('setActive');
+  });
+
+  test('uses the reloaded sign-in future for callback state and finalization', async () => {
+    const reloadedSignIn = {
+      ...mockSignIn,
+      createdSessionId: 'sess_reloaded',
+      firstFactorVerification: {
+        ...mockSignIn.firstFactorVerification,
+        status: 'verified',
+      },
+      finalize: vi.fn().mockResolvedValue({ error: null }),
+    };
+    mockClientSignIn.reload.mockResolvedValue({ __internal_future: reloadedSignIn });
+    const { result } = renderHook(() => useSSO());
+
+    const response = await result.current.startSSOFlow({ strategy: 'oauth_google' });
+
+    expect(reloadedSignIn.finalize).toHaveBeenCalledOnce();
+    expect(mockSignIn.finalize).not.toHaveBeenCalled();
+    expect(response.createdSessionId).toBe('sess_reloaded');
+    expect(response.signIn).toBe(reloadedSignIn);
+  });
+
+  test('ignores a session retained by an unrelated sign-up resource', async () => {
+    mockSignUp.createdSessionId = 'sess_stale_signup';
+    const { result } = renderHook(() => useSSO());
+
+    const response = await result.current.startSSOFlow({ strategy: 'oauth_google' });
+
+    expect(mockSignIn.finalize).toHaveBeenCalledOnce();
+    expect(mockSignUp.finalize).not.toHaveBeenCalled();
+    expect(response.createdSessionId).toBe('sess_123');
+  });
+
+  test('passes an enterprise SSO identifier to sign-in creation', async () => {
+    const { result } = renderHook(() => useSSO());
+
+    await result.current.startSSOFlow({
+      strategy: 'enterprise_sso',
+      identifier: 'user@example.com',
+    });
+
+    expect(mockSignIn.create).toHaveBeenCalledWith({
+      strategy: 'enterprise_sso',
+      redirectUrl: 'myapp://sso-callback',
+      identifier: 'user@example.com',
+    });
+  });
+
+  test('creates a transfer sign-up with unsafe metadata when sign-in is transferable', async () => {
+    const reloadedSignIn = {
+      ...mockSignIn,
+      firstFactorVerification: {
+        ...mockSignIn.firstFactorVerification,
+        status: 'transferable',
+      },
+    };
+    mockClientSignIn.reload.mockResolvedValue({ __internal_future: reloadedSignIn });
+    mockSignUp.create.mockImplementation(() => {
+      mockSignUp.createdSessionId = 'sess_signup';
+      return Promise.resolve({ error: null });
+    });
+
+    const unsafeMetadata = { source: 'mobile' };
+    const { result } = renderHook(() => useSSO());
+
+    const response = await result.current.startSSOFlow({
+      strategy: 'oauth_google',
+      unsafeMetadata,
+    });
+
+    expect(mockSignUp.create).toHaveBeenCalledWith({
+      transfer: true,
+      unsafeMetadata,
+    });
+    expect(mockSignUp.finalize).toHaveBeenCalledOnce();
+    expect(response.createdSessionId).toBe('sess_signup');
+    expect(response.signIn).toBe(reloadedSignIn);
+  });
+
+  test('activates an existing session without finalizing a future resource', async () => {
+    const reloadedSignIn = {
+      ...mockSignIn,
+      existingSession: { sessionId: 'sess_existing' },
+    };
+    mockClientSignIn.reload.mockResolvedValue({ __internal_future: reloadedSignIn });
+
+    const { result } = renderHook(() => useSSO());
+
+    const response = await result.current.startSSOFlow({ strategy: 'oauth_google' });
+
+    expect(mockSetActive).toHaveBeenCalledWith({ session: 'sess_existing' });
+    expect(mockSignIn.finalize).not.toHaveBeenCalled();
+    expect(mockSignUp.finalize).not.toHaveBeenCalled();
+    expect(response.createdSessionId).toBe(null);
+    expect(response.signIn).toBe(reloadedSignIn);
+  });
+
+  test('does not activate an existing session retained by an unrelated sign-up resource', async () => {
+    mockClientSignIn.reload.mockResolvedValue({ __internal_future: mockSignIn });
+    mockSignUp.existingSession = { sessionId: 'sess_stale_signup' };
+    const { result } = renderHook(() => useSSO());
+
+    const response = await result.current.startSSOFlow({ strategy: 'oauth_google' });
+
+    expect(mockSetActive).not.toHaveBeenCalled();
+    expect(mockSignIn.finalize).not.toHaveBeenCalled();
+    expect(mockSignUp.finalize).not.toHaveBeenCalled();
+    expect(response.createdSessionId).toBe(null);
+  });
+
+  test('returns without reloading when the browser auth session is dismissed', async () => {
+    mocks.openAuthSessionAsync.mockResolvedValue({
+      type: 'dismiss',
+    });
+
+    const { result } = renderHook(() => useSSO());
+
+    const response = await result.current.startSSOFlow({ strategy: 'oauth_google' });
+
+    expect(mockClientSignIn.reload).not.toHaveBeenCalled();
+    expect(mockSignIn.finalize).not.toHaveBeenCalled();
+    expect(mockSignUp.finalize).not.toHaveBeenCalled();
+    expect(response.createdSessionId).toBe(null);
+    expect(response.authSessionResult).toEqual({ type: 'dismiss' });
+  });
+
+  test('preserves structured future sign-in create errors', async () => {
+    const clerkError = Object.assign(new Error('sign-in failed'), {
+      code: 'form_identifier_not_found',
+      errors: [{ code: 'form_identifier_not_found' }],
+    });
+    mockSignIn.create.mockResolvedValue({ error: clerkError });
+
+    const { result } = renderHook(() => useSSO());
+
+    await expect(result.current.startSSOFlow({ strategy: 'oauth_google' })).rejects.toBe(clerkError);
+    expect(mocks.openAuthSessionAsync).not.toHaveBeenCalled();
+  });
+
+  test('surfaces the underlying error when an auth-session dependency fails to load', async () => {
+    mocks.loadSSODependencies.mockImplementation(() => {
+      throw new Error(
+        '@clerk/expo: Unable to load expo-auth-session and expo-web-browser, which are required for SSO: missing auth session. If they are not installed, run: npx expo install expo-auth-session expo-web-browser',
+      );
+    });
+
+    const { result } = renderHook(() => useSSO());
+
+    await expect(result.current.startSSOFlow({ strategy: 'oauth_google' })).rejects.toThrow(
+      /required for SSO: missing auth session\. If they are not installed/s,
+    );
+  });
+});