fix(expo): treat missing secure key storage as unavailable

getAvailability() and signIn() report biometric_authentication_unavailable
before reading local records when @clerk/expo-biometrics reports no secure
key storage, and enroll() maps its secure_key_storage_unavailable rejection
to biometric_authentication_unavailable before contacting Clerk.

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

Author: mikepitre

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

@@ -58,6 +58,7 @@ function createExpoBiometrics({ withHash = true }: { withHash?: boolean } = {})
       canEvaluateBiometrics: true,
       canEvaluateDeviceOwner: true,
       errorCode: null,
+      secureKeyStorageAvailable: true as boolean | undefined,
     })),
     createKey: asyncFn(() => {
       store.keys.add('key_new');
@@ -220,6 +221,42 @@ describe('getAvailability', () => {
     expect(biometrics.listRecords).not.toHaveBeenCalled();
   });
 
+  test('reports biometric authentication unavailable without secure key storage, before reading local records', async () => {
+    addLocalCredential();
+    biometrics.getAvailability.mockResolvedValue({
+      biometryType: 'faceID',
+      canEvaluateBiometrics: true,
+      canEvaluateDeviceOwner: true,
+      errorCode: null,
+      secureKeyStorageAvailable: false,
+    });
+
+    await expect(renderBiometricCredentials().getAvailability()).resolves.toEqual({
+      isAvailable: false,
+      unavailableReason: 'biometric_authentication_unavailable',
+    });
+    expect(biometrics.listRecords).not.toHaveBeenCalled();
+    expect(biometrics.hasKey).not.toHaveBeenCalled();
+    expect(biometrics.deleteRecord).not.toHaveBeenCalled();
+    expect(biometrics.store.records).toHaveLength(1);
+  });
+
+  test('treats a module that does not report secure key storage as having it', async () => {
+    addLocalCredential();
+    biometrics.getAvailability.mockResolvedValue({
+      biometryType: 'faceID',
+      canEvaluateBiometrics: true,
+      canEvaluateDeviceOwner: true,
+      errorCode: null,
+      secureKeyStorageAvailable: undefined,
+    });
+
+    await expect(renderBiometricCredentials().getAvailability()).resolves.toEqual({
+      isAvailable: true,
+      unavailableReason: null,
+    });
+  });
+
   test('reports no local credential when the device has none for this app', async () => {
     addLocalCredential({ appIdentifier: 'com.example.other' });
 
@@ -581,6 +618,18 @@ describe('enroll', () => {
     expect(clerk.user.__experimental_prepareBiometricCredential).not.toHaveBeenCalled();
   });
 
+  test('fails fast when the device has no secure key storage', async () => {
+    biometrics.createKey.mockRejectedValue(moduleError('secure_key_storage_unavailable', 'No Secure Enclave'));
+
+    await expect(renderBiometricCredentials().enroll()).rejects.toMatchObject({
+      code: 'biometric_authentication_unavailable',
+      message: 'No Secure Enclave',
+    });
+    expect(clerk.user.__experimental_prepareBiometricCredential).not.toHaveBeenCalled();
+    expect(biometrics.sign).not.toHaveBeenCalled();
+    expect(biometrics.saveRecord).not.toHaveBeenCalled();
+  });
+
   test('surfaces reverification errors from prepare unchanged and deletes the key', async () => {
     const error = apiError('session_reverification_required');
     clerk.user.__experimental_prepareBiometricCredential.mockRejectedValue(error);
@@ -740,6 +789,23 @@ describe('signIn', () => {
     expect(clerk.clientSignIn.create).not.toHaveBeenCalled();
   });
 
+  test('rejects without contacting the server when the device has no secure key storage', async () => {
+    addLocalCredential();
+    biometrics.getAvailability.mockResolvedValue({
+      biometryType: 'faceID',
+      canEvaluateBiometrics: true,
+      canEvaluateDeviceOwner: true,
+      errorCode: null,
+      secureKeyStorageAvailable: false,
+    });
+
+    const operation = renderBiometricCredentials().signIn();
+
+    await expect(operation).rejects.toThrow('biometric_authentication_unavailable');
+    expect(clerk.clientSignIn.create).not.toHaveBeenCalled();
+    expect(biometrics.sign).not.toHaveBeenCalled();
+  });
+
   test('rejects when the Clerk client is unavailable', async () => {
     addLocalCredential();
     clerk.instance.client = undefined;

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

@@ -61,6 +61,7 @@ const MODULE_ERROR_CODES: Record<string, BiometricCredentialErrorCode | undefine
   biometry_not_enrolled: 'biometric_authentication_unavailable',
   biometry_lockout: 'biometric_authentication_unavailable',
   passcode_not_set: 'biometric_authentication_unavailable',
+  secure_key_storage_unavailable: 'biometric_authentication_unavailable',
   key_not_found: 'key_not_found',
   key_invalidated: 'key_invalidated',
   key_generation_failed: 'key_generation_failed',
@@ -263,6 +264,12 @@ export function createBiometricCredentials(clerk: Clerk): UseBiometricCredential
       return unavailableReason;
     }
 
+    const device = await callModule(biometrics, module => module.getAvailability());
+    // Older @clerk/expo-biometrics versions do not report secureKeyStorageAvailable.
+    if (device.secureKeyStorageAvailable === false) {
+      return 'biometric_authentication_unavailable';
+    }
+
     const matchesIdentifierHint = await identifierHintMatcher(biometrics, identifierHint);
     const records = (await callModule(biometrics, module => module.listRecords()))
       .filter(
@@ -288,7 +295,6 @@ export function createBiometricCredentials(clerk: Clerk): UseBiometricCredential
       return 'local_key_missing';
     }
 
-    const device = await callModule(biometrics, module => module.getAvailability());
     const supportedRecords = recordsWithKeys.filter(record =>
       record.policy === 'biometry_or_device_passcode' ? device.canEvaluateDeviceOwner : device.canEvaluateBiometrics,
     );