fix(expo-biometrics): report missing secure key storage

Add secureKeyStorageAvailable to getAvailability() and reject createKey()
with secure_key_storage_unavailable when the device has no Secure Enclave,
such as the iOS Simulator, instead of failing inside SecKeyCreateRandomKey.

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

Author: mikepitre

packages/expo-biometrics/README.md

@@ -37,6 +37,7 @@ The key and record layout is shared with the Clerk iOS SDK, so credentials enrol
 - Expo SDK 54 or later, in a development build (the module is not available in Expo Go or on the web)
 - iOS. Android support is not implemented yet: every call rejects with `not_implemented`.
 - `NSFaceIDUsageDescription` in your `Info.plist`. The `@clerk/expo` config plugin sets it through its `faceIDPermission` option.
+- A device with a Secure Enclave. The iOS Simulator has none, so `createKey()` rejects there with `secure_key_storage_unavailable`.
 
 ## Installation
 
@@ -66,7 +67,7 @@ import {
 | Function                                       | Description                                                                                                              |
 | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
 | `getAppIdentifier()`                           | The app identifier sent to Clerk as `app_identifier` (the iOS bundle identifier).                                        |
-| `getAvailability()`                            | The device's biometry type and whether biometrics or device owner authentication can be evaluated.                       |
+| `getAvailability()`                            | The device's biometry type, whether biometrics or device owner authentication can be evaluated, and secure key storage.  |
 | `createKey(policy)`                            | Creates a Secure Enclave P-256 key and returns its `localKeyId` and public key JWK.                                      |
 | `sign(localKeyId, clientData, reason?)`        | Prompts for authentication and returns an ES256 signature over `clientData` (raw `r \|\| s`, base64url without padding). |
 | `hasKey(localKeyId)` / `deleteKey(localKeyId)` | Checks for or deletes a key.                                                                                             |

packages/expo-biometrics/ios/BiometricKeyManager.swift

@@ -1,3 +1,4 @@
+import CryptoKit
 import Foundation
 import LocalAuthentication
 import Security
@@ -7,6 +8,7 @@ struct BiometricAvailability: Equatable {
   let canEvaluateBiometrics: Bool
   let canEvaluateDeviceOwner: Bool
   let errorCode: BiometricsError.Code?
+  let secureKeyStorageAvailable: Bool
 }
 
 struct BiometricCredentialKey: Equatable {
@@ -16,6 +18,21 @@ struct BiometricCredentialKey: Equatable {
 
 /// Secure Enclave keys laid out as ClerkKit's `BiometricCredentialKeyManager` creates them.
 final class BiometricKeyManager {
+  private let isSecureEnclaveAvailable: () -> Bool
+
+  init(isSecureEnclaveAvailable: @escaping () -> Bool = BiometricKeyManager.deviceHasSecureEnclave) {
+    self.isSecureEnclaveAvailable = isSecureEnclaveAvailable
+  }
+
+  static func deviceHasSecureEnclave() -> Bool {
+    // SecureEnclave.isAvailable is true on the Simulator, where Secure Enclave keys still fail with errSecAuthFailed.
+    #if targetEnvironment(simulator)
+      return false
+    #else
+      return SecureEnclave.isAvailable
+    #endif
+  }
+
   func availability() -> BiometricAvailability {
     let context = LAContext()
     var biometricsError: NSError?
@@ -31,11 +48,16 @@ final class BiometricKeyManager {
       canEvaluateDeviceOwner: canEvaluateDeviceOwner,
       errorCode: canEvaluateBiometrics
         ? nil
-        : BiometricsError.localAuthentication(biometricsError, fallback: .biometryNotAvailable).code
+        : BiometricsError.localAuthentication(biometricsError, fallback: .biometryNotAvailable).code,
+      secureKeyStorageAvailable: isSecureEnclaveAvailable()
     )
   }
 
   func createKey(policy: BiometricCredentialPolicy) throws -> BiometricCredentialKey {
+    guard isSecureEnclaveAvailable() else {
+      throw BiometricsError(.secureKeyStorageUnavailable, "This device has no Secure Enclave to hold the biometric credential key.")
+    }
+
     let context = LAContext()
     var laError: NSError?
     guard context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &laError) else {

packages/expo-biometrics/ios/BiometricsError.swift

@@ -12,6 +12,7 @@ struct BiometricsError: Error, Equatable {
     case biometryNotEnrolled = "biometry_not_enrolled"
     case biometryLockout = "biometry_lockout"
     case passcodeNotSet = "passcode_not_set"
+    case secureKeyStorageUnavailable = "secure_key_storage_unavailable"
     case keyNotFound = "key_not_found"
     case keyInvalidated = "key_invalidated"
     case keyGenerationFailed = "key_generation_failed"

packages/expo-biometrics/ios/ClerkExpoBiometrics.podspec

@@ -16,7 +16,7 @@ Pod::Spec.new do |s|
   s.static_framework = true
 
   s.dependency 'ExpoModulesCore'
-  s.frameworks = 'LocalAuthentication', 'Security'
+  s.frameworks = 'CryptoKit', 'LocalAuthentication', 'Security'
 
   s.pod_target_xcconfig = {
     'DEFINES_MODULE' => 'YES',

packages/expo-biometrics/ios/ClerkExpoBiometricsModule.swift

@@ -20,6 +20,7 @@ struct BiometricAvailabilityResult: Record {
   @Field var canEvaluateBiometrics: Bool = false
   @Field var canEvaluateDeviceOwner: Bool = false
   @Field var errorCode: String?
+  @Field var secureKeyStorageAvailable: Bool = false
 }
 
 struct BiometricCredentialKeyResult: Record {
@@ -64,6 +65,7 @@ public final class ClerkExpoBiometricsModule: Module {
       result.canEvaluateBiometrics = availability.canEvaluateBiometrics
       result.canEvaluateDeviceOwner = availability.canEvaluateDeviceOwner
       result.errorCode = availability.errorCode?.rawValue
+      result.secureKeyStorageAvailable = availability.secureKeyStorageAvailable
       return result
     }
 

packages/expo-biometrics/ios/Tests/BiometricSystemIntegrationTests.swift

@@ -76,6 +76,29 @@ final class BiometricKeyManagerTests: XCTestCase {
     XCTAssertEqual(availability.errorCode == nil, availability.canEvaluateBiometrics)
   }
 
+  func testSimulatorReportsNoSecureKeyStorage() throws {
+    #if targetEnvironment(simulator)
+      XCTAssertFalse(BiometricKeyManager().availability().secureKeyStorageAvailable)
+    #else
+      throw XCTSkip("Only the Simulator is known to lack a Secure Enclave.")
+    #endif
+  }
+
+  func testAvailabilityReportsSecureKeyStorage() {
+    XCTAssertTrue(BiometricKeyManager(isSecureEnclaveAvailable: { true }).availability().secureKeyStorageAvailable)
+    XCTAssertFalse(BiometricKeyManager(isSecureEnclaveAvailable: { false }).availability().secureKeyStorageAvailable)
+  }
+
+  func testCreateKeyRejectsWithoutSecureKeyStorage() {
+    let keyManager = BiometricKeyManager(isSecureEnclaveAvailable: { false })
+
+    for policy in BiometricCredentialPolicy.allCases {
+      XCTAssertThrowsError(try keyManager.createKey(policy: policy)) { error in
+        XCTAssertEqual((error as? BiometricsError)?.code, .secureKeyStorageUnavailable)
+      }
+    }
+  }
+
   func testErrorMapping() {
     XCTAssertEqual(BiometricsError.code(forLAErrorCode: LAError.Code.userCancel.rawValue), .userCanceled)
     XCTAssertEqual(BiometricsError.code(forLAErrorCode: LAError.Code.systemCancel.rawValue), .systemCanceled)

packages/expo-biometrics/src/__tests__/index.test.ts

@@ -21,6 +21,7 @@ const createNativeModule = () => ({
     canEvaluateBiometrics: true,
     canEvaluateDeviceOwner: true,
     errorCode: null,
+    secureKeyStorageAvailable: true,
   }),
   createKey: vi.fn().mockResolvedValue({ localKeyId: 'tdlk_1', publicKeyJwk: '{"kty":"EC"}' }),
   sign: vi.fn().mockResolvedValue('c2lnbmF0dXJl'),
@@ -67,9 +68,23 @@ describe('@clerk/expo-biometrics', () => {
       canEvaluateBiometrics: true,
       canEvaluateDeviceOwner: true,
       errorCode: null,
+      secureKeyStorageAvailable: true,
     });
   });
 
+  test('getAvailability reports missing secure key storage', async () => {
+    native.getAvailability.mockResolvedValueOnce({
+      biometryType: 'faceID',
+      canEvaluateBiometrics: true,
+      canEvaluateDeviceOwner: true,
+      errorCode: null,
+      secureKeyStorageAvailable: false,
+    });
+    const biometrics = await load();
+
+    await expect(biometrics.getAvailability()).resolves.toMatchObject({ secureKeyStorageAvailable: false });
+  });
+
   test('rejects with native_module_unavailable when the native module is missing', async () => {
     mocks.nativeModule = null;
     const biometrics = await load();
@@ -92,6 +107,17 @@ describe('@clerk/expo-biometrics', () => {
       expect(native.createKey).toHaveBeenCalledWith('biometry_or_device_passcode');
     });
 
+    test('createKey preserves secure_key_storage_unavailable', async () => {
+      native.createKey.mockRejectedValueOnce(nativeError('secure_key_storage_unavailable', 'no Secure Enclave'));
+      const biometrics = await load();
+
+      await expect(biometrics.createKey('biometry_current_set')).rejects.toMatchObject({
+        name: 'ClerkBiometricsError',
+        code: 'secure_key_storage_unavailable',
+        message: 'no Secure Enclave',
+      });
+    });
+
     test('createKey rejects unknown policies without calling native', async () => {
       const biometrics = await load();
 
@@ -139,6 +165,7 @@ describe('@clerk/expo-biometrics', () => {
       'biometry_not_enrolled',
       'biometry_lockout',
       'passcode_not_set',
+      'secure_key_storage_unavailable',
       'key_not_found',
       'key_invalidated',
       'key_generation_failed',
@@ -176,6 +203,7 @@ describe('@clerk/expo-biometrics', () => {
       const { isBiometricsErrorCode } = await load();
 
       expect(isBiometricsErrorCode('biometry_lockout')).toBe(true);
+      expect(isBiometricsErrorCode('secure_key_storage_unavailable')).toBe(true);
       expect(isBiometricsErrorCode('ERR_UNKNOWN')).toBe(false);
       expect(isBiometricsErrorCode(undefined)).toBe(false);
     });

packages/expo-biometrics/src/errors.ts

@@ -9,6 +9,7 @@ const ERROR_CODES: ReadonlySet<string> = new Set<BiometricsErrorCode>([
   'biometry_not_enrolled',
   'biometry_lockout',
   'passcode_not_set',
+  'secure_key_storage_unavailable',
   'key_not_found',
   'key_invalidated',
   'key_generation_failed',

packages/expo-biometrics/src/index.ts

@@ -108,7 +108,8 @@ export function getAvailability(): Promise<BiometricAvailability> {
 
 /**
  * Creates a new hardware-backed P-256 private key protected by `policy`.
- * Rejects with `biometry_not_available`, `biometry_not_enrolled`, or `biometry_lockout` when biometrics cannot be used.
+ * Rejects with `secure_key_storage_unavailable` when the device has no hardware-backed key storage (see `getAvailability()`),
+ * and with `biometry_not_available`, `biometry_not_enrolled`, or `biometry_lockout` when biometrics cannot be used.
  */
 export async function createKey(policy: BiometricCredentialPolicy): Promise<BiometricCredentialKey> {
   assertPolicy(policy);

packages/expo-biometrics/src/types.ts

@@ -18,6 +18,11 @@ export interface BiometricAvailability {
   canEvaluateDeviceOwner: boolean;
   /** Why biometric authentication cannot be evaluated, or `null` when it can. */
   errorCode: BiometricsErrorCode | null;
+  /**
+   * Whether the device has hardware-backed key storage (the Secure Enclave on iOS). `false` on the iOS Simulator.
+   * `createKey()` rejects with `secure_key_storage_unavailable` when this is `false`.
+   */
+  secureKeyStorageAvailable: boolean;
 }
 
 export interface BiometricCredentialKey {
@@ -75,6 +80,7 @@ export type BiometricsErrorCode =
   | 'biometry_not_enrolled'
   | 'biometry_lockout'
   | 'passcode_not_set'
+  | 'secure_key_storage_unavailable'
   | 'key_not_found'
   | 'key_invalidated'
   | 'key_generation_failed'