@clerk/expo-biometrics 0.0.1

package/android/src/main/java/expo/modules/clerk/biometrics/BiometricCredentialStore.kt

@@ -0,0 +1,96 @@
+package expo.modules.clerk.biometrics
+
+import org.json.JSONArray
+import org.json.JSONObject
+
+/** The record shape the JS API uses, before the identifier hint is hashed for storage. */
+internal data class BiometricCredentialRecordInput(
+  val id: String,
+  val localKeyId: String,
+  val userId: String,
+  val appIdentifier: String,
+  val identifierHint: String?,
+  val policy: String,
+  val createdAt: Double,
+  val updatedAt: Double,
+) {
+  fun toLocalRecord(): BiometricCredentialLocalRecord {
+    for ((name, value) in listOf("id" to id, "localKeyId" to localKeyId, "userId" to userId, "appIdentifier" to appIdentifier)) {
+      if (value.isEmpty()) {
+        throw BiometricsError(BiometricsErrorCode.INVALID_ARGUMENT, "record.$name must be a non-empty string.")
+      }
+    }
+    val policy =
+      BiometricCredentialPolicy.fromValue(policy)
+        ?: throw BiometricsError(BiometricsErrorCode.INVALID_ARGUMENT, "Unknown biometric credential policy '$policy'.")
+    if (!isValidTimestamp(createdAt) || !isValidTimestamp(updatedAt)) {
+      throw BiometricsError(
+        BiometricsErrorCode.INVALID_ARGUMENT,
+        "record.createdAt and record.updatedAt must be milliseconds since the Unix epoch.",
+      )
+    }
+    return BiometricCredentialLocalRecord(
+      id = id,
+      localKeyId = localKeyId,
+      userId = userId,
+      appIdentifier = appIdentifier,
+      identifierHintSha256 = BiometricCredentialCoding.hashIdentifierHint(identifierHint),
+      policy = policy,
+      createdAt = Math.round(createdAt),
+      updatedAt = Math.round(updatedAt),
+    )
+  }
+
+  private fun isValidTimestamp(value: Double) = value.isFinite() && value >= 0 && value < 9.0e15
+}
+
+/** The store operations exposed to JS, on top of the contract v2 file and the Keystore. */
+internal class BiometricCredentialStore(
+  private val fileStore: BiometricCredentialFileStore,
+  private val deleteKey: (String) -> Unit,
+) {
+  /** Every decodable record for every app, mapped to the JS field names, with unknown stored fields passed through. */
+  fun listRecordsJson(): String = JSONArray(fileStore.records().map(::bridgeJson)).toString()
+
+  fun save(input: BiometricCredentialRecordInput, removeOtherRecordsForApp: Boolean) {
+    val record = input.toLocalRecord()
+    fileStore.save(record)?.let { runCatching { deleteKey(it) } }
+    if (!removeOtherRecordsForApp) return
+
+    // Contract v2 section 5.3: only the same user's other credentials; other users' are left for reconciliation.
+    val removable =
+      fileStore
+        .records()
+        .map { it.record }
+        .filter { it.appIdentifier == record.appIdentifier && it.userId == record.userId && it.id != record.id }
+        .filter { it.localKeyId == record.localKeyId || runCatching { deleteKey(it.localKeyId) }.isSuccess }
+        .map { it.id }
+    runCatching { fileStore.delete(removable.toSet()) }
+  }
+
+  /** Deletes the key, then every record that references it. When the key cannot be deleted the records are kept. */
+  fun deleteRecords(localKeyId: String) {
+    deleteKey(localKeyId)
+    fileStore.delete(fileStore.records().filter { it.record.localKeyId == localKeyId }.map { it.record.id }.toSet())
+  }
+
+  companion object {
+    fun bridgeJson(stored: StoredBiometricCredentialRecord): JSONObject {
+      val json = JSONObject()
+      for (key in stored.json.keys()) {
+        if (key !in BiometricCredentialRecordJson.KNOWN_FIELDS) json.put(key, stored.json.get(key))
+      }
+      val record = stored.record
+      json.put("id", record.id)
+      json.put("localKeyId", record.localKeyId)
+      json.put("userId", record.userId)
+      json.put("appIdentifier", record.appIdentifier)
+      json.put("identifierHint", JSONObject.NULL)
+      json.put("identifierHintSha256", record.identifierHintSha256 ?: JSONObject.NULL)
+      json.put("policy", record.policy.value)
+      json.put("createdAt", record.createdAt)
+      json.put("updatedAt", record.updatedAt)
+      return json
+    }
+  }
+}

