@clerk/expo-biometrics 0.0.1

package/ios/BiometricKeyManager.swift

@@ -0,0 +1,228 @@
+import CryptoKit
+import Foundation
+import LocalAuthentication
+import Security
+
+struct BiometricAvailability: Equatable {
+  let biometryType: String
+  let canEvaluateBiometrics: Bool
+  let canEvaluateDeviceOwner: Bool
+  let errorCode: BiometricsError.Code?
+  let secureKeyStorageAvailable: Bool
+}
+
+struct BiometricCredentialKey: Equatable {
+  let localKeyId: String
+  let publicKeyJWK: String
+}
+
+/// 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?
+    let canEvaluateBiometrics = context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &biometricsError)
+    // biometryType is only populated after canEvaluatePolicy has run.
+    let biometryType = Self.biometryTypeName(context.biometryType)
+    var deviceOwnerError: NSError?
+    let canEvaluateDeviceOwner = context.canEvaluatePolicy(.deviceOwnerAuthentication, error: &deviceOwnerError)
+
+    return BiometricAvailability(
+      biometryType: biometryType,
+      canEvaluateBiometrics: canEvaluateBiometrics,
+      canEvaluateDeviceOwner: canEvaluateDeviceOwner,
+      errorCode: canEvaluateBiometrics
+        ? nil
+        : 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 {
+      throw BiometricsError.localAuthentication(laError, fallback: .biometryNotAvailable)
+    }
+
+    let localKeyId = BiometricCredentialCoding.makeLocalKeyId()
+    let attributes = Self.privateKeyAttributes(localKeyId: localKeyId, accessControl: try Self.accessControl(policy: policy))
+
+    var error: Unmanaged<CFError>?
+    guard let privateKey = SecKeyCreateRandomKey(attributes as CFDictionary, &error) else {
+      throw Self.cfError(error, fallback: .keyGenerationFailed)
+    }
+
+    do {
+      return BiometricCredentialKey(localKeyId: localKeyId, publicKeyJWK: try Self.publicKeyJWK(for: privateKey))
+    } catch {
+      try? deleteKey(localKeyId: localKeyId)
+      throw error
+    }
+  }
+
+  func sign(localKeyId: String, clientData: String, reason: String?) throws -> String {
+    let privateKey = try privateKey(localKeyId: localKeyId, reason: reason)
+    let algorithm = SecKeyAlgorithm.ecdsaSignatureMessageX962SHA256
+    guard SecKeyIsAlgorithmSupported(privateKey, .sign, algorithm) else {
+      throw BiometricsError(.signingFailed, "The key does not support ES256 signing.")
+    }
+
+    var error: Unmanaged<CFError>?
+    guard let signature = SecKeyCreateSignature(privateKey, algorithm, Data(clientData.utf8) as CFData, &error) as Data? else {
+      throw Self.cfError(error, fallback: .signingFailed)
+    }
+
+    return BiometricCredentialCoding.base64URLEncodedString(
+      try BiometricCredentialCoding.rawES256Signature(fromDEREncoded: signature)
+    )
+  }
+
+  func hasKey(localKeyId: String) throws -> Bool {
+    var query = Self.privateKeyQuery(localKeyId: localKeyId)
+    query[kSecMatchLimit as String] = kSecMatchLimitOne
+
+    let status = SecItemCopyMatching(query as CFDictionary, nil)
+    switch status {
+    case errSecSuccess:
+      return true
+    case errSecItemNotFound:
+      return false
+    default:
+      throw BiometricsError(.storageFailed, BiometricsError.statusMessage(status))
+    }
+  }
+
+  func deleteKey(localKeyId: String) throws {
+    let status = SecItemDelete(Self.privateKeyQuery(localKeyId: localKeyId) as CFDictionary)
+    switch status {
+    case errSecSuccess, errSecItemNotFound:
+      return
+    default:
+      throw BiometricsError(.storageFailed, BiometricsError.statusMessage(status))
+    }
+  }
+
+  private func privateKey(localKeyId: String, reason: String?) throws -> SecKey {
+    let context = LAContext()
+    if let reason {
+      context.localizedReason = reason
+    }
+
+    var query = Self.privateKeyQuery(localKeyId: localKeyId)
+    query[kSecReturnRef as String] = true
+    query[kSecMatchLimit as String] = kSecMatchLimitOne
+    query[kSecUseAuthenticationContext as String] = context
+
+    var result: CFTypeRef?
+    let status = SecItemCopyMatching(query as CFDictionary, &result)
+    switch status {
+    case errSecSuccess:
+      guard let result, CFGetTypeID(result) == SecKeyGetTypeID() else {
+        throw BiometricsError(.keyNotFound, "The biometric credential key was not found.")
+      }
+      return result as! SecKey
+    case errSecItemNotFound:
+      throw BiometricsError(.keyNotFound, "The biometric credential key was not found.")
+    default:
+      throw BiometricsError.status(status, fallback: .signingFailed)
+    }
+  }
+
+  static func accessControlFlags(for policy: BiometricCredentialPolicy) -> SecAccessControlCreateFlags {
+    switch policy {
+    case .biometryCurrentSet:
+      return [.privateKeyUsage, .biometryCurrentSet]
+    case .biometryAny:
+      return [.privateKeyUsage, .biometryAny]
+    case .biometryOrDevicePasscode:
+      return [.privateKeyUsage, .userPresence]
+    }
+  }
+
+  static func accessControl(policy: BiometricCredentialPolicy) throws -> SecAccessControl {
+    var error: Unmanaged<CFError>?
+    guard let accessControl = SecAccessControlCreateWithFlags(
+      kCFAllocatorDefault,
+      kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
+      accessControlFlags(for: policy),
+      &error
+    ) else {
+      throw cfError(error, fallback: .keyGenerationFailed)
+    }
+    return accessControl
+  }
+
+  static func privateKeyAttributes(localKeyId: String, accessControl: SecAccessControl) -> [String: Any] {
+    [
+      kSecAttrKeyType as String: kSecAttrKeyTypeECSECPrimeRandom,
+      kSecAttrKeySizeInBits as String: 256,
+      kSecAttrTokenID as String: kSecAttrTokenIDSecureEnclave,
+      kSecPrivateKeyAttrs as String: [
+        kSecAttrIsPermanent as String: true,
+        kSecAttrApplicationTag as String: BiometricCredentialCoding.applicationTag(localKeyId: localKeyId),
+        kSecAttrAccessControl as String: accessControl,
+      ] as [String: Any],
+    ]
+  }
+
+  static func privateKeyQuery(localKeyId: String) -> [String: Any] {
+    [
+      kSecClass as String: kSecClassKey,
+      kSecAttrKeyClass as String: kSecAttrKeyClassPrivate,
+      kSecAttrKeyType as String: kSecAttrKeyTypeECSECPrimeRandom,
+      kSecAttrApplicationTag as String: BiometricCredentialCoding.applicationTag(localKeyId: localKeyId),
+    ]
+  }
+
+  static func biometryTypeName(_ type: LABiometryType) -> String {
+    switch type {
+    case .faceID:
+      return "faceID"
+    case .touchID:
+      return "touchID"
+    default:
+      if #available(iOS 17.0, *), type == .opticID {
+        return "opticID"
+      }
+      return "none"
+    }
+  }
+
+  private static func publicKeyJWK(for privateKey: SecKey) throws -> String {
+    guard let publicKey = SecKeyCopyPublicKey(privateKey) else {
+      throw BiometricsError(.keyGenerationFailed, "Unable to copy the public key.")
+    }
+    var error: Unmanaged<CFError>?
+    guard let representation = SecKeyCopyExternalRepresentation(publicKey, &error) as Data? else {
+      throw cfError(error, fallback: .keyGenerationFailed)
+    }
+    return try BiometricCredentialCoding.publicKeyJWK(fromX963Representation: representation)
+  }
+
+  private static func cfError(_ error: Unmanaged<CFError>?, fallback: BiometricsError.Code) -> BiometricsError {
+    guard let error else {
+      return BiometricsError(fallback, "Unknown Security framework error.")
+    }
+    return BiometricsError.security(error.takeRetainedValue() as Error, fallback: fallback)
+  }
+}

