@clerk/expo-biometrics 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clerk, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+<p align="center">
+  <a href="https://clerk.com?utm_source=github&utm_medium=clerk_expo_biometrics" target="_blank" rel="noopener noreferrer">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://images.clerk.com/static/logo-dark-mode-400x400.png">
+      <img src="https://images.clerk.com/static/logo-light-mode-400x400.png" height="64">
+    </picture>
+  </a>
+  <br />
+  <h1 align="center">@clerk/expo-biometrics</h1>
+</p>
+
+<div align="center">
+
+[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord)
+[![Clerk documentation](https://img.shields.io/badge/documentation-clerk-green.svg)](https://clerk.com/docs?utm_source=github&utm_medium=expo_biometrics)
+[![Follow on X](https://img.shields.io/twitter/follow/clerk?style=social)](https://x.com/intent/follow?screen_name=clerk)
+
+[Changelog](https://github.com/clerk/javascript/blob/main/packages/expo-biometrics/CHANGELOG.md)
+·
+[Report a Bug](https://github.com/clerk/javascript/issues/new?assignees=&labels=needs-triage&projects=&template=BUG_REPORT.yml)
+·
+[Request a Feature](https://feedback.clerk.com/roadmap)
+·
+[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=expo_biometrics)
+
+</div>
+
+> [!NOTE]
+> Install this package to use `useBiometricCredentials()` from `@clerk/expo`. Its JavaScript API is used by `@clerk/expo` and isn't meant to be called directly.
+
+The native building block for Clerk biometric credentials in Expo apps. It creates hardware-backed signing keys, signs challenges behind a Face ID / Touch ID or Android biometric prompt, and stores the on-device records that link each key to a Clerk credential. It does not talk to Clerk's API; `@clerk/expo` builds the sign-in and enrollment flows on top of it.
+
+The key and record layout is shared with the Clerk iOS and Android SDKs, so credentials enrolled by either SDK in the same app are visible to both.
+
+### Prerequisites
+
+- Expo SDK 54 or later, in a development build (the module is not available in Expo Go or on the web)
+- iOS: `NSFaceIDUsageDescription` in your `Info.plist`. The `@clerk/expo` config plugin sets it through its `faceIDPermission` option.
+- iOS: a device with a Secure Enclave. The iOS Simulator has none, so `createKey()` rejects there with `secure_key_storage_unavailable`.
+- Android 9 (API level 28) or later with a strong (Class 3) biometric. On older versions `getAvailability()` reports `secureKeyStorageAvailable: false`, `createKey()` rejects with `secure_key_storage_unavailable`, and `sign()` with `biometry_not_available`.
+
+## Installation
+
+```sh
+npx expo install @clerk/expo-biometrics
+```
+
+Then rebuild your native app.
+
+## API
+
+For reference only. `@clerk/expo` calls these for you.
+
+```ts
+import {
+  createKey,
+  deleteKey,
+  deleteRecord,
+  ensureInstallationMarker,
+  getAppIdentifier,
+  getAvailability,
+  hashIdentifierHint,
+  hasKey,
+  listRecords,
+  saveRecord,
+  sign,
+} from '@clerk/expo-biometrics';
+```
+
+| Function                                       | Description                                                                                                              |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `getAppIdentifier()`                           | The app identifier sent to Clerk as `app_identifier` (the iOS bundle identifier or the Android package name).            |
+| `hashIdentifierHint(hint)`                     | The SHA-256 of the trimmed, lowercased hint as lowercase hex, or `null` when it is empty.                                |
+| `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 or Android Keystore 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.                                                                                             |
+| `listRecords()`                                | Every stored credential record, for every app identifier, with its `identifierHintSha256`.                               |
+| `saveRecord(record, options)`                  | Saves a record. With `removeOtherRecordsForApp: true`, deletes the app's other records and their keys.                   |
+| `deleteRecord(localKeyId)`                     | Deletes a key, then the records that reference it.                                                                       |
+| `ensureInstallationMarker()`                   | Deletes records and keys left behind by a previous installation of the app. The store functions call it for you.         |
+
+### Platform differences
+
+- Android stores only the hash of the identifier hint, so its records have `identifierHint: null`. Match hints by comparing `hashIdentifierHint(hint)` with `identifierHintSha256`, which both platforms return.
+- On Android, `removeOtherRecordsForApp` deletes only the same user's other records; other users' records are left for the next sign-in to reconcile.
+- Android reports `biometryType: 'biometric'`, since it does not say which sensor is a strong biometric.
+- Android's `ensureInstallationMarker()` always resolves `{ wiped: false }`: uninstalling the app already deletes its records and keys.
+
+Every error is a `ClerkBiometricsError` with a stable `code`, such as `user_canceled`, `biometry_not_enrolled`, `biometry_lockout`, `key_not_found`, or `storage_failed`.
+
+## License
+
+This project is licensed under the **MIT license**.
+
+See [LICENSE](https://github.com/clerk/javascript/blob/main/packages/expo-biometrics/LICENSE) for more information.

package/android/build.gradle

@@ -0,0 +1,49 @@
+apply plugin: 'com.android.library'
+// AGP 9+ registers the `kotlin` extension itself, and applying kotlin-android on top of that fails configuration.
+if (project.extensions.findByName('kotlin') == null) {
+  apply plugin: 'kotlin-android'
+}
+
+apply plugin: 'maven-publish'
+
+group = 'expo.modules.clerk.biometrics'
+version = '1.0.0'
+
+def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
+apply from: expoModulesCorePlugin
+applyKotlinExpoModulesCorePlugin()
+useCoreDependencies()
+useExpoPublishing()
+
+buildscript {
+  ext.safeExtGet = { prop, fallback ->
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+  }
+}
+
+android {
+  namespace "expo.modules.clerk.biometrics"
+
+  compileSdkVersion safeExtGet("compileSdkVersion", 36)
+
+  defaultConfig {
+    minSdkVersion safeExtGet("minSdkVersion", 24)
+    targetSdkVersion safeExtGet("targetSdkVersion", 36)
+    versionCode 1
+    versionName "1.0.0"
+  }
+
+  testOptions {
+    unitTests {
+      includeAndroidResources = true
+    }
+  }
+}
+
+dependencies {
+  implementation project(':expo-modules-core')
+  implementation "androidx.biometric:biometric:1.1.0"
+
+  testImplementation "junit:junit:4.13.2"
+  testImplementation "org.robolectric:robolectric:4.16"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest>
+</manifest>

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

@@ -0,0 +1,147 @@
+package expo.modules.clerk.biometrics
+
+import android.os.Build
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyProperties
+import android.util.Base64
+import java.math.BigInteger
+import java.security.MessageDigest
+import java.security.spec.ECGenParameterSpec
+import java.util.UUID
+
+// Implements clerk-android source/api/docs/biometric-credential-storage-contract.md (version 2). Any change here must
+// stay compatible with clerk-android, which reads and writes the same Keystore aliases and metadata file.
+
+internal enum class BiometricCredentialPolicy(val value: String) {
+  BIOMETRY_CURRENT_SET("biometry_current_set"),
+  BIOMETRY_ANY("biometry_any"),
+  BIOMETRY_OR_DEVICE_PASSCODE("biometry_or_device_passcode");
+
+  companion object {
+    fun fromValue(value: String?): BiometricCredentialPolicy? = entries.firstOrNull { it.value == value }
+  }
+}
+
+internal object BiometricCredentialCoding {
+  const val KEY_ALIAS_PREFIX = "com.clerk.trusted_device."
+  const val LOCAL_KEY_ID_PREFIX = "tdlk_"
+  const val SIGNATURE_ALGORITHM = "SHA256withECDSA"
+  const val EC_CURVE = "secp256r1"
+  const val MIN_SDK = Build.VERSION_CODES.P
+
+  private const val COORDINATE_SIZE = 32
+  private const val HEX = "0123456789abcdef"
+
+  fun makeLocalKeyId(): String = LOCAL_KEY_ID_PREFIX + UUID.randomUUID().toString().replace("-", "").lowercase()
+
+  fun keyAlias(localKeyId: String): String = KEY_ALIAS_PREFIX + localKeyId
+
+  /** Lowercase hex SHA-256 of the trimmed, locale-independently lowercased hint, or `null` when it is empty. */
+  fun hashIdentifierHint(hint: String?): String? {
+    val normalized = hint?.trim()?.lowercase() ?: return null
+    if (normalized.isEmpty()) return null
+    val digest = MessageDigest.getInstance("SHA-256").digest(normalized.toByteArray(Charsets.UTF_8))
+    return buildString(digest.size * 2) {
+      for (byte in digest) {
+        val value = byte.toInt() and 0xFF
+        append(HEX[value ushr 4])
+        append(HEX[value and 0x0F])
+      }
+    }
+  }
+
+  fun keyAuthenticators(policy: BiometricCredentialPolicy): Int =
+    if (policy == BiometricCredentialPolicy.BIOMETRY_OR_DEVICE_PASSCODE) {
+      KeyProperties.AUTH_BIOMETRIC_STRONG or KeyProperties.AUTH_DEVICE_CREDENTIAL
+    } else {
+      KeyProperties.AUTH_BIOMETRIC_STRONG
+    }
+
+  fun keyGenParameterSpec(localKeyId: String, policy: BiometricCredentialPolicy): KeyGenParameterSpec {
+    val builder =
+      KeyGenParameterSpec.Builder(keyAlias(localKeyId), KeyProperties.PURPOSE_SIGN)
+        .setAlgorithmParameterSpec(ECGenParameterSpec(EC_CURVE))
+        .setDigests(KeyProperties.DIGEST_SHA256)
+        .setUserAuthenticationRequired(true)
+        .setInvalidatedByBiometricEnrollment(policy == BiometricCredentialPolicy.BIOMETRY_CURRENT_SET)
+
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+      builder.setUserAuthenticationParameters(0, keyAuthenticators(policy))
+    } else {
+      @Suppress("DEPRECATION")
+      builder.setUserAuthenticationValidityDurationSeconds(-1)
+    }
+    return builder.build()
+  }
+
+  fun base64UrlEncode(bytes: ByteArray): String =
+    Base64.encodeToString(bytes, Base64.URL_SAFE or Base64.NO_PADDING or Base64.NO_WRAP)
+
+  fun publicKeyJwk(x: BigInteger, y: BigInteger): String {
+    val encodedX = base64UrlEncode(fixedWidthCoordinate(x))
+    val encodedY = base64UrlEncode(fixedWidthCoordinate(y))
+    return """{"kty":"EC","crv":"P-256","x":"$encodedX","y":"$encodedY","alg":"ES256"}"""
+  }
+
+  private fun fixedWidthCoordinate(coordinate: BigInteger): ByteArray {
+    val bytes = coordinate.toByteArray()
+    return when {
+      bytes.size == COORDINATE_SIZE -> bytes
+      bytes.size > COORDINATE_SIZE -> bytes.copyOfRange(bytes.size - COORDINATE_SIZE, bytes.size)
+      else -> ByteArray(COORDINATE_SIZE - bytes.size) + bytes
+    }
+  }
+
+  fun rawES256SignatureFromDer(signature: ByteArray): ByteArray {
+    val reader = DerReader(signature)
+    if (reader.readByte() != 0x30) throw invalidSignature()
+    if (reader.readLength() != reader.remaining) throw invalidSignature()
+    val r = reader.readInteger()
+    val s = reader.readInteger()
+    if (reader.remaining != 0) throw invalidSignature()
+    return paddedComponent(r) + paddedComponent(s)
+  }
+
+  private fun paddedComponent(component: ByteArray): ByteArray {
+    if (component.isEmpty() || component[0].toInt() and 0x80 != 0) throw invalidSignature()
+    var start = 0
+    while (component.size - start > COORDINATE_SIZE && component[start].toInt() == 0) {
+      start += 1
+    }
+    val size = component.size - start
+    if (size !in 1..COORDINATE_SIZE) throw invalidSignature()
+    return ByteArray(COORDINATE_SIZE).also { component.copyInto(it, COORDINATE_SIZE - size, start) }
+  }
+
+  private fun invalidSignature() =
+    BiometricsError(BiometricsErrorCode.SIGNING_FAILED, "Android Keystore returned an invalid ES256 signature.")
+
+  private class DerReader(private val bytes: ByteArray) {
+    private var offset = 0
+
+    val remaining: Int
+      get() = bytes.size - offset
+
+    fun readByte(): Int {
+      if (offset >= bytes.size) throw invalidSignature()
+      return bytes[offset++].toInt() and 0xFF
+    }
+
+    fun readLength(): Int {
+      val first = readByte()
+      if (first and 0x80 == 0) return first
+      val byteCount = first and 0x7F
+      if (byteCount == 0 || byteCount > Int.SIZE_BYTES || byteCount > remaining) throw invalidSignature()
+      var length = 0
+      repeat(byteCount) { length = (length shl 8) or readByte() }
+      return length
+    }
+
+    fun readInteger(): ByteArray {
+      if (readByte() != 0x02) throw invalidSignature()
+      val length = readLength()
+      if (length <= 0 || length > remaining) throw invalidSignature()
+      return bytes.copyOfRange(offset, offset + length).also { offset += length }
+    }
+  }
+}

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

@@ -0,0 +1,304 @@
+package expo.modules.clerk.biometrics
+
+import android.system.Os
+import android.system.OsConstants
+import java.io.File
+import java.io.FileOutputStream
+import java.io.IOException
+import java.io.RandomAccessFile
+import java.nio.channels.FileChannel
+import java.nio.channels.FileLock
+import java.nio.channels.OverlappingFileLockException
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.locks.ReentrantLock
+import org.json.JSONArray
+import org.json.JSONException
+import org.json.JSONObject
+
+/** A decodable credential record with a known policy (contract v2, section 3.3). */
+internal data class BiometricCredentialLocalRecord(
+  val id: String,
+  val localKeyId: String,
+  val userId: String,
+  val appIdentifier: String,
+  val identifierHintSha256: String?,
+  val policy: BiometricCredentialPolicy,
+  val createdAt: Long,
+  val updatedAt: Long,
+)
+
+/** A decoded record and the stored JSON object it came from, including fields this module does not know. */
+internal class StoredBiometricCredentialRecord(val record: BiometricCredentialLocalRecord, val json: JSONObject)
+
+/**
+ * The contract v2 metadata file shared with clerk-android: plaintext JSON in `noBackupFilesDir/clerk`, changed only by
+ * read-modify-writes under an exclusive lock on a sibling lock file and replaced atomically. Everything this module
+ * does not understand is kept on rewrite.
+ */
+internal class BiometricCredentialFileStore(
+  private val directory: File,
+  private val processGuard: ReentrantLock = PROCESS_GUARD,
+  private val lockTimeoutMillis: Long = LOCK_TIMEOUT_MILLIS,
+) {
+  val dataFile = File(directory, DATA_FILE_NAME)
+  val lockFile = File(directory, LOCK_FILE_NAME)
+  private val tempFile = File(directory, TEMP_FILE_NAME)
+
+  /** Reads without the lock: the atomic rename means a reader sees either the previous or the next complete file. */
+  fun records(): List<StoredBiometricCredentialRecord> {
+    val document = readDocument()
+    if (!document.writable) return emptyList()
+    return document.credentials.mapNotNull { element ->
+      val json = element as? JSONObject ?: return@mapNotNull null
+      BiometricCredentialRecordJson.decode(json)?.let { StoredBiometricCredentialRecord(it, json) }
+    }
+  }
+
+  /** Replaces the record with the same `id`, or appends it. Returns the replaced record's key when it differs. */
+  fun save(record: BiometricCredentialLocalRecord): String? {
+    var replacedLocalKeyId: String? = null
+    update { credentials ->
+      val index = credentials.indexOfFirst { recordId(it) == record.id }
+      val existing = credentials.getOrNull(index) as? JSONObject
+      val encoded = BiometricCredentialRecordJson.encode(record, preserving = existing)
+      if (index < 0) {
+        credentials.add(encoded)
+      } else {
+        replacedLocalKeyId =
+          (existing?.opt(BiometricCredentialRecordJson.LOCAL_KEY_ID) as? String)?.takeIf { it != record.localKeyId }
+        credentials[index] = encoded
+        for (i in credentials.lastIndex downTo index + 1) {
+          if (recordId(credentials[i]) == record.id) credentials.removeAt(i)
+        }
+      }
+      true
+    }
+    return replacedLocalKeyId
+  }
+
+  /** Removes every record, decodable or not, whose `id` is in [ids]. */
+  fun delete(ids: Set<String>) {
+    if (ids.isEmpty()) return
+    update { credentials -> credentials.removeAll { recordId(it) in ids } }
+  }
+
+  private fun update(transform: (MutableList<Any?>) -> Boolean) {
+    withExclusiveLock {
+      val document = readDocument()
+      if (!document.writable) {
+        throw IOException("The biometric credential store uses an unsupported version.")
+      }
+      val credentials = document.credentials.toMutableList()
+      if (transform(credentials)) {
+        writeDocument(document.serialized(credentials))
+      }
+    }
+  }
+
+  // Only a missing file is an empty store; other read errors must not let a writer replace it.
+  private fun readDocument(): StoreDocument {
+    if (!dataFile.exists()) return StoreDocument(JSONObject(), writable = true)
+    val text = dataFile.readText(Charsets.UTF_8)
+    val root =
+      try {
+        JSONObject(text)
+      } catch (_: JSONException) {
+        return StoreDocument(JSONObject(), writable = true)
+      }
+    val version = root.opt(KEY_VERSION)
+    val writable = (version is Int || version is Long) && (version as Number).toLong() == STORE_VERSION.toLong()
+    return StoreDocument(root, writable)
+  }
+
+  private fun writeDocument(text: String) {
+    ensureDirectory()
+    FileOutputStream(tempFile).use { output ->
+      output.write(text.toByteArray(Charsets.UTF_8))
+      output.flush()
+      output.fd.sync()
+    }
+    if (!tempFile.renameTo(dataFile)) {
+      tempFile.delete()
+      throw IOException("Failed to replace the biometric credential store.")
+    }
+    syncDirectory()
+  }
+
+  private fun syncDirectory() {
+    try {
+      val fd = Os.open(directory.path, OsConstants.O_RDONLY, 0)
+      try {
+        Os.fsync(fd)
+      } finally {
+        Os.close(fd)
+      }
+    } catch (_: Throwable) {
+    }
+  }
+
+  private fun ensureDirectory() {
+    if (!directory.isDirectory && !directory.mkdirs() && !directory.isDirectory) {
+      throw IOException("Failed to create the biometric credential store directory.")
+    }
+  }
+
+  private fun <T> withExclusiveLock(block: () -> T): T {
+    if (!processGuard.tryLock(lockTimeoutMillis, TimeUnit.MILLISECONDS)) {
+      throw IOException("Timed out waiting for the biometric credential store lock.")
+    }
+    try {
+      val fileLock = acquireFileLock()
+      try {
+        return block()
+      } finally {
+        fileLock.release()
+      }
+    } finally {
+      processGuard.unlock()
+    }
+  }
+
+  // Another SDK in this process holding the lock surfaces as OverlappingFileLockException, another process as null.
+  private fun acquireFileLock(): FileLock {
+    val channel = lockChannel()
+    val deadline = System.nanoTime() + TimeUnit.MILLISECONDS.toNanos(lockTimeoutMillis)
+    var backoffMillis = INITIAL_LOCK_BACKOFF_MILLIS
+    while (true) {
+      val lock =
+        try {
+          channel.tryLock()
+        } catch (_: OverlappingFileLockException) {
+          null
+        }
+      if (lock != null) return lock
+      if (System.nanoTime() >= deadline) {
+        throw IOException("Timed out waiting for the biometric credential store lock.")
+      }
+      Thread.sleep(backoffMillis)
+      backoffMillis = (backoffMillis * 2).coerceAtMost(MAX_LOCK_BACKOFF_MILLIS)
+    }
+  }
+
+  // Closing any descriptor of the lock file can release this process's POSIX lock, so channels are never closed.
+  private fun lockChannel(): FileChannel {
+    val path = lockFile.absolutePath
+    LOCK_CHANNELS[path]?.let { return it }
+    synchronized(LOCK_CHANNELS) {
+      return LOCK_CHANNELS.getOrPut(path) {
+        ensureDirectory()
+        RandomAccessFile(lockFile, "rw").channel
+      }
+    }
+  }
+
+  private class StoreDocument(val root: JSONObject, val writable: Boolean) {
+    val credentials: List<Any?> = (root.opt(KEY_CREDENTIALS) as? JSONArray).elements()
+
+    /** Known keys first, then unknown top-level keys in their original order. */
+    fun serialized(credentials: List<Any?>): String {
+      val pending =
+        (root.opt(KEY_PENDING_CLEANUP_USER_IDS) as? JSONArray)
+          .elements()
+          .filterIsInstance<String>()
+          .filter { it.isNotBlank() }
+          .toSortedSet()
+      val output = JSONObject()
+      output.put(KEY_VERSION, STORE_VERSION)
+      output.put(KEY_CREDENTIALS, JSONArray(credentials))
+      output.put(KEY_PENDING_CLEANUP_USER_IDS, JSONArray(pending.toList()))
+      for (key in root.keys()) {
+        if (key !in TOP_LEVEL_KEYS) output.put(key, root.get(key))
+      }
+      return output.toString()
+    }
+  }
+
+  companion object {
+    const val DIRECTORY_NAME = "clerk"
+    const val DATA_FILE_NAME = "biometric_credentials.v2.json"
+    const val TEMP_FILE_NAME = "biometric_credentials.v2.json.tmp"
+    const val LOCK_FILE_NAME = "biometric_credentials.lock"
+    const val STORE_VERSION = 2
+
+    const val KEY_VERSION = "version"
+    const val KEY_CREDENTIALS = "credentials"
+    const val KEY_PENDING_CLEANUP_USER_IDS = "pending_cleanup_user_ids"
+    private val TOP_LEVEL_KEYS = setOf(KEY_VERSION, KEY_CREDENTIALS, KEY_PENDING_CLEANUP_USER_IDS)
+
+    private const val LOCK_TIMEOUT_MILLIS = 5_000L
+    private const val INITIAL_LOCK_BACKOFF_MILLIS = 2L
+    private const val MAX_LOCK_BACKOFF_MILLIS = 50L
+
+    private val PROCESS_GUARD = ReentrantLock()
+    private val LOCK_CHANNELS = ConcurrentHashMap<String, FileChannel>()
+
+    fun inDirectory(noBackupFilesDir: File) = BiometricCredentialFileStore(File(noBackupFilesDir, DIRECTORY_NAME))
+
+    private fun recordId(element: Any?): String? = (element as? JSONObject)?.opt(BiometricCredentialRecordJson.ID) as? String
+
+    private fun JSONArray?.elements(): List<Any?> = if (this == null) emptyList() else List(length()) { opt(it) }
+  }
+}
+
+/** Contract v2 JSON encoding of a single credential record. */
+internal object BiometricCredentialRecordJson {
+  const val ID = "id"
+  const val LOCAL_KEY_ID = "local_key_id"
+  const val USER_ID = "user_id"
+  const val APP_IDENTIFIER = "app_identifier"
+  const val IDENTIFIER_HINT_SHA256 = "identifier_hint_sha256"
+  const val POLICY = "policy"
+  const val CREATED_AT = "created_at"
+  const val UPDATED_AT = "updated_at"
+
+  val KNOWN_FIELDS = setOf(ID, LOCAL_KEY_ID, USER_ID, APP_IDENTIFIER, IDENTIFIER_HINT_SHA256, POLICY, CREATED_AT, UPDATED_AT)
+
+  /** Returns `null` for records that are malformed or use a policy this module does not know. */
+  fun decode(json: JSONObject): BiometricCredentialLocalRecord? {
+    val hint =
+      when (val value = json.opt(IDENTIFIER_HINT_SHA256)) {
+        null, JSONObject.NULL -> null
+        is String -> value
+        else -> return null
+      }
+    return BiometricCredentialLocalRecord(
+      id = json.string(ID) ?: return null,
+      localKeyId = json.string(LOCAL_KEY_ID) ?: return null,
+      userId = json.string(USER_ID) ?: return null,
+      appIdentifier = json.string(APP_IDENTIFIER) ?: return null,
+      identifierHintSha256 = hint,
+      policy = BiometricCredentialPolicy.fromValue(json.string(POLICY)) ?: return null,
+      createdAt = json.long(CREATED_AT) ?: return null,
+      updatedAt = json.long(UPDATED_AT) ?: return null,
+    )
+  }
+
+  /** Encodes [record], keeping every field of [preserving] that is not part of the schema. */
+  fun encode(record: BiometricCredentialLocalRecord, preserving: JSONObject?): JSONObject {
+    val json = JSONObject()
+    json.put(ID, record.id)
+    json.put(LOCAL_KEY_ID, record.localKeyId)
+    json.put(USER_ID, record.userId)
+    json.put(APP_IDENTIFIER, record.appIdentifier)
+    record.identifierHintSha256?.let { json.put(IDENTIFIER_HINT_SHA256, it) }
+    json.put(POLICY, record.policy.value)
+    json.put(CREATED_AT, record.createdAt)
+    json.put(UPDATED_AT, record.updatedAt)
+    if (preserving != null) {
+      for (key in preserving.keys()) {
+        if (key !in KNOWN_FIELDS) json.put(key, preserving.get(key))
+      }
+    }
+    return json
+  }
+
+  private fun JSONObject.string(key: String): String? = opt(key) as? String
+
+  private fun JSONObject.long(key: String): Long? =
+    when (val value = opt(key)) {
+      is Int -> value.toLong()
+      is Long -> value
+      else -> null
+    }
+}