package/android/src/main/java/expo/modules/clerk/biometrics/BiometricKeyManager.kt

@@ -0,0 +1,216 @@
+package expo.modules.clerk.biometrics
+
+import android.content.Context
+import android.os.Build
+import android.security.keystore.KeyInfo
+import android.security.keystore.KeyPermanentlyInvalidatedException
+import android.security.keystore.KeyProperties
+import androidx.annotation.RequiresApi
+import androidx.biometric.BiometricManager
+import androidx.biometric.BiometricManager.Authenticators
+import androidx.biometric.BiometricPrompt
+import androidx.core.content.ContextCompat
+import androidx.fragment.app.FragmentActivity
+import java.security.KeyFactory
+import java.security.KeyPairGenerator
+import java.security.KeyStore
+import java.security.PrivateKey
+import java.security.Signature
+import java.security.interfaces.ECPublicKey
+import java.util.concurrent.atomic.AtomicBoolean
+
+internal data class BiometricAvailability(
+  val biometryType: String,
+  val canEvaluateBiometrics: Boolean,
+  val canEvaluateDeviceOwner: Boolean,
+  val errorCode: BiometricsErrorCode?,
+  val secureKeyStorageAvailable: Boolean,
+)
+
+internal data class BiometricCredentialKey(val localKeyId: String, val publicKeyJwk: String)
+
+/** Android Keystore keys laid out as clerk-android's `DefaultBiometricCredentialKeyManager` creates them. */
+internal class BiometricKeyManager {
+  fun availability(context: Context): BiometricAvailability {
+    if (!secureKeyStorageAvailable()) {
+      return BiometricAvailability("none", false, false, BiometricsErrorCode.BIOMETRY_NOT_AVAILABLE, false)
+    }
+    val manager = BiometricManager.from(context)
+    val strong = manager.canAuthenticate(Authenticators.BIOMETRIC_STRONG)
+    val canEvaluateBiometrics = strong == BiometricManager.BIOMETRIC_SUCCESS
+    // Keys only accept device credentials on API 30+; before that, device owner authentication cannot sign.
+    val canEvaluateDeviceOwner =
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+        manager.canAuthenticate(Authenticators.BIOMETRIC_STRONG or Authenticators.DEVICE_CREDENTIAL) ==
+          BiometricManager.BIOMETRIC_SUCCESS
+      } else {
+        canEvaluateBiometrics
+      }
+    return BiometricAvailability(
+      biometryType = biometryType(strong),
+      canEvaluateBiometrics = canEvaluateBiometrics,
+      canEvaluateDeviceOwner = canEvaluateDeviceOwner,
+      errorCode = if (canEvaluateBiometrics) null else BiometricsError.forCanAuthenticate(strong).code,
+      secureKeyStorageAvailable = true,
+    )
+  }
+
+  fun createKey(context: Context, policy: BiometricCredentialPolicy): BiometricCredentialKey {
+    if (!secureKeyStorageAvailable()) {
+      throw BiometricsError(
+        BiometricsErrorCode.SECURE_KEY_STORAGE_UNAVAILABLE,
+        "Biometric credential keys require Android 9 (API 28) or later.",
+      )
+    }
+    val status = BiometricManager.from(context).canAuthenticate(promptAuthenticators(policy))
+    if (status != BiometricManager.BIOMETRIC_SUCCESS) {
+      throw BiometricsError.forCanAuthenticate(status)
+    }
+
+    val localKeyId = BiometricCredentialCoding.makeLocalKeyId()
+    try {
+      val generator = KeyPairGenerator.getInstance(KeyProperties.KEY_ALGORITHM_EC, ANDROID_KEY_STORE)
+      generator.initialize(BiometricCredentialCoding.keyGenParameterSpec(localKeyId, policy))
+      val publicKey = generator.generateKeyPair().public as ECPublicKey
+      return BiometricCredentialKey(
+        localKeyId = localKeyId,
+        publicKeyJwk = BiometricCredentialCoding.publicKeyJwk(publicKey.w.affineX, publicKey.w.affineY),
+      )
+    } catch (e: Exception) {
+      runCatching { deleteKey(localKeyId) }
+      throw BiometricsError(
+        BiometricsErrorCode.KEY_GENERATION_FAILED,
+        e.message ?: "Unable to create the biometric credential key.",
+        e,
+      )
+    }
+  }
+
+  fun hasKey(localKeyId: String): Boolean =
+    storageCall { keyStore().containsAlias(BiometricCredentialCoding.keyAlias(localKeyId)) }
+
+  fun deleteKey(localKeyId: String) =
+    storageCall {
+      val keyStore = keyStore()
+      val alias = BiometricCredentialCoding.keyAlias(localKeyId)
+      if (keyStore.containsAlias(alias)) keyStore.deleteEntry(alias)
+    }
+
+  /** Shows the biometric prompt on [activity] and signs the UTF-8 bytes of [clientData] with the unlocked key. */
+  fun sign(
+    activity: FragmentActivity,
+    localKeyId: String,
+    clientData: String,
+    reason: String?,
+    onResult: (Result<String>) -> Unit,
+  ) {
+    requireSupportedSdk()
+    val privateKey =
+      storageCall { keyStore().getKey(BiometricCredentialCoding.keyAlias(localKeyId), null) as? PrivateKey }
+        ?: throw BiometricsError(BiometricsErrorCode.KEY_NOT_FOUND, "The biometric credential key was not found.")
+    val signature =
+      try {
+        Signature.getInstance(BiometricCredentialCoding.SIGNATURE_ALGORITHM).apply { initSign(privateKey) }
+      } catch (e: KeyPermanentlyInvalidatedException) {
+        throw BiometricsError(BiometricsErrorCode.KEY_INVALIDATED, "The biometric credential key was invalidated.", e)
+      } catch (e: Exception) {
+        throw BiometricsError(BiometricsErrorCode.SIGNING_FAILED, e.message ?: "Unable to initialize signing.", e)
+      }
+    val allowsDeviceCredential = Build.VERSION.SDK_INT >= Build.VERSION_CODES.R && keyAllowsDeviceCredential(privateKey)
+    val title = reason?.takeIf { it.isNotBlank() } ?: activity.applicationInfo.loadLabel(activity.packageManager).toString()
+
+    val completed = AtomicBoolean(false)
+    val complete = { result: Result<String> -> if (completed.compareAndSet(false, true)) onResult(result) }
+    val callback =
+      object : BiometricPrompt.AuthenticationCallback() {
+        override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
+          val unlocked = result.cryptoObject?.signature ?: signature
+          complete(
+            runCatching {
+              unlocked.update(clientData.toByteArray(Charsets.UTF_8))
+              BiometricCredentialCoding.base64UrlEncode(BiometricCredentialCoding.rawES256SignatureFromDer(unlocked.sign()))
+            }.recoverCatching { e ->
+              throw e as? BiometricsError
+                ?: BiometricsError(BiometricsErrorCode.SIGNING_FAILED, e.message ?: "Unable to sign the challenge.", e)
+            }
+          )
+        }
+
+        override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
+          complete(Result.failure(BiometricsError.forPromptError(errorCode, errString)))
+        }
+      }
+
+    activity.runOnUiThread {
+      try {
+        val promptInfo =
+          BiometricPrompt.PromptInfo.Builder().setTitle(title).apply {
+            if (allowsDeviceCredential) {
+              setAllowedAuthenticators(Authenticators.BIOMETRIC_STRONG or Authenticators.DEVICE_CREDENTIAL)
+            } else {
+              setAllowedAuthenticators(Authenticators.BIOMETRIC_STRONG)
+              setNegativeButtonText(activity.getString(android.R.string.cancel))
+            }
+          }.build()
+        BiometricPrompt(activity, ContextCompat.getMainExecutor(activity), callback)
+          .authenticate(promptInfo, BiometricPrompt.CryptoObject(signature))
+      } catch (e: Exception) {
+        complete(
+          Result.failure(
+            BiometricsError(BiometricsErrorCode.AUTHENTICATION_FAILED, e.message ?: "Unable to show the prompt.", e)
+          )
+        )
+      }
+    }
+  }
+
+  // The key's own protections decide whether a device credential can unlock it, so keys created for
+  // biometry_or_device_passcode on API 28-29 stay biometric-only after an OS upgrade.
+  @RequiresApi(Build.VERSION_CODES.R)
+  private fun keyAllowsDeviceCredential(key: PrivateKey): Boolean =
+    runCatching {
+      val info = KeyFactory.getInstance(key.algorithm, ANDROID_KEY_STORE).getKeySpec(key, KeyInfo::class.java)
+      info.userAuthenticationType and KeyProperties.AUTH_DEVICE_CREDENTIAL != 0
+    }.getOrDefault(false)
+
+  private fun requireSupportedSdk() {
+    if (Build.VERSION.SDK_INT < BiometricCredentialCoding.MIN_SDK) {
+      throw BiometricsError(BiometricsErrorCode.BIOMETRY_NOT_AVAILABLE, "Biometric credentials require Android 9 (API 28) or later.")
+    }
+  }
+
+  private fun keyStore(): KeyStore = KeyStore.getInstance(ANDROID_KEY_STORE).apply { load(null) }
+
+  private fun <T> storageCall(body: () -> T): T =
+    try {
+      body()
+    } catch (e: BiometricsError) {
+      throw e
+    } catch (e: Exception) {
+      throw BiometricsError(BiometricsErrorCode.STORAGE_FAILED, e.message ?: "Android Keystore access failed.", e)
+    }
+
+  companion object {
+    private const val ANDROID_KEY_STORE = "AndroidKeyStore"
+
+    fun secureKeyStorageAvailable(sdkInt: Int = Build.VERSION.SDK_INT): Boolean = sdkInt >= BiometricCredentialCoding.MIN_SDK
+
+    /** Contract v2 section 2: device credentials only for biometry_or_device_passcode, and only on API 30+. */
+    fun promptAuthenticators(policy: BiometricCredentialPolicy, sdkInt: Int = Build.VERSION.SDK_INT): Int =
+      if (policy == BiometricCredentialPolicy.BIOMETRY_OR_DEVICE_PASSCODE && sdkInt >= Build.VERSION_CODES.R) {
+        Authenticators.BIOMETRIC_STRONG or Authenticators.DEVICE_CREDENTIAL
+      } else {
+        Authenticators.BIOMETRIC_STRONG
+      }
+
+    /** Android does not report which biometric is Class 3, so any present strong biometric is `biometric`. */
+    fun biometryType(canAuthenticateStrong: Int): String =
+      when (canAuthenticateStrong) {
+        BiometricManager.BIOMETRIC_SUCCESS,
+        BiometricManager.BIOMETRIC_ERROR_NONE_ENROLLED,
+        BiometricManager.BIOMETRIC_ERROR_HW_UNAVAILABLE,
+        BiometricManager.BIOMETRIC_ERROR_SECURITY_UPDATE_REQUIRED -> "biometric"
+        else -> "none"
+      }
+  }
+}

