fix(expo): keep API error codes on biometric credential errors

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: mikepitre

.changeset/expo-biometric-credentials-js.md

@@ -7,5 +7,4 @@
 - Install `@clerk/expo-biometrics` (`npx expo install @clerk/expo-biometrics`) and rebuild your development build. Without it, these methods throw an error explaining how to install it.
 - Enrollment, listing, revocation and sign-in no longer require `@clerk/expo-native-components` or iOS 17.
 - `reverify()` still uses Clerk's native SDK and requires `@clerk/expo-native-components`.
-- Errors returned by Clerk's API are now thrown as `ClerkAPIResponseError`, like the rest of `@clerk/expo`. Read the API error code from `error.errors[0].code`. Errors raised on the device, such as `biometric_authentication_canceled` or `key_invalidated`, keep their `code`.
 - On Android, credentials enrolled through the previous native implementation may not be found by apps that don't use `@clerk/expo-native-components`. Users of those apps need to enroll again.

packages/expo/src/biometric-credentials/__tests__/useBiometricCredentials.test.ts

@@ -114,11 +114,29 @@ function serverCredential(overrides: Record<string, unknown> = {}) {
 
 function apiError(code: string, paramName?: string) {
   return new ClerkAPIResponseError(code, {
-    data: [{ code, message: code, long_message: code, meta: paramName ? { param_name: paramName } : {} }],
+    data: [
+      {
+        code,
+        message: `${code} message`,
+        long_message: `${code} long message`,
+        meta: paramName ? { param_name: paramName } : {},
+      },
+    ],
     status: 422,
   });
 }
 
+async function expectBiometricApiError(operation: Promise<unknown>, cause: ClerkAPIResponseError) {
+  const error = await operation.then(
+    () => expect.unreachable('Expected the operation to reject'),
+    (rejection: unknown) => rejection,
+  );
+  const code = cause.errors[0].code;
+  expect(isBiometricCredentialError(error)).toBe(true);
+  expect(error).not.toBeInstanceOf(ClerkAPIResponseError);
+  expect(error).toMatchObject({ code, message: `${code} long message`, cause });
+}
+
 function createClerk() {
   const user = {
     id: 'user_1',
@@ -386,7 +404,7 @@ describe('getAvailability', () => {
       const error = apiError('session_reverification_required');
       clerk.user.__experimental_getBiometricCredentials.mockRejectedValue(error);
 
-      await expect(renderBiometricCredentials().getAvailability()).rejects.toBe(error);
+      await expectBiometricApiError(renderBiometricCredentials().getAvailability(), error);
       expect(biometrics.store.records).toHaveLength(1);
     });
   });
@@ -567,7 +585,7 @@ describe('enroll', () => {
     const error = apiError('session_reverification_required');
     clerk.user.__experimental_prepareBiometricCredential.mockRejectedValue(error);
 
-    await expect(renderBiometricCredentials().enroll()).rejects.toBe(error);
+    await expectBiometricApiError(renderBiometricCredentials().enroll(), error);
     expect(biometrics.deleteKey).toHaveBeenCalledWith('key_new');
     expect(biometrics.sign).not.toHaveBeenCalled();
     expect(biometrics.saveRecord).not.toHaveBeenCalled();
@@ -587,7 +605,7 @@ describe('enroll', () => {
     const error = apiError('form_param_invalid', 'signature');
     clerk.user.__experimental_attemptBiometricCredential.mockRejectedValue(error);
 
-    await expect(renderBiometricCredentials().enroll()).rejects.toBe(error);
+    await expectBiometricApiError(renderBiometricCredentials().enroll(), error);
     expect(biometrics.deleteKey).toHaveBeenCalledWith('key_new');
     expect(biometrics.saveRecord).not.toHaveBeenCalled();
     expect(clerk.user.__experimental_revokeBiometricCredential).not.toHaveBeenCalled();
@@ -637,7 +655,7 @@ describe('revoke', () => {
     const error = apiError('session_reverification_required');
     clerk.user.__experimental_revokeBiometricCredential.mockRejectedValue(error);
 
-    await expect(renderBiometricCredentials().revoke('td_1')).rejects.toBe(error);
+    await expectBiometricApiError(renderBiometricCredentials().revoke('td_1'), error);
     expect(biometrics.deleteRecord).not.toHaveBeenCalled();
   });
 
@@ -744,7 +762,7 @@ describe('signIn', () => {
       const error = apiError(code, 'trusted_device_id');
       clerk.clientSignIn.create.mockRejectedValue(error);
 
-      await expect(renderBiometricCredentials().signIn()).rejects.toBe(error);
+      await expectBiometricApiError(renderBiometricCredentials().signIn(), error);
       expect(biometrics.deleteRecord).toHaveBeenCalledWith('key_1');
       expect(biometrics.store.records).toEqual([]);
     },
@@ -755,7 +773,7 @@ describe('signIn', () => {
     const error = apiError('trusted_device_not_registered', 'trusted_device_id');
     clerk.createdSignIn.attemptFirstFactor.mockRejectedValue(error);
 
-    await expect(renderBiometricCredentials().signIn()).rejects.toBe(error);
+    await expectBiometricApiError(renderBiometricCredentials().signIn(), error);
     expect(biometrics.store.records).toEqual([]);
   });
 
@@ -764,7 +782,7 @@ describe('signIn', () => {
     const error = apiError('form_resource_not_found', 'sign_in_id');
     clerk.createdSignIn.attemptFirstFactor.mockRejectedValue(error);
 
-    await expect(renderBiometricCredentials().signIn()).rejects.toBe(error);
+    await expectBiometricApiError(renderBiometricCredentials().signIn(), error);
     expect(biometrics.deleteRecord).not.toHaveBeenCalled();
   });
 
@@ -806,6 +824,51 @@ describe('signIn', () => {
   });
 });
 
+describe('API errors', () => {
+  test('surface a reverification-required error with its API code', async () => {
+    signInClerkUser();
+    clerk.user.__experimental_prepareBiometricCredential.mockRejectedValue(apiError('session_reverification_required'));
+
+    const operation = renderBiometricCredentials().enroll();
+
+    await expect(operation).rejects.toMatchObject({ code: 'session_reverification_required' });
+    await operation.catch(error => expect(isBiometricCredentialError(error)).toBe(true));
+  });
+
+  test('surface a trusted_device_not_registered error with its API code', async () => {
+    addLocalCredential();
+    clerk.clientSignIn.create.mockRejectedValue(apiError('trusted_device_not_registered', 'trusted_device_id'));
+
+    const operation = renderBiometricCredentials().signIn();
+
+    await expect(operation).rejects.toMatchObject({
+      code: 'trusted_device_not_registered',
+      message: 'trusted_device_not_registered long message',
+    });
+    await operation.catch(error => expect(isBiometricCredentialError(error)).toBe(true));
+  });
+
+  test('fall back to the short message and the operation code', async () => {
+    signInClerkUser();
+    const withoutLongMessage = new ClerkAPIResponseError('native_api_disabled', {
+      data: [{ code: 'native_api_disabled', message: 'Native API is disabled', long_message: undefined as never }],
+      status: 403,
+    });
+    clerk.user.__experimental_getBiometricCredentials.mockRejectedValueOnce(withoutLongMessage);
+    clerk.user.__experimental_getBiometricCredentials.mockRejectedValueOnce(new Error('Network down'));
+    const biometricCredentials = renderBiometricCredentials();
+
+    await expect(biometricCredentials.list()).rejects.toMatchObject({
+      code: 'native_api_disabled',
+      message: 'Native API is disabled',
+    });
+    await expect(biometricCredentials.list()).rejects.toMatchObject({
+      code: 'E_TRUSTED_DEVICE_LIST_FAILED',
+      message: 'Network down',
+    });
+  });
+});
+
 describe('missing @clerk/expo-biometrics', () => {
   test.each(['getAvailability', 'list', 'enroll', 'revoke', 'signIn'] as const)(
     '%s explains how to install the package',

packages/expo/src/biometric-credentials/createBiometricCredentials.ts

@@ -173,6 +173,29 @@ function toBiometricCredential(credential: BiometricCredentialResource): Biometr
   };
 }
 
+function toApiBiometricCredentialError(error: unknown, fallbackCode: OperationErrorCode): unknown {
+  if (isClerkAPIResponseError(error)) {
+    const apiError = error.errors[0];
+    return biometricCredentialError(
+      apiError?.code ?? fallbackCode,
+      apiError?.longMessage ?? apiError?.message ?? error.message,
+      error,
+    );
+  }
+  if (error instanceof Error && typeof (error as { code?: unknown }).code === 'string') {
+    return error;
+  }
+  return biometricCredentialError(fallbackCode, error instanceof Error ? error.message : String(error), error);
+}
+
+async function callApi<T>(fallbackCode: OperationErrorCode, request: () => Promise<T>): Promise<T> {
+  try {
+    return await request();
+  } catch (error) {
+    throw toApiBiometricCredentialError(error, fallbackCode);
+  }
+}
+
 function isMissingCredentialError(error: unknown): boolean {
   return (
     isClerkAPIResponseError(error) &&
@@ -296,7 +319,9 @@ export function createBiometricCredentials(clerk: Clerk): UseBiometricCredential
       return { unavailableReason: 'no_local_credential' };
     }
 
-    const serverCredentials = await activeUser.__experimental_getBiometricCredentials();
+    const serverCredentials = await callApi(biometrics.fallbackCode, () =>
+      activeUser.__experimental_getBiometricCredentials(),
+    );
     let firstUnavailableReason: BiometricCredentialUnavailableReason | null = null;
     for (const record of activeUserRecords) {
       const serverCredential = serverCredentials.find(credential => credential.id === record.id);
@@ -325,8 +350,9 @@ export function createBiometricCredentials(clerk: Clerk): UseBiometricCredential
     },
 
     list: async () => {
-      requireBiometrics('E_TRUSTED_DEVICE_LIST_FAILED');
-      const credentials = await requireUser('E_TRUSTED_DEVICE_LIST_FAILED').__experimental_getBiometricCredentials();
+      const biometrics = requireBiometrics('E_TRUSTED_DEVICE_LIST_FAILED');
+      const user = requireUser(biometrics.fallbackCode);
+      const credentials = await callApi(biometrics.fallbackCode, () => user.__experimental_getBiometricCredentials());
       return credentials.map(toBiometricCredential);
     },
 
@@ -360,15 +386,19 @@ export function createBiometricCredentials(clerk: Clerk): UseBiometricCredential
 
       let credential: BiometricCredentialResource;
       try {
-        const challenge = await user.__experimental_prepareBiometricCredential(enrollment);
+        const challenge = await callApi(biometrics.fallbackCode, () =>
+          user.__experimental_prepareBiometricCredential(enrollment),
+        );
         const signature = await callModule(biometrics, module =>
           module.sign(key.localKeyId, challenge.clientData, params?.reason ?? DEFAULT_ENROLLMENT_REASON),
         );
-        credential = await user.__experimental_attemptBiometricCredential({
-          ...enrollment,
-          clientData: challenge.clientData,
-          signature,
-        });
+        credential = await callApi(biometrics.fallbackCode, () =>
+          user.__experimental_attemptBiometricCredential({
+            ...enrollment,
+            clientData: challenge.clientData,
+            signature,
+          }),
+        );
       } catch (error) {
         await ignoreErrors(() => biometrics.module.deleteKey(key.localKeyId));
         throw error;
@@ -401,7 +431,10 @@ export function createBiometricCredentials(clerk: Clerk): UseBiometricCredential
 
     revoke: async id => {
       const biometrics = requireBiometrics('E_TRUSTED_DEVICE_REVOCATION_FAILED');
-      const credential = await requireUser(biometrics.fallbackCode).__experimental_revokeBiometricCredential(id);
+      const user = requireUser(biometrics.fallbackCode);
+      const credential = await callApi(biometrics.fallbackCode, () =>
+        user.__experimental_revokeBiometricCredential(id),
+      );
       await ignoreErrors(async () => {
         const records = await biometrics.module.listRecords();
         const localKeyIds = new Set(records.filter(record => record.id === id).map(record => record.localKeyId));
@@ -435,7 +468,7 @@ export function createBiometricCredentials(clerk: Clerk): UseBiometricCredential
         if (isMissingCredentialError(error)) {
           await ignoreErrors(() => deleteLocalCredential(biometrics, record));
         }
-        return error;
+        return toApiBiometricCredentialError(error, biometrics.fallbackCode);
       };
 
       let signIn: SignInResource;