package/ios/BiometricsError.swift

@@ -0,0 +1,117 @@
+import Foundation
+import LocalAuthentication
+import Security
+
+struct BiometricsError: Error, Equatable {
+  enum Code: String {
+    case userCanceled = "user_canceled"
+    case systemCanceled = "system_canceled"
+    case userFallback = "user_fallback"
+    case authenticationFailed = "authentication_failed"
+    case biometryNotAvailable = "biometry_not_available"
+    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"
+    case signingFailed = "signing_failed"
+    case storageFailed = "storage_failed"
+    case invalidArgument = "invalid_argument"
+  }
+
+  let code: Code
+  let message: String
+
+  init(_ code: Code, _ message: String) {
+    self.code = code
+    self.message = message
+  }
+
+  static func localAuthentication(_ error: Error?, fallback: Code) -> BiometricsError {
+    guard let error = error as NSError?, error.domain == LAErrorDomain else {
+      return BiometricsError(fallback, error?.localizedDescription ?? "Local authentication failed.")
+    }
+    return BiometricsError(code(forLAErrorCode: error.code) ?? fallback, error.localizedDescription)
+  }
+
+  static func security(_ error: Error, fallback: Code) -> BiometricsError {
+    let nsError = error as NSError
+    let code: Code?
+    switch nsError.domain {
+    case LAErrorDomain:
+      code = Self.code(forLAErrorCode: nsError.code)
+    case NSOSStatusErrorDomain:
+      code = Self.code(forStatus: OSStatus(truncatingIfNeeded: nsError.code))
+    case cryptoTokenKitErrorDomain:
+      code = Self.code(forCryptoTokenKitErrorCode: nsError.code)
+    default:
+      code = nil
+    }
+    return BiometricsError(code ?? fallback, nsError.localizedDescription)
+  }
+
+  static func status(_ status: OSStatus, fallback: Code) -> BiometricsError {
+    BiometricsError(code(forStatus: status) ?? fallback, statusMessage(status))
+  }
+
+  static func statusMessage(_ status: OSStatus) -> String {
+    let description = SecCopyErrorMessageString(status, nil) as String? ?? "Unknown error"
+    return "\(description) (OSStatus \(status))"
+  }
+
+  static func code(forLAErrorCode rawValue: Int) -> Code? {
+    switch LAError.Code(rawValue: rawValue) {
+    case .userCancel:
+      return .userCanceled
+    case .appCancel, .systemCancel:
+      return .systemCanceled
+    case .userFallback:
+      return .userFallback
+    case .authenticationFailed:
+      return .authenticationFailed
+    case .biometryNotAvailable:
+      return .biometryNotAvailable
+    case .biometryNotEnrolled:
+      return .biometryNotEnrolled
+    case .biometryLockout:
+      return .biometryLockout
+    case .passcodeNotSet:
+      return .passcodeNotSet
+    default:
+      return nil
+    }
+  }
+
+  static func code(forStatus status: OSStatus) -> Code? {
+    switch status {
+    case errSecUserCanceled:
+      return .userCanceled
+    case errSecAuthFailed:
+      return .authenticationFailed
+    case errSecInteractionNotAllowed:
+      return .biometryNotAvailable
+    case errSecItemNotFound:
+      return .keyNotFound
+    default:
+      return nil
+    }
+  }
+
+  private static let cryptoTokenKitErrorDomain = "CryptoTokenKit"
+
+  // TKError.Code values; the Secure Enclave reports these when the key is unusable.
+  static func code(forCryptoTokenKitErrorCode rawValue: Int) -> Code? {
+    switch rawValue {
+    case -4:
+      return .userCanceled
+    case -5:
+      return .authenticationFailed
+    case -6:
+      return .keyInvalidated
+    default:
+      return nil
+    }
+  }
+}