package/android/src/main/java/expo/modules/clerk/biometrics/BiometricsError.kt

@@ -0,0 +1,58 @@
+package expo.modules.clerk.biometrics
+
+import androidx.biometric.BiometricManager
+import androidx.biometric.BiometricPrompt
+
+internal enum class BiometricsErrorCode(val value: String) {
+  USER_CANCELED("user_canceled"),
+  SYSTEM_CANCELED("system_canceled"),
+  AUTHENTICATION_FAILED("authentication_failed"),
+  BIOMETRY_NOT_AVAILABLE("biometry_not_available"),
+  BIOMETRY_NOT_ENROLLED("biometry_not_enrolled"),
+  BIOMETRY_LOCKOUT("biometry_lockout"),
+  PASSCODE_NOT_SET("passcode_not_set"),
+  SECURE_KEY_STORAGE_UNAVAILABLE("secure_key_storage_unavailable"),
+  KEY_NOT_FOUND("key_not_found"),
+  KEY_INVALIDATED("key_invalidated"),
+  KEY_GENERATION_FAILED("key_generation_failed"),
+  SIGNING_FAILED("signing_failed"),
+  STORAGE_FAILED("storage_failed"),
+  INVALID_ARGUMENT("invalid_argument"),
+}
+
+internal class BiometricsError(
+  val code: BiometricsErrorCode,
+  message: String,
+  cause: Throwable? = null,
+) : Exception(message, cause) {
+  companion object {
+    fun forCanAuthenticate(status: Int): BiometricsError =
+      when (status) {
+        BiometricManager.BIOMETRIC_ERROR_NONE_ENROLLED ->
+          BiometricsError(BiometricsErrorCode.BIOMETRY_NOT_ENROLLED, "No biometrics are enrolled on this device.")
+        else ->
+          BiometricsError(
+            BiometricsErrorCode.BIOMETRY_NOT_AVAILABLE,
+            "Strong biometric authentication is not available on this device (status $status).",
+          )
+      }
+
+    fun forPromptError(errorCode: Int, message: CharSequence?): BiometricsError {
+      val code =
+        when (errorCode) {
+          BiometricPrompt.ERROR_USER_CANCELED,
+          BiometricPrompt.ERROR_NEGATIVE_BUTTON -> BiometricsErrorCode.USER_CANCELED
+          BiometricPrompt.ERROR_CANCELED -> BiometricsErrorCode.SYSTEM_CANCELED
+          BiometricPrompt.ERROR_LOCKOUT,
+          BiometricPrompt.ERROR_LOCKOUT_PERMANENT -> BiometricsErrorCode.BIOMETRY_LOCKOUT
+          BiometricPrompt.ERROR_NO_BIOMETRICS -> BiometricsErrorCode.BIOMETRY_NOT_ENROLLED
+          BiometricPrompt.ERROR_HW_NOT_PRESENT,
+          BiometricPrompt.ERROR_HW_UNAVAILABLE,
+          BiometricPrompt.ERROR_SECURITY_UPDATE_REQUIRED -> BiometricsErrorCode.BIOMETRY_NOT_AVAILABLE
+          BiometricPrompt.ERROR_NO_DEVICE_CREDENTIAL -> BiometricsErrorCode.PASSCODE_NOT_SET
+          else -> BiometricsErrorCode.AUTHENTICATION_FAILED
+        }
+      return BiometricsError(code, message?.toString() ?: "Biometric authentication failed (error $errorCode).")
+    }
+  }
+}

package/android/src/main/java/expo/modules/clerk/biometrics/ClerkExpoBiometricsModule.kt

@@ -0,0 +1,139 @@
+package expo.modules.clerk.biometrics
+
+import android.content.Context
+import androidx.fragment.app.FragmentActivity
+import expo.modules.kotlin.Promise
+import expo.modules.kotlin.exception.CodedException
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+import expo.modules.kotlin.records.Field
+import expo.modules.kotlin.records.Record
+
+class ClerkBiometricsException internal constructor(error: BiometricsError) :
+  CodedException(error.code.value, error.message, error.cause)
+
+class BiometricCredentialRecordArgument : Record {
+  @Field var id: String = ""
+  @Field var localKeyId: String = ""
+  @Field var userId: String = ""
+  @Field var appIdentifier: String = ""
+  @Field var identifierHint: String? = null
+  @Field var policy: String = ""
+  @Field var createdAt: Double = -1.0
+  @Field var updatedAt: Double = -1.0
+}
+
+class SaveRecordOptionsArgument : Record {
+  @Field var removeOtherRecordsForApp: Boolean = false
+}
+
+class ClerkExpoBiometricsModule : Module() {
+  private val keyManager = BiometricKeyManager()
+  private var cachedStore: BiometricCredentialStore? = null
+
+  override fun definition() = ModuleDefinition {
+    Name("ClerkExpoBiometrics")
+
+    Function("getAppIdentifier") { -> context().packageName }
+
+    Function("hashIdentifierHint") { hint: String -> BiometricCredentialCoding.hashIdentifierHint(hint) }
+
+    AsyncFunction("getAvailability") { ->
+      val availability = keyManager.availability(context())
+      mapOf(
+        "biometryType" to availability.biometryType,
+        "canEvaluateBiometrics" to availability.canEvaluateBiometrics,
+        "canEvaluateDeviceOwner" to availability.canEvaluateDeviceOwner,
+        "errorCode" to availability.errorCode?.value,
+        "secureKeyStorageAvailable" to availability.secureKeyStorageAvailable,
+      )
+    }
+
+    AsyncFunction("createKey") { policy: String ->
+      bridge {
+        val parsed =
+          BiometricCredentialPolicy.fromValue(policy)
+            ?: throw BiometricsError(BiometricsErrorCode.INVALID_ARGUMENT, "Unknown biometric credential policy '$policy'.")
+        val key = keyManager.createKey(context(), parsed)
+        mapOf("localKeyId" to key.localKeyId, "publicKeyJwk" to key.publicKeyJwk)
+      }
+    }
+
+    AsyncFunction("sign") { localKeyId: String, clientData: String, reason: String?, promise: Promise ->
+      try {
+        val activity =
+          appContext.currentActivity as? FragmentActivity
+            ?: throw BiometricsError(BiometricsErrorCode.SIGNING_FAILED, "Signing requires a foreground FragmentActivity.")
+        keyManager.sign(activity, localKeyId, clientData, reason) { result ->
+          result.fold(promise::resolve) { error -> promise.reject(codedException(error)) }
+        }
+      } catch (e: Throwable) {
+        promise.reject(codedException(e))
+      }
+    }
+
+    AsyncFunction("hasKey") { localKeyId: String -> bridge { keyManager.hasKey(localKeyId) } }
+
+    AsyncFunction("deleteKey") { localKeyId: String -> bridge { keyManager.deleteKey(localKeyId) } }
+
+    AsyncFunction("listRecords") { -> storeCall { store().listRecordsJson() } }
+
+    AsyncFunction("saveRecord") { record: BiometricCredentialRecordArgument, options: SaveRecordOptionsArgument ->
+      storeCall {
+        val input =
+          BiometricCredentialRecordInput(
+            id = record.id,
+            localKeyId = record.localKeyId,
+            userId = record.userId,
+            appIdentifier = record.appIdentifier,
+            identifierHint = record.identifierHint,
+            policy = record.policy,
+            createdAt = record.createdAt,
+            updatedAt = record.updatedAt,
+          )
+        store().save(input, options.removeOtherRecordsForApp)
+      }
+    }
+
+    AsyncFunction("deleteRecord") { localKeyId: String -> storeCall { store().deleteRecords(localKeyId) } }
+
+    // Uninstalling wipes both noBackupFilesDir and the app's Keystore keys, so no reinstall marker is needed.
+    AsyncFunction("ensureInstallationMarker") { -> mapOf("wiped" to false) }
+  }
+
+  private fun context(): Context =
+    appContext.reactContext?.applicationContext ?: throw CodedException("storage_failed", "The React context is not available.", null)
+
+  @Synchronized
+  private fun store(): BiometricCredentialStore =
+    cachedStore
+      ?: BiometricCredentialStore(
+        BiometricCredentialFileStore.inDirectory(context().noBackupFilesDir),
+        keyManager::deleteKey,
+      ).also { cachedStore = it }
+
+  private fun <T> bridge(body: () -> T): T =
+    try {
+      body()
+    } catch (e: BiometricsError) {
+      throw ClerkBiometricsException(e)
+    }
+
+  private fun <T> storeCall(body: () -> T): T =
+    try {
+      body()
+    } catch (e: CodedException) {
+      throw e
+    } catch (e: BiometricsError) {
+      throw ClerkBiometricsException(e)
+    } catch (e: Exception) {
+      throw CodedException("storage_failed", e.message ?: "The biometric credential store failed.", e)
+    }
+
+  private fun codedException(error: Throwable): CodedException =
+    when (error) {
+      is CodedException -> error
+      is BiometricsError -> ClerkBiometricsException(error)
+      else -> CodedException("unknown", error.message ?: "Biometric signing failed.", error)
+    }
+}