feat(clerk-expo): Add native Apple Sign-In support for iOS

.changeset/brave-apples-sign.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-expo': minor
+'@clerk/types': patch
+---
+
+Add native Apple Sign-In support for iOS via `useAppleSignIn()` hook. Requires `expo-apple-authentication` and native build (EAS Build or local prebuild).

packages/expo/package.json

@@ -94,6 +94,7 @@
   "devDependencies": {
     "@clerk/expo-passkeys": "workspace:*",
     "@types/base-64": "^1.0.2",
+    "expo-apple-authentication": "^7.2.4",
     "expo-auth-session": "^5.4.0",
     "expo-local-authentication": "^13.8.0",
     "expo-secure-store": "^12.8.1",
@@ -102,6 +103,7 @@
   },
   "peerDependencies": {
     "@clerk/expo-passkeys": ">=0.0.6",
+    "expo-apple-authentication": ">=7.0.0",
     "expo-auth-session": ">=5",
     "expo-local-authentication": ">=13.5.0",
     "expo-secure-store": ">=12.4.0",
@@ -114,6 +116,9 @@
     "@clerk/expo-passkeys": {
       "optional": true
     },
+    "expo-apple-authentication": {
+      "optional": true
+    },
     "expo-local-authentication": {
       "optional": true
     },

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

@@ -0,0 +1,197 @@
+import { renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { useAppleSignIn } from '../useAppleSignIn';
+
+const mocks = vi.hoisted(() => {
+  return {
+    useSignIn: vi.fn(),
+    useSignUp: vi.fn(),
+    signInAsync: vi.fn(),
+    isAvailableAsync: vi.fn(),
+  };
+});
+
+vi.mock('@clerk/clerk-react', () => {
+  return {
+    useSignIn: mocks.useSignIn,
+    useSignUp: mocks.useSignUp,
+  };
+});
+
+vi.mock('expo-apple-authentication', () => {
+  return {
+    signInAsync: mocks.signInAsync,
+    isAvailableAsync: mocks.isAvailableAsync,
+    AppleAuthenticationScope: {
+      FULL_NAME: 0,
+      EMAIL: 1,
+    },
+  };
+});
+
+vi.mock('react-native', () => {
+  return {
+    Platform: {
+      OS: 'ios',
+    },
+  };
+});
+
+describe('useAppleSignIn', () => {
+  const mockSignIn = {
+    create: vi.fn(),
+    createdSessionId: 'test-session-id',
+    firstFactorVerification: {
+      status: 'verified',
+    },
+  };
+
+  const mockSignUp = {
+    create: vi.fn(),
+    createdSessionId: null,
+  };
+
+  const mockSetActive = vi.fn();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    mocks.useSignIn.mockReturnValue({
+      signIn: mockSignIn,
+      setActive: mockSetActive,
+      isLoaded: true,
+    });
+
+    mocks.useSignUp.mockReturnValue({
+      signUp: mockSignUp,
+      isLoaded: true,
+    });
+
+    mocks.isAvailableAsync.mockResolvedValue(true);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('startAppleSignInFlow', () => {
+    test('should return the hook with startAppleSignInFlow function', () => {
+      const { result } = renderHook(() => useAppleSignIn());
+
+      expect(result.current).toHaveProperty('startAppleSignInFlow');
+      expect(typeof result.current.startAppleSignInFlow).toBe('function');
+    });
+
+    test('should successfully sign in existing user', async () => {
+      const mockIdentityToken = 'mock-identity-token';
+      mocks.signInAsync.mockResolvedValue({
+        identityToken: mockIdentityToken,
+      });
+
+      mockSignIn.create.mockResolvedValue(undefined);
+      mockSignIn.firstFactorVerification.status = 'verified';
+      mockSignIn.createdSessionId = 'test-session-id';
+
+      const { result } = renderHook(() => useAppleSignIn());
+
+      const response = await result.current.startAppleSignInFlow();
+
+      expect(mocks.isAvailableAsync).toHaveBeenCalled();
+      expect(mocks.signInAsync).toHaveBeenCalledWith(
+        expect.objectContaining({
+          requestedScopes: expect.any(Array),
+          nonce: expect.any(String),
+        }),
+      );
+      expect(mockSignIn.create).toHaveBeenCalledWith({
+        strategy: 'oauth_token_apple',
+        token: mockIdentityToken,
+      });
+      expect(response.createdSessionId).toBe('test-session-id');
+      expect(response.setActive).toBe(mockSetActive);
+    });
+
+    test('should handle transfer flow for new user', async () => {
+      const mockIdentityToken = 'mock-identity-token';
+      mocks.signInAsync.mockResolvedValue({
+        identityToken: mockIdentityToken,
+      });
+
+      mockSignIn.create.mockResolvedValue(undefined);
+      mockSignIn.firstFactorVerification.status = 'transferable';
+
+      const mockSignUpWithSession = { ...mockSignUp, createdSessionId: 'new-user-session-id' };
+      mocks.useSignUp.mockReturnValue({
+        signUp: mockSignUpWithSession,
+        isLoaded: true,
+      });
+
+      const { result } = renderHook(() => useAppleSignIn());
+
+      const response = await result.current.startAppleSignInFlow({
+        unsafeMetadata: { source: 'test' },
+      });
+
+      expect(mockSignIn.create).toHaveBeenCalledWith({
+        strategy: 'oauth_token_apple',
+        token: mockIdentityToken,
+      });
+      expect(mockSignUp.create).toHaveBeenCalledWith({
+        transfer: true,
+        unsafeMetadata: { source: 'test' },
+      });
+      expect(response.createdSessionId).toBe('new-user-session-id');
+    });
+
+    test('should handle user cancellation gracefully', async () => {
+      const cancelError = Object.assign(new Error('User canceled'), { code: 'ERR_REQUEST_CANCELED' });
+      mocks.signInAsync.mockRejectedValue(cancelError);
+
+      const { result } = renderHook(() => useAppleSignIn());
+
+      const response = await result.current.startAppleSignInFlow();
+
+      expect(response.createdSessionId).toBe(null);
+      expect(response.setActive).toBe(mockSetActive);
+    });
+
+    test('should throw error when Apple Authentication is not available', async () => {
+      mocks.isAvailableAsync.mockResolvedValue(false);
+
+      const { result } = renderHook(() => useAppleSignIn());
+
+      await expect(result.current.startAppleSignInFlow()).rejects.toThrow(
+        'Apple Authentication is not available on this device.',
+      );
+    });
+
+    test('should throw error when no identity token received', async () => {
+      mocks.signInAsync.mockResolvedValue({
+        identityToken: null,
+      });
+
+      const { result } = renderHook(() => useAppleSignIn());
+
+      await expect(result.current.startAppleSignInFlow()).rejects.toThrow(
+        'No identity token received from Apple Sign-In.',
+      );
+    });
+
+    test('should return early when clerk is not loaded', async () => {
+      mocks.useSignIn.mockReturnValue({
+        signIn: mockSignIn,
+        setActive: mockSetActive,
+        isLoaded: false,
+      });
+
+      const { result } = renderHook(() => useAppleSignIn());
+
+      const response = await result.current.startAppleSignInFlow();
+
+      expect(mocks.isAvailableAsync).not.toHaveBeenCalled();
+      expect(mocks.signInAsync).not.toHaveBeenCalled();
+      expect(response.createdSessionId).toBe(null);
+    });
+  });
+});

packages/expo/src/hooks/index.ts

@@ -11,6 +11,7 @@ export {
   useReverification,
 } from '@clerk/clerk-react';
 
+export * from './useAppleSignIn';
 export * from './useSSO';
 export * from './useOAuth';
 export * from './useAuth';

packages/expo/src/hooks/useAppleSignIn.ts

@@ -0,0 +1,158 @@
+import { useSignIn, useSignUp } from '@clerk/clerk-react';
+import type { SetActive, SignInResource, SignUpResource, SignUpUnsafeMetadata } from '@clerk/types';
+import * as AppleAuthentication from 'expo-apple-authentication';
+import { Platform } from 'react-native';
+
+import { errorThrower } from '../utils/errors';
+
+export type StartAppleSignInFlowParams = {
+  unsafeMetadata?: SignUpUnsafeMetadata;
+};
+
+export type StartAppleSignInFlowReturnType = {
+  createdSessionId: string | null;
+  setActive?: SetActive;
+  signIn?: SignInResource;
+  signUp?: SignUpResource;
+};
+
+/**
+ * Hook for native Apple Sign-In on iOS using expo-apple-authentication.
+ *
+ * This hook provides a simplified way to authenticate users with their Apple ID
+ * using the native iOS Sign in with Apple UI. The authentication flow automatically
+ * handles the ID token exchange with Clerk's backend and manages the transfer flow
+ * between sign-in and sign-up.
+ *
+ * @example
+ * ```tsx
+ * import { useAppleSignIn } from '@clerk/clerk-expo';
+ * import { Button } from 'react-native';
+ *
+ * function AppleSignInButton() {
+ *   const { startAppleSignInFlow } = useAppleSignIn();
+ *
+ *   const onPress = async () => {
+ *     try {
+ *       const { createdSessionId, setActive } = await startAppleSignInFlow();
+ *
+ *       if (createdSessionId && setActive) {
+ *         await setActive({ session: createdSessionId });
+ *       }
+ *     } catch (err) {
+ *       console.error('Apple Sign-In error:', err);
+ *     }
+ *   };
+ *
+ *   return <Button title="Sign in with Apple" onPress={onPress} />;
+ * }
+ * ```
+ *
+ * @requires expo-apple-authentication - Must be installed as a peer dependency
+ * @platform iOS - This hook only works on iOS. On other platforms, it will throw an error.
+ *
+ * @returns An object containing the `startAppleSignInFlow` function
+ */
+export function useAppleSignIn() {
+  const { signIn, setActive, isLoaded: isSignInLoaded } = useSignIn();
+  const { signUp, isLoaded: isSignUpLoaded } = useSignUp();
+
+  async function startAppleSignInFlow(
+    startAppleSignInFlowParams?: StartAppleSignInFlowParams,
+  ): Promise<StartAppleSignInFlowReturnType> {
+    // Check platform compatibility
+    if (Platform.OS !== 'ios') {
+      return errorThrower.throw(
+        'Apple Sign-In is only available on iOS. Please use the web-based OAuth flow (useSSO with strategy: "oauth_apple") on other platforms.',
+      );
+    }
+
+    if (!isSignInLoaded || !isSignUpLoaded) {
+      return {
+        createdSessionId: null,
+        signIn,
+        signUp,
+        setActive,
+      };
+    }
+
+    // Check if Apple Authentication is available on the device
+    const isAvailable = await AppleAuthentication.isAvailableAsync();
+    if (!isAvailable) {
+      return errorThrower.throw('Apple Authentication is not available on this device.');
+    }
+
+    try {
+      // Generate a nonce for the Apple Sign-In request (required by Clerk)
+      // Note: Using Math.random() is acceptable here as the identity token is validated by Clerk's backend
+      const nonce = Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
+
+      // Request Apple authentication with requested scopes
+      const credential = await AppleAuthentication.signInAsync({
+        requestedScopes: [
+          AppleAuthentication.AppleAuthenticationScope.FULL_NAME,
+          AppleAuthentication.AppleAuthenticationScope.EMAIL,
+        ],
+        nonce,
+      });
+
+      // Extract the identity token from the credential
+      const { identityToken } = credential;
+
+      if (!identityToken) {
+        return errorThrower.throw('No identity token received from Apple Sign-In.');
+      }
+
+      // Create a SignIn with the Apple ID token strategy
+      // Note: Type assertions needed until @clerk/clerk-react propagates the new oauth_token_apple strategy type
+      await signIn.create({
+        strategy: 'oauth_token_apple' as any,
+        token: identityToken,
+      } as any);
+
+      // Check if we need to transfer to SignUp (user doesn't exist yet)
+      const userNeedsToBeCreated = signIn.firstFactorVerification.status === 'transferable';
+
+      if (userNeedsToBeCreated) {
+        // User doesn't exist - create a new SignUp with transfer
+        await signUp.create({
+          transfer: true,
+          unsafeMetadata: startAppleSignInFlowParams?.unsafeMetadata,
+        });
+
+        return {
+          createdSessionId: signUp.createdSessionId,
+          setActive,
+          signIn,
+          signUp,
+        };
+      }
+
+      // User exists - return the SignIn session
+      return {
+        createdSessionId: signIn.createdSessionId,
+        setActive,
+        signIn,
+        signUp,
+      };
+    } catch (error: any) {
+      // Handle Apple Authentication errors
+      if (error?.code === 'ERR_REQUEST_CANCELED') {
+        // User canceled the sign-in flow
+        return {
+          createdSessionId: null,
+          setActive,
+          signIn,
+          signUp,
+        };
+      }
+
+      // Re-throw other errors
+      throw error;
+    }
+  }
+
+  return {
+    startAppleSignInFlow,
+  };
+}