package/ios/ClerkExpoBiometrics.podspec

@@ -0,0 +1,32 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name           = 'ClerkExpoBiometrics'
+  s.version        = package['version']
+  s.summary        = package['description']
+  s.description    = package['description']
+  s.license        = package['license']
+  s.author         = package['author']
+  s.homepage       = package['homepage']
+  s.platforms      = { :ios => '15.1' }
+  s.swift_version  = '5.9'
+  s.source         = { git: 'https://github.com/clerk/javascript.git' }
+  s.static_framework = true
+
+  s.dependency 'ExpoModulesCore'
+  s.frameworks = 'CryptoKit', 'LocalAuthentication', 'Security'
+
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+    'SWIFT_COMPILATION_MODE' => 'wholemodule'
+  }
+
+  s.source_files = '*.swift'
+
+  s.test_spec 'Tests' do |test_spec|
+    test_spec.source_files = 'Tests/**/*.swift'
+    test_spec.resources = 'Tests/Resources/*.json'
+  end
+end

package/ios/ClerkExpoBiometricsModule.swift

@@ -0,0 +1,164 @@
+import ExpoModulesCore
+import Foundation
+
+final class ClerkBiometricsException: Exception {
+  private let errorCode: String
+  private let message: String
+
+  init(_ error: BiometricsError) {
+    errorCode = error.code.rawValue
+    message = error.message
+    super.init()
+  }
+
+  override var code: String { errorCode }
+  override var reason: String { message }
+}
+
+struct BiometricAvailabilityResult: Record {
+  @Field var biometryType: String = "none"
+  @Field var canEvaluateBiometrics: Bool = false
+  @Field var canEvaluateDeviceOwner: Bool = false
+  @Field var errorCode: String?
+  @Field var secureKeyStorageAvailable: Bool = false
+}
+
+struct BiometricCredentialKeyResult: Record {
+  @Field var localKeyId: String = ""
+  @Field var publicKeyJwk: String = ""
+}
+
+struct BiometricCredentialRecordInput: Record {
+  @Field var id: String = ""
+  @Field var localKeyId: String = ""
+  @Field var userId: String = ""
+  @Field var appIdentifier: String = ""
+  @Field var identifierHint: String?
+  @Field var policy: String = ""
+  @Field var createdAt: Double = -1
+  @Field var updatedAt: Double = -1
+}
+
+struct SaveRecordOptions: Record {
+  @Field var removeOtherRecordsForApp: Bool = false
+}
+
+struct InstallationMarkerResult: Record {
+  @Field var wiped: Bool = false
+}
+
+public final class ClerkExpoBiometricsModule: Module {
+  private let keyManager = BiometricKeyManager()
+  private lazy var store = BiometricCredentialStore.live(keyManager: keyManager)
+
+  public func definition() -> ModuleDefinition {
+    Name("ClerkExpoBiometrics")
+
+    Function("getAppIdentifier") { () -> String in
+      Bundle.main.bundleIdentifier ?? ""
+    }
+
+    Function("hashIdentifierHint") { (hint: String) -> String? in
+      BiometricCredentialCoding.identifierHintSHA256(hint)
+    }
+
+    AsyncFunction("getAvailability") { () -> BiometricAvailabilityResult in
+      let availability = self.keyManager.availability()
+      let result = BiometricAvailabilityResult()
+      result.biometryType = availability.biometryType
+      result.canEvaluateBiometrics = availability.canEvaluateBiometrics
+      result.canEvaluateDeviceOwner = availability.canEvaluateDeviceOwner
+      result.errorCode = availability.errorCode?.rawValue
+      result.secureKeyStorageAvailable = availability.secureKeyStorageAvailable
+      return result
+    }
+
+    AsyncFunction("createKey") { (policy: String) throws -> BiometricCredentialKeyResult in
+      try Self.bridge {
+        guard let policy = BiometricCredentialPolicy(rawValue: policy) else {
+          throw BiometricsError(.invalidArgument, "Unknown biometric credential policy '\(policy)'.")
+        }
+        let key = try self.keyManager.createKey(policy: policy)
+        let result = BiometricCredentialKeyResult()
+        result.localKeyId = key.localKeyId
+        result.publicKeyJwk = key.publicKeyJWK
+        return result
+      }
+    }
+
+    AsyncFunction("sign") { (localKeyId: String, clientData: String, reason: String?) throws -> String in
+      try Self.bridge {
+        try self.keyManager.sign(localKeyId: localKeyId, clientData: clientData, reason: reason)
+      }
+    }
+
+    AsyncFunction("hasKey") { (localKeyId: String) throws -> Bool in
+      try Self.bridge { try self.keyManager.hasKey(localKeyId: localKeyId) }
+    }
+
+    AsyncFunction("deleteKey") { (localKeyId: String) throws in
+      try Self.bridge { try self.keyManager.deleteKey(localKeyId: localKeyId) }
+    }
+
+    // Store operations run on the main queue so they cannot interleave with ClerkKit's @MainActor store access.
+    AsyncFunction("listRecords") { () throws -> String in
+      try Self.bridge { try self.store.listRecordsJSON() }
+    }.runOnQueue(.main)
+
+    AsyncFunction("saveRecord") { (input: BiometricCredentialRecordInput, options: SaveRecordOptions) throws in
+      try Self.bridge {
+        try self.store.save(Self.record(from: input), removeOtherRecordsForApp: options.removeOtherRecordsForApp)
+      }
+    }.runOnQueue(.main)
+
+    AsyncFunction("deleteRecord") { (localKeyId: String) throws in
+      try Self.bridge { try self.store.deleteRecords(localKeyId: localKeyId) }
+    }.runOnQueue(.main)
+
+    AsyncFunction("ensureInstallationMarker") { () throws -> InstallationMarkerResult in
+      try Self.bridge {
+        let result = InstallationMarkerResult()
+        result.wiped = try self.store.ensureInstallationMarker()
+        return result
+      }
+    }.runOnQueue(.main)
+  }
+
+  static func record(from input: BiometricCredentialRecordInput) throws -> BiometricCredentialRecord {
+    for (name, value) in [
+      ("id", input.id),
+      ("localKeyId", input.localKeyId),
+      ("userId", input.userId),
+      ("appIdentifier", input.appIdentifier),
+    ] where value.isEmpty {
+      throw BiometricsError(.invalidArgument, "record.\(name) must be a non-empty string.")
+    }
+    guard let policy = BiometricCredentialPolicy(rawValue: input.policy) else {
+      throw BiometricsError(.invalidArgument, "Unknown biometric credential policy '\(input.policy)'.")
+    }
+    guard
+      BiometricCredentialRecord.isValidTimestamp(input.createdAt),
+      BiometricCredentialRecord.isValidTimestamp(input.updatedAt)
+    else {
+      throw BiometricsError(.invalidArgument, "record.createdAt and record.updatedAt must be milliseconds since the Unix epoch.")
+    }
+    return BiometricCredentialRecord(
+      id: input.id,
+      localKeyId: input.localKeyId,
+      userId: input.userId,
+      appIdentifier: input.appIdentifier,
+      identifierHint: input.identifierHint,
+      policy: policy,
+      createdAt: input.createdAt,
+      updatedAt: input.updatedAt
+    )
+  }
+
+  private static func bridge<T>(_ body: () throws -> T) throws -> T {
+    do {
+      return try body()
+    } catch let error as BiometricsError {
+      throw ClerkBiometricsException(error)
+    }
+  }
+}