) =>
+ Object.fromEntries(new URLSearchParams(stringifyQueryParams(body, { keyEncoder: camelToSnake })));
+
+ it('creates a sign-in with a trusted device id', async () => {
+ vi.stubGlobal('navigator', { language: '' });
+ const mockFetch = vi.fn().mockResolvedValue({
+ client: null,
+ response: {
+ id: 'signin_123',
+ status: 'needs_first_factor',
+ first_factor_verification: {
+ object: 'verification_trusted_device',
+ status: 'unverified',
+ strategy: 'trusted_device',
+ attempts: 0,
+ trusted_device_challenge: {
+ object: 'trusted_device_challenge',
+ challenge: 'challenge_value',
+ challenge_id: 'tdch_123',
+ trusted_device_id: 'td_123',
+ client_data: 'client_data_value',
+ expires_at: 1_700_000_300,
+ algorithm: 'ES256',
+ },
+ },
+ },
+ });
+ BaseResource._fetch = mockFetch;
+ SignIn.clerk = {
+ client: { captchaBypass: false },
+ __internal_environment: { displayConfig: { captchaOauthBypass: [] } },
+ } as any;
+
+ const signIn = new SignIn();
+ await signIn.create({ strategy: 'trusted_device', trustedDeviceId: 'td_123' });
+
+ const { path, method, body } = mockFetch.mock.calls[0][0];
+ expect({ path, method }).toEqual({ path: '/client/sign_ins', method: 'POST' });
+ expect(toFormFields(body)).toEqual({ strategy: 'trusted_device', trusted_device_id: 'td_123' });
+ expect(signIn.firstFactorVerification.trustedDeviceChallenge).toEqual({
+ challenge: 'challenge_value',
+ challengeId: 'tdch_123',
+ trustedDeviceId: 'td_123',
+ clientData: 'client_data_value',
+ expiresAt: new Date(1_700_000_300_000),
+ algorithm: 'ES256',
+ });
+ });
+
+ it('attempts the first factor with a signed challenge', async () => {
+ const mockFetch = vi.fn().mockResolvedValue({
+ client: null,
+ response: { id: 'signin_123', status: 'complete' },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const signIn = new SignIn({ id: 'signin_123' } as any);
+ await signIn.attemptFirstFactor({
+ strategy: 'trusted_device',
+ trustedDeviceId: 'td_123',
+ clientData: 'client_data_value',
+ signature: 'signature_value',
+ algorithm: 'ES256',
+ });
+
+ const { path, method, body } = mockFetch.mock.calls[0][0];
+ expect({ path, method }).toEqual({ path: '/client/sign_ins/signin_123/attempt_first_factor', method: 'POST' });
+ expect(toFormFields(body)).toEqual({
+ strategy: 'trusted_device',
+ trusted_device_id: 'td_123',
+ client_data: 'client_data_value',
+ signature: 'signature_value',
+ algorithm: 'ES256',
+ });
+ });
+ });
+
describe('SignInFuture', () => {
it('can be serialized with JSON.stringify', () => {
const signIn = new SignIn();
diff --git a/packages/clerk-js/src/core/resources/__tests__/Verification.test.ts b/packages/clerk-js/src/core/resources/__tests__/Verification.test.ts
new file mode 100644
index 00000000000..0dc14642d9d
--- /dev/null
+++ b/packages/clerk-js/src/core/resources/__tests__/Verification.test.ts
@@ -0,0 +1,75 @@
+import type { VerificationJSON } from '@clerk/shared/types';
+import { describe, expect, it } from 'vitest';
+
+import { Verification } from '../Verification';
+
+const trustedDeviceVerificationJSON = {
+ object: 'verification_trusted_device',
+ id: '',
+ status: 'unverified',
+ strategy: 'trusted_device',
+ attempts: 0,
+ expire_at: 1_700_000_600_000,
+ verified_at_client: '',
+ error: null,
+ trusted_device_challenge: {
+ object: 'trusted_device_challenge',
+ challenge: 'challenge_value',
+ challenge_id: 'tdch_123',
+ trusted_device_id: 'td_123',
+ client_data: 'client_data_value',
+ expires_at: 1_700_000_300,
+ algorithm: 'ES256',
+ },
+} as unknown as VerificationJSON;
+
+describe('Verification', () => {
+ it('parses a trusted device challenge', () => {
+ const verification = new Verification(trustedDeviceVerificationJSON);
+
+ expect(verification.strategy).toBe('trusted_device');
+ expect(verification.trustedDeviceChallenge).toEqual({
+ challenge: 'challenge_value',
+ challengeId: 'tdch_123',
+ trustedDeviceId: 'td_123',
+ clientData: 'client_data_value',
+ expiresAt: new Date(1_700_000_300_000),
+ algorithm: 'ES256',
+ });
+ });
+
+ it('round-trips a trusted device challenge through the snapshot', () => {
+ const snapshot = new Verification(trustedDeviceVerificationJSON).__internal_toSnapshot();
+
+ expect(snapshot.trusted_device_challenge).toEqual(trustedDeviceVerificationJSON.trusted_device_challenge);
+ expect(new Verification(snapshot).trustedDeviceChallenge).toEqual(
+ new Verification(trustedDeviceVerificationJSON).trustedDeviceChallenge,
+ );
+ });
+
+ it('parses an enrollment challenge without a trusted device id', () => {
+ const verification = new Verification({
+ ...trustedDeviceVerificationJSON,
+ trusted_device_challenge: {
+ object: 'trusted_device_challenge',
+ challenge: 'challenge_value',
+ challenge_id: 'tdch_123',
+ client_data: 'client_data_value',
+ expires_at: 1_700_000_300,
+ algorithm: 'ES256',
+ },
+ });
+
+ expect(verification.trustedDeviceChallenge?.trustedDeviceId).toBeNull();
+ expect(verification.__internal_toSnapshot().trusted_device_challenge).not.toHaveProperty('trusted_device_id');
+ });
+
+ it('defaults to a null trusted device challenge and omits it from the snapshot', () => {
+ const { trusted_device_challenge: _, ...json } = trustedDeviceVerificationJSON;
+ const verification = new Verification(json as VerificationJSON);
+
+ expect(verification.trustedDeviceChallenge).toBeNull();
+ expect(new Verification(null).trustedDeviceChallenge).toBeNull();
+ expect(verification.__internal_toSnapshot()).not.toHaveProperty('trusted_device_challenge');
+ });
+});
diff --git a/packages/clerk-js/src/core/resources/internal.ts b/packages/clerk-js/src/core/resources/internal.ts
index aab127ec134..dc5a17847b7 100644
--- a/packages/clerk-js/src/core/resources/internal.ts
+++ b/packages/clerk-js/src/core/resources/internal.ts
@@ -12,6 +12,7 @@ export * from './BillingPaymentMethod';
export * from './BillingPlan';
export * from './BillingStatement';
export * from './BillingSubscription';
+export * from './BiometricCredential';
export * from './Client';
export * from './CommerceSettings';
export * from './DeletedObject';
diff --git a/packages/expo-biometrics/.gitignore b/packages/expo-biometrics/.gitignore
new file mode 100644
index 00000000000..3dde874d50d
--- /dev/null
+++ b/packages/expo-biometrics/.gitignore
@@ -0,0 +1,58 @@
+# OSX
+#
+.DS_Store
+
+# VSCode
+.vscode/
+jsconfig.json
+
+# Xcode
+#
+build/
+*.pbxuser
+!default.pbxuser
+*.mode1v3
+!default.mode1v3
+*.mode2v3
+!default.mode2v3
+*.perspectivev3
+!default.perspectivev3
+xcuserdata
+*.xccheckout
+*.moved-aside
+DerivedData
+*.hmap
+*.ipa
+*.xcuserstate
+project.xcworkspace
+
+# Android/IJ
+#
+.classpath
+.cxx
+.gradle
+.idea
+.project
+.settings
+local.properties
+android.iml
+android/app/libs
+android/keystores/debug.keystore
+
+# Cocoapods
+#
+example/ios/Pods
+
+# Ruby
+example/vendor/
+
+# node.js
+#
+node_modules/
+npm-debug.log
+yarn-debug.log
+yarn-error.log
+
+# Expo
+.expo/*
+.env
\ No newline at end of file
diff --git a/packages/expo-biometrics/.npmignore b/packages/expo-biometrics/.npmignore
new file mode 100644
index 00000000000..937d158a8ea
--- /dev/null
+++ b/packages/expo-biometrics/.npmignore
@@ -0,0 +1,14 @@
+# Exclude all top-level hidden directories by convention
+/.*/
+
+# Exclude tarballs generated by `npm pack`
+/*.tgz
+
+__mocks__
+__tests__
+
+/babel.config.js
+/android/src/androidTest/
+/android/src/test/
+/android/build/
+/example/
diff --git a/packages/expo-biometrics/LICENSE b/packages/expo-biometrics/LICENSE
new file mode 100644
index 00000000000..daceccfbc84
--- /dev/null
+++ b/packages/expo-biometrics/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.
diff --git a/packages/expo-biometrics/README.md b/packages/expo-biometrics/README.md
new file mode 100644
index 00000000000..c3ff2f2d534
--- /dev/null
+++ b/packages/expo-biometrics/README.md
@@ -0,0 +1,96 @@
+
+
+
+
+ 
+
+
+
+
@clerk/expo-biometrics
+
+
+
+
+[](https://clerk.com/discord)
+[](https://clerk.com/docs?utm_source=github&utm_medium=expo_biometrics)
+[](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)
+
+
+
+> [!NOTE]
+> Install this package to use `useBiometricCredentials()` from `@clerk/expo/biometrics`. 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.
diff --git a/packages/expo-biometrics/android/build.gradle b/packages/expo-biometrics/android/build.gradle
new file mode 100644
index 00000000000..992ea003e89
--- /dev/null
+++ b/packages/expo-biometrics/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"
+}
diff --git a/packages/expo-biometrics/android/src/main/AndroidManifest.xml b/packages/expo-biometrics/android/src/main/AndroidManifest.xml
new file mode 100644
index 00000000000..bdae66c8f5a
--- /dev/null
+++ b/packages/expo-biometrics/android/src/main/AndroidManifest.xml
@@ -0,0 +1,2 @@
+
+
diff --git a/packages/expo-biometrics/android/src/main/java/expo/modules/clerk/biometrics/BiometricCredentialCoding.kt b/packages/expo-biometrics/android/src/main/java/expo/modules/clerk/biometrics/BiometricCredentialCoding.kt
new file mode 100644
index 00000000000..ab578fe10a2
--- /dev/null
+++ b/packages/expo-biometrics/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
+
+// Mirrors clerk-android's storage contract v2, pinned by its BiometricCredentialStorageContractTest. 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 }
+ }
+ }
+}
diff --git a/packages/expo-biometrics/android/src/main/java/expo/modules/clerk/biometrics/BiometricCredentialFileStore.kt b/packages/expo-biometrics/android/src/main/java/expo/modules/clerk/biometrics/BiometricCredentialFileStore.kt
new file mode 100644
index 00000000000..4907229282a
--- /dev/null
+++ b/packages/expo-biometrics/android/src/main/java/expo/modules/clerk/biometrics/BiometricCredentialFileStore.kt
@@ -0,0 +1,303 @@
+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
+
+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 {
+ 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) {
+ if (ids.isEmpty()) return
+ update { credentials -> credentials.removeAll { recordId(it) in ids } }
+ }
+
+ private fun update(transform: (MutableList) -> 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))
+ }
+ }
+ }
+
+ // A missing or malformed file is an empty store, as in the Clerk Android SDK. Another version must not be replaced.
+ 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 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 = (root.opt(KEY_CREDENTIALS) as? JSONArray).elements()
+
+ /** Known keys first, then unknown top-level keys in their original order. */
+ fun serialized(credentials: List): String {
+ val pending =
+ (root.opt(KEY_PENDING_CLEANUP_USER_IDS) as? JSONArray)
+ .elements()
+ .filterIsInstance()
+ .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()
+
+ 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 = 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
+ }
+}
diff --git a/packages/expo-biometrics/android/src/main/java/expo/modules/clerk/biometrics/BiometricCredentialStore.kt b/packages/expo-biometrics/android/src/main/java/expo/modules/clerk/biometrics/BiometricCredentialStore.kt
new file mode 100644
index 00000000000..aef668e18a3
--- /dev/null
+++ b/packages/expo-biometrics/android/src/main/java/expo/modules/clerk/biometrics/BiometricCredentialStore.kt
@@ -0,0 +1,98 @@
+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) = synchronized(operationLock) {
+ val record = input.toLocalRecord()
+ fileStore.save(record)?.let { runCatching { deleteKey(it) } }
+ if (!removeOtherRecordsForApp) return@synchronized
+
+ // Only the same user's other credentials; other users' are left for reconciliation, as clerk-android does.
+ 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) = synchronized(operationLock) {
+ deleteKey(localKeyId)
+ fileStore.delete(fileStore.records().filter { it.record.localKeyId == localKeyId }.map { it.record.id }.toSet())
+ }
+
+ companion object {
+ private val operationLock = Any()
+
+ 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
+ }
+ }
+}
diff --git a/packages/expo-biometrics/android/src/main/java/expo/modules/clerk/biometrics/BiometricKeyManager.kt b/packages/expo-biometrics/android/src/main/java/expo/modules/clerk/biometrics/BiometricKeyManager.kt
new file mode 100644
index 00000000000..390865f7cd0
--- /dev/null
+++ b/packages/expo-biometrics/android/src/main/java/expo/modules/clerk/biometrics/BiometricKeyManager.kt
@@ -0,0 +1,252 @@
+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 androidx.lifecycle.Lifecycle
+import androidx.lifecycle.LifecycleEventObserver
+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(Authenticators.BIOMETRIC_STRONG)
+ 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) -> 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)
+ var prompt: BiometricPrompt? = null
+ var lifecycleObserver: LifecycleEventObserver? = null
+ // Every caller runs on the main thread, which removeObserver requires.
+ val complete = { result: Result ->
+ if (completed.compareAndSet(false, true)) {
+ lifecycleObserver?.let { activity.lifecycle.removeObserver(it) }
+ 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 {
+ // BiometricPrompt.authenticate() returns without calling back once state is saved, which would leave the promise
+ // pending forever.
+ if (!canShowPrompt(activity)) {
+ complete(
+ Result.failure(
+ BiometricsError(
+ BiometricsErrorCode.SYSTEM_CANCELED,
+ "The biometric prompt cannot be shown while the app is in the background.",
+ )
+ )
+ )
+ return@runOnUiThread
+ }
+ // A recreated activity does not reattach this callback, so settle the promise when this one is destroyed.
+ lifecycleObserver =
+ LifecycleEventObserver { _, event ->
+ if (event == Lifecycle.Event.ON_DESTROY) {
+ prompt?.cancelAuthentication()
+ complete(
+ Result.failure(
+ BiometricsError(BiometricsErrorCode.SYSTEM_CANCELED, "The activity showing the biometric prompt was destroyed.")
+ )
+ )
+ }
+ }.also { activity.lifecycle.addObserver(it) }
+ 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()
+ prompt =
+ BiometricPrompt(activity, ContextCompat.getMainExecutor(activity), callback).also {
+ it.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.SECURE_KEY_STORAGE_UNAVAILABLE,
+ "Biometric credential keys require Android 9 (API 28) or later.",
+ )
+ }
+ }
+
+ private fun keyStore(): KeyStore = KeyStore.getInstance(ANDROID_KEY_STORE).apply { load(null) }
+
+ private fun 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"
+
+ /** Whether [activity] can still show a prompt: not finishing and not past `onSaveInstanceState`. */
+ fun canShowPrompt(activity: FragmentActivity): Boolean =
+ !activity.isFinishing && !activity.isDestroyed && !activity.supportFragmentManager.isStateSaved
+
+ fun secureKeyStorageAvailable(sdkInt: Int = Build.VERSION.SDK_INT): Boolean = sdkInt >= BiometricCredentialCoding.MIN_SDK
+
+ /** 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"
+ }
+ }
+}
diff --git a/packages/expo-biometrics/android/src/main/java/expo/modules/clerk/biometrics/BiometricsError.kt b/packages/expo-biometrics/android/src/main/java/expo/modules/clerk/biometrics/BiometricsError.kt
new file mode 100644
index 00000000000..a501e7b731b
--- /dev/null
+++ b/packages/expo-biometrics/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).")
+ }
+ }
+}
diff --git a/packages/expo-biometrics/android/src/main/java/expo/modules/clerk/biometrics/ClerkExpoBiometricsModule.kt b/packages/expo-biometrics/android/src/main/java/expo/modules/clerk/biometrics/ClerkExpoBiometricsModule.kt
new file mode 100644
index 00000000000..ff0a8cc69be
--- /dev/null
+++ b/packages/expo-biometrics/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 bridge(body: () -> T): T =
+ try {
+ body()
+ } catch (e: BiometricsError) {
+ throw ClerkBiometricsException(e)
+ }
+
+ private fun 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)
+ }
+}
diff --git a/packages/expo-biometrics/android/src/test/java/expo/modules/clerk/biometrics/BiometricCredentialStorageContractTest.kt b/packages/expo-biometrics/android/src/test/java/expo/modules/clerk/biometrics/BiometricCredentialStorageContractTest.kt
new file mode 100644
index 00000000000..fd1d1b054ad
--- /dev/null
+++ b/packages/expo-biometrics/android/src/test/java/expo/modules/clerk/biometrics/BiometricCredentialStorageContractTest.kt
@@ -0,0 +1,434 @@
+package expo.modules.clerk.biometrics
+
+import android.security.keystore.KeyProperties
+import java.io.File
+import java.io.IOException
+import java.io.RandomAccessFile
+import java.math.BigInteger
+import java.security.KeyPairGenerator
+import java.security.Signature
+import java.security.spec.ECGenParameterSpec
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.Executors
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.locks.ReentrantLock
+import kotlin.concurrent.thread
+import org.json.JSONArray
+import org.json.JSONObject
+import org.junit.Assert.assertArrayEquals
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertThrows
+import org.junit.Assert.assertTrue
+import org.junit.Rule
+import org.junit.Test
+import org.junit.rules.TemporaryFolder
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+/**
+ * Pins clerk-android's biometric credential storage contract v2 with the same literals and fixture as its
+ * `BiometricCredentialStorageContractTest`. Update them only together with a contract version bump.
+ */
+@RunWith(RobolectricTestRunner::class)
+class BiometricCredentialStorageContractTest {
+ @get:Rule val temporaryFolder = TemporaryFolder()
+
+ private val directory by lazy { File(temporaryFolder.root, DIRECTORY_NAME) }
+ private val dataFile by lazy { File(directory, DATA_FILE_NAME) }
+
+ @Test
+ fun `store identifiers match the contract`() {
+ assertEquals(DIRECTORY_NAME, BiometricCredentialFileStore.DIRECTORY_NAME)
+ assertEquals(DATA_FILE_NAME, BiometricCredentialFileStore.DATA_FILE_NAME)
+ assertEquals("$DATA_FILE_NAME.tmp", BiometricCredentialFileStore.TEMP_FILE_NAME)
+ assertEquals(LOCK_FILE_NAME, BiometricCredentialFileStore.LOCK_FILE_NAME)
+ assertEquals(2, BiometricCredentialFileStore.STORE_VERSION)
+ assertEquals(KEY_ALIAS_PREFIX + LOCAL_KEY_ID, BiometricCredentialCoding.keyAlias(LOCAL_KEY_ID))
+
+ val store = BiometricCredentialFileStore.inDirectory(temporaryFolder.root)
+ assertEquals(dataFile, store.dataFile)
+ assertEquals(File(directory, LOCK_FILE_NAME), store.lockFile)
+ }
+
+ @Test
+ fun `v2 fixture written by clerk-android is readable`() {
+ writeFixture()
+
+ assertEquals(fixtureRecords, BiometricCredentialFileStore(directory).records().map { it.record })
+ }
+
+ @Test
+ fun `records written by this module match the schema`() {
+ val store = BiometricCredentialFileStore(directory)
+
+ fixtureRecords.forEach { store.save(it) }
+
+ assertEquals(
+ parse(
+ """{
+ "version":2,
+ "credentials":[
+ {"id":"td_current_set","local_key_id":"tdlk_0123456789abcdef0123456789abcdef",
+ "user_id":"user_1","app_identifier":"com.example.app",
+ "identifier_hint_sha256":"$USER_HINT_SHA256",
+ "policy":"biometry_current_set","created_at":1735689600000,"updated_at":1735689600001},
+ {"id":"td_any","local_key_id":"tdlk_fedcba9876543210fedcba9876543210",
+ "user_id":"user_2","app_identifier":"com.example.app",
+ "policy":"biometry_any","created_at":1735689700000,"updated_at":1735689700000},
+ {"id":"td_device_passcode","local_key_id":"tdlk_00000000000000000000000000000000",
+ "user_id":"user_3","app_identifier":"com.example.other",
+ "policy":"biometry_or_device_passcode","created_at":1735689800000,"updated_at":1735689800000}
+ ],
+ "pending_cleanup_user_ids":[]
+ }"""
+ ),
+ parse(dataFile.readText()),
+ )
+ assertTrue(dataFile.readText().startsWith("""{"version":2,"credentials":["""))
+ assertEquals(setOf(DATA_FILE_NAME, LOCK_FILE_NAME), directory.list()!!.toSet())
+ }
+
+ @Test
+ fun `rewrites preserve unknown fields, unknown policies, undecodable records and top-level keys`() {
+ writeFixture()
+ val store = BiometricCredentialFileStore(directory)
+
+ store.save(fixtureRecords.first())
+
+ assertEquals(parse(fixture()), parse(dataFile.readText()))
+
+ store.save(fixtureRecords.first().copy(updatedAt = 1_735_689_600_002))
+ store.delete(setOf("td_any"))
+
+ val root = JSONObject(dataFile.readText())
+ val credentials = root.getJSONArray("credentials")
+ assertEquals(
+ listOf("td_current_set", "td_device_passcode", "td_future_policy", "td_incomplete"),
+ List(credentials.length()) { credentials.getJSONObject(it).getString("id") },
+ )
+ val current = credentials.getJSONObject(0)
+ assertEquals(1_735_689_600_002, current.getLong("updated_at"))
+ assertEquals(parse("""{"nested":[1,2,3]}"""), toValue(current.get("future_field")))
+ assertEquals("some_future_policy", credentials.getJSONObject(2).getString("policy"))
+ assertEquals(parse("""{"id":"td_incomplete","user_id":"user_5"}"""), toValue(credentials.get(3)))
+ assertEquals(parse("""["user_6"]"""), toValue(root.get("pending_cleanup_user_ids")))
+ assertEquals(parse("""{"written_by":"a newer SDK"}"""), toValue(root.get("future_top_level_key")))
+ }
+
+ @Test
+ fun `pending cleanup ids are kept, sorted and de-duplicated on rewrite`() {
+ directory.mkdirs()
+ dataFile.writeText("""{"version":2,"credentials":[],"pending_cleanup_user_ids":["user_b"," ",3,"user_a","user_b"]}""")
+
+ BiometricCredentialFileStore(directory).save(fixtureRecords.first())
+
+ assertEquals(parse("""["user_a","user_b"]"""), toValue(JSONObject(dataFile.readText()).get("pending_cleanup_user_ids")))
+ }
+
+ @Test
+ fun `a different store version is read as empty and never modified`() {
+ for (future in listOf("""{"version":3,"credentials":[]}""", """{"version":"2","credentials":[]}""", """{"credentials":[]}""")) {
+ directory.mkdirs()
+ dataFile.writeText(future)
+ val store = BiometricCredentialFileStore(directory)
+
+ assertTrue(store.records().isEmpty())
+ assertThrows(IOException::class.java) { store.save(fixtureRecords.first()) }
+ assertThrows(IOException::class.java) { store.delete(setOf("td_any")) }
+ assertEquals(future, dataFile.readText())
+ }
+ }
+
+ @Test
+ fun `a malformed file reads as empty and is replaced by the next write`() {
+ directory.mkdirs()
+ dataFile.writeText("[not json")
+ val store = BiometricCredentialFileStore(directory)
+
+ assertTrue(store.records().isEmpty())
+ store.save(fixtureRecords.first())
+
+ assertEquals(listOf(fixtureRecords.first()), store.records().map { it.record })
+ }
+
+ @Test
+ fun `saving replaces the record with the same id and reports its previous key`() {
+ val store = BiometricCredentialFileStore(directory)
+ store.save(fixtureRecords.first())
+
+ assertNull(store.save(fixtureRecords.first()))
+ assertEquals(LOCAL_KEY_ID, store.save(fixtureRecords.first().copy(localKeyId = "tdlk_new")))
+ assertEquals(listOf("tdlk_new"), store.records().map { it.record.localKeyId })
+ }
+
+ @Test
+ fun `concurrent writers in independent store instances do not lose updates`() {
+ val stores = List(2) { BiometricCredentialFileStore(directory, processGuard = ReentrantLock()) }
+ val writersPerStore = 4
+ val recordsPerWriter = 15
+ val executor = Executors.newFixedThreadPool(stores.size * writersPerStore)
+ val start = CountDownLatch(1)
+ try {
+ val futures =
+ stores.flatMapIndexed { storeIndex, store ->
+ List(writersPerStore) { writer ->
+ executor.submit {
+ start.await()
+ repeat(recordsPerWriter) { index ->
+ store.save(fixtureRecords.first().copy(id = "td_${storeIndex}_${writer}_$index"))
+ }
+ }
+ }
+ }
+ start.countDown()
+ futures.forEach { it.get(60, TimeUnit.SECONDS) }
+ } finally {
+ executor.shutdownNow()
+ }
+
+ assertEquals(
+ stores.size * writersPerStore * recordsPerWriter,
+ BiometricCredentialFileStore(directory).records().map { it.record.id }.toSet().size,
+ )
+ assertFalse(File(directory, "$DATA_FILE_NAME.tmp").exists())
+ }
+
+ @Test
+ fun `writers wait for a lock held through another channel`() {
+ val store = BiometricCredentialFileStore(directory)
+ directory.mkdirs()
+ RandomAccessFile(File(directory, LOCK_FILE_NAME), "rw").channel.use { channel ->
+ val held = channel.lock()
+ val writer = thread { store.save(fixtureRecords.first()) }
+
+ writer.join(300)
+ assertTrue(writer.isAlive)
+ assertFalse(dataFile.exists())
+
+ held.release()
+ writer.join(5_000)
+ assertFalse(writer.isAlive)
+ }
+
+ assertEquals(listOf(fixtureRecords.first()), store.records().map { it.record })
+ }
+
+ @Test
+ fun `writers give up when the lock is not released in time`() {
+ val store = BiometricCredentialFileStore(directory, lockTimeoutMillis = 100)
+ directory.mkdirs()
+ RandomAccessFile(File(directory, LOCK_FILE_NAME), "rw").channel.use { channel ->
+ channel.lock().use { assertThrows(IOException::class.java) { store.save(fixtureRecords.first()) } }
+ }
+ assertFalse(dataFile.exists())
+ }
+
+ @Test
+ fun `identifier hints are hashed after trimming and lowercasing`() {
+ assertEquals(USER_HINT_SHA256, BiometricCredentialCoding.hashIdentifierHint(" User@Example.COM\n"))
+ assertEquals(USER_HINT_SHA256, BiometricCredentialCoding.hashIdentifierHint("user@example.com"))
+ assertNull(BiometricCredentialCoding.hashIdentifierHint(" \n\t"))
+ assertNull(BiometricCredentialCoding.hashIdentifierHint(""))
+ assertNull(BiometricCredentialCoding.hashIdentifierHint(null))
+ }
+
+ @Test
+ fun `local key ids are tdlk_ followed by 32 lowercase hex characters`() {
+ val localKeyId = BiometricCredentialCoding.makeLocalKeyId()
+
+ assertTrue(localKeyId, Regex("tdlk_[0-9a-f]{32}").matches(localKeyId))
+ }
+
+ @Test
+ @Config(sdk = [30])
+ fun `signing key parameters match the contract on Android 11 and later`() {
+ val expectations =
+ mapOf(
+ BiometricCredentialPolicy.BIOMETRY_CURRENT_SET to (KeyProperties.AUTH_BIOMETRIC_STRONG to true),
+ BiometricCredentialPolicy.BIOMETRY_ANY to (KeyProperties.AUTH_BIOMETRIC_STRONG to false),
+ BiometricCredentialPolicy.BIOMETRY_OR_DEVICE_PASSCODE to
+ ((KeyProperties.AUTH_BIOMETRIC_STRONG or KeyProperties.AUTH_DEVICE_CREDENTIAL) to false),
+ )
+
+ expectations.forEach { (policy, expected) ->
+ val spec = BiometricCredentialCoding.keyGenParameterSpec(LOCAL_KEY_ID, policy)
+
+ assertEquals(KEY_ALIAS_PREFIX + LOCAL_KEY_ID, spec.keystoreAlias)
+ assertEquals(KeyProperties.PURPOSE_SIGN, spec.purposes)
+ assertArrayEquals(arrayOf(KeyProperties.DIGEST_SHA256), spec.digests)
+ assertEquals("secp256r1", (spec.algorithmParameterSpec as ECGenParameterSpec).name)
+ assertTrue(spec.isUserAuthenticationRequired)
+ assertEquals(0, spec.userAuthenticationValidityDurationSeconds)
+ assertEquals(expected.first, spec.userAuthenticationType)
+ assertEquals(expected.second, spec.isInvalidatedByBiometricEnrollment)
+ assertFalse(spec.isStrongBoxBacked)
+ assertFalse(spec.isUnlockedDeviceRequired)
+ assertNull(spec.attestationChallenge)
+ }
+ }
+
+ @Test
+ @Config(sdk = [28])
+ fun `signing key parameters match the contract before Android 11`() {
+ BiometricCredentialPolicy.entries.forEach { policy ->
+ val spec = BiometricCredentialCoding.keyGenParameterSpec(LOCAL_KEY_ID, policy)
+
+ assertEquals(KEY_ALIAS_PREFIX + LOCAL_KEY_ID, spec.keystoreAlias)
+ assertEquals(KeyProperties.PURPOSE_SIGN, spec.purposes)
+ assertArrayEquals(arrayOf(KeyProperties.DIGEST_SHA256), spec.digests)
+ assertEquals("secp256r1", (spec.algorithmParameterSpec as ECGenParameterSpec).name)
+ assertTrue(spec.isUserAuthenticationRequired)
+ assertEquals(-1, spec.userAuthenticationValidityDurationSeconds)
+ assertEquals(policy == BiometricCredentialPolicy.BIOMETRY_CURRENT_SET, spec.isInvalidatedByBiometricEnrollment)
+ }
+ }
+
+ @Test
+ fun `policy values match the contract`() {
+ assertEquals(
+ listOf("biometry_current_set", "biometry_any", "biometry_or_device_passcode"),
+ BiometricCredentialPolicy.entries.map { it.value },
+ )
+ }
+
+ @Test
+ fun `public key JWK uses unpadded base64url 32-byte coordinates`() {
+ assertEquals(
+ """{"kty":"EC","crv":"P-256","x":"AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE","y":"AgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgI","alg":"ES256"}""",
+ BiometricCredentialCoding.publicKeyJwk(BigInteger(1, ByteArray(32) { 1 }), BigInteger(1, ByteArray(32) { 2 })),
+ )
+
+ val highBit = BigInteger(1, ByteArray(32) { 0xFF.toByte() })
+ val jwk = JSONObject(BiometricCredentialCoding.publicKeyJwk(highBit, BigInteger.ONE))
+ assertEquals("__________________________________________8", jwk.getString("x"))
+ assertEquals("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAE", jwk.getString("y"))
+ }
+
+ @Test
+ fun `DER signatures convert to raw r and s`() {
+ val r = byteArrayOf(0x00, 0x80.toByte()) + ByteArray(31) { 0xAA.toByte() }
+ val s = ByteArray(31) { 0x11 }
+ val der = byteArrayOf(0x30, 0x44, 0x02, r.size.toByte()) + r + byteArrayOf(0x02, s.size.toByte()) + s
+
+ val raw = BiometricCredentialCoding.rawES256SignatureFromDer(der)
+
+ assertEquals(64, raw.size)
+ assertEquals(
+ "gKqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqoAEREREREREREREREREREREREREREREREREREREREREQ",
+ BiometricCredentialCoding.base64UrlEncode(raw),
+ )
+ }
+
+ @Test
+ fun `malformed DER signatures are rejected`() {
+ val valid = byteArrayOf(0x30, 0x06, 0x02, 0x01, 0x01, 0x02, 0x01, 0x02)
+ BiometricCredentialCoding.rawES256SignatureFromDer(valid)
+
+ val malformed =
+ listOf(
+ byteArrayOf(),
+ byteArrayOf(0x31) + valid.copyOfRange(1, valid.size),
+ byteArrayOf(0x30, 0x07) + valid.copyOfRange(2, valid.size),
+ valid + byteArrayOf(0x00),
+ byteArrayOf(0x30, 0x06, 0x02, 0x01, 0x81.toByte(), 0x02, 0x01, 0x02),
+ byteArrayOf(0x30, 0x06, 0x02, 0x00, 0x02, 0x02, 0x01, 0x02),
+ byteArrayOf(0x30, 0x25, 0x02, 0x21, 0x01) + ByteArray(32) { 1 } + byteArrayOf(0x02, 0x01, 0x02),
+ )
+ for (bytes in malformed) {
+ val error = assertThrows(BiometricsError::class.java) { BiometricCredentialCoding.rawES256SignatureFromDer(bytes) }
+ assertEquals(BiometricsErrorCode.SIGNING_FAILED, error.code)
+ }
+ }
+
+ @Test
+ fun `raw signatures verify as IEEE P1363 over the UTF-8 client data`() {
+ val keyPair = KeyPairGenerator.getInstance("EC").apply { initialize(ECGenParameterSpec("secp256r1")) }.generateKeyPair()
+ val clientData = """{"challenge":"abc","nonce":"é"}"""
+
+ repeat(32) {
+ val der =
+ Signature.getInstance("SHA256withECDSA").run {
+ initSign(keyPair.private)
+ update(clientData.toByteArray(Charsets.UTF_8))
+ sign()
+ }
+ val raw = BiometricCredentialCoding.rawES256SignatureFromDer(der)
+
+ assertEquals(64, raw.size)
+ val verified =
+ Signature.getInstance("SHA256withECDSAinP1363Format").run {
+ initVerify(keyPair.public)
+ update(clientData.toByteArray(Charsets.UTF_8))
+ verify(raw)
+ }
+ assertTrue(verified)
+ }
+ }
+
+ private fun writeFixture() {
+ directory.mkdirs()
+ dataFile.writeText(fixture())
+ }
+
+ companion object {
+ const val DIRECTORY_NAME = "clerk"
+ const val DATA_FILE_NAME = "biometric_credentials.v2.json"
+ const val LOCK_FILE_NAME = "biometric_credentials.lock"
+ const val KEY_ALIAS_PREFIX = "com.clerk.trusted_device."
+ const val LOCAL_KEY_ID = "tdlk_0123456789abcdef0123456789abcdef"
+ const val USER_HINT_SHA256 = "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514"
+
+ internal val fixtureRecords =
+ listOf(
+ BiometricCredentialLocalRecord(
+ id = "td_current_set",
+ localKeyId = LOCAL_KEY_ID,
+ userId = "user_1",
+ appIdentifier = "com.example.app",
+ identifierHintSha256 = USER_HINT_SHA256,
+ policy = BiometricCredentialPolicy.BIOMETRY_CURRENT_SET,
+ createdAt = 1_735_689_600_000,
+ updatedAt = 1_735_689_600_001,
+ ),
+ BiometricCredentialLocalRecord(
+ id = "td_any",
+ localKeyId = "tdlk_fedcba9876543210fedcba9876543210",
+ userId = "user_2",
+ appIdentifier = "com.example.app",
+ identifierHintSha256 = null,
+ policy = BiometricCredentialPolicy.BIOMETRY_ANY,
+ createdAt = 1_735_689_700_000,
+ updatedAt = 1_735_689_700_000,
+ ),
+ BiometricCredentialLocalRecord(
+ id = "td_device_passcode",
+ localKeyId = "tdlk_00000000000000000000000000000000",
+ userId = "user_3",
+ appIdentifier = "com.example.other",
+ identifierHintSha256 = null,
+ policy = BiometricCredentialPolicy.BIOMETRY_OR_DEVICE_PASSCODE,
+ createdAt = 1_735_689_800_000,
+ updatedAt = 1_735_689_800_000,
+ ),
+ )
+
+ fun fixture(): String =
+ checkNotNull(BiometricCredentialStorageContractTest::class.java.getResourceAsStream("/biometric-credential-storage/v2/biometric_credentials.v2.json"))
+ .use { it.readBytes().toString(Charsets.UTF_8) }
+
+ fun parse(json: String): Any? = toValue(org.json.JSONTokener(json).nextValue())
+
+ /** Converts org.json values to plain collections so equality ignores key order and Int/Long boxing. */
+ fun toValue(value: Any?): Any? =
+ when (value) {
+ is JSONObject -> value.keys().asSequence().associateWith { toValue(value.get(it)) }
+ is JSONArray -> List(value.length()) { toValue(value.get(it)) }
+ is Int -> value.toLong()
+ JSONObject.NULL -> null
+ else -> value
+ }
+ }
+}
diff --git a/packages/expo-biometrics/android/src/test/java/expo/modules/clerk/biometrics/BiometricCredentialStoreTest.kt b/packages/expo-biometrics/android/src/test/java/expo/modules/clerk/biometrics/BiometricCredentialStoreTest.kt
new file mode 100644
index 00000000000..667c64b1e53
--- /dev/null
+++ b/packages/expo-biometrics/android/src/test/java/expo/modules/clerk/biometrics/BiometricCredentialStoreTest.kt
@@ -0,0 +1,205 @@
+package expo.modules.clerk.biometrics
+
+import expo.modules.clerk.biometrics.BiometricCredentialStorageContractTest.Companion.USER_HINT_SHA256
+import expo.modules.clerk.biometrics.BiometricCredentialStorageContractTest.Companion.fixture
+import expo.modules.clerk.biometrics.BiometricCredentialStorageContractTest.Companion.parse
+import java.io.File
+import java.io.IOException
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+import kotlin.concurrent.thread
+import org.json.JSONObject
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertThrows
+import org.junit.Assert.assertTrue
+import org.junit.Rule
+import org.junit.Test
+import org.junit.rules.TemporaryFolder
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+
+@RunWith(RobolectricTestRunner::class)
+class BiometricCredentialStoreTest {
+ @get:Rule val temporaryFolder = TemporaryFolder()
+
+ private val directory by lazy { File(temporaryFolder.root, "clerk") }
+ private val dataFile by lazy { File(directory, "biometric_credentials.v2.json") }
+ private val fileStore by lazy { BiometricCredentialFileStore(directory) }
+ private val deletedKeys = mutableListOf()
+ private val undeletableKeys = mutableSetOf()
+ private val store by lazy {
+ BiometricCredentialStore(fileStore) { localKeyId ->
+ if (localKeyId in undeletableKeys) throw IOException("Keystore failure")
+ deletedKeys += localKeyId
+ }
+ }
+
+ @Test
+ fun `listRecords maps stored records to the JS shape and passes unknown fields through`() {
+ writeFixture()
+
+ assertEquals(
+ parse(
+ """[
+ {"id":"td_current_set","localKeyId":"tdlk_0123456789abcdef0123456789abcdef","userId":"user_1",
+ "appIdentifier":"com.example.app","identifierHint":null,"identifierHintSha256":"$USER_HINT_SHA256",
+ "policy":"biometry_current_set","createdAt":1735689600000,"updatedAt":1735689600001,
+ "future_field":{"nested":[1,2,3]}},
+ {"id":"td_any","localKeyId":"tdlk_fedcba9876543210fedcba9876543210","userId":"user_2",
+ "appIdentifier":"com.example.app","identifierHint":null,"identifierHintSha256":null,
+ "policy":"biometry_any","createdAt":1735689700000,"updatedAt":1735689700000},
+ {"id":"td_device_passcode","localKeyId":"tdlk_00000000000000000000000000000000","userId":"user_3",
+ "appIdentifier":"com.example.other","identifierHint":null,"identifierHintSha256":null,
+ "policy":"biometry_or_device_passcode","createdAt":1735689800000,"updatedAt":1735689800000}
+ ]"""
+ ),
+ parse(store.listRecordsJson()),
+ )
+ }
+
+ @Test
+ fun `listRecords is empty without a file`() {
+ assertEquals("[]", store.listRecordsJson())
+ }
+
+ @Test
+ fun `saveRecord stores only the hash of the identifier hint`() {
+ store.save(input(identifierHint = " User@Example.COM\n"), removeOtherRecordsForApp = false)
+
+ val stored = JSONObject(dataFile.readText()).getJSONArray("credentials").getJSONObject(0)
+ assertEquals(USER_HINT_SHA256, stored.getString("identifier_hint_sha256"))
+ assertFalse(dataFile.readText().contains("example.com", ignoreCase = true))
+ assertEquals(
+ setOf("id", "local_key_id", "user_id", "app_identifier", "identifier_hint_sha256", "policy", "created_at", "updated_at"),
+ stored.keys().asSequence().toSet(),
+ )
+ assertEquals(1_735_689_600_001, stored.getLong("created_at"))
+
+ store.save(input(identifierHint = " "), removeOtherRecordsForApp = false)
+ assertFalse(JSONObject(dataFile.readText()).getJSONArray("credentials").getJSONObject(0).has("identifier_hint_sha256"))
+ }
+
+ @Test
+ fun `saveRecord deletes the key of the record it replaces`() {
+ store.save(input(localKeyId = "tdlk_old"), removeOtherRecordsForApp = false)
+ store.save(input(localKeyId = "tdlk_new"), removeOtherRecordsForApp = false)
+
+ assertEquals(listOf("tdlk_old"), deletedKeys)
+ assertEquals(listOf("tdlk_new"), fileStore.records().map { it.record.localKeyId })
+ }
+
+ @Test
+ fun `removing other records deletes only the same user's records for the app`() {
+ store.save(input(id = "td_same_user", localKeyId = "tdlk_same_user"), removeOtherRecordsForApp = false)
+ store.save(input(id = "td_shared_key", localKeyId = "tdlk_new"), removeOtherRecordsForApp = false)
+ store.save(input(id = "td_other_user", localKeyId = "tdlk_other_user", userId = "user_2"), removeOtherRecordsForApp = false)
+ store.save(input(id = "td_other_app", localKeyId = "tdlk_other_app", appIdentifier = "com.example.other"), removeOtherRecordsForApp = false)
+ store.save(input(id = "td_stuck", localKeyId = "tdlk_stuck"), removeOtherRecordsForApp = false)
+ undeletableKeys += "tdlk_stuck"
+
+ store.save(input(id = "td_new", localKeyId = "tdlk_new"), removeOtherRecordsForApp = true)
+
+ assertEquals(listOf("tdlk_same_user"), deletedKeys)
+ assertEquals(
+ listOf("td_other_user", "td_other_app", "td_stuck", "td_new"),
+ fileStore.records().map { it.record.id },
+ )
+ }
+
+ @Test
+ fun `a save waits for another save to finish removing records`() {
+ val otherSaveDone = CountDownLatch(1)
+ var otherSaveFinishedDuringCleanup = true
+ val racingStore =
+ BiometricCredentialStore(fileStore) { localKeyId ->
+ if (localKeyId == "tdlk_old") {
+ thread {
+ store.save(input(id = "td_second", localKeyId = "tdlk_second"), removeOtherRecordsForApp = true)
+ otherSaveDone.countDown()
+ }
+ otherSaveFinishedDuringCleanup = otherSaveDone.await(300, TimeUnit.MILLISECONDS)
+ }
+ }
+ racingStore.save(input(id = "td_old", localKeyId = "tdlk_old"), removeOtherRecordsForApp = false)
+
+ racingStore.save(input(id = "td_first", localKeyId = "tdlk_first"), removeOtherRecordsForApp = true)
+
+ assertFalse(otherSaveFinishedDuringCleanup)
+ assertTrue(otherSaveDone.await(5, TimeUnit.SECONDS))
+ assertEquals(listOf("td_second"), fileStore.records().map { it.record.id })
+ }
+
+ @Test
+ fun `removing other records keeps records this module cannot decode`() {
+ writeFixture()
+
+ store.save(input(id = "td_new", localKeyId = "tdlk_new", userId = "user_4"), removeOtherRecordsForApp = true)
+
+ val ids = JSONObject(dataFile.readText()).getJSONArray("credentials").let { array -> List(array.length()) { array.getJSONObject(it).getString("id") } }
+ assertEquals(listOf("td_current_set", "td_any", "td_device_passcode", "td_future_policy", "td_incomplete", "td_new"), ids)
+ assertTrue(deletedKeys.isEmpty())
+ }
+
+ @Test
+ fun `deleteRecord deletes the key then the records that reference it`() {
+ writeFixture()
+
+ store.deleteRecords("tdlk_fedcba9876543210fedcba9876543210")
+
+ assertEquals(listOf("tdlk_fedcba9876543210fedcba9876543210"), deletedKeys)
+ assertEquals(listOf("td_current_set", "td_device_passcode"), fileStore.records().map { it.record.id })
+ assertTrue(dataFile.readText().contains("td_future_policy"))
+ }
+
+ @Test
+ fun `deleteRecord keeps the records when the key cannot be deleted`() {
+ writeFixture()
+ undeletableKeys += "tdlk_fedcba9876543210fedcba9876543210"
+
+ assertThrows(IOException::class.java) { store.deleteRecords("tdlk_fedcba9876543210fedcba9876543210") }
+
+ assertEquals(parse(fixture()), parse(dataFile.readText()))
+ }
+
+ @Test
+ fun `record input is validated`() {
+ val invalid =
+ listOf(
+ input(id = ""),
+ input(localKeyId = ""),
+ input(userId = ""),
+ input(appIdentifier = ""),
+ input(policy = "face_id"),
+ input(createdAt = -1.0),
+ input(updatedAt = Double.NaN),
+ input(createdAt = 9.0e15),
+ )
+ for (record in invalid) {
+ val error = assertThrows(BiometricsError::class.java) { store.save(record, removeOtherRecordsForApp = false) }
+ assertEquals(BiometricsErrorCode.INVALID_ARGUMENT, error.code)
+ }
+ assertFalse(dataFile.exists())
+ }
+
+ @Test
+ fun `timestamps are rounded to integer milliseconds`() {
+ assertEquals(1_714_000_000_001, input(createdAt = 1_714_000_000_000.5).toLocalRecord().createdAt)
+ }
+
+ private fun writeFixture() {
+ directory.mkdirs()
+ dataFile.writeText(fixture())
+ }
+
+ private fun input(
+ id: String = "td_1",
+ localKeyId: String = "tdlk_1",
+ userId: String = "user_1",
+ appIdentifier: String = "com.example.app",
+ identifierHint: String? = null,
+ policy: String = "biometry_current_set",
+ createdAt: Double = 1_735_689_600_001.0,
+ updatedAt: Double = 1_735_689_600_002.0,
+ ) = BiometricCredentialRecordInput(id, localKeyId, userId, appIdentifier, identifierHint, policy, createdAt, updatedAt)
+}
diff --git a/packages/expo-biometrics/android/src/test/java/expo/modules/clerk/biometrics/BiometricKeyManagerTest.kt b/packages/expo-biometrics/android/src/test/java/expo/modules/clerk/biometrics/BiometricKeyManagerTest.kt
new file mode 100644
index 00000000000..fb3d79ee865
--- /dev/null
+++ b/packages/expo-biometrics/android/src/test/java/expo/modules/clerk/biometrics/BiometricKeyManagerTest.kt
@@ -0,0 +1,77 @@
+package expo.modules.clerk.biometrics
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertThrows
+import org.junit.Assert.assertTrue
+import androidx.fragment.app.FragmentActivity
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.Robolectric
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.RuntimeEnvironment
+import org.robolectric.annotation.Config
+
+@RunWith(RobolectricTestRunner::class)
+class BiometricKeyManagerTest {
+ @Test
+ fun `secure key storage requires Android 9`() {
+ assertFalse(BiometricKeyManager.secureKeyStorageAvailable(sdkInt = 27))
+ assertTrue(BiometricKeyManager.secureKeyStorageAvailable(sdkInt = 28))
+ assertTrue(BiometricKeyManager.secureKeyStorageAvailable(sdkInt = 36))
+ }
+
+ @Test
+ @Config(sdk = [27])
+ fun `availability reports no secure key storage before Android 9`() {
+ val availability = BiometricKeyManager().availability(RuntimeEnvironment.getApplication())
+
+ assertFalse(availability.secureKeyStorageAvailable)
+ assertFalse(availability.canEvaluateBiometrics)
+ assertEquals(BiometricsErrorCode.BIOMETRY_NOT_AVAILABLE, availability.errorCode)
+ }
+
+ @Test
+ @Config(sdk = [28])
+ fun `availability reports secure key storage on Android 9 and later`() {
+ assertTrue(BiometricKeyManager().availability(RuntimeEnvironment.getApplication()).secureKeyStorageAvailable)
+ }
+
+ @Test
+ @Config(sdk = [27])
+ fun `createKey rejects with secure_key_storage_unavailable before Android 9`() {
+ for (policy in BiometricCredentialPolicy.entries) {
+ val error =
+ assertThrows(BiometricsError::class.java) {
+ BiometricKeyManager().createKey(RuntimeEnvironment.getApplication(), policy)
+ }
+ assertEquals(BiometricsErrorCode.SECURE_KEY_STORAGE_UNAVAILABLE, error.code)
+ }
+ }
+
+ @Test
+ @Config(sdk = [27])
+ fun `sign rejects with secure_key_storage_unavailable before Android 9`() {
+ val activity = Robolectric.buildActivity(FragmentActivity::class.java).setup().get()
+ val error =
+ assertThrows(BiometricsError::class.java) {
+ BiometricKeyManager().sign(activity, "tdlk_0", "client-data", null) {}
+ }
+ assertEquals(BiometricsErrorCode.SECURE_KEY_STORAGE_UNAVAILABLE, error.code)
+ }
+
+ @Test
+ fun `the prompt is only shown before state is saved`() {
+ val controller = Robolectric.buildActivity(FragmentActivity::class.java).setup()
+ assertTrue(BiometricKeyManager.canShowPrompt(controller.get()))
+
+ controller.pause().stop()
+ assertFalse(BiometricKeyManager.canShowPrompt(controller.get()))
+
+ controller.start().resume()
+ assertTrue(BiometricKeyManager.canShowPrompt(controller.get()))
+
+ controller.pause().stop().destroy()
+ assertFalse(BiometricKeyManager.canShowPrompt(controller.get()))
+ }
+}
diff --git a/packages/expo-biometrics/android/src/test/resources/biometric-credential-storage/v2/biometric_credentials.v2.json b/packages/expo-biometrics/android/src/test/resources/biometric-credential-storage/v2/biometric_credentials.v2.json
new file mode 100644
index 00000000000..21e9526106c
--- /dev/null
+++ b/packages/expo-biometrics/android/src/test/resources/biometric-credential-storage/v2/biometric_credentials.v2.json
@@ -0,0 +1,50 @@
+{
+ "version": 2,
+ "credentials": [
+ {
+ "id": "td_current_set",
+ "local_key_id": "tdlk_0123456789abcdef0123456789abcdef",
+ "user_id": "user_1",
+ "app_identifier": "com.example.app",
+ "identifier_hint_sha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514",
+ "policy": "biometry_current_set",
+ "created_at": 1735689600000,
+ "updated_at": 1735689600001,
+ "future_field": { "nested": [1, 2, 3] }
+ },
+ {
+ "id": "td_any",
+ "local_key_id": "tdlk_fedcba9876543210fedcba9876543210",
+ "user_id": "user_2",
+ "app_identifier": "com.example.app",
+ "policy": "biometry_any",
+ "created_at": 1735689700000,
+ "updated_at": 1735689700000
+ },
+ {
+ "id": "td_device_passcode",
+ "local_key_id": "tdlk_00000000000000000000000000000000",
+ "user_id": "user_3",
+ "app_identifier": "com.example.other",
+ "identifier_hint_sha256": null,
+ "policy": "biometry_or_device_passcode",
+ "created_at": 1735689800000,
+ "updated_at": 1735689800000
+ },
+ {
+ "id": "td_future_policy",
+ "local_key_id": "tdlk_11111111111111111111111111111111",
+ "user_id": "user_4",
+ "app_identifier": "com.example.app",
+ "policy": "some_future_policy",
+ "created_at": 1735689900000,
+ "updated_at": 1735689900000
+ },
+ {
+ "id": "td_incomplete",
+ "user_id": "user_5"
+ }
+ ],
+ "pending_cleanup_user_ids": ["user_6"],
+ "future_top_level_key": { "written_by": "a newer SDK" }
+}
diff --git a/packages/expo-biometrics/android/src/test/resources/robolectric.properties b/packages/expo-biometrics/android/src/test/resources/robolectric.properties
new file mode 100644
index 00000000000..28a4ed295fa
--- /dev/null
+++ b/packages/expo-biometrics/android/src/test/resources/robolectric.properties
@@ -0,0 +1 @@
+sdk=30
diff --git a/packages/expo-biometrics/expo-module.config.json b/packages/expo-biometrics/expo-module.config.json
new file mode 100644
index 00000000000..08bfbbf215e
--- /dev/null
+++ b/packages/expo-biometrics/expo-module.config.json
@@ -0,0 +1,9 @@
+{
+ "platforms": ["apple", "android"],
+ "apple": {
+ "modules": ["ClerkExpoBiometricsModule"]
+ },
+ "android": {
+ "modules": ["expo.modules.clerk.biometrics.ClerkExpoBiometricsModule"]
+ }
+}
diff --git a/packages/expo-biometrics/ios/BiometricCredentialCoding.swift b/packages/expo-biometrics/ios/BiometricCredentialCoding.swift
new file mode 100644
index 00000000000..45a744975bd
--- /dev/null
+++ b/packages/expo-biometrics/ios/BiometricCredentialCoding.swift
@@ -0,0 +1,335 @@
+import CryptoKit
+import Foundation
+
+// Mirrors the format pinned by clerk-ios BiometricCredentialStorageContractTests. Any change here must stay
+// byte-compatible with ClerkKit, which reads and writes the same keys, Keychain item, and UserDefaults marker.
+
+enum BiometricCredentialPolicy: String, CaseIterable {
+ case biometryCurrentSet = "biometry_current_set"
+ case biometryAny = "biometry_any"
+ case biometryOrDevicePasscode = "biometry_or_device_passcode"
+}
+
+enum BiometricCredentialCoding {
+ static let applicationTagPrefix = "dev.clerk.trusted_device"
+ static let metadataAccount = "trustedDeviceCredentials"
+ static let installationMarkerPrefix = "com.clerk.trusted-device-installation-marker"
+
+ static func makeLocalKeyId() -> String {
+ "tdlk_" + UUID().uuidString.replacingOccurrences(of: "-", with: "").lowercased()
+ }
+
+ static func applicationTag(localKeyId: String) -> Data {
+ Data("\(applicationTagPrefix).\(localKeyId)".utf8)
+ }
+
+ static func metadataService(infoDictionaryService: String?, bundleIdentifier: String?) -> String {
+ if let infoDictionaryService, !infoDictionaryService.isEmpty {
+ return infoDictionaryService
+ }
+ return bundleIdentifier ?? ""
+ }
+
+ static func installationMarkerKey(service: String?, accessGroup: String?, appIdentifier: String?) -> String {
+ [
+ installationMarkerPrefix,
+ encodeInstallationMarkerComponent(service),
+ encodeInstallationMarkerComponent(accessGroup),
+ encodeInstallationMarkerComponent(appIdentifier),
+ ].joined(separator: ".")
+ }
+
+ private static func encodeInstallationMarkerComponent(_ value: String?) -> String {
+ guard let value else { return "n" }
+ return "s\(value.utf8.count):\(value)"
+ }
+
+ /// Lowercase hex SHA-256 of the normalized hint, as clerk-android's storage contract v2 stores it; `nil` when it is empty.
+ static func identifierHintSHA256(_ identifierHint: String?) -> String? {
+ guard let normalized = BiometricCredentialRecord.normalizedIdentifierHint(identifierHint) else { return nil }
+ return SHA256.hash(data: Data(normalized.utf8)).map { String(format: "%02x", $0) }.joined()
+ }
+
+ static func base64URLEncodedString(_ data: D) -> String {
+ Data(data)
+ .base64EncodedString()
+ .replacingOccurrences(of: "+", with: "-")
+ .replacingOccurrences(of: "/", with: "_")
+ .replacingOccurrences(of: "=", with: "")
+ }
+
+ static func publicKeyJWK(fromX963Representation representation: Data) throws -> String {
+ let bytes = [UInt8](representation)
+ guard bytes.count == 65, bytes[0] == 0x04 else {
+ throw BiometricsError(.keyGenerationFailed, "The public key is not an uncompressed P-256 point.")
+ }
+ let x = base64URLEncodedString(bytes[1 ..< 33])
+ let y = base64URLEncodedString(bytes[33 ..< 65])
+ return #"{"kty":"EC","crv":"P-256","x":"\#(x)","y":"\#(y)","alg":"ES256"}"#
+ }
+
+ static func rawES256Signature(fromDEREncoded signature: Data) throws -> Data {
+ let bytes = [UInt8](signature)
+ var offset = 0
+
+ guard try readDERByte(bytes, offset: &offset) == 0x30 else {
+ throw invalidSignature()
+ }
+ let sequenceLength = try readDERLength(bytes, offset: &offset)
+ guard sequenceLength == bytes.count - offset else {
+ throw invalidSignature()
+ }
+
+ let r = try readDERInteger(bytes, offset: &offset)
+ let s = try readDERInteger(bytes, offset: &offset)
+ guard offset == bytes.count else {
+ throw invalidSignature()
+ }
+
+ var raw = try paddedES256Component(r)
+ raw.append(try paddedES256Component(s))
+ return raw
+ }
+
+ private static func readDERByte(_ bytes: [UInt8], offset: inout Int) throws -> UInt8 {
+ guard offset < bytes.count else { throw invalidSignature() }
+ let byte = bytes[offset]
+ offset += 1
+ return byte
+ }
+
+ private static func readDERLength(_ bytes: [UInt8], offset: inout Int) throws -> Int {
+ let first = try readDERByte(bytes, offset: &offset)
+ if first & 0x80 == 0 {
+ return Int(first)
+ }
+ let byteCount = Int(first & 0x7F)
+ guard byteCount > 0, byteCount <= MemoryLayout.size, byteCount <= bytes.count - offset else {
+ throw invalidSignature()
+ }
+ var length = 0
+ for _ in 0 ..< byteCount {
+ length = (length << 8) | Int(try readDERByte(bytes, offset: &offset))
+ }
+ return length
+ }
+
+ private static func readDERInteger(_ bytes: [UInt8], offset: inout Int) throws -> [UInt8] {
+ guard try readDERByte(bytes, offset: &offset) == 0x02 else { throw invalidSignature() }
+ let length = try readDERLength(bytes, offset: &offset)
+ guard length > 0, length <= bytes.count - offset else { throw invalidSignature() }
+ let value = Array(bytes[offset ..< offset + length])
+ offset += length
+ return value
+ }
+
+ private static func paddedES256Component(_ bytes: [UInt8]) throws -> Data {
+ guard let first = bytes.first, first & 0x80 == 0 else { throw invalidSignature() }
+ var component = bytes
+ while component.first == 0x00, component.count > 32 {
+ component.removeFirst()
+ }
+ guard !component.isEmpty, component.count <= 32 else { throw invalidSignature() }
+ var padded = Data(repeating: 0x00, count: 32 - component.count)
+ padded.append(contentsOf: component)
+ return padded
+ }
+
+ private static func invalidSignature() -> BiometricsError {
+ BiometricsError(.signingFailed, "Security returned an invalid ES256 signature.")
+ }
+}
+
+/// A record in the metadata Keychain item.
+struct BiometricCredentialRecord: Equatable {
+ enum Field {
+ static let id = "id"
+ static let localKeyId = "localKeyId"
+ static let userId = "userId"
+ static let appIdentifier = "appIdentifier"
+ static let identifierHint = "identifierHint"
+ static let identifierHintSha256 = "identifierHintSha256"
+ static let policy = "policy"
+ static let createdAt = "createdAt"
+ static let updatedAt = "updatedAt"
+ }
+
+ let id: String
+ let localKeyId: String
+ let userId: String
+ let appIdentifier: String
+ let identifierHint: String?
+ let policy: BiometricCredentialPolicy
+ /// Milliseconds since the Unix epoch.
+ let createdAt: Double
+ /// Milliseconds since the Unix epoch.
+ let updatedAt: Double
+
+ init(
+ id: String,
+ localKeyId: String,
+ userId: String,
+ appIdentifier: String,
+ identifierHint: String?,
+ policy: BiometricCredentialPolicy,
+ createdAt: Double,
+ updatedAt: Double
+ ) {
+ self.id = id
+ self.localKeyId = localKeyId
+ self.userId = userId
+ self.appIdentifier = appIdentifier
+ self.identifierHint = Self.normalizedIdentifierHint(identifierHint)
+ self.policy = policy
+ self.createdAt = createdAt
+ self.updatedAt = updatedAt
+ }
+
+ /// Decodes a stored record, returning `nil` for records ClerkKit treats as malformed.
+ init?(jsonObject object: [String: Any]) {
+ guard
+ let id = object[Field.id] as? String,
+ let localKeyId = object[Field.localKeyId] as? String,
+ let userId = object[Field.userId] as? String,
+ let appIdentifier = object[Field.appIdentifier] as? String,
+ let policyValue = object[Field.policy] as? String,
+ let policy = BiometricCredentialPolicy(rawValue: policyValue),
+ let createdAt = Self.number(object[Field.createdAt]),
+ let updatedAt = Self.number(object[Field.updatedAt])
+ else {
+ return nil
+ }
+
+ let identifierHint: String?
+ switch object[Field.identifierHint] {
+ case .none, is NSNull:
+ identifierHint = nil
+ case let value as String:
+ identifierHint = value
+ default:
+ return nil
+ }
+
+ self.init(
+ id: id,
+ localKeyId: localKeyId,
+ userId: userId,
+ appIdentifier: appIdentifier,
+ identifierHint: identifierHint,
+ policy: policy,
+ createdAt: createdAt,
+ updatedAt: updatedAt
+ )
+ }
+
+ /// The object written to the Keychain: integer milliseconds, `identifierHint` omitted when absent.
+ var jsonObject: [String: Any] {
+ var object: [String: Any] = [
+ Field.id: id,
+ Field.localKeyId: localKeyId,
+ Field.userId: userId,
+ Field.appIdentifier: appIdentifier,
+ Field.policy: policy.rawValue,
+ Field.createdAt: Int64(createdAt.rounded()),
+ Field.updatedAt: Int64(updatedAt.rounded()),
+ ]
+ if let identifierHint {
+ object[Field.identifierHint] = identifierHint
+ }
+ return object
+ }
+
+ static func normalizedIdentifierHint(_ identifierHint: String?) -> String? {
+ guard let identifierHint else { return nil }
+ let normalized = identifierHint.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+ return normalized.isEmpty ? nil : normalized
+ }
+
+ static func isValidTimestamp(_ value: Double) -> Bool {
+ value.isFinite && value >= 0 && value < 9.0e15
+ }
+
+ private static func number(_ value: Any?) -> Double? {
+ guard let number = value as? NSNumber, CFGetTypeID(number) != CFBooleanGetTypeID() else {
+ return nil
+ }
+ return number.doubleValue
+ }
+}
+
+enum BiometricCredentialRecordList {
+ /// Parses the metadata item. A missing item is an empty list; a top-level value that is not an array of objects is an error.
+ static func decode(_ data: Data?) throws -> [[String: Any]] {
+ guard let data else { return [] }
+ let object: Any
+ do {
+ object = try JSONSerialization.jsonObject(with: data)
+ } catch {
+ throw BiometricsError(.storageFailed, "Biometric credential metadata is not valid JSON.")
+ }
+ guard let records = object as? [[String: Any]] else {
+ throw BiometricsError(.storageFailed, "Biometric credential metadata is not an array.")
+ }
+ return records
+ }
+
+ /// Serializes the list, or returns `nil` when it is empty so the caller deletes the item instead of writing `[]`.
+ static func encode(_ records: [[String: Any]]) throws -> Data? {
+ guard !records.isEmpty else { return nil }
+ do {
+ return try JSONSerialization.data(withJSONObject: records)
+ } catch {
+ throw BiometricsError(.storageFailed, "Biometric credential metadata could not be encoded.")
+ }
+ }
+
+ /// Well-formed records with their stored fields passed through, `identifierHint` normalized as ClerkKit reads it, and
+ /// its `identifierHintSha256`.
+ static func listable(_ records: [[String: Any]]) -> [[String: Any]] {
+ records.compactMap { object in
+ guard let record = BiometricCredentialRecord(jsonObject: object) else { return nil }
+ var listed = object
+ if let identifierHint = record.identifierHint {
+ listed[BiometricCredentialRecord.Field.identifierHint] = identifierHint
+ } else {
+ listed.removeValue(forKey: BiometricCredentialRecord.Field.identifierHint)
+ }
+ listed[BiometricCredentialRecord.Field.identifierHintSha256] =
+ BiometricCredentialCoding.identifierHintSHA256(record.identifierHint) ?? NSNull()
+ return listed
+ }
+ }
+
+ struct SaveResult {
+ let records: [[String: Any]]
+ /// Keys of records with the same `id` that pointed at a different key.
+ let replacedLocalKeyIds: [String]
+ }
+
+ /// Replaces any record with the same `id`, drops malformed records for the same app, and keeps everything else untouched.
+ static func saving(_ record: BiometricCredentialRecord, into records: [[String: Any]]) -> SaveResult {
+ var kept: [[String: Any]] = []
+ var replacedLocalKeyIds: [String] = []
+
+ for object in records {
+ if object[BiometricCredentialRecord.Field.id] as? String == record.id {
+ if let localKeyId = object[BiometricCredentialRecord.Field.localKeyId] as? String,
+ localKeyId != record.localKeyId
+ {
+ replacedLocalKeyIds.append(localKeyId)
+ }
+ continue
+ }
+ guard object[BiometricCredentialRecord.Field.appIdentifier] as? String == record.appIdentifier else {
+ kept.append(object)
+ continue
+ }
+ if BiometricCredentialRecord(jsonObject: object) != nil {
+ kept.append(object)
+ }
+ }
+
+ kept.append(record.jsonObject)
+ return SaveResult(records: kept, replacedLocalKeyIds: replacedLocalKeyIds)
+ }
+}
diff --git a/packages/expo-biometrics/ios/BiometricCredentialStore.swift b/packages/expo-biometrics/ios/BiometricCredentialStore.swift
new file mode 100644
index 00000000000..252a381f9c8
--- /dev/null
+++ b/packages/expo-biometrics/ios/BiometricCredentialStore.swift
@@ -0,0 +1,230 @@
+import Foundation
+import Security
+
+protocol BiometricCredentialMetadataStorage {
+ func read() throws -> Data?
+ func write(_ data: Data) throws
+ func delete() throws
+}
+
+/// The generic-password item ClerkKit's `SystemKeychain` uses for biometric credential metadata, with no access group.
+struct KeychainMetadataStorage: BiometricCredentialMetadataStorage {
+ let service: String
+ var account: String = BiometricCredentialCoding.metadataAccount
+
+ func read() throws -> Data? {
+ var query = baseQuery()
+ query[kSecReturnData as String] = true
+ query[kSecMatchLimit as String] = kSecMatchLimitOne
+
+ var result: CFTypeRef?
+ let status = SecItemCopyMatching(query as CFDictionary, &result)
+ switch status {
+ case errSecSuccess:
+ return result as? Data
+ case errSecItemNotFound:
+ return nil
+ default:
+ throw BiometricsError(.storageFailed, BiometricsError.statusMessage(status))
+ }
+ }
+
+ func write(_ data: Data) throws {
+ var addQuery = baseQuery()
+ addQuery[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+ addQuery[kSecValueData as String] = data
+
+ let status = SecItemAdd(addQuery as CFDictionary, nil)
+ switch status {
+ case errSecSuccess:
+ return
+ case errSecDuplicateItem:
+ let attributes: [String: Any] = [
+ kSecValueData as String: data,
+ kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly,
+ ]
+ let updateStatus = SecItemUpdate(baseQuery() as CFDictionary, attributes as CFDictionary)
+ guard updateStatus == errSecSuccess else {
+ throw BiometricsError(.storageFailed, BiometricsError.statusMessage(updateStatus))
+ }
+ default:
+ throw BiometricsError(.storageFailed, BiometricsError.statusMessage(status))
+ }
+ }
+
+ func delete() throws {
+ let status = SecItemDelete(baseQuery() as CFDictionary)
+ switch status {
+ case errSecSuccess, errSecItemNotFound:
+ return
+ default:
+ throw BiometricsError(.storageFailed, BiometricsError.statusMessage(status))
+ }
+ }
+
+ func baseQuery() -> [String: Any] {
+ [
+ kSecClass as String: kSecClassGenericPassword,
+ kSecAttrService as String: service,
+ kSecAttrAccount as String: account,
+ ]
+ }
+}
+
+/// Read-modify-write operations on the shared metadata item. Every operation runs under one lock and first applies the
+/// reinstall marker, so records written here are never wiped by ClerkKit's first configuration in this installation.
+final class BiometricCredentialStore {
+ private let storage: BiometricCredentialMetadataStorage
+ private let deleteKey: (String) throws -> Void
+ private let userDefaults: UserDefaults
+ private let service: String
+ private let appIdentifier: String?
+ private let lock = NSRecursiveLock()
+
+ init(
+ storage: BiometricCredentialMetadataStorage,
+ deleteKey: @escaping (String) throws -> Void,
+ userDefaults: UserDefaults,
+ service: String,
+ appIdentifier: String?
+ ) {
+ self.storage = storage
+ self.deleteKey = deleteKey
+ self.userDefaults = userDefaults
+ self.service = service
+ self.appIdentifier = appIdentifier
+ }
+
+ static func live(keyManager: BiometricKeyManager, bundle: Bundle = .main) -> BiometricCredentialStore {
+ let service = BiometricCredentialCoding.metadataService(
+ infoDictionaryService: bundle.object(forInfoDictionaryKey: "ClerkKeychainService") as? String,
+ bundleIdentifier: bundle.bundleIdentifier
+ )
+ return BiometricCredentialStore(
+ storage: KeychainMetadataStorage(service: service),
+ deleteKey: { try keyManager.deleteKey(localKeyId: $0) },
+ userDefaults: .standard,
+ service: service,
+ appIdentifier: bundle.bundleIdentifier
+ )
+ }
+
+ var installationMarkerKey: String {
+ BiometricCredentialCoding.installationMarkerKey(service: service, accessGroup: nil, appIdentifier: appIdentifier)
+ }
+
+ /// Returns `true` when the marker was missing and this app's records and keys from a previous installation were deleted.
+ @discardableResult
+ func ensureInstallationMarker() throws -> Bool {
+ lock.lock()
+ defer { lock.unlock() }
+
+ guard appIdentifier != nil else { return false }
+ let markerKey = installationMarkerKey
+ if userDefaults.object(forKey: markerKey) as? Bool == true {
+ return false
+ }
+
+ let records = try readRecords()
+ var remaining: [[String: Any]] = []
+ var keyDeletionError: Error?
+ for record in records {
+ guard record[BiometricCredentialRecord.Field.appIdentifier] as? String == appIdentifier else {
+ remaining.append(record)
+ continue
+ }
+ if let localKeyId = record[BiometricCredentialRecord.Field.localKeyId] as? String {
+ do {
+ try deleteKey(localKeyId)
+ } catch {
+ keyDeletionError = keyDeletionError ?? error
+ remaining.append(record)
+ continue
+ }
+ }
+ }
+
+ if remaining.count != records.count {
+ try persist(remaining)
+ }
+ if let keyDeletionError {
+ throw keyDeletionError
+ }
+
+ userDefaults.set(true, forKey: markerKey)
+ return true
+ }
+
+ /// JSON array of every well-formed record, for every app identifier.
+ func listRecordsJSON() throws -> String {
+ lock.lock()
+ defer { lock.unlock() }
+
+ try ensureInstallationMarker()
+ let data = try JSONSerialization.data(withJSONObject: BiometricCredentialRecordList.listable(readRecords()))
+ return String(decoding: data, as: UTF8.self)
+ }
+
+ func save(_ record: BiometricCredentialRecord, removeOtherRecordsForApp: Bool) throws {
+ lock.lock()
+ defer { lock.unlock() }
+
+ try ensureInstallationMarker()
+ let result = BiometricCredentialRecordList.saving(record, into: try readRecords())
+ try persist(result.records)
+
+ for localKeyId in result.replacedLocalKeyIds where localKeyId != record.localKeyId {
+ try? deleteKey(localKeyId)
+ }
+
+ guard removeOtherRecordsForApp else { return }
+
+ var remaining: [[String: Any]] = []
+ for object in result.records {
+ let isOtherRecordForApp = object[BiometricCredentialRecord.Field.appIdentifier] as? String == record.appIdentifier
+ && object[BiometricCredentialRecord.Field.id] as? String != record.id
+ guard isOtherRecordForApp else {
+ remaining.append(object)
+ continue
+ }
+ if let localKeyId = object[BiometricCredentialRecord.Field.localKeyId] as? String, localKeyId != record.localKeyId {
+ do {
+ try deleteKey(localKeyId)
+ } catch {
+ remaining.append(object)
+ continue
+ }
+ }
+ }
+ if remaining.count != result.records.count {
+ try? persist(remaining)
+ }
+ }
+
+ /// Deletes the key, then every record that references it. When the key cannot be deleted the records are kept.
+ func deleteRecords(localKeyId: String) throws {
+ lock.lock()
+ defer { lock.unlock() }
+
+ try ensureInstallationMarker()
+ try deleteKey(localKeyId)
+
+ let records = try readRecords()
+ let remaining = records.filter { $0[BiometricCredentialRecord.Field.localKeyId] as? String != localKeyId }
+ if remaining.count != records.count {
+ try persist(remaining)
+ }
+ }
+
+ private func readRecords() throws -> [[String: Any]] {
+ try BiometricCredentialRecordList.decode(storage.read())
+ }
+
+ private func persist(_ records: [[String: Any]]) throws {
+ if let data = try BiometricCredentialRecordList.encode(records) {
+ try storage.write(data)
+ } else {
+ try storage.delete()
+ }
+ }
+}
diff --git a/packages/expo-biometrics/ios/BiometricKeyManager.swift b/packages/expo-biometrics/ios/BiometricKeyManager.swift
new file mode 100644
index 00000000000..ff4d34bf893
--- /dev/null
+++ b/packages/expo-biometrics/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?
+ 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?
+ 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?
+ 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?
+ 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?, fallback: BiometricsError.Code) -> BiometricsError {
+ guard let error else {
+ return BiometricsError(fallback, "Unknown Security framework error.")
+ }
+ return BiometricsError.security(error.takeRetainedValue() as Error, fallback: fallback)
+ }
+}
diff --git a/packages/expo-biometrics/ios/BiometricsError.swift b/packages/expo-biometrics/ios/BiometricsError.swift
new file mode 100644
index 00000000000..c33ddf13561
--- /dev/null
+++ b/packages/expo-biometrics/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
+ }
+ }
+}
diff --git a/packages/expo-biometrics/ios/ClerkExpoBiometrics.podspec b/packages/expo-biometrics/ios/ClerkExpoBiometrics.podspec
new file mode 100644
index 00000000000..05c8cecf532
--- /dev/null
+++ b/packages/expo-biometrics/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
diff --git a/packages/expo-biometrics/ios/ClerkExpoBiometricsModule.swift b/packages/expo-biometrics/ios/ClerkExpoBiometricsModule.swift
new file mode 100644
index 00000000000..72de2d4e7d3
--- /dev/null
+++ b/packages/expo-biometrics/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(_ body: () throws -> T) throws -> T {
+ do {
+ return try body()
+ } catch let error as BiometricsError {
+ throw ClerkBiometricsException(error)
+ }
+ }
+}
diff --git a/packages/expo-biometrics/ios/Tests/BiometricCredentialContractTests.swift b/packages/expo-biometrics/ios/Tests/BiometricCredentialContractTests.swift
new file mode 100644
index 00000000000..519f17ce291
--- /dev/null
+++ b/packages/expo-biometrics/ios/Tests/BiometricCredentialContractTests.swift
@@ -0,0 +1,286 @@
+import CryptoKit
+import Foundation
+import Security
+import XCTest
+@testable import ClerkExpoBiometrics
+
+/// Mirrors clerk-ios `BiometricCredentialStorageContractTests` (contract version 1) with the same vectors and fixture.
+final class BiometricCredentialContractTests: XCTestCase {
+ private let fixtureLocalKeyId = "tdlk_0123456789abcdef0123456789abcdef"
+
+ // MARK: - Secure Enclave key
+
+ func testPrivateKeyQueryUsesContractApplicationTagWithoutAccessGroup() {
+ let query = BiometricKeyManager.privateKeyQuery(localKeyId: fixtureLocalKeyId)
+
+ XCTAssertEqual(query[kSecClass as String] as? String, kSecClassKey as String)
+ XCTAssertEqual(query[kSecAttrKeyClass as String] as? String, kSecAttrKeyClassPrivate as String)
+ XCTAssertEqual(query[kSecAttrKeyType as String] as? String, kSecAttrKeyTypeECSECPrimeRandom as String)
+ XCTAssertEqual(
+ query[kSecAttrApplicationTag as String] as? Data,
+ Data("dev.clerk.trusted_device.tdlk_0123456789abcdef0123456789abcdef".utf8)
+ )
+ XCTAssertNil(query[kSecAttrAccessGroup as String])
+ XCTAssertNil(query[kSecAttrLabel as String])
+ XCTAssertNil(query[kSecAttrApplicationLabel as String])
+ XCTAssertEqual(query.count, 4)
+ }
+
+ func testPrivateKeyAttributesMatchContract() throws {
+ let attributes = BiometricKeyManager.privateKeyAttributes(
+ localKeyId: fixtureLocalKeyId,
+ accessControl: try BiometricKeyManager.accessControl(policy: .biometryCurrentSet)
+ )
+
+ XCTAssertEqual(attributes[kSecAttrKeyType as String] as? String, kSecAttrKeyTypeECSECPrimeRandom as String)
+ XCTAssertEqual(attributes[kSecAttrKeySizeInBits as String] as? Int, 256)
+ XCTAssertEqual(attributes[kSecAttrTokenID as String] as? String, kSecAttrTokenIDSecureEnclave as String)
+ XCTAssertNil(attributes[kSecAttrAccessGroup as String])
+ XCTAssertEqual(attributes.count, 4)
+
+ let privateKeyAttributes = try XCTUnwrap(attributes[kSecPrivateKeyAttrs as String] as? [String: Any])
+ XCTAssertEqual(privateKeyAttributes[kSecAttrIsPermanent as String] as? Bool, true)
+ XCTAssertEqual(
+ privateKeyAttributes[kSecAttrApplicationTag as String] as? Data,
+ Data("dev.clerk.trusted_device.tdlk_0123456789abcdef0123456789abcdef".utf8)
+ )
+ XCTAssertNotNil(privateKeyAttributes[kSecAttrAccessControl as String])
+ XCTAssertNil(privateKeyAttributes[kSecAttrAccessGroup as String])
+ XCTAssertEqual(privateKeyAttributes.count, 3)
+ }
+
+ func testPolicyRawValuesAndAccessControlFlagsMatchContract() throws {
+ XCTAssertEqual(BiometricCredentialPolicy.biometryCurrentSet.rawValue, "biometry_current_set")
+ XCTAssertEqual(BiometricCredentialPolicy.biometryAny.rawValue, "biometry_any")
+ XCTAssertEqual(BiometricCredentialPolicy.biometryOrDevicePasscode.rawValue, "biometry_or_device_passcode")
+
+ XCTAssertEqual(BiometricKeyManager.accessControlFlags(for: .biometryCurrentSet), [.privateKeyUsage, .biometryCurrentSet])
+ XCTAssertEqual(BiometricKeyManager.accessControlFlags(for: .biometryAny), [.privateKeyUsage, .biometryAny])
+ XCTAssertEqual(BiometricKeyManager.accessControlFlags(for: .biometryOrDevicePasscode), [.privateKeyUsage, .userPresence])
+
+ for policy in BiometricCredentialPolicy.allCases {
+ XCTAssertNoThrow(try BiometricKeyManager.accessControl(policy: policy))
+ }
+ }
+
+ func testLocalKeyIdFormat() {
+ let localKeyId = BiometricCredentialCoding.makeLocalKeyId()
+
+ XCTAssertTrue(localKeyId.hasPrefix("tdlk_"))
+ let suffix = localKeyId.dropFirst("tdlk_".count)
+ XCTAssertEqual(suffix.count, 32)
+ XCTAssertTrue(suffix.allSatisfy { "0123456789abcdef".contains($0) })
+ XCTAssertNotEqual(localKeyId, BiometricCredentialCoding.makeLocalKeyId())
+ }
+
+ // MARK: - Signing and public key
+
+ func testPublicKeyJWKMatchesContractFormat() throws {
+ var representation = Data([0x04])
+ representation.append(Data(repeating: 0x01, count: 32))
+ representation.append(Data(repeating: 0x02, count: 32))
+
+ XCTAssertEqual(
+ try BiometricCredentialCoding.publicKeyJWK(fromX963Representation: representation),
+ #"{"kty":"EC","crv":"P-256","x":"AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE","y":"AgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgI","alg":"ES256"}"#
+ )
+ }
+
+ func testPublicKeyJWKRejectsCompressedOrShortKeys() {
+ XCTAssertThrowsError(try BiometricCredentialCoding.publicKeyJWK(fromX963Representation: Data([0x02] + Array(repeating: 1, count: 32))))
+ XCTAssertThrowsError(try BiometricCredentialCoding.publicKeyJWK(fromX963Representation: Data([0x05] + Array(repeating: 1, count: 64))))
+ }
+
+ func testSignatureIsRawRAndSEncodedAsUnpaddedBase64URL() throws {
+ let rComponent: [UInt8] = [0x00, 0x80] + Array(repeating: 0xAA, count: 31)
+ let sComponent: [UInt8] = Array(repeating: 0x11, count: 31)
+ let der = Data([0x30, 0x44, 0x02, UInt8(rComponent.count)] + rComponent + [0x02, UInt8(sComponent.count)] + sComponent)
+
+ let raw = try BiometricCredentialCoding.rawES256Signature(fromDEREncoded: der)
+
+ XCTAssertEqual(raw.count, 64)
+ XCTAssertEqual(
+ BiometricCredentialCoding.base64URLEncodedString(raw),
+ "gKqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqoAEREREREREREREREREREREREREREREREREREREREREQ"
+ )
+ }
+
+ func testRawSignatureRejectsMalformedDER() {
+ let valid: [UInt8] = [0x30, 0x06, 0x02, 0x01, 0x01, 0x02, 0x01, 0x02]
+ XCTAssertNoThrow(try BiometricCredentialCoding.rawES256Signature(fromDEREncoded: Data(valid)))
+
+ let malformed: [[UInt8]] = [
+ [],
+ [0x31] + valid.dropFirst(),
+ [0x30, 0x07] + valid.dropFirst(2),
+ valid + [0x00],
+ [0x30, 0x06, 0x02, 0x01, 0x81, 0x02, 0x01, 0x02],
+ [0x30, 0x06, 0x02, 0x00, 0x02, 0x02, 0x01, 0x02],
+ [0x30, 0x25, 0x02, 0x21, 0x01] + Array(repeating: 0x01, count: 32) + [0x02, 0x01, 0x02],
+ ]
+ for bytes in malformed {
+ XCTAssertThrowsError(try BiometricCredentialCoding.rawES256Signature(fromDEREncoded: Data(bytes)), "\(bytes)") { error in
+ XCTAssertEqual((error as? BiometricsError)?.code, .signingFailed)
+ }
+ }
+ }
+
+ func testSecuritySignatureConvertsToVerifiableRawSignature() throws {
+ var error: Unmanaged?
+ let attributes: [String: Any] = [
+ kSecAttrKeyType as String: kSecAttrKeyTypeECSECPrimeRandom,
+ kSecAttrKeySizeInBits as String: 256,
+ ]
+ let privateKey = try XCTUnwrap(SecKeyCreateRandomKey(attributes as CFDictionary, &error))
+ let publicKey = try XCTUnwrap(SecKeyCopyPublicKey(privateKey))
+ let publicKeyData = try XCTUnwrap(SecKeyCopyExternalRepresentation(publicKey, &error) as Data?)
+ let clientData = #"{"challenge":"abc","nonce":"é"}"#
+
+ for _ in 0 ..< 32 {
+ let der = try XCTUnwrap(SecKeyCreateSignature(
+ privateKey,
+ .ecdsaSignatureMessageX962SHA256,
+ Data(clientData.utf8) as CFData,
+ &error
+ ) as Data?)
+ let raw = try BiometricCredentialCoding.rawES256Signature(fromDEREncoded: der)
+
+ XCTAssertEqual(raw.count, 64)
+ let signature = try P256.Signing.ECDSASignature(rawRepresentation: raw)
+ let verifyingKey = try P256.Signing.PublicKey(x963Representation: publicKeyData)
+ XCTAssertTrue(verifyingKey.isValidSignature(signature, for: Data(clientData.utf8)))
+ }
+
+ let jwk = try BiometricCredentialCoding.publicKeyJWK(fromX963Representation: publicKeyData)
+ let decoded = try XCTUnwrap(JSONSerialization.jsonObject(with: Data(jwk.utf8)) as? [String: String])
+ XCTAssertEqual(decoded["x"], BiometricCredentialCoding.base64URLEncodedString(publicKeyData[1 ..< 33]))
+ XCTAssertEqual(decoded["y"], BiometricCredentialCoding.base64URLEncodedString(publicKeyData[33 ..< 65]))
+ XCTAssertFalse(jwk.contains("="))
+ }
+
+ // MARK: - Metadata Keychain item
+
+ func testMetadataItemQueryMatchesContract() {
+ let query = KeychainMetadataStorage(service: "com.clerk.example").baseQuery()
+
+ XCTAssertEqual(query[kSecClass as String] as? String, kSecClassGenericPassword as String)
+ XCTAssertEqual(query[kSecAttrService as String] as? String, "com.clerk.example")
+ XCTAssertEqual(query[kSecAttrAccount as String] as? String, "trustedDeviceCredentials")
+ XCTAssertNil(query[kSecAttrAccessGroup as String])
+ XCTAssertEqual(query.count, 3)
+ }
+
+ func testMetadataServicePrefersNonEmptyClerkKeychainService() {
+ XCTAssertEqual(BiometricCredentialCoding.metadataService(infoDictionaryService: "com.example.shared", bundleIdentifier: "com.example.app"), "com.example.shared")
+ XCTAssertEqual(BiometricCredentialCoding.metadataService(infoDictionaryService: "", bundleIdentifier: "com.example.app"), "com.example.app")
+ XCTAssertEqual(BiometricCredentialCoding.metadataService(infoDictionaryService: nil, bundleIdentifier: "com.example.app"), "com.example.app")
+ XCTAssertEqual(BiometricCredentialCoding.metadataService(infoDictionaryService: nil, bundleIdentifier: nil), "")
+ }
+
+ func testV1FixtureDecodesToExpectedRecords() throws {
+ let records = try BiometricCredentialRecordList.decode(Self.fixtureData())
+
+ XCTAssertEqual(records.compactMap(BiometricCredentialRecord.init(jsonObject:)), Self.fixtureRecords)
+ }
+
+ func testExpectedRecordsEncodeToV1Fixture() throws {
+ var records: [[String: Any]] = []
+ for record in Self.fixtureRecords {
+ records = BiometricCredentialRecordList.saving(record, into: records).records
+ }
+
+ let stored = try XCTUnwrap(BiometricCredentialRecordList.encode(records))
+ let storedJSON = try JSONSerialization.jsonObject(with: stored) as? NSArray
+ let fixtureJSON = try JSONSerialization.jsonObject(with: Self.fixtureData()) as? NSArray
+ XCTAssertNotNil(storedJSON)
+ XCTAssertEqual(storedJSON, fixtureJSON)
+ }
+
+ func testRecordFieldNamesAndIntegerMilliseconds() throws {
+ let data = try XCTUnwrap(BiometricCredentialRecordList.encode(Self.fixtureRecords.prefix(2).map(\.jsonObject)))
+ let records = try XCTUnwrap(JSONSerialization.jsonObject(with: data) as? [[String: Any]])
+
+ XCTAssertEqual(Set(records[0].keys), ["id", "localKeyId", "userId", "appIdentifier", "identifierHint", "policy", "createdAt", "updatedAt"])
+ XCTAssertEqual(Set(records[1].keys), ["id", "localKeyId", "userId", "appIdentifier", "policy", "createdAt", "updatedAt"])
+ XCTAssertEqual((records[0]["createdAt"] as? NSNumber)?.int64Value, 1_714_000_000_500)
+ XCTAssertTrue(String(decoding: data, as: UTF8.self).contains(#""createdAt":1714000000500"#))
+ }
+
+ func testReadersIgnoreUnknownFieldsAndNormalizeIdentifierHints() throws {
+ let json = """
+ [{"id":"tdc_future","localKeyId":"tdlk_future","userId":"user_1","appIdentifier":"com.clerk.example",\
+ "identifierHint":" User@Example.COM ","policy":"biometry_any","createdAt":1714000000000.25,\
+ "updatedAt":1714000000000,"futureField":{"nested":true}}]
+ """
+ let listed = BiometricCredentialRecordList.listable(try BiometricCredentialRecordList.decode(Data(json.utf8)))
+
+ XCTAssertEqual(listed.count, 1)
+ XCTAssertEqual(listed[0]["identifierHint"] as? String, "user@example.com")
+ XCTAssertEqual(listed[0]["futureField"] as? [String: Bool], ["nested": true])
+ XCTAssertEqual((listed[0]["createdAt"] as? NSNumber)?.doubleValue, 1_714_000_000_000.25)
+ }
+
+ func testIdentifierHintHashMatchesAndroidContractVector() {
+ XCTAssertEqual(
+ BiometricCredentialCoding.identifierHintSHA256(" User@Example.COM\n"),
+ "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514"
+ )
+ XCTAssertNil(BiometricCredentialCoding.identifierHintSHA256(" \n\t"))
+ XCTAssertNil(BiometricCredentialCoding.identifierHintSHA256(nil))
+ }
+
+ func testInstallationMarkerKeyMatchesContractFormat() {
+ XCTAssertEqual(
+ BiometricCredentialCoding.installationMarkerKey(service: "com.clerk.example", accessGroup: nil, appIdentifier: "com.clerk.example"),
+ "com.clerk.trusted-device-installation-marker.s17:com.clerk.example.n.s17:com.clerk.example"
+ )
+ XCTAssertEqual(
+ BiometricCredentialCoding.installationMarkerKey(service: "com.clerk.é", accessGroup: "TEAMID.com.clerk.shared", appIdentifier: "com.clerk.example"),
+ "com.clerk.trusted-device-installation-marker.s12:com.clerk.é.s23:TEAMID.com.clerk.shared.s17:com.clerk.example"
+ )
+ XCTAssertEqual(
+ BiometricCredentialCoding.installationMarkerKey(service: "com.clerk.example", accessGroup: "", appIdentifier: "com.clerk.example"),
+ "com.clerk.trusted-device-installation-marker.s17:com.clerk.example.s0:.s17:com.clerk.example"
+ )
+ }
+
+ static let fixtureRecords: [BiometricCredentialRecord] = [
+ BiometricCredentialRecord(
+ id: "tdc_contract_current_set",
+ localKeyId: "tdlk_0123456789abcdef0123456789abcdef",
+ userId: "user_contract_1",
+ appIdentifier: "com.clerk.example",
+ identifierHint: "user@example.com",
+ policy: .biometryCurrentSet,
+ createdAt: 1_714_000_000_500,
+ updatedAt: 1_714_000_001_500
+ ),
+ BiometricCredentialRecord(
+ id: "tdc_contract_any",
+ localKeyId: "tdlk_fedcba9876543210fedcba9876543210",
+ userId: "user_contract_2",
+ appIdentifier: "com.clerk.example",
+ identifierHint: nil,
+ policy: .biometryAny,
+ createdAt: 1_714_000_002_000,
+ updatedAt: 1_714_000_003_000
+ ),
+ BiometricCredentialRecord(
+ id: "tdc_contract_passcode",
+ localKeyId: "tdlk_00000000000000000000000000000000",
+ userId: "user_contract_1",
+ appIdentifier: "com.clerk.other",
+ identifierHint: "+15555550100",
+ policy: .biometryOrDevicePasscode,
+ createdAt: 1_714_000_004_000,
+ updatedAt: 1_714_000_004_000
+ ),
+ ]
+
+ static func fixtureData() throws -> Data {
+ let url = try XCTUnwrap(
+ Bundle(for: BiometricCredentialContractTests.self).url(forResource: "BiometricCredentialStorageContractV1", withExtension: "json")
+ )
+ return try Data(contentsOf: url)
+ }
+}
diff --git a/packages/expo-biometrics/ios/Tests/BiometricCredentialStoreTests.swift b/packages/expo-biometrics/ios/Tests/BiometricCredentialStoreTests.swift
new file mode 100644
index 00000000000..aef10fbfd2f
--- /dev/null
+++ b/packages/expo-biometrics/ios/Tests/BiometricCredentialStoreTests.swift
@@ -0,0 +1,323 @@
+import Foundation
+import Security
+import XCTest
+@testable import ClerkExpoBiometrics
+
+final class BiometricCredentialStoreTests: XCTestCase {
+ private final class InMemoryStorage: BiometricCredentialMetadataStorage {
+ var data: Data?
+ var writes = 0
+ var deletes = 0
+
+ func read() throws -> Data? { data }
+ func write(_ data: Data) throws {
+ writes += 1
+ self.data = data
+ }
+
+ func delete() throws {
+ deletes += 1
+ data = nil
+ }
+
+ func records() throws -> [[String: Any]] {
+ try BiometricCredentialRecordList.decode(data)
+ }
+
+ func ids() throws -> [String?] {
+ try records().map { $0["id"] as? String }
+ }
+ }
+
+ private var storage: InMemoryStorage!
+ private var userDefaults: UserDefaults!
+ private var suiteName: String!
+ private var deletedKeys: [String] = []
+ private var failingKeys: Set = []
+
+ override func setUp() {
+ super.setUp()
+ storage = InMemoryStorage()
+ suiteName = "ClerkExpoBiometricsTests.\(UUID().uuidString)"
+ userDefaults = UserDefaults(suiteName: suiteName)
+ deletedKeys = []
+ failingKeys = []
+ }
+
+ override func tearDown() {
+ userDefaults.removePersistentDomain(forName: suiteName)
+ super.tearDown()
+ }
+
+ private func makeStore(appIdentifier: String? = "com.clerk.example") -> BiometricCredentialStore {
+ BiometricCredentialStore(
+ storage: storage,
+ deleteKey: { [unowned self] localKeyId in
+ if failingKeys.contains(localKeyId) {
+ throw BiometricsError(.storageFailed, "delete failed")
+ }
+ deletedKeys.append(localKeyId)
+ },
+ userDefaults: userDefaults,
+ service: "com.clerk.example",
+ appIdentifier: appIdentifier
+ )
+ }
+
+ private let markerKey = "com.clerk.trusted-device-installation-marker.s17:com.clerk.example.n.s17:com.clerk.example"
+
+ private func setMarker() {
+ userDefaults.set(true, forKey: markerKey)
+ }
+
+ private func record(
+ id: String,
+ localKeyId: String? = nil,
+ userId: String = "user_1",
+ appIdentifier: String = "com.clerk.example",
+ identifierHint: String? = nil
+ ) -> BiometricCredentialRecord {
+ BiometricCredentialRecord(
+ id: id,
+ localKeyId: localKeyId ?? "tdlk_\(id)",
+ userId: userId,
+ appIdentifier: appIdentifier,
+ identifierHint: identifierHint,
+ policy: .biometryCurrentSet,
+ createdAt: 1_714_000_000_000,
+ updatedAt: 1_714_000_000_000
+ )
+ }
+
+ // MARK: - Reinstall marker
+
+ func testMissingMarkerWipesOnlyThisAppsRecordsAndKeysThenSetsMarker() throws {
+ storage.data = try BiometricCredentialContractTests.fixtureData()
+ let store = makeStore()
+
+ XCTAssertEqual(store.installationMarkerKey, markerKey)
+ XCTAssertTrue(try store.ensureInstallationMarker())
+
+ XCTAssertEqual(deletedKeys, ["tdlk_0123456789abcdef0123456789abcdef", "tdlk_fedcba9876543210fedcba9876543210"])
+ XCTAssertEqual(try storage.ids(), ["tdc_contract_passcode"])
+ XCTAssertEqual(userDefaults.object(forKey: markerKey) as? Bool, true)
+ XCTAssertEqual(UserDefaults.standard.object(forKey: markerKey) as? Bool, nil)
+ }
+
+ func testMarkerIsIdempotent() throws {
+ let store = makeStore()
+
+ XCTAssertTrue(try store.ensureInstallationMarker())
+ storage.data = try BiometricCredentialContractTests.fixtureData()
+ XCTAssertFalse(try store.ensureInstallationMarker())
+
+ XCTAssertEqual(deletedKeys, [])
+ XCTAssertEqual(try storage.records().count, 3)
+ }
+
+ func testMarkerIsNotSetWhenAKeyCannotBeDeleted() throws {
+ storage.data = try BiometricCredentialContractTests.fixtureData()
+ failingKeys = ["tdlk_fedcba9876543210fedcba9876543210"]
+ let store = makeStore()
+
+ XCTAssertThrowsError(try store.ensureInstallationMarker())
+
+ XCTAssertEqual(try storage.ids(), ["tdc_contract_any", "tdc_contract_passcode"])
+ XCTAssertNil(userDefaults.object(forKey: markerKey))
+
+ failingKeys = []
+ XCTAssertTrue(try store.ensureInstallationMarker())
+ XCTAssertEqual(try storage.ids(), ["tdc_contract_passcode"])
+ }
+
+ func testMarkerWipesMalformedRecordsForThisApp() throws {
+ storage.data = Data(#"[{"appIdentifier":"com.clerk.example","localKeyId":"tdlk_bad"},{"appIdentifier":"com.clerk.example"}]"#.utf8)
+
+ XCTAssertTrue(try makeStore().ensureInstallationMarker())
+
+ XCTAssertEqual(deletedKeys, ["tdlk_bad"])
+ XCTAssertNil(storage.data)
+ XCTAssertEqual(storage.deletes, 1)
+ }
+
+ func testMarkerIsNotSetWhenMetadataIsNotAnArray() {
+ storage.data = Data(#"{"id":"tdc_1"}"#.utf8)
+
+ XCTAssertThrowsError(try makeStore().ensureInstallationMarker()) { error in
+ XCTAssertEqual((error as? BiometricsError)?.code, .storageFailed)
+ }
+ XCTAssertNil(userDefaults.object(forKey: markerKey))
+ }
+
+ func testMissingAppIdentifierSkipsTheMarker() throws {
+ storage.data = try BiometricCredentialContractTests.fixtureData()
+
+ XCTAssertFalse(try makeStore(appIdentifier: nil).ensureInstallationMarker())
+ XCTAssertEqual(try storage.records().count, 3)
+ }
+
+ func testStoreOperationsApplyTheMarkerFirst() throws {
+ storage.data = try BiometricCredentialContractTests.fixtureData()
+ let store = makeStore()
+
+ let listed = try JSONSerialization.jsonObject(with: Data(store.listRecordsJSON().utf8)) as? [[String: Any]]
+
+ XCTAssertEqual(listed?.map { $0["id"] as? String }, ["tdc_contract_passcode"])
+ XCTAssertEqual(userDefaults.object(forKey: markerKey) as? Bool, true)
+ }
+
+ // MARK: - List
+
+ func testListReturnsWellFormedRecordsForEveryAppWithUnknownFields() throws {
+ setMarker()
+ storage.data = Data("""
+ [{"id":"tdc_1","localKeyId":"tdlk_1","userId":"user_1","appIdentifier":"com.clerk.example","identifierHint":" A@B.co ",\
+ "policy":"biometry_any","createdAt":1714000000000,"updatedAt":1714000000001,"futureField":[1,true,null]},\
+ {"id":"tdc_2","localKeyId":"tdlk_2","userId":"user_2","appIdentifier":"com.clerk.other","identifierHint":" ",\
+ "policy":"biometry_current_set","createdAt":1714000000000,"updatedAt":1714000000000},\
+ {"id":"tdc_bad_policy","localKeyId":"tdlk_3","userId":"user_1","appIdentifier":"com.clerk.example",\
+ "policy":"face","createdAt":1,"updatedAt":1},\
+ {"id":"tdc_bool_date","localKeyId":"tdlk_4","userId":"user_1","appIdentifier":"com.clerk.example",\
+ "policy":"biometry_any","createdAt":true,"updatedAt":1},\
+ {"id":"tdc_missing","userId":"user_1","appIdentifier":"com.clerk.example","policy":"biometry_any","createdAt":1,"updatedAt":1},\
+ {"id":"tdc_hint_number","localKeyId":"tdlk_5","userId":"user_1","appIdentifier":"com.clerk.example",\
+ "identifierHint":5,"policy":"biometry_any","createdAt":1,"updatedAt":1},\
+ {"id":"tdc_null_hint","localKeyId":"tdlk_6","userId":"user_1","appIdentifier":"com.clerk.example",\
+ "identifierHint":null,"policy":"biometry_or_device_passcode","createdAt":1,"updatedAt":1}]
+ """.utf8)
+
+ let json = try makeStore().listRecordsJSON()
+ let listed = try XCTUnwrap(JSONSerialization.jsonObject(with: Data(json.utf8)) as? [[String: Any]])
+
+ XCTAssertEqual(listed.map { $0["id"] as? String }, ["tdc_1", "tdc_2", "tdc_null_hint"])
+ XCTAssertEqual(listed[0]["identifierHint"] as? String, "a@b.co")
+ XCTAssertNil(listed[1]["identifierHint"])
+ XCTAssertNil(listed[2]["identifierHint"])
+ XCTAssertEqual(listed[0]["identifierHintSha256"] as? String, "80305c9bb1bb2480e03894350e0a8a366dcbdeb302e69e0817aa0743abd77054")
+ XCTAssertTrue(listed[1]["identifierHintSha256"] is NSNull)
+ XCTAssertTrue(listed[2]["identifierHintSha256"] is NSNull)
+ XCTAssertTrue(json.contains(#""futureField":[1,true,null]"#))
+ XCTAssertTrue(json.contains(#""updatedAt":1714000000001"#))
+ }
+
+ func testListIsEmptyWithoutAnItem() throws {
+ setMarker()
+ XCTAssertEqual(try makeStore().listRecordsJSON(), "[]")
+ }
+
+ // MARK: - Save
+
+ func testSaveAddsRecordAndPreservesOtherAppsAndUnknownFields() throws {
+ setMarker()
+ storage.data = Data("""
+ [{"id":"tdc_other","localKeyId":"tdlk_other","userId":"user_1","appIdentifier":"com.clerk.other",\
+ "policy":"biometry_any","createdAt":1714000000000,"updatedAt":1714000000000,"futureField":"kept"},\
+ {"id":"tdc_same","localKeyId":"tdlk_same","userId":"user_2","appIdentifier":"com.clerk.example",\
+ "policy":"biometry_any","createdAt":1714000000000,"updatedAt":1714000000000,"futureField":"also kept"}]
+ """.utf8)
+
+ try makeStore().save(record(id: "tdc_new", identifierHint: " New@Example.com"), removeOtherRecordsForApp: false)
+
+ let records = try storage.records()
+ XCTAssertEqual(records.map { $0["id"] as? String }, ["tdc_other", "tdc_same", "tdc_new"])
+ XCTAssertEqual(records[0]["futureField"] as? String, "kept")
+ XCTAssertEqual(records[1]["futureField"] as? String, "also kept")
+ XCTAssertEqual(records[2]["identifierHint"] as? String, "new@example.com")
+ XCTAssertEqual(deletedKeys, [])
+ }
+
+ func testSaveReplacesSameIdAndDeletesItsOldKey() throws {
+ setMarker()
+ let store = makeStore()
+ try store.save(record(id: "tdc_1", localKeyId: "tdlk_old"), removeOtherRecordsForApp: false)
+
+ try store.save(record(id: "tdc_1", localKeyId: "tdlk_new"), removeOtherRecordsForApp: false)
+
+ let records = try storage.records()
+ XCTAssertEqual(records.count, 1)
+ XCTAssertEqual(records[0]["localKeyId"] as? String, "tdlk_new")
+ XCTAssertEqual(deletedKeys, ["tdlk_old"])
+ }
+
+ func testSaveDropsMalformedRecordsForTheSameAppOnly() throws {
+ setMarker()
+ storage.data = Data("""
+ [{"id":"tdc_bad","appIdentifier":"com.clerk.example"},{"id":"tdc_bad_other","appIdentifier":"com.clerk.other"}]
+ """.utf8)
+
+ try makeStore().save(record(id: "tdc_1"), removeOtherRecordsForApp: false)
+
+ XCTAssertEqual(try storage.ids(), ["tdc_bad_other", "tdc_1"])
+ XCTAssertEqual(deletedKeys, [])
+ }
+
+ func testSaveRemovingOtherRecordsDeletesThisAppsOtherRecordsAndKeys() throws {
+ setMarker()
+ let store = makeStore()
+ try store.save(record(id: "tdc_a", userId: "user_1"), removeOtherRecordsForApp: false)
+ try store.save(record(id: "tdc_b", userId: "user_2"), removeOtherRecordsForApp: false)
+ try store.save(record(id: "tdc_other_app", appIdentifier: "com.clerk.other"), removeOtherRecordsForApp: false)
+ failingKeys = ["tdlk_tdc_b"]
+
+ try store.save(record(id: "tdc_new"), removeOtherRecordsForApp: true)
+
+ XCTAssertEqual(deletedKeys, ["tdlk_tdc_a"])
+ XCTAssertEqual(try storage.ids(), ["tdc_b", "tdc_other_app", "tdc_new"])
+ }
+
+ func testSaveAppliesTheMarkerBeforeWriting() throws {
+ storage.data = try BiometricCredentialContractTests.fixtureData()
+
+ try makeStore().save(record(id: "tdc_new"), removeOtherRecordsForApp: false)
+
+ XCTAssertEqual(try storage.ids(), ["tdc_contract_passcode", "tdc_new"])
+ XCTAssertEqual(userDefaults.object(forKey: markerKey) as? Bool, true)
+ }
+
+ func testSaveFailsWithoutWritingWhenTheMarkerCannotBeSet() throws {
+ storage.data = try BiometricCredentialContractTests.fixtureData()
+ failingKeys = ["tdlk_0123456789abcdef0123456789abcdef"]
+
+ XCTAssertThrowsError(try makeStore().save(record(id: "tdc_new"), removeOtherRecordsForApp: false))
+
+ XCTAssertFalse(try storage.ids().contains("tdc_new"))
+ }
+
+ // MARK: - Delete
+
+ func testDeleteRecordsDeletesKeyThenRecordsAndDropsTheItemWhenEmpty() throws {
+ setMarker()
+ let store = makeStore()
+ try store.save(record(id: "tdc_1", localKeyId: "tdlk_1"), removeOtherRecordsForApp: false)
+
+ try store.deleteRecords(localKeyId: "tdlk_1")
+
+ XCTAssertEqual(deletedKeys, ["tdlk_1"])
+ XCTAssertNil(storage.data)
+ XCTAssertEqual(storage.deletes, 1)
+ }
+
+ func testDeleteRecordsKeepsRecordsWhenTheKeyCannotBeDeleted() throws {
+ setMarker()
+ let store = makeStore()
+ try store.save(record(id: "tdc_1", localKeyId: "tdlk_1"), removeOtherRecordsForApp: false)
+ failingKeys = ["tdlk_1"]
+
+ XCTAssertThrowsError(try store.deleteRecords(localKeyId: "tdlk_1"))
+
+ XCTAssertEqual(try storage.ids(), ["tdc_1"])
+ }
+
+ func testDeleteRecordsPreservesUnknownFieldsOnOtherRecords() throws {
+ setMarker()
+ storage.data = Data("""
+ [{"id":"tdc_1","localKeyId":"tdlk_1","futureField":"kept"},{"id":"tdc_2","localKeyId":"tdlk_2"}]
+ """.utf8)
+
+ try makeStore().deleteRecords(localKeyId: "tdlk_2")
+
+ let records = try storage.records()
+ XCTAssertEqual(records.count, 1)
+ XCTAssertEqual(records[0]["futureField"] as? String, "kept")
+ }
+}
diff --git a/packages/expo-biometrics/ios/Tests/BiometricSystemIntegrationTests.swift b/packages/expo-biometrics/ios/Tests/BiometricSystemIntegrationTests.swift
new file mode 100644
index 00000000000..0dd3bfcb402
--- /dev/null
+++ b/packages/expo-biometrics/ios/Tests/BiometricSystemIntegrationTests.swift
@@ -0,0 +1,169 @@
+import Foundation
+import LocalAuthentication
+import Security
+import XCTest
+@testable import ClerkExpoBiometrics
+
+/// Skips tests that need the real Keychain when the test bundle runs without a host app.
+func skipUnlessKeychainIsAvailable() throws {
+ let query: [String: Any] = [
+ kSecClass as String: kSecClassGenericPassword,
+ kSecAttrService as String: "ClerkExpoBiometricsTests.probe",
+ ]
+ let status = SecItemCopyMatching(query as CFDictionary, nil)
+ try XCTSkipIf(status == errSecMissingEntitlement, "The Keychain is only available to tests running in a host app.")
+}
+
+final class KeychainMetadataStorageTests: XCTestCase {
+ private var storage: KeychainMetadataStorage!
+
+ override func setUpWithError() throws {
+ try super.setUpWithError()
+ try skipUnlessKeychainIsAvailable()
+ storage = KeychainMetadataStorage(service: "ClerkExpoBiometricsTests.\(UUID().uuidString)")
+ }
+
+ override func tearDownWithError() throws {
+ try storage?.delete()
+ try super.tearDownWithError()
+ }
+
+ func testWriteAddsThenUpdatesTheGenericPasswordItem() throws {
+ XCTAssertNil(try storage.read())
+
+ try storage.write(Data("[1]".utf8))
+ try storage.write(Data("[2]".utf8))
+
+ XCTAssertEqual(try storage.read(), Data("[2]".utf8))
+
+ var query = storage.baseQuery()
+ query[kSecReturnAttributes as String] = true
+ query[kSecMatchLimit as String] = kSecMatchLimitAll
+ var result: CFTypeRef?
+ XCTAssertEqual(SecItemCopyMatching(query as CFDictionary, &result), errSecSuccess)
+ let items = try XCTUnwrap(result as? [[String: Any]])
+ XCTAssertEqual(items.count, 1)
+ XCTAssertEqual(items[0][kSecAttrAccessible as String] as? String, kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly as String)
+ XCTAssertEqual(items[0][kSecAttrAccount as String] as? String, "trustedDeviceCredentials")
+ }
+
+ func testDeleteIsIdempotent() throws {
+ try storage.write(Data("[]".utf8))
+ try storage.delete()
+ try storage.delete()
+
+ XCTAssertNil(try storage.read())
+ }
+}
+
+final class BiometricKeyManagerTests: XCTestCase {
+ func testMissingKeyIsReportedWithoutPrompting() throws {
+ try skipUnlessKeychainIsAvailable()
+ let keyManager = BiometricKeyManager()
+ let localKeyId = BiometricCredentialCoding.makeLocalKeyId()
+
+ XCTAssertFalse(try keyManager.hasKey(localKeyId: localKeyId))
+ XCTAssertNoThrow(try keyManager.deleteKey(localKeyId: localKeyId))
+ XCTAssertThrowsError(try keyManager.sign(localKeyId: localKeyId, clientData: "data", reason: "Sign in")) { error in
+ XCTAssertEqual((error as? BiometricsError)?.code, .keyNotFound)
+ }
+ }
+
+ func testAvailabilityReportsAKnownBiometryType() {
+ let availability = BiometricKeyManager().availability()
+
+ XCTAssertTrue(["faceID", "touchID", "opticID", "none"].contains(availability.biometryType))
+ 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)
+ XCTAssertEqual(BiometricsError.code(forLAErrorCode: LAError.Code.appCancel.rawValue), .systemCanceled)
+ XCTAssertEqual(BiometricsError.code(forLAErrorCode: LAError.Code.userFallback.rawValue), .userFallback)
+ XCTAssertEqual(BiometricsError.code(forLAErrorCode: LAError.Code.authenticationFailed.rawValue), .authenticationFailed)
+ XCTAssertEqual(BiometricsError.code(forLAErrorCode: LAError.Code.biometryNotAvailable.rawValue), .biometryNotAvailable)
+ XCTAssertEqual(BiometricsError.code(forLAErrorCode: LAError.Code.biometryNotEnrolled.rawValue), .biometryNotEnrolled)
+ XCTAssertEqual(BiometricsError.code(forLAErrorCode: LAError.Code.biometryLockout.rawValue), .biometryLockout)
+ XCTAssertEqual(BiometricsError.code(forLAErrorCode: LAError.Code.passcodeNotSet.rawValue), .passcodeNotSet)
+
+ XCTAssertEqual(BiometricsError.code(forStatus: errSecUserCanceled), .userCanceled)
+ XCTAssertEqual(BiometricsError.code(forStatus: errSecAuthFailed), .authenticationFailed)
+ XCTAssertEqual(BiometricsError.code(forStatus: errSecInteractionNotAllowed), .biometryNotAvailable)
+ XCTAssertEqual(BiometricsError.code(forStatus: errSecItemNotFound), .keyNotFound)
+ XCTAssertNil(BiometricsError.code(forStatus: errSecParam))
+
+ let laError = NSError(domain: LAErrorDomain, code: LAError.Code.biometryLockout.rawValue)
+ XCTAssertEqual(BiometricsError.security(laError, fallback: .signingFailed).code, .biometryLockout)
+ XCTAssertEqual(BiometricsError.localAuthentication(laError, fallback: .biometryNotAvailable).code, .biometryLockout)
+ XCTAssertEqual(BiometricsError.localAuthentication(nil, fallback: .biometryNotAvailable).code, .biometryNotAvailable)
+ let statusError = NSError(domain: NSOSStatusErrorDomain, code: Int(errSecUserCanceled))
+ XCTAssertEqual(BiometricsError.security(statusError, fallback: .signingFailed).code, .userCanceled)
+ let tokenError = NSError(domain: "CryptoTokenKit", code: -6)
+ XCTAssertEqual(BiometricsError.security(tokenError, fallback: .signingFailed).code, .keyInvalidated)
+ let unknownError = NSError(domain: "Other", code: 1)
+ XCTAssertEqual(BiometricsError.security(unknownError, fallback: .signingFailed).code, .signingFailed)
+ }
+
+ // Record fields are reference-backed, so each case builds a fresh input.
+ private func makeInput(_ configure: (BiometricCredentialRecordInput) -> Void = { _ in }) -> BiometricCredentialRecordInput {
+ let input = BiometricCredentialRecordInput()
+ input.id = "tdc_1"
+ input.localKeyId = "tdlk_1"
+ input.userId = "user_1"
+ input.appIdentifier = "com.clerk.example"
+ input.identifierHint = " Hint "
+ input.policy = "biometry_any"
+ input.createdAt = 1_714_000_000_000.4
+ input.updatedAt = 1_714_000_000_001
+ configure(input)
+ return input
+ }
+
+ func testRecordInputValidation() throws {
+ let record = try ClerkExpoBiometricsModule.record(from: makeInput())
+ XCTAssertEqual(record.identifierHint, "hint")
+ XCTAssertEqual(record.policy, .biometryAny)
+ XCTAssertEqual(record.jsonObject["createdAt"] as? Int64, 1_714_000_000_000)
+ XCTAssertEqual(record.jsonObject["updatedAt"] as? Int64, 1_714_000_000_001)
+
+ let invalidInputs: [(String, (BiometricCredentialRecordInput) -> Void)] = [
+ ("policy", { $0.policy = "face_id" }),
+ ("id", { $0.id = "" }),
+ ("localKeyId", { $0.localKeyId = "" }),
+ ("userId", { $0.userId = "" }),
+ ("appIdentifier", { $0.appIdentifier = "" }),
+ ("nan createdAt", { $0.createdAt = .nan }),
+ ("negative createdAt", { $0.createdAt = -1 }),
+ ("infinite updatedAt", { $0.updatedAt = .infinity }),
+ ]
+ for (name, configure) in invalidInputs {
+ XCTAssertThrowsError(try ClerkExpoBiometricsModule.record(from: makeInput(configure)), name) { error in
+ XCTAssertEqual((error as? BiometricsError)?.code, .invalidArgument, name)
+ }
+ }
+ }
+}
diff --git a/packages/expo-biometrics/ios/Tests/Resources/BiometricCredentialStorageContractV1.json b/packages/expo-biometrics/ios/Tests/Resources/BiometricCredentialStorageContractV1.json
new file mode 100644
index 00000000000..0bbdf1f1a63
--- /dev/null
+++ b/packages/expo-biometrics/ios/Tests/Resources/BiometricCredentialStorageContractV1.json
@@ -0,0 +1,31 @@
+[
+ {
+ "id": "tdc_contract_current_set",
+ "localKeyId": "tdlk_0123456789abcdef0123456789abcdef",
+ "userId": "user_contract_1",
+ "appIdentifier": "com.clerk.example",
+ "identifierHint": "user@example.com",
+ "policy": "biometry_current_set",
+ "createdAt": 1714000000500,
+ "updatedAt": 1714000001500
+ },
+ {
+ "id": "tdc_contract_any",
+ "localKeyId": "tdlk_fedcba9876543210fedcba9876543210",
+ "userId": "user_contract_2",
+ "appIdentifier": "com.clerk.example",
+ "policy": "biometry_any",
+ "createdAt": 1714000002000,
+ "updatedAt": 1714000003000
+ },
+ {
+ "id": "tdc_contract_passcode",
+ "localKeyId": "tdlk_00000000000000000000000000000000",
+ "userId": "user_contract_1",
+ "appIdentifier": "com.clerk.other",
+ "identifierHint": "+15555550100",
+ "policy": "biometry_or_device_passcode",
+ "createdAt": 1714000004000,
+ "updatedAt": 1714000004000
+ }
+]
diff --git a/packages/expo-biometrics/package.json b/packages/expo-biometrics/package.json
new file mode 100644
index 00000000000..d285272b12f
--- /dev/null
+++ b/packages/expo-biometrics/package.json
@@ -0,0 +1,55 @@
+{
+ "name": "@clerk/expo-biometrics",
+ "version": "0.0.0",
+ "description": "Native biometric credential module to be used with Clerk for Expo",
+ "keywords": [
+ "react-native",
+ "expo",
+ "biometrics",
+ "face-id",
+ "touch-id",
+ "ClerkExpoBiometrics",
+ "clerk"
+ ],
+ "homepage": "https://clerk.com/",
+ "bugs": {
+ "url": "https://github.com/clerk/javascript/issues"
+ },
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/clerk/javascript.git",
+ "directory": "packages/expo-biometrics"
+ },
+ "license": "MIT",
+ "author": "Clerk",
+ "main": "dist/index.js",
+ "types": "dist/index.d.ts",
+ "files": [
+ "dist",
+ "android",
+ "!android/src/test",
+ "ios",
+ "!ios/Tests",
+ "expo-module.config.json"
+ ],
+ "scripts": {
+ "build": "tsup",
+ "build:declarations": "tsc -p tsconfig.declarations.json",
+ "clean": "rimraf ./dist",
+ "dev": "tsup --watch",
+ "format": "node ../../scripts/format-package.mjs",
+ "format:check": "node ../../scripts/format-package.mjs --check",
+ "lint": "eslint src",
+ "test": "vitest run",
+ "test:watch": "vitest watch"
+ },
+ "devDependencies": {
+ "expo": "~54.0.36"
+ },
+ "peerDependencies": {
+ "expo": "catalog:peer-expo"
+ },
+ "publishConfig": {
+ "access": "public"
+ }
+}
diff --git a/packages/expo-biometrics/src/ClerkExpoBiometricsModule.ts b/packages/expo-biometrics/src/ClerkExpoBiometricsModule.ts
new file mode 100644
index 00000000000..83ab05b6956
--- /dev/null
+++ b/packages/expo-biometrics/src/ClerkExpoBiometricsModule.ts
@@ -0,0 +1,27 @@
+import { requireOptionalNativeModule } from 'expo';
+
+import type {
+ BiometricAvailability,
+ BiometricCredentialKey,
+ BiometricCredentialPolicy,
+ BiometricCredentialRecord,
+ InstallationMarkerResult,
+ SaveRecordOptions,
+} from './types';
+
+export interface ClerkExpoBiometricsNativeModule {
+ getAppIdentifier(): string;
+ hashIdentifierHint(hint: string): string | null;
+ getAvailability(): Promise;
+ createKey(policy: BiometricCredentialPolicy): Promise;
+ sign(localKeyId: string, clientData: string, reason: string | null): Promise;
+ hasKey(localKeyId: string): Promise;
+ deleteKey(localKeyId: string): Promise;
+ /** JSON-encoded array of records, so fields the bridge cannot represent survive unchanged. */
+ listRecords(): Promise;
+ saveRecord(record: BiometricCredentialRecord, options: SaveRecordOptions): Promise;
+ deleteRecord(localKeyId: string): Promise;
+ ensureInstallationMarker(): Promise;
+}
+
+export default requireOptionalNativeModule('ClerkExpoBiometrics');
diff --git a/packages/expo-biometrics/src/__tests__/index.test.ts b/packages/expo-biometrics/src/__tests__/index.test.ts
new file mode 100644
index 00000000000..e79882aa9e3
--- /dev/null
+++ b/packages/expo-biometrics/src/__tests__/index.test.ts
@@ -0,0 +1,351 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+import type { BiometricCredentialRecord } from '../types';
+
+const mocks = vi.hoisted(() => ({
+ nativeModule: null as Record> | null,
+ requestedName: null as string | null,
+}));
+
+vi.mock('expo', () => ({
+ requireOptionalNativeModule: (name: string) => {
+ mocks.requestedName = name;
+ return mocks.nativeModule;
+ },
+}));
+
+const HINT_SHA256 = 'b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514';
+
+const createNativeModule = () => ({
+ getAppIdentifier: vi.fn().mockReturnValue('com.clerk.example'),
+ hashIdentifierHint: vi.fn().mockReturnValue(HINT_SHA256),
+ getAvailability: vi.fn().mockResolvedValue({
+ biometryType: 'faceID',
+ canEvaluateBiometrics: true,
+ canEvaluateDeviceOwner: true,
+ errorCode: null,
+ secureKeyStorageAvailable: true,
+ }),
+ createKey: vi.fn().mockResolvedValue({ localKeyId: 'tdlk_1', publicKeyJwk: '{"kty":"EC"}' }),
+ sign: vi.fn().mockResolvedValue('c2lnbmF0dXJl'),
+ hasKey: vi.fn().mockResolvedValue(true),
+ deleteKey: vi.fn().mockResolvedValue(undefined),
+ listRecords: vi.fn().mockResolvedValue('[]'),
+ saveRecord: vi.fn().mockResolvedValue(undefined),
+ deleteRecord: vi.fn().mockResolvedValue(undefined),
+ ensureInstallationMarker: vi.fn().mockResolvedValue({ wiped: false }),
+});
+
+const nativeError = (code: string, message = 'native failure') => Object.assign(new Error(message), { code });
+
+const record: BiometricCredentialRecord = {
+ id: 'tdc_1',
+ localKeyId: 'tdlk_1',
+ userId: 'user_1',
+ appIdentifier: 'com.clerk.example',
+ identifierHint: 'user@example.com',
+ policy: 'biometry_current_set',
+ createdAt: 1714000000500,
+ updatedAt: 1714000001500,
+};
+
+const load = async () => import('../index.js');
+
+describe('@clerk/expo-biometrics', () => {
+ let native: ReturnType;
+
+ beforeEach(() => {
+ vi.resetModules();
+ native = createNativeModule();
+ mocks.nativeModule = native;
+ mocks.requestedName = null;
+ });
+
+ test('loads the ClerkExpoBiometrics native module', async () => {
+ const biometrics = await load();
+
+ expect(mocks.requestedName).toBe('ClerkExpoBiometrics');
+ expect(biometrics.getAppIdentifier()).toBe('com.clerk.example');
+ await expect(biometrics.getAvailability()).resolves.toEqual({
+ biometryType: 'faceID',
+ 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();
+
+ expect(() => biometrics.getAppIdentifier()).toThrow(
+ expect.objectContaining({ name: 'ClerkBiometricsError', code: 'native_module_unavailable' }),
+ );
+ await expect(biometrics.getAvailability()).rejects.toMatchObject({ code: 'native_module_unavailable' });
+ await expect(biometrics.listRecords()).rejects.toMatchObject({ code: 'native_module_unavailable' });
+ expect(() => biometrics.hashIdentifierHint('user@example.com')).toThrow(
+ expect.objectContaining({ code: 'native_module_unavailable' }),
+ );
+ });
+
+ describe('hashIdentifierHint', () => {
+ test('returns the native hash synchronously', async () => {
+ const biometrics = await load();
+
+ expect(biometrics.hashIdentifierHint(' User@Example.COM\n')).toBe(HINT_SHA256);
+ expect(native.hashIdentifierHint).toHaveBeenCalledWith(' User@Example.COM\n');
+ });
+
+ test('passes through null for empty hints', async () => {
+ native.hashIdentifierHint.mockReturnValueOnce(null);
+ const biometrics = await load();
+
+ expect(biometrics.hashIdentifierHint(' ')).toBeNull();
+ });
+
+ test('rejects non-string hints without calling native', async () => {
+ const biometrics = await load();
+
+ // @ts-expect-error testing a non-string hint
+ expect(() => biometrics.hashIdentifierHint(null)).toThrow(expect.objectContaining({ code: 'invalid_argument' }));
+ expect(native.hashIdentifierHint).not.toHaveBeenCalled();
+ });
+
+ test('wraps native errors', async () => {
+ native.hashIdentifierHint.mockImplementationOnce(() => {
+ throw nativeError('ERR_ARGUMENT_CAST');
+ });
+ const biometrics = await load();
+
+ expect(() => biometrics.hashIdentifierHint('user@example.com')).toThrow(
+ expect.objectContaining({ name: 'ClerkBiometricsError', code: 'unknown' }),
+ );
+ });
+ });
+
+ describe('keys', () => {
+ test('createKey forwards the policy', async () => {
+ const biometrics = await load();
+
+ await expect(biometrics.createKey('biometry_or_device_passcode')).resolves.toEqual({
+ localKeyId: 'tdlk_1',
+ publicKeyJwk: '{"kty":"EC"}',
+ });
+ 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();
+
+ // @ts-expect-error testing an invalid policy
+ await expect(biometrics.createKey('face_id')).rejects.toMatchObject({ code: 'invalid_argument' });
+ expect(native.createKey).not.toHaveBeenCalled();
+ });
+
+ test('sign forwards arguments and defaults the reason to null', async () => {
+ const biometrics = await load();
+
+ await expect(biometrics.sign('tdlk_1', 'client-data', 'Sign in')).resolves.toBe('c2lnbmF0dXJl');
+ await biometrics.sign('tdlk_1', 'client-data');
+
+ expect(native.sign).toHaveBeenNthCalledWith(1, 'tdlk_1', 'client-data', 'Sign in');
+ expect(native.sign).toHaveBeenNthCalledWith(2, 'tdlk_1', 'client-data', null);
+ });
+
+ test('sign validates its arguments', async () => {
+ const biometrics = await load();
+
+ await expect(biometrics.sign('', 'client-data')).rejects.toMatchObject({ code: 'invalid_argument' });
+ // @ts-expect-error testing a non-string client data
+ await expect(biometrics.sign('tdlk_1', 42)).rejects.toMatchObject({ code: 'invalid_argument' });
+ expect(native.sign).not.toHaveBeenCalled();
+ });
+
+ test('hasKey and deleteKey forward the local key id', async () => {
+ const biometrics = await load();
+
+ await expect(biometrics.hasKey('tdlk_1')).resolves.toBe(true);
+ await expect(biometrics.deleteKey('tdlk_1')).resolves.toBeUndefined();
+ expect(native.hasKey).toHaveBeenCalledWith('tdlk_1');
+ expect(native.deleteKey).toHaveBeenCalledWith('tdlk_1');
+ });
+ });
+
+ describe('errors', () => {
+ test.each([
+ 'user_canceled',
+ 'system_canceled',
+ 'user_fallback',
+ 'authentication_failed',
+ 'biometry_not_available',
+ 'biometry_not_enrolled',
+ 'biometry_lockout',
+ 'passcode_not_set',
+ 'secure_key_storage_unavailable',
+ 'key_not_found',
+ 'key_invalidated',
+ 'key_generation_failed',
+ 'signing_failed',
+ 'storage_failed',
+ ])('preserves the native %s code', async code => {
+ native.sign.mockRejectedValueOnce(nativeError(code, 'details'));
+ const biometrics = await load();
+
+ const error = await biometrics.sign('tdlk_1', 'client-data').catch((e: unknown) => e);
+
+ expect(biometrics.isClerkBiometricsError(error)).toBe(true);
+ expect(error).toMatchObject({ code, message: 'details' });
+ expect((error as Error).cause).toBeInstanceOf(Error);
+ });
+
+ test('maps unrecognized native codes to unknown', async () => {
+ native.hasKey.mockRejectedValueOnce(nativeError('ERR_ARGUMENT_CAST'));
+ const biometrics = await load();
+
+ await expect(biometrics.hasKey('tdlk_1')).rejects.toMatchObject({ code: 'unknown' });
+ });
+
+ test('wraps synchronous native errors', async () => {
+ native.getAppIdentifier.mockImplementationOnce(() => {
+ throw nativeError('storage_failed');
+ });
+ const biometrics = await load();
+
+ expect(() => biometrics.getAppIdentifier()).toThrow(expect.objectContaining({ code: 'storage_failed' }));
+ });
+
+ test('isBiometricsErrorCode recognizes known codes', async () => {
+ 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);
+ });
+ });
+
+ describe('store', () => {
+ test('listRecords parses native JSON and passes unknown fields through', async () => {
+ native.listRecords.mockResolvedValueOnce(
+ JSON.stringify([{ ...record, identifierHintSha256: HINT_SHA256, futureField: { nested: [1, true, null] } }]),
+ );
+ const biometrics = await load();
+
+ const records = await biometrics.listRecords();
+
+ expect(records).toEqual([
+ { ...record, identifierHintSha256: HINT_SHA256, futureField: { nested: [1, true, null] } },
+ ]);
+ });
+
+ test('listRecords returns Android records with only the hashed identifier hint', async () => {
+ const { identifierHint: _, ...withoutHint } = record;
+ const androidRecord = { ...withoutHint, identifierHint: null, identifierHintSha256: HINT_SHA256 };
+ native.listRecords.mockResolvedValueOnce(JSON.stringify([androidRecord]));
+ const biometrics = await load();
+
+ await expect(biometrics.listRecords()).resolves.toEqual([androidRecord]);
+ });
+
+ test('listRecords rejects with storage_failed on invalid native output', async () => {
+ native.listRecords.mockResolvedValueOnce('not json');
+ native.listRecords.mockResolvedValueOnce('{}');
+ const biometrics = await load();
+
+ await expect(biometrics.listRecords()).rejects.toMatchObject({ code: 'storage_failed' });
+ await expect(biometrics.listRecords()).rejects.toMatchObject({ code: 'storage_failed' });
+ });
+
+ test('saveRecord sends only contract fields', async () => {
+ const biometrics = await load();
+
+ await biometrics.saveRecord({ ...record, extra: 'dropped' } as BiometricCredentialRecord, {
+ removeOtherRecordsForApp: true,
+ });
+
+ expect(native.saveRecord).toHaveBeenCalledWith(record, { removeOtherRecordsForApp: true });
+ });
+
+ test('saveRecord omits an absent identifier hint', async () => {
+ const biometrics = await load();
+ const { identifierHint: _, ...withoutHint } = record;
+
+ await biometrics.saveRecord(withoutHint, { removeOtherRecordsForApp: false });
+
+ expect(native.saveRecord.mock.calls[0][0]).not.toHaveProperty('identifierHint');
+ });
+
+ test.each<[string, Partial>]>([
+ ['an empty id', { id: '' }],
+ ['a missing localKeyId', { localKeyId: undefined }],
+ ['a non-string userId', { userId: 1 }],
+ ['an empty appIdentifier', { appIdentifier: '' }],
+ ['a non-string identifierHint', { identifierHint: 1 }],
+ ['an unknown policy', { policy: 'face_id' }],
+ ['a negative createdAt', { createdAt: -1 }],
+ ['a non-finite updatedAt', { updatedAt: Number.NaN }],
+ ['a string createdAt', { createdAt: '1714000000500' }],
+ ])('saveRecord rejects %s', async (_, override) => {
+ const biometrics = await load();
+
+ await expect(
+ biometrics.saveRecord({ ...record, ...override } as BiometricCredentialRecord, {
+ removeOtherRecordsForApp: false,
+ }),
+ ).rejects.toMatchObject({ code: 'invalid_argument' });
+ expect(native.saveRecord).not.toHaveBeenCalled();
+ });
+
+ test('saveRecord requires removeOtherRecordsForApp', async () => {
+ const biometrics = await load();
+
+ // @ts-expect-error testing missing options
+ await expect(biometrics.saveRecord(record)).rejects.toMatchObject({ code: 'invalid_argument' });
+ });
+
+ test('deleteRecord and ensureInstallationMarker forward to native', async () => {
+ native.ensureInstallationMarker.mockResolvedValueOnce({ wiped: true });
+ const biometrics = await load();
+
+ await biometrics.deleteRecord('tdlk_1');
+ await expect(biometrics.ensureInstallationMarker()).resolves.toEqual({ wiped: true });
+
+ expect(native.deleteRecord).toHaveBeenCalledWith('tdlk_1');
+ await expect(biometrics.deleteRecord('')).rejects.toMatchObject({ code: 'invalid_argument' });
+ });
+
+ test('store errors keep their native code', async () => {
+ native.saveRecord.mockRejectedValueOnce(nativeError('storage_failed'));
+ const biometrics = await load();
+
+ await expect(biometrics.saveRecord(record, { removeOtherRecordsForApp: false })).rejects.toMatchObject({
+ code: 'storage_failed',
+ });
+ });
+ });
+});
diff --git a/packages/expo-biometrics/src/errors.ts b/packages/expo-biometrics/src/errors.ts
new file mode 100644
index 00000000000..03707ec1c46
--- /dev/null
+++ b/packages/expo-biometrics/src/errors.ts
@@ -0,0 +1,48 @@
+import type { BiometricsErrorCode } from './types';
+
+const ERROR_CODES: ReadonlySet = new Set([
+ 'user_canceled',
+ 'system_canceled',
+ 'user_fallback',
+ 'authentication_failed',
+ 'biometry_not_available',
+ 'biometry_not_enrolled',
+ 'biometry_lockout',
+ 'passcode_not_set',
+ 'secure_key_storage_unavailable',
+ 'key_not_found',
+ 'key_invalidated',
+ 'key_generation_failed',
+ 'signing_failed',
+ 'storage_failed',
+ 'invalid_argument',
+ 'native_module_unavailable',
+ 'unknown',
+]);
+
+export class ClerkBiometricsError extends Error {
+ readonly code: BiometricsErrorCode;
+
+ constructor(code: BiometricsErrorCode, message: string, options?: { cause?: unknown }) {
+ super(message, options);
+ this.name = 'ClerkBiometricsError';
+ this.code = code;
+ }
+}
+
+export function isClerkBiometricsError(error: unknown): error is ClerkBiometricsError {
+ return error instanceof ClerkBiometricsError;
+}
+
+export function isBiometricsErrorCode(value: unknown): value is BiometricsErrorCode {
+ return typeof value === 'string' && ERROR_CODES.has(value);
+}
+
+export function toClerkBiometricsError(error: unknown): ClerkBiometricsError {
+ if (error instanceof ClerkBiometricsError) {
+ return error;
+ }
+ const code = (error as { code?: unknown } | null)?.code;
+ const message = error instanceof Error ? error.message : String(error);
+ return new ClerkBiometricsError(isBiometricsErrorCode(code) ? code : 'unknown', message, { cause: error });
+}
diff --git a/packages/expo-biometrics/src/index.ts b/packages/expo-biometrics/src/index.ts
new file mode 100644
index 00000000000..eeb11dea379
--- /dev/null
+++ b/packages/expo-biometrics/src/index.ts
@@ -0,0 +1,224 @@
+import type { ClerkExpoBiometricsNativeModule } from './ClerkExpoBiometricsModule';
+import ClerkExpoBiometrics from './ClerkExpoBiometricsModule';
+import { ClerkBiometricsError, toClerkBiometricsError } from './errors';
+import type {
+ BiometricAvailability,
+ BiometricCredentialKey,
+ BiometricCredentialPolicy,
+ BiometricCredentialRecord,
+ InstallationMarkerResult,
+ SaveRecordOptions,
+ StoredBiometricCredentialRecord,
+} from './types';
+
+export { ClerkBiometricsError, isBiometricsErrorCode, isClerkBiometricsError } from './errors';
+export type {
+ BiometricAvailability,
+ BiometricCredentialKey,
+ BiometricCredentialPolicy,
+ BiometricCredentialRecord,
+ BiometricsErrorCode,
+ BiometryType,
+ InstallationMarkerResult,
+ SaveRecordOptions,
+ StoredBiometricCredentialRecord,
+} from './types';
+
+const POLICIES: ReadonlySet = new Set([
+ 'biometry_current_set',
+ 'biometry_any',
+ 'biometry_or_device_passcode',
+]);
+
+function nativeModule(): ClerkExpoBiometricsNativeModule {
+ if (!ClerkExpoBiometrics) {
+ throw new ClerkBiometricsError(
+ 'native_module_unavailable',
+ 'The ClerkExpoBiometrics native module is not available. Rebuild your app with @clerk/expo-biometrics installed; it cannot run in Expo Go or on the web.',
+ );
+ }
+ return ClerkExpoBiometrics;
+}
+
+async function callNative(fn: (module: ClerkExpoBiometricsNativeModule) => Promise): Promise {
+ const module = nativeModule();
+ try {
+ return await fn(module);
+ } catch (error) {
+ throw toClerkBiometricsError(error);
+ }
+}
+
+function invalidArgument(message: string): ClerkBiometricsError {
+ return new ClerkBiometricsError('invalid_argument', message);
+}
+
+function assertNonEmptyString(value: unknown, name: string): asserts value is string {
+ if (typeof value !== 'string' || value.length === 0) {
+ throw invalidArgument(`${name} must be a non-empty string.`);
+ }
+}
+
+function assertPolicy(value: unknown): asserts value is BiometricCredentialPolicy {
+ if (typeof value !== 'string' || !POLICIES.has(value)) {
+ throw invalidArgument(`policy must be one of ${[...POLICIES].join(', ')}.`);
+ }
+}
+
+function assertTimestamp(value: unknown, name: string): asserts value is number {
+ if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+ throw invalidArgument(`${name} must be a non-negative number of milliseconds since the Unix epoch.`);
+ }
+}
+
+function assertRecord(record: BiometricCredentialRecord): void {
+ if (typeof record !== 'object' || record === null) {
+ throw invalidArgument('record must be an object.');
+ }
+ assertNonEmptyString(record.id, 'record.id');
+ assertNonEmptyString(record.localKeyId, 'record.localKeyId');
+ assertNonEmptyString(record.userId, 'record.userId');
+ assertNonEmptyString(record.appIdentifier, 'record.appIdentifier');
+ if (record.identifierHint !== undefined && typeof record.identifierHint !== 'string') {
+ throw invalidArgument('record.identifierHint must be a string when provided.');
+ }
+ assertPolicy(record.policy);
+ assertTimestamp(record.createdAt, 'record.createdAt');
+ assertTimestamp(record.updatedAt, 'record.updatedAt');
+}
+
+function callNativeSync(fn: (module: ClerkExpoBiometricsNativeModule) => T): T {
+ const module = nativeModule();
+ try {
+ return fn(module);
+ } catch (error) {
+ throw toClerkBiometricsError(error);
+ }
+}
+
+/**
+ * Returns the identifier Clerk uses as the credential's `app_identifier` (the iOS bundle identifier or the Android package name).
+ */
+export function getAppIdentifier(): string {
+ return callNativeSync(module => module.getAppIdentifier());
+}
+
+/**
+ * Returns the SHA-256 of `hint` after trimming and lowercasing it, as 64 lowercase hex characters, or `null` when the
+ * normalized hint is empty. Compare it with a record's `identifierHintSha256` to match an identifier on every platform.
+ */
+export function hashIdentifierHint(hint: string): string | null {
+ if (typeof hint !== 'string') {
+ throw invalidArgument('hint must be a string.');
+ }
+ return callNativeSync(module => module.hashIdentifierHint(hint));
+}
+
+/**
+ * Reports which biometry the device supports and whether it can be used right now.
+ */
+export function getAvailability(): Promise {
+ return callNative(module => module.getAvailability());
+}
+
+/**
+ * Creates a new hardware-backed P-256 private key protected by `policy`.
+ * 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 {
+ assertPolicy(policy);
+ return callNative(module => module.createKey(policy));
+}
+
+/**
+ * Prompts for local authentication and signs the UTF-8 bytes of `clientData` with ES256.
+ * Resolves with the raw `r || s` signature, base64url-encoded without padding.
+ *
+ * @param reason - The message shown in the authentication prompt. On Android it is the prompt title, which defaults to the app name.
+ */
+export async function sign(localKeyId: string, clientData: string, reason: string | null = null): Promise {
+ assertNonEmptyString(localKeyId, 'localKeyId');
+ if (typeof clientData !== 'string') {
+ throw invalidArgument('clientData must be a string.');
+ }
+ return callNative(module => module.sign(localKeyId, clientData, reason));
+}
+
+/**
+ * Resolves whether the private key for `localKeyId` exists. Does not prompt for authentication.
+ */
+export async function hasKey(localKeyId: string): Promise {
+ assertNonEmptyString(localKeyId, 'localKeyId');
+ return callNative(module => module.hasKey(localKeyId));
+}
+
+/**
+ * Deletes the private key for `localKeyId`. Resolves when the key does not exist.
+ */
+export async function deleteKey(localKeyId: string): Promise {
+ assertNonEmptyString(localKeyId, 'localKeyId');
+ return callNative(module => module.deleteKey(localKeyId));
+}
+
+/**
+ * Lists every well-formed credential record on the device, for every app identifier.
+ */
+export async function listRecords(): Promise {
+ const json = await callNative(module => module.listRecords());
+ let records: unknown;
+ try {
+ records = JSON.parse(json);
+ } catch (error) {
+ throw new ClerkBiometricsError('storage_failed', 'The native module returned invalid record data.', {
+ cause: error,
+ });
+ }
+ if (!Array.isArray(records)) {
+ throw new ClerkBiometricsError('storage_failed', 'The native module returned invalid record data.');
+ }
+ return records as StoredBiometricCredentialRecord[];
+}
+
+/**
+ * Saves `record`, replacing any record with the same `id`. When the replaced record used a different key, that key is deleted.
+ */
+export async function saveRecord(record: BiometricCredentialRecord, options: SaveRecordOptions): Promise {
+ assertRecord(record);
+ if (typeof options?.removeOtherRecordsForApp !== 'boolean') {
+ throw invalidArgument('options.removeOtherRecordsForApp must be a boolean.');
+ }
+ const nativeRecord: BiometricCredentialRecord = {
+ id: record.id,
+ localKeyId: record.localKeyId,
+ userId: record.userId,
+ appIdentifier: record.appIdentifier,
+ policy: record.policy,
+ createdAt: record.createdAt,
+ updatedAt: record.updatedAt,
+ };
+ if (record.identifierHint !== undefined) {
+ nativeRecord.identifierHint = record.identifierHint;
+ }
+ return callNative(module =>
+ module.saveRecord(nativeRecord, { removeOtherRecordsForApp: options.removeOtherRecordsForApp }),
+ );
+}
+
+/**
+ * Deletes the private key for `localKeyId`, then every record that references it.
+ * When the key cannot be deleted the records are kept and the promise rejects.
+ */
+export async function deleteRecord(localKeyId: string): Promise {
+ assertNonEmptyString(localKeyId, 'localKeyId');
+ return callNative(module => module.deleteRecord(localKeyId));
+}
+
+/**
+ * Detects a new installation and deletes the records and keys a previous installation of this app left in the Keychain.
+ * Safe to call repeatedly. The store operations above call it before they read or write.
+ * On Android it always resolves `{ wiped: false }`: uninstalling the app deletes its records and keys.
+ */
+export function ensureInstallationMarker(): Promise {
+ return callNative(module => module.ensureInstallationMarker());
+}
diff --git a/packages/expo-biometrics/src/types.ts b/packages/expo-biometrics/src/types.ts
new file mode 100644
index 00000000000..09e3a5225b4
--- /dev/null
+++ b/packages/expo-biometrics/src/types.ts
@@ -0,0 +1,109 @@
+/**
+ * The local authentication policy that protects a biometric credential's private key.
+ *
+ * - `biometry_current_set`: requires a biometric from the currently enrolled set. Adding or removing a Face ID / Touch ID enrollment invalidates the key.
+ * - `biometry_any`: requires a biometric, and survives biometric enrollment changes.
+ * - `biometry_or_device_passcode`: requires biometrics to be available at creation, then accepts a biometric or the device passcode.
+ */
+export type BiometricCredentialPolicy = 'biometry_current_set' | 'biometry_any' | 'biometry_or_device_passcode';
+
+/**
+ * The biometry the device supports. iOS reports `faceID`, `touchID`, or `opticID`. Android cannot tell which sensor is a
+ * strong (Class 3) biometric, so it reports `biometric` whenever one is present.
+ */
+export type BiometryType = 'faceID' | 'touchID' | 'opticID' | 'biometric' | 'none';
+
+export interface BiometricAvailability {
+ /** The biometry the device supports, or `none`. */
+ biometryType: BiometryType;
+ /** Whether biometric authentication can be evaluated now. Key creation requires this for every policy. */
+ canEvaluateBiometrics: boolean;
+ /** Whether device owner authentication (biometrics or passcode) can be evaluated now. */
+ 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, which the iOS Simulator lacks, or the
+ * Android Keystore on Android 9 (API level 28) and later.
+ * `createKey()` rejects with `secure_key_storage_unavailable` when this is `false`.
+ */
+ secureKeyStorageAvailable: boolean;
+}
+
+export interface BiometricCredentialKey {
+ /** Opaque identifier of the private key. Stored in the credential record as `localKeyId`. */
+ localKeyId: string;
+ /** P-256 public key as a compact JWK string: `{"kty":"EC","crv":"P-256","x":"…","y":"…","alg":"ES256"}`. */
+ publicKeyJwk: string;
+}
+
+/**
+ * On-device metadata linking a Clerk biometric credential to its private key.
+ */
+export interface BiometricCredentialRecord {
+ /** Server credential ID. */
+ id: string;
+ /** Identifier of the private key returned by `createKey()`. */
+ localKeyId: string;
+ /** Clerk user ID that enrolled the credential. */
+ userId: string;
+ /** App identifier the credential was enrolled for (see `getAppIdentifier()`). */
+ appIdentifier: string;
+ /**
+ * Local-only identifier hint. Normalized (trimmed, lowercased) when stored; empty values are omitted.
+ * iOS stores the normalized hint; Android stores only its hash (see `hashIdentifierHint()`).
+ */
+ identifierHint?: string;
+ policy: BiometricCredentialPolicy;
+ /** Server credential creation time, in milliseconds since the Unix epoch. */
+ createdAt: number;
+ /** Server credential update time, in milliseconds since the Unix epoch. */
+ updatedAt: number;
+}
+
+/**
+ * A record read from the store. Fields written by other SDK versions are passed through unchanged.
+ */
+export type StoredBiometricCredentialRecord = Omit & {
+ /** The normalized identifier hint on iOS, when one was stored. Always `null` on Android, which stores only the hash. */
+ identifierHint?: string | null;
+ /** `hashIdentifierHint()` of the stored identifier hint, or `null` when there is none. Compare hints with this field. */
+ identifierHintSha256: string | null;
+ readonly [field: string]: unknown;
+};
+
+export interface SaveRecordOptions {
+ /**
+ * Delete every other record for the same `appIdentifier`, along with its private key, after the record is saved.
+ * Set this after a successful enrollment, since the server has already replaced those credentials.
+ * On Android only the same `userId`'s other records are deleted, as the shared storage contract requires.
+ */
+ removeOtherRecordsForApp: boolean;
+}
+
+export interface InstallationMarkerResult {
+ /**
+ * `true` when this is a new installation and the records left behind by a previous one were deleted.
+ * Always `false` on Android, where uninstalling the app already deletes its records and keys.
+ */
+ wiped: boolean;
+}
+
+export type BiometricsErrorCode =
+ | 'user_canceled'
+ | 'system_canceled'
+ | 'user_fallback'
+ | 'authentication_failed'
+ | 'biometry_not_available'
+ | 'biometry_not_enrolled'
+ | 'biometry_lockout'
+ | 'passcode_not_set'
+ | 'secure_key_storage_unavailable'
+ | 'key_not_found'
+ | 'key_invalidated'
+ | 'key_generation_failed'
+ | 'signing_failed'
+ | 'storage_failed'
+ | 'invalid_argument'
+ | 'native_module_unavailable'
+ | 'unknown';
diff --git a/packages/expo-biometrics/tsconfig.declarations.json b/packages/expo-biometrics/tsconfig.declarations.json
new file mode 100644
index 00000000000..30037049bb1
--- /dev/null
+++ b/packages/expo-biometrics/tsconfig.declarations.json
@@ -0,0 +1,15 @@
+{
+ "extends": "./tsconfig.json",
+ "compilerOptions": {
+ "rootDir": "./src",
+ "incremental": false,
+ "skipLibCheck": true,
+ "noEmit": false,
+ "declaration": true,
+ "emitDeclarationOnly": true,
+ "declarationMap": true,
+ "sourceMap": false,
+ "declarationDir": "./dist"
+ },
+ "exclude": ["**/__tests__/**/*"]
+}
diff --git a/packages/expo-biometrics/tsconfig.json b/packages/expo-biometrics/tsconfig.json
new file mode 100644
index 00000000000..ba72a15ff1d
--- /dev/null
+++ b/packages/expo-biometrics/tsconfig.json
@@ -0,0 +1,27 @@
+{
+ "compilerOptions": {
+ "allowJs": true,
+ "declaration": true,
+ "declarationMap": false,
+ "esModuleInterop": true,
+ "importHelpers": true,
+ "incremental": true,
+ "jsx": "react-jsx",
+ "lib": ["ESNext", "dom"],
+ "module": "NodeNext",
+ "moduleResolution": "NodeNext",
+ "noEmitOnError": false,
+ "noImplicitReturns": true,
+ "noUnusedLocals": true,
+ "noUnusedParameters": true,
+ "outDir": "dist",
+ "resolveJsonModule": true,
+ "skipLibCheck": true,
+ "sourceMap": false,
+ "strict": true,
+ "target": "ES2019",
+ "types": ["node"],
+ "rootDir": "./src"
+ },
+ "include": ["src"]
+}
diff --git a/packages/expo-biometrics/tsup.config.ts b/packages/expo-biometrics/tsup.config.ts
new file mode 100644
index 00000000000..f705ef7fde7
--- /dev/null
+++ b/packages/expo-biometrics/tsup.config.ts
@@ -0,0 +1,19 @@
+import type { Options } from 'tsup';
+import { defineConfig } from 'tsup';
+
+import { runAfterLast } from '../../scripts/utils';
+
+export default defineConfig(() => {
+ const options: Options = {
+ format: 'cjs',
+ outDir: './dist',
+ entry: ['./src/**/*.{ts,tsx,js,jsx}', '!./src/**/__tests__/**'],
+ bundle: false,
+ clean: true,
+ minify: false,
+ sourcemap: true,
+ legacyOutput: true,
+ };
+
+ return runAfterLast(['pnpm build:declarations'])(options);
+});
diff --git a/packages/expo-biometrics/vitest.config.mts b/packages/expo-biometrics/vitest.config.mts
new file mode 100644
index 00000000000..4ac6027d578
--- /dev/null
+++ b/packages/expo-biometrics/vitest.config.mts
@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+ test: {
+ environment: 'node',
+ },
+});
diff --git a/packages/expo/biometrics/package.json b/packages/expo/biometrics/package.json
new file mode 100644
index 00000000000..e017b6e9bcb
--- /dev/null
+++ b/packages/expo/biometrics/package.json
@@ -0,0 +1,4 @@
+{
+ "main": "../dist/biometrics/index.js",
+ "types": "../dist/biometrics/index.d.ts"
+}
diff --git a/packages/expo/package.json b/packages/expo/package.json
index 5904e907b05..14c5de2702e 100644
--- a/packages/expo/package.json
+++ b/packages/expo/package.json
@@ -61,6 +61,10 @@
"types": "./dist/apple/index.d.ts",
"default": "./dist/apple/index.js"
},
+ "./biometrics": {
+ "types": "./dist/biometrics/index.d.ts",
+ "default": "./dist/biometrics/index.js"
+ },
"./hosted-auth": {
"types": "./dist/hosted-auth/index.d.ts",
"default": "./dist/hosted-auth/index.js"
@@ -96,6 +100,7 @@
"token-cache",
"google",
"apple",
+ "biometrics",
"hosted-auth",
"experimental",
"legacy",
@@ -126,6 +131,7 @@
"tslib": "catalog:repo"
},
"devDependencies": {
+ "@clerk/expo-biometrics": "workspace:*",
"@clerk/expo-google-signin": "workspace:*",
"@clerk/expo-passkeys": "workspace:*",
"@expo/config-plugins": "^54.0.4",
@@ -141,6 +147,7 @@
"react-native": "^0.86.0"
},
"peerDependencies": {
+ "@clerk/expo-biometrics": ">=0.1.0",
"@clerk/expo-google-signin": ">=0.1.0",
"@clerk/expo-passkeys": ">=0.0.6",
"expo": "catalog:peer-expo",
@@ -156,6 +163,9 @@
"react-native": ">=0.75"
},
"peerDependenciesMeta": {
+ "@clerk/expo-biometrics": {
+ "optional": true
+ },
"@clerk/expo-google-signin": {
"optional": true
},
diff --git a/packages/expo/src/biometric-credentials/__tests__/reverification.test.ts b/packages/expo/src/biometric-credentials/__tests__/reverification.test.ts
deleted file mode 100644
index 75978520dd1..00000000000
--- a/packages/expo/src/biometric-credentials/__tests__/reverification.test.ts
+++ /dev/null
@@ -1,242 +0,0 @@
-import { renderHook } from '@testing-library/react';
-import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
-
-import {
- __internal_resetNativeClientSyncCoordinator,
- registerNativeToJsSyncHandler,
- trackPendingJsToNativeSync,
-} from '../../provider/nativeClientSyncCoordinator';
-import { useBiometricCredentials as useUnsupportedBiometrics } from '../useBiometricCredentials';
-import { useBiometricCredentials as useAndroidBiometrics } from '../useBiometricCredentials.android';
-import { useBiometricCredentials as useIosBiometrics } from '../useBiometricCredentials.ios';
-
-const mocks = vi.hoisted(() => ({
- useClerk: vi.fn(),
- nativeModule: {
- getTrustedDeviceAvailability: vi.fn(),
- listTrustedDevices: vi.fn(),
- enrollTrustedDevice: vi.fn(),
- revokeTrustedDevice: vi.fn(),
- signInWithTrustedDevice: vi.fn(),
- reverifyWithBiometrics: vi.fn(),
- },
-}));
-
-vi.mock('@clerk/react', () => ({ useClerk: mocks.useClerk }));
-vi.mock('../../utils/native-module', () => ({ ClerkExpoModule: mocks.nativeModule }));
-vi.mock('react-native', () => ({ Platform: { OS: 'ios' } }));
-
-const session = {
- id: 'sess_123',
- clearCache: vi.fn(),
- getToken: vi.fn(),
-};
-const clerk = { session: session as typeof session | null, setActive: vi.fn() };
-const synchronize = vi.fn();
-let unregister: () => void;
-
-beforeEach(() => {
- vi.resetAllMocks();
- __internal_resetNativeClientSyncCoordinator();
- unregister = registerNativeToJsSyncHandler(synchronize);
- clerk.session = session;
- mocks.useClerk.mockReturnValue(clerk);
- session.getToken.mockResolvedValue('fresh-token');
- mocks.nativeModule.reverifyWithBiometrics.mockResolvedValue({
- id: 'stepup_123',
- status: 'complete',
- level: 'first_factor',
- sessionId: session.id,
- });
-});
-
-afterEach(() => unregister());
-
-describe.each([
- ['iOS', useIosBiometrics],
- ['Android', useAndroidBiometrics],
-] as const)('biometric reverification on %s', (_platform, useBiometrics) => {
- test('refreshes the same session and forces a fresh token before completing', async () => {
- const { result } = renderHook(useBiometrics);
-
- await expect(result.current.reverify({ reason: 'Approve this change' })).resolves.toEqual({
- id: 'stepup_123',
- status: 'complete',
- level: 'first_factor',
- session,
- });
- expect(mocks.nativeModule.reverifyWithBiometrics).toHaveBeenCalledWith(
- session.id,
- 'first_factor',
- 'Approve this change',
- );
- expect(synchronize).toHaveBeenCalledOnce();
- expect(session.clearCache).toHaveBeenCalledTimes(2);
- expect(session.clearCache.mock.invocationCallOrder[0]).toBeLessThan(synchronize.mock.invocationCallOrder[0]);
- expect(session.getToken).toHaveBeenCalledWith({ skipCache: true });
- expect(synchronize.mock.invocationCallOrder[0]).toBeLessThan(session.getToken.mock.invocationCallOrder[0]);
- expect(clerk.setActive).not.toHaveBeenCalled();
- expect(mocks.nativeModule.signInWithTrustedDevice).not.toHaveBeenCalled();
- });
-
- test.each(['first_factor', 'second_factor', 'multi_factor'] as const)(
- 'passes the requested %s requirement',
- async level => {
- const { result } = renderHook(useBiometrics);
- await result.current.reverify({ level });
- expect(mocks.nativeModule.reverifyWithBiometrics).toHaveBeenCalledWith(session.id, level, null);
- },
- );
-});
-
-test('returns the server level when it differs from the requested level', async () => {
- const { result } = renderHook(useIosBiometrics);
- await expect(result.current.reverify({ level: 'multi_factor' })).resolves.toMatchObject({ level: 'first_factor' });
-});
-
-test('incomplete verification returns the synchronized session without refreshing tokens', async () => {
- mocks.nativeModule.reverifyWithBiometrics.mockResolvedValue({
- id: 'stepup_123',
- status: 'needs_second_factor',
- level: 'multi_factor',
- sessionId: session.id,
- });
- const refreshedSession = { ...session };
- synchronize.mockImplementation(() => {
- clerk.session = refreshedSession;
- });
- const { result } = renderHook(useIosBiometrics);
- const verification = await result.current.reverify({ level: 'multi_factor' });
- expect(verification.status).toBe('needs_second_factor');
- expect(verification.session).toBe(refreshedSession);
- expect(session.clearCache).not.toHaveBeenCalled();
- expect(session.getToken).not.toHaveBeenCalled();
-});
-
-test('waits for pending JS-to-native synchronization', async () => {
- let finish!: () => void;
- trackPendingJsToNativeSync(
- new Promise(resolve => {
- finish = resolve;
- }),
- );
- const { result } = renderHook(useIosBiometrics);
- const verification = result.current.reverify();
- await Promise.resolve();
- expect(mocks.nativeModule.reverifyWithBiometrics).not.toHaveBeenCalled();
- finish();
- await verification;
-});
-
-test('does not start a biometric operation after the active session changes during synchronization', async () => {
- let finish!: () => void;
- trackPendingJsToNativeSync(
- new Promise(resolve => {
- finish = resolve;
- }),
- );
- const { result } = renderHook(useIosBiometrics);
- const verification = result.current.reverify();
- clerk.session = { ...session, id: 'sess_other' };
- finish();
- await expect(verification).rejects.toThrow('active session changed');
- expect(mocks.nativeModule.reverifyWithBiometrics).not.toHaveBeenCalled();
-});
-
-test.each(['biometric_authentication_canceled', 'biometric_credential_policy_incompatible', 'key_invalidated'])(
- 'preserves the native %s error and leaves the session cache intact',
- async code => {
- const error = Object.assign(new Error(code), { code });
- mocks.nativeModule.reverifyWithBiometrics.mockRejectedValue(error);
- const { result } = renderHook(useAndroidBiometrics);
- await expect(result.current.reverify()).rejects.toBe(error);
- expect(session.clearCache).not.toHaveBeenCalled();
- expect(session.getToken).not.toHaveBeenCalled();
- expect(synchronize).not.toHaveBeenCalled();
- },
-);
-
-test('rejects a native result belonging to another session', async () => {
- mocks.nativeModule.reverifyWithBiometrics.mockResolvedValue({ status: 'complete', sessionId: 'sess_other' });
- const { result } = renderHook(useIosBiometrics);
- await expect(result.current.reverify()).rejects.toThrow('different session');
- expect(synchronize).not.toHaveBeenCalled();
-});
-
-test('does not refresh or activate another session if the active session changes', async () => {
- const otherSession = { ...session, id: 'sess_other', getToken: vi.fn() };
- synchronize.mockImplementation(() => {
- clerk.session = otherSession;
- });
- const { result } = renderHook(useIosBiometrics);
- await expect(result.current.reverify()).rejects.toThrow('active session changed');
- expect(otherSession.getToken).not.toHaveBeenCalled();
- expect(clerk.setActive).not.toHaveBeenCalled();
-});
-
-test('propagates synchronization failures after invalidating cached tokens', async () => {
- synchronize.mockRejectedValue(new Error('sync failed'));
- const { result } = renderHook(useIosBiometrics);
- await expect(result.current.reverify()).rejects.toThrow('sync failed');
- expect(session.clearCache).toHaveBeenCalledOnce();
- expect(session.getToken).not.toHaveBeenCalled();
-});
-
-test.each([null, 'failure'])('does not report success when token refresh returns %s', async outcome => {
- if (outcome === null) {
- session.getToken.mockResolvedValue(null);
- } else {
- session.getToken.mockRejectedValue(new Error('token refresh failed'));
- }
- const { result } = renderHook(useIosBiometrics);
- await expect(result.current.reverify()).rejects.toThrow();
-});
-
-test('requires an active session', async () => {
- clerk.session = null;
- const { result } = renderHook(useIosBiometrics);
- await expect(result.current.reverify()).rejects.toThrow('requires an active session');
- expect(mocks.nativeModule.reverifyWithBiometrics).not.toHaveBeenCalled();
-});
-
-test('rejects an invalid runtime level before starting verification', async () => {
- const { result } = renderHook(useIosBiometrics);
- await expect(result.current.reverify({ level: 'invalid' as 'first_factor' })).rejects.toThrow(
- 'level must be first_factor, second_factor, or multi_factor',
- );
- expect(mocks.nativeModule.reverifyWithBiometrics).not.toHaveBeenCalled();
-});
-
-test('rejects completion if the active session changes while refreshing its token', async () => {
- let finish!: (token: string) => void;
- session.getToken.mockReturnValue(
- new Promise(resolve => {
- finish = resolve;
- }),
- );
- const { result } = renderHook(useIosBiometrics);
- const verification = result.current.reverify();
- await vi.waitFor(() => expect(session.getToken).toHaveBeenCalled());
- clerk.session = { ...session, id: 'sess_other' };
- finish('fresh-token');
- await expect(verification).rejects.toThrow('active session changed');
- expect(clerk.setActive).not.toHaveBeenCalled();
-});
-
-test('older native builds keep existing operations but explain the missing reverification method', async () => {
- const reverify = mocks.nativeModule.reverifyWithBiometrics;
- Object.assign(mocks.nativeModule, { reverifyWithBiometrics: undefined });
- mocks.nativeModule.listTrustedDevices.mockResolvedValue([]);
- try {
- const { result } = renderHook(useIosBiometrics);
- await expect(result.current.list()).resolves.toEqual([]);
- await expect(result.current.reverify()).rejects.toThrow('Biometric reverification requires a development build');
- } finally {
- Object.assign(mocks.nativeModule, { reverifyWithBiometrics: reverify });
- }
-});
-
-test('unsupported platforms reject reverification', async () => {
- const { result } = renderHook(useUnsupportedBiometrics);
- await expect(result.current.reverify()).rejects.toThrow('only available on iOS and Android');
-});
diff --git a/packages/expo/src/biometric-credentials/__tests__/useBiometricCredentials.test.ts b/packages/expo/src/biometric-credentials/__tests__/useBiometricCredentials.test.ts
index dee295ff1a5..51e27bfa2bc 100644
--- a/packages/expo/src/biometric-credentials/__tests__/useBiometricCredentials.test.ts
+++ b/packages/expo/src/biometric-credentials/__tests__/useBiometricCredentials.test.ts
@@ -1,621 +1,1028 @@
+import { ClerkAPIResponseError } from '@clerk/shared/error';
import { renderHook } from '@testing-library/react';
-import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
-import {
- __internal_resetNativeClientSyncCoordinator,
- registerNativeToJsSyncHandler,
- trackPendingJsToNativeSync,
-} from '../../provider/nativeClientSyncCoordinator';
import { isBiometricCredentialError } from '../errors';
+import type { ExpoBiometricsRecord } from '../loadExpoBiometrics';
import { useBiometricCredentials as useBiometricCredentialsOnUnsupportedPlatform } from '../useBiometricCredentials';
import { useBiometricCredentials as useBiometricCredentialsOnAndroid } from '../useBiometricCredentials.android';
import { useBiometricCredentials as useBiometricCredentialsOnIos } from '../useBiometricCredentials.ios';
const mocks = vi.hoisted(() => ({
- jsSignIn: {
- id: 'sia_123',
- status: 'complete',
- createdSessionId: 'sess_123',
- prepareSecondFactor: vi.fn(),
- attemptSecondFactor: vi.fn(),
- resetPassword: vi.fn(),
- },
- jsSignedInSessions: [{ id: 'sess_123' }],
useClerk: vi.fn(),
- setActive: vi.fn(),
- synchronizeNativeClientToJs: vi.fn(),
- nativeModule: {
- getTrustedDeviceAvailability: vi.fn(),
- listTrustedDevices: vi.fn(),
- enrollTrustedDevice: vi.fn(),
- revokeTrustedDevice: vi.fn(),
- signInWithTrustedDevice: vi.fn(),
- },
+ loadExpoBiometrics: vi.fn(),
+ platform: { OS: 'ios' },
}));
-vi.mock('@clerk/react', () => ({
- useClerk: mocks.useClerk,
-}));
+vi.mock('@clerk/react', () => ({ useClerk: mocks.useClerk }));
+vi.mock('../loadExpoBiometrics', () => ({ loadExpoBiometrics: mocks.loadExpoBiometrics }));
+vi.mock('react-native', () => ({ Platform: mocks.platform }));
-vi.mock('../../utils/native-module', () => ({
- ClerkExpoModule: mocks.nativeModule,
-}));
+const APP_IDENTIFIER = 'com.example.app';
-vi.mock('react-native', () => ({
- Platform: {
- OS: 'ios',
- },
-}));
+const moduleError = (code: string, message = code) => Object.assign(new Error(message), { code });
+
+const asyncFn = (implementation: (...args: Args) => Result) =>
+ vi.fn((...args: Args) => Promise.resolve(implementation(...args)));
+
+const hashHint = (hint: string) => `sha256(${hint})`;
+
+function localRecord(overrides: Partial = {}): ExpoBiometricsRecord {
+ return {
+ id: 'td_1',
+ localKeyId: 'key_1',
+ userId: 'user_1',
+ appIdentifier: APP_IDENTIFIER,
+ policy: 'biometry_current_set',
+ createdAt: 1_700_000_000_000,
+ updatedAt: 1_700_000_000_000,
+ identifierHintSha256: null,
+ ...overrides,
+ };
+}
+
+function createExpoBiometrics() {
+ const store = {
+ records: [] as ExpoBiometricsRecord[],
+ keys: new Set(),
+ };
+ const module = {
+ store,
+ getAppIdentifier: vi.fn(() => APP_IDENTIFIER),
+ getAvailability: asyncFn(() => ({
+ biometryType: 'faceID',
+ canEvaluateBiometrics: true,
+ canEvaluateDeviceOwner: true,
+ errorCode: null,
+ secureKeyStorageAvailable: true as boolean,
+ })),
+ createKey: asyncFn(() => {
+ store.keys.add('key_new');
+ return { localKeyId: 'key_new', publicKeyJwk: '{"kty":"EC","crv":"P-256","x":"x","y":"y","alg":"ES256"}' };
+ }),
+ sign: asyncFn(() => 'signature'),
+ hasKey: asyncFn((localKeyId: string) => store.keys.has(localKeyId)),
+ deleteKey: asyncFn((localKeyId: string) => {
+ store.keys.delete(localKeyId);
+ }),
+ listRecords: asyncFn(() => store.records.map(record => ({ ...record }))),
+ saveRecord: asyncFn((record: ExpoBiometricsRecord, options: { removeOtherRecordsForApp: boolean }) => {
+ store.records = store.records.filter(
+ existing =>
+ existing.id !== record.id &&
+ !(options.removeOtherRecordsForApp && existing.appIdentifier === record.appIdentifier),
+ );
+ store.records.push(record);
+ }),
+ deleteRecord: asyncFn((localKeyId: string) => {
+ store.keys.delete(localKeyId);
+ store.records = store.records.filter(record => record.localKeyId !== localKeyId);
+ }),
+ ensureInstallationMarker: asyncFn(() => ({ wiped: false })),
+ hashIdentifierHint: vi.fn(hashHint),
+ };
+ return module;
+}
-const nativeBiometricCredential = {
- id: 'td_123',
- object: 'trusted_device' as const,
- platform: 'ios' as const,
- appIdentifier: 'com.example.app',
- name: "Sean's iPhone",
- algorithm: 'ES256' as const,
- status: 'active' as const,
- createdAt: 1_700_000_000_000,
- updatedAt: 1_700_000_100_000,
- lastUsedAt: 1_700_000_200_000,
- revokedAt: null,
-};
+function addLocalCredential(overrides: Partial = {}, { withKey = true } = {}) {
+ const record = localRecord(overrides);
+ biometrics.store.records.push(record);
+ if (withKey) {
+ biometrics.store.keys.add(record.localKeyId);
+ }
+ return record;
+}
+
+function serverCredential(overrides: Record = {}) {
+ return {
+ id: 'td_1',
+ platform: 'ios',
+ appIdentifier: APP_IDENTIFIER,
+ name: "Sean's iPhone",
+ algorithm: 'ES256',
+ status: 'active',
+ createdAt: new Date(1_700_000_000_000),
+ updatedAt: new Date(1_700_000_100_000),
+ lastUsedAt: null,
+ revokedAt: null,
+ ...overrides,
+ };
+}
+
+function apiError(code: string, paramName?: string) {
+ return new ClerkAPIResponseError(code, {
+ data: [
+ {
+ code,
+ message: `${code} message`,
+ long_message: `${code} long message`,
+ meta: paramName ? { param_name: paramName } : {},
+ },
+ ],
+ status: 422,
+ });
+}
+
+async function expectBiometricApiError(operation: Promise, cause: ClerkAPIResponseError) {
+ const error = await operation.then(
+ () => expect.unreachable('Expected the operation to reject'),
+ (rejection: unknown) => rejection,
+ );
+ const code = cause.errors[0].code;
+ expect(isBiometricCredentialError(error)).toBe(true);
+ expect(error).not.toBeInstanceOf(ClerkAPIResponseError);
+ expect(error).toMatchObject({ code, message: `${code} long message`, cause });
+}
+
+function trustedDeviceVerification(challengeOverrides: Record = {}) {
+ return {
+ strategy: 'trusted_device',
+ trustedDeviceChallenge: {
+ challenge: 'challenge',
+ challengeId: 'challenge_1',
+ trustedDeviceId: 'td_1',
+ clientData: 'reverification-client-data',
+ expiresAt: null as Date | null,
+ algorithm: 'ES256',
+ ...challengeOverrides,
+ },
+ };
+}
+
+function sessionVerification(status: string, overrides: Record = {}) {
+ return {
+ id: 'sessver_1',
+ status,
+ level: 'multi_factor',
+ firstFactorVerification: null as unknown,
+ secondFactorVerification: null as unknown,
+ ...overrides,
+ };
+}
+
+function createClerk() {
+ const user = {
+ id: 'user_1',
+ __experimental_getBiometricCredentials: asyncFn(() => [serverCredential()]),
+ __experimental_prepareBiometricCredential: asyncFn(() => ({
+ challenge: 'challenge',
+ challengeId: 'challenge_1',
+ trustedDeviceId: null,
+ clientData: 'enrollment-client-data',
+ expiresAt: null,
+ algorithm: 'ES256',
+ })),
+ __experimental_attemptBiometricCredential: asyncFn(() => serverCredential({ id: 'td_new' })),
+ __experimental_revokeBiometricCredential: asyncFn((id: string) =>
+ serverCredential({ id, status: 'revoked', revokedAt: new Date(1_700_000_300_000) }),
+ ),
+ };
+ const completedSignIn = { id: 'sia_1', status: 'complete', createdSessionId: 'sess_new' };
+ const createdSignIn = {
+ id: 'sia_1',
+ status: 'needs_first_factor',
+ createdSessionId: null,
+ firstFactorVerification: { trustedDeviceChallenge: { clientData: 'sign-in-client-data' } },
+ attemptFirstFactor: asyncFn(() => completedSignIn),
+ };
+ const clientSignIn = { create: asyncFn(() => createdSignIn) };
+ const session = {
+ id: 'sess_1',
+ status: 'active',
+ user,
+ startVerification: asyncFn(() => sessionVerification('needs_first_factor')),
+ prepareFirstFactorVerification: asyncFn(() =>
+ sessionVerification('needs_first_factor', { firstFactorVerification: trustedDeviceVerification() }),
+ ),
+ attemptFirstFactorVerification: asyncFn(() => sessionVerification('complete')),
+ prepareSecondFactorVerification: asyncFn(() =>
+ sessionVerification('needs_second_factor', { secondFactorVerification: trustedDeviceVerification() }),
+ ),
+ attemptSecondFactorVerification: asyncFn(() => sessionVerification('complete')),
+ clearCache: vi.fn(),
+ getToken: asyncFn((): string | null => 'fresh-token'),
+ };
+ return {
+ user,
+ session,
+ createdSignIn,
+ completedSignIn,
+ clientSignIn,
+ instance: {
+ __internal_environment: {
+ authConfig: { nativeSettings: { apiEnabled: true, trustedDeviceSignInEnabled: true } },
+ } as { authConfig: { nativeSettings: { apiEnabled: boolean; trustedDeviceSignInEnabled: boolean } | null } },
+ session: null as typeof session | null,
+ user: null as typeof user | null,
+ client: { signIn: clientSignIn } as { signIn: typeof clientSignIn } | undefined,
+ setActive: vi.fn(),
+ },
+ };
+}
+
+let biometrics: ReturnType;
+let clerk: ReturnType;
+
+function signInClerkUser(status = 'active') {
+ clerk.session.status = status;
+ clerk.instance.session = clerk.session;
+ clerk.instance.user = clerk.user;
+}
function renderBiometricCredentials(useHook = useBiometricCredentialsOnIos) {
return renderHook(() => useHook()).result.current;
}
-let unregisterNativeToJsSyncHandler: (() => void) | undefined;
-
beforeEach(() => {
- __internal_resetNativeClientSyncCoordinator();
- unregisterNativeToJsSyncHandler = registerNativeToJsSyncHandler(mocks.synchronizeNativeClientToJs);
- mocks.synchronizeNativeClientToJs.mockResolvedValue(undefined);
- mocks.useClerk.mockReturnValue({
- client: { signIn: mocks.jsSignIn, signedInSessions: mocks.jsSignedInSessions },
- setActive: mocks.setActive,
- });
- Object.assign(mocks.jsSignIn, {
- id: 'sia_123',
- status: 'complete',
- createdSessionId: 'sess_123',
- });
- mocks.jsSignedInSessions.splice(0, mocks.jsSignedInSessions.length, { id: 'sess_123' });
+ vi.clearAllMocks();
+ mocks.platform.OS = 'ios';
+ biometrics = createExpoBiometrics();
+ clerk = createClerk();
+ mocks.loadExpoBiometrics.mockImplementation(() => biometrics);
+ mocks.useClerk.mockImplementation(() => clerk.instance);
});
-afterEach(() => {
- vi.useRealTimers();
- unregisterNativeToJsSyncHandler?.();
-});
+describe('getAvailability', () => {
+ test.each([
+ ['environment_unavailable', null],
+ ['native_api_disabled', { apiEnabled: false, trustedDeviceSignInEnabled: true }],
+ ['feature_disabled', { apiEnabled: true, trustedDeviceSignInEnabled: false }],
+ ] as const)('reports %s from the environment before reading local records', async (reason, nativeSettings) => {
+ clerk.instance.__internal_environment.authConfig.nativeSettings = nativeSettings;
+ addLocalCredential();
+
+ await expect(renderBiometricCredentials().getAvailability()).resolves.toEqual({
+ isAvailable: false,
+ unavailableReason: reason,
+ });
+ expect(biometrics.listRecords).not.toHaveBeenCalled();
+ });
-describe('useBiometricCredentials on iOS', () => {
- beforeEach(() => {
- vi.clearAllMocks();
+ 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('reports no local credential when the device has none for this app', async () => {
+ addLocalCredential({ appIdentifier: 'com.example.other' });
+
+ await expect(renderBiometricCredentials().getAvailability()).resolves.toEqual({
+ isAvailable: false,
+ unavailableReason: 'no_local_credential',
+ });
});
- test('checks availability for an optional credential selector', async () => {
- mocks.nativeModule.getTrustedDeviceAvailability.mockResolvedValue({
+ test('is available for a signed-out user with a usable local credential', async () => {
+ addLocalCredential();
+
+ await expect(renderBiometricCredentials().getAvailability()).resolves.toEqual({
isAvailable: true,
unavailableReason: null,
});
+ expect(clerk.user.__experimental_getBiometricCredentials).not.toHaveBeenCalled();
+ });
+ test('filters by credential ID', async () => {
+ addLocalCredential();
const biometricCredentials = renderBiometricCredentials();
- const availability = await biometricCredentials.getAvailability({
- id: 'td_123',
- identifierHint: 'sean@example.com',
- });
- expect(mocks.nativeModule.getTrustedDeviceAvailability).toHaveBeenCalledWith('td_123', 'sean@example.com');
- expect(availability).toEqual({ isAvailable: true, unavailableReason: null });
+ await expect(biometricCredentials.getAvailability({ id: 'td_1' })).resolves.toMatchObject({ isAvailable: true });
+ await expect(biometricCredentials.getAvailability({ id: 'td_other' })).resolves.toEqual({
+ isAvailable: false,
+ unavailableReason: 'no_local_credential',
+ });
});
- test('waits for native client synchronization before checking availability', async () => {
- let finishNativeSync!: () => void;
- const nativeSync = new Promise(resolve => {
- finishNativeSync = resolve;
+ test('matches the identifier hint by its normalized hash', async () => {
+ addLocalCredential({ identifierHintSha256: hashHint('sean@example.com') });
+ const biometricCredentials = renderBiometricCredentials();
+
+ await expect(
+ biometricCredentials.getAvailability({ identifierHint: ' Sean@Example.com ' }),
+ ).resolves.toMatchObject({ isAvailable: true });
+ expect(biometrics.hashIdentifierHint).toHaveBeenCalledWith('sean@example.com');
+ await expect(biometricCredentials.getAvailability({ identifierHint: 'other@example.com' })).resolves.toEqual({
+ isAvailable: false,
+ unavailableReason: 'no_local_credential',
});
- trackPendingJsToNativeSync(nativeSync);
- mocks.nativeModule.getTrustedDeviceAvailability.mockResolvedValue({
+ });
+
+ test('ignores a blank identifier hint', async () => {
+ addLocalCredential({ identifierHintSha256: hashHint('sean@example.com') });
+
+ await expect(renderBiometricCredentials().getAvailability({ identifierHint: ' ' })).resolves.toMatchObject({
isAvailable: true,
- unavailableReason: null,
});
+ expect(biometrics.hashIdentifierHint).not.toHaveBeenCalled();
+ });
- const availability = renderBiometricCredentials().getAvailability();
- await Promise.resolve();
+ test('prunes local records whose key is missing', async () => {
+ addLocalCredential({ id: 'td_orphan', localKeyId: 'key_orphan' }, { withKey: false });
- expect(mocks.nativeModule.getTrustedDeviceAvailability).not.toHaveBeenCalled();
+ await expect(renderBiometricCredentials().getAvailability()).resolves.toEqual({
+ isAvailable: false,
+ unavailableReason: 'local_key_missing',
+ });
+ expect(biometrics.deleteRecord).toHaveBeenCalledWith('key_orphan');
+ expect(biometrics.store.records).toEqual([]);
+ });
+
+ test('keeps usable records while pruning the ones without a key', async () => {
+ addLocalCredential({ id: 'td_orphan', localKeyId: 'key_orphan' }, { withKey: false });
+ addLocalCredential();
- finishNativeSync();
- await expect(availability).resolves.toEqual({ isAvailable: true, unavailableReason: null });
- expect(mocks.nativeModule.getTrustedDeviceAvailability).toHaveBeenCalledTimes(1);
+ await expect(renderBiometricCredentials().getAvailability()).resolves.toMatchObject({ isAvailable: true });
+ expect(biometrics.store.records.map(record => record.id)).toEqual(['td_1']);
});
- test('rejects availability when native client synchronization times out', async () => {
- vi.useFakeTimers();
- let finishNativeSync!: () => void;
- const nativeSync = new Promise(resolve => {
- finishNativeSync = resolve;
+ test('reports biometric authentication unavailable when no record policy can be evaluated', async () => {
+ addLocalCredential();
+ biometrics.getAvailability.mockResolvedValue({
+ biometryType: 'none',
+ canEvaluateBiometrics: false,
+ canEvaluateDeviceOwner: true,
+ errorCode: null,
+ secureKeyStorageAvailable: true,
+ });
+
+ await expect(renderBiometricCredentials().getAvailability()).resolves.toEqual({
+ isAvailable: false,
+ unavailableReason: 'biometric_authentication_unavailable',
});
- trackPendingJsToNativeSync(nativeSync);
+ });
- const availability = expect(renderBiometricCredentials().getAvailability()).rejects.toMatchObject({
- code: 'environment_unavailable',
+ test('allows passcode-backed records when only device owner authentication is available', async () => {
+ addLocalCredential({ policy: 'biometry_or_device_passcode' });
+ biometrics.getAvailability.mockResolvedValue({
+ biometryType: 'none',
+ canEvaluateBiometrics: false,
+ canEvaluateDeviceOwner: true,
+ errorCode: null,
+ secureKeyStorageAvailable: true,
});
- await vi.advanceTimersByTimeAsync(5_000);
- await availability;
- expect(mocks.nativeModule.getTrustedDeviceAvailability).not.toHaveBeenCalled();
- finishNativeSync();
+ await expect(renderBiometricCredentials().getAvailability()).resolves.toMatchObject({ isAvailable: true });
});
- test('lists biometric credentials and converts native timestamps to dates', async () => {
- mocks.nativeModule.listTrustedDevices.mockResolvedValue([nativeBiometricCredential]);
+ describe('with an active session', () => {
+ beforeEach(() => {
+ signInClerkUser();
+ });
- const [biometricCredential] = await renderBiometricCredentials().list();
+ test('is available when the server credential is active', async () => {
+ addLocalCredential();
- expect(biometricCredential).toEqual({
- ...nativeBiometricCredential,
- createdAt: new Date(nativeBiometricCredential.createdAt),
- updatedAt: new Date(nativeBiometricCredential.updatedAt),
- lastUsedAt: new Date(nativeBiometricCredential.lastUsedAt),
- revokedAt: null,
+ await expect(renderBiometricCredentials().getAvailability()).resolves.toEqual({
+ isAvailable: true,
+ unavailableReason: null,
+ });
+ expect(clerk.user.__experimental_getBiometricCredentials).toHaveBeenCalledOnce();
});
- });
- test('maps omitted optional native timestamps to null', async () => {
- mocks.nativeModule.listTrustedDevices.mockResolvedValue([
- {
- ...nativeBiometricCredential,
- lastUsedAt: undefined,
- revokedAt: undefined,
- },
- ]);
+ test('only considers records enrolled by the active user', async () => {
+ addLocalCredential({ userId: 'user_other' });
- const [biometricCredential] = await renderBiometricCredentials().list();
+ await expect(renderBiometricCredentials().getAvailability()).resolves.toEqual({
+ isAvailable: false,
+ unavailableReason: 'no_local_credential',
+ });
+ expect(clerk.user.__experimental_getBiometricCredentials).not.toHaveBeenCalled();
+ });
- expect(biometricCredential.lastUsedAt).toBeNull();
- expect(biometricCredential.revokedAt).toBeNull();
- });
+ test('deletes a local record the server no longer has', async () => {
+ addLocalCredential();
+ clerk.user.__experimental_getBiometricCredentials.mockResolvedValue([]);
+
+ await expect(renderBiometricCredentials().getAvailability()).resolves.toEqual({
+ isAvailable: false,
+ unavailableReason: 'server_credential_missing',
+ });
+ expect(biometrics.deleteRecord).toHaveBeenCalledWith('key_1');
+ });
- test('waits for native client synchronization before listing biometric credentials', async () => {
- let finishNativeSync!: () => void;
- const nativeSync = new Promise(resolve => {
- finishNativeSync = resolve;
+ test('deletes a local record whose server credential is revoked', async () => {
+ addLocalCredential();
+ clerk.user.__experimental_getBiometricCredentials.mockResolvedValue([serverCredential({ status: 'revoked' })]);
+
+ await expect(renderBiometricCredentials().getAvailability()).resolves.toEqual({
+ isAvailable: false,
+ unavailableReason: 'server_credential_revoked',
+ });
+ expect(biometrics.store.records).toEqual([]);
+ });
+
+ test('falls through to an older record that is still active on the server', async () => {
+ addLocalCredential({ id: 'td_old', localKeyId: 'key_old', createdAt: 1 });
+ addLocalCredential({ id: 'td_new', localKeyId: 'key_new', createdAt: 2 });
+ clerk.user.__experimental_getBiometricCredentials.mockResolvedValue([serverCredential({ id: 'td_old' })]);
+
+ await expect(renderBiometricCredentials().getAvailability()).resolves.toMatchObject({ isAvailable: true });
+ expect(biometrics.store.records.map(record => record.id)).toEqual(['td_old']);
});
- trackPendingJsToNativeSync(nativeSync);
- mocks.nativeModule.listTrustedDevices.mockResolvedValue([nativeBiometricCredential]);
- const listing = renderBiometricCredentials().list();
- await Promise.resolve();
+ test('does not reconcile a pending session', async () => {
+ signInClerkUser('pending');
+ addLocalCredential();
- expect(mocks.nativeModule.listTrustedDevices).not.toHaveBeenCalled();
+ await expect(renderBiometricCredentials().getAvailability()).resolves.toMatchObject({ isAvailable: true });
+ expect(clerk.user.__experimental_getBiometricCredentials).not.toHaveBeenCalled();
+ });
+
+ test('surfaces server errors unchanged', async () => {
+ addLocalCredential();
+ const error = apiError('session_reverification_required');
+ clerk.user.__experimental_getBiometricCredentials.mockRejectedValue(error);
- finishNativeSync();
- await expect(listing).resolves.toHaveLength(1);
- expect(mocks.nativeModule.listTrustedDevices).toHaveBeenCalledTimes(1);
+ await expectBiometricApiError(renderBiometricCredentials().getAvailability(), error);
+ expect(biometrics.store.records).toHaveLength(1);
+ });
});
- test('returns stable operation identities', () => {
- const { result, rerender } = renderHook(() => useBiometricCredentialsOnIos());
- const initialBiometricCredentials = result.current;
+ test('maps module failures to the operation error code', async () => {
+ biometrics.listRecords.mockRejectedValue(moduleError('storage_failed', 'Keychain unavailable'));
- rerender();
+ const operation = renderBiometricCredentials().getAvailability();
+
+ await expect(operation).rejects.toMatchObject({
+ code: 'E_TRUSTED_DEVICE_AVAILABILITY_FAILED',
+ message: 'Keychain unavailable',
+ });
+ });
+});
+
+describe('list', () => {
+ test('lists the signed-in user credentials', async () => {
+ signInClerkUser();
+ clerk.user.__experimental_getBiometricCredentials.mockResolvedValue([
+ serverCredential({ lastUsedAt: new Date(1_700_000_200_000) }),
+ ]);
- expect(result.current).toBe(initialBiometricCredentials);
+ await expect(renderBiometricCredentials().list()).resolves.toEqual([
+ {
+ id: 'td_1',
+ object: 'trusted_device',
+ platform: 'ios',
+ appIdentifier: APP_IDENTIFIER,
+ name: "Sean's iPhone",
+ algorithm: 'ES256',
+ status: 'active',
+ createdAt: new Date(1_700_000_000_000),
+ updatedAt: new Date(1_700_000_100_000),
+ lastUsedAt: new Date(1_700_000_200_000),
+ revokedAt: null,
+ },
+ ]);
});
- test('enrolls with the safe default authentication policy', async () => {
- mocks.nativeModule.enrollTrustedDevice.mockResolvedValue(nativeBiometricCredential);
+ test('normalizes unknown resource values', async () => {
+ signInClerkUser();
+ clerk.user.__experimental_getBiometricCredentials.mockResolvedValue([
+ serverCredential({ platform: 'visionos', algorithm: 'ES384', status: 'pending_review', lastUsedAt: undefined }),
+ ]);
+
+ const [credential] = await renderBiometricCredentials().list();
- const biometricCredential = await renderBiometricCredentials().enroll({
+ expect(credential).toMatchObject({ platform: 'unknown', algorithm: 'ES384', status: 'unknown', lastUsedAt: null });
+ });
+
+ test('requires a signed-in user', async () => {
+ await expect(renderBiometricCredentials().list()).rejects.toMatchObject({ code: 'E_TRUSTED_DEVICE_LIST_FAILED' });
+ });
+});
+
+describe('enroll', () => {
+ beforeEach(() => {
+ signInClerkUser();
+ });
+
+ test('rejects an unknown policy without creating a key', async () => {
+ await expect(renderBiometricCredentials().enroll({ policy: 'bogus' as never })).rejects.toMatchObject({
+ code: 'invalid_trusted_device_policy',
+ });
+ expect(biometrics.createKey).not.toHaveBeenCalled();
+ expect(clerk.user.__experimental_prepareBiometricCredential).not.toHaveBeenCalled();
+ });
+
+ test('creates a key, completes the server enrollment and saves the local record', async () => {
+ const credential = await renderBiometricCredentials().enroll({
name: "Sean's iPhone",
- identifierHint: 'sean@example.com',
+ identifierHint: ' Sean@Example.com ',
reason: 'Use Face ID to trust this device.',
});
- expect(mocks.nativeModule.enrollTrustedDevice).toHaveBeenCalledWith(
- "Sean's iPhone",
- 'sean@example.com',
+ const publicKeyJwk = '{"kty":"EC","crv":"P-256","x":"x","y":"y","alg":"ES256"}';
+ expect(biometrics.createKey).toHaveBeenCalledWith('biometry_current_set');
+ expect(clerk.user.__experimental_prepareBiometricCredential).toHaveBeenCalledWith({
+ platform: 'ios',
+ appIdentifier: APP_IDENTIFIER,
+ name: "Sean's iPhone",
+ algorithm: 'ES256',
+ publicKeyJwk,
+ });
+ expect(biometrics.sign).toHaveBeenCalledWith(
+ 'key_new',
+ 'enrollment-client-data',
'Use Face ID to trust this device.',
- 'biometry_current_set',
);
- expect(biometricCredential.createdAt).toEqual(new Date(nativeBiometricCredential.createdAt));
+ expect(clerk.user.__experimental_attemptBiometricCredential).toHaveBeenCalledWith({
+ platform: 'ios',
+ appIdentifier: APP_IDENTIFIER,
+ name: "Sean's iPhone",
+ algorithm: 'ES256',
+ publicKeyJwk,
+ clientData: 'enrollment-client-data',
+ signature: 'signature',
+ });
+ expect(biometrics.saveRecord).toHaveBeenCalledWith(
+ {
+ id: 'td_new',
+ localKeyId: 'key_new',
+ userId: 'user_1',
+ appIdentifier: APP_IDENTIFIER,
+ identifierHint: 'sean@example.com',
+ policy: 'biometry_current_set',
+ createdAt: 1_700_000_000_000,
+ updatedAt: 1_700_000_100_000,
+ },
+ { removeOtherRecordsForApp: true },
+ );
+ expect(credential).toMatchObject({ id: 'td_new', object: 'trusted_device', status: 'active' });
});
- test('waits for native client synchronization before enrollment', async () => {
- let finishNativeSync!: () => void;
- const nativeSync = new Promise(resolve => {
- finishNativeSync = resolve;
- });
- trackPendingJsToNativeSync(nativeSync);
- mocks.nativeModule.enrollTrustedDevice.mockResolvedValue(nativeBiometricCredential);
+ test('replaces the other local records for the app', async () => {
+ addLocalCredential({ id: 'td_old', localKeyId: 'key_old', userId: 'user_other' });
- const enrollment = renderBiometricCredentials().enroll();
- await Promise.resolve();
+ await renderBiometricCredentials().enroll();
- expect(mocks.nativeModule.enrollTrustedDevice).not.toHaveBeenCalled();
+ expect(biometrics.store.records.map(record => record.id)).toEqual(['td_new']);
+ });
+
+ test('uses the requested policy, platform and default prompt', async () => {
+ mocks.platform.OS = 'android';
- finishNativeSync();
- await expect(enrollment).resolves.toMatchObject({ id: 'td_123' });
- expect(mocks.nativeModule.enrollTrustedDevice).toHaveBeenCalledTimes(1);
+ await renderBiometricCredentials(useBiometricCredentialsOnAndroid).enroll({
+ policy: 'biometry_or_device_passcode',
+ });
+
+ expect(biometrics.createKey).toHaveBeenCalledWith('biometry_or_device_passcode');
+ expect(clerk.user.__experimental_prepareBiometricCredential).toHaveBeenCalledWith(
+ expect.not.objectContaining({ name: expect.anything() }),
+ );
+ expect(clerk.user.__experimental_prepareBiometricCredential).toHaveBeenCalledWith(
+ expect.objectContaining({ platform: 'android' }),
+ );
+ expect(biometrics.sign).toHaveBeenCalledWith(
+ 'key_new',
+ 'enrollment-client-data',
+ 'Use biometrics to enroll this device.',
+ );
+ expect(biometrics.saveRecord).toHaveBeenCalledWith(
+ expect.not.objectContaining({ identifierHint: expect.anything() }),
+ { removeOtherRecordsForApp: true },
+ );
});
- test('revokes a biometric credential by ID', async () => {
- mocks.nativeModule.revokeTrustedDevice.mockResolvedValue({
- ...nativeBiometricCredential,
- status: 'revoked',
- revokedAt: 1_700_000_300_000,
+ test('requires an active or pending session', async () => {
+ clerk.instance.session = null;
+
+ await expect(renderBiometricCredentials().enroll()).rejects.toMatchObject({
+ code: 'E_TRUSTED_DEVICE_ENROLLMENT_FAILED',
});
+ expect(biometrics.createKey).not.toHaveBeenCalled();
+ });
- const biometricCredential = await renderBiometricCredentials().revoke('td_123');
+ test('enrolls with a pending session', async () => {
+ signInClerkUser('pending');
- expect(mocks.nativeModule.revokeTrustedDevice).toHaveBeenCalledWith('td_123');
- expect(biometricCredential.status).toBe('revoked');
- expect(biometricCredential.revokedAt).toEqual(new Date(1_700_000_300_000));
+ await expect(renderBiometricCredentials().enroll()).resolves.toMatchObject({ id: 'td_new' });
});
- test('waits for native client synchronization before revoking a biometric credential', async () => {
- let finishNativeSync!: () => void;
- const nativeSync = new Promise(resolve => {
- finishNativeSync = resolve;
+ test('requires the feature to be enabled', async () => {
+ clerk.instance.__internal_environment.authConfig.nativeSettings = {
+ apiEnabled: true,
+ trustedDeviceSignInEnabled: false,
+ };
+
+ await expect(renderBiometricCredentials().enroll()).rejects.toMatchObject({
+ code: 'E_TRUSTED_DEVICE_ENROLLMENT_FAILED',
});
- trackPendingJsToNativeSync(nativeSync);
- mocks.nativeModule.revokeTrustedDevice.mockResolvedValue({
- ...nativeBiometricCredential,
- status: 'revoked',
+ expect(biometrics.createKey).not.toHaveBeenCalled();
+ });
+
+ test('maps key creation failures without calling the server', async () => {
+ biometrics.createKey.mockRejectedValue(moduleError('biometry_not_enrolled'));
+
+ await expect(renderBiometricCredentials().enroll()).rejects.toMatchObject({
+ code: 'biometric_authentication_unavailable',
});
+ expect(clerk.user.__experimental_prepareBiometricCredential).not.toHaveBeenCalled();
+ });
- const revocation = renderBiometricCredentials().revoke('td_123');
- await Promise.resolve();
+ test('fails fast when the device has no secure key storage', async () => {
+ biometrics.createKey.mockRejectedValue(moduleError('secure_key_storage_unavailable', 'No Secure Enclave'));
- expect(mocks.nativeModule.revokeTrustedDevice).not.toHaveBeenCalled();
+ 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();
+ });
- finishNativeSync();
- await expect(revocation).resolves.toMatchObject({ id: 'td_123', status: 'revoked' });
- expect(mocks.nativeModule.revokeTrustedDevice).toHaveBeenCalledWith('td_123');
+ test('surfaces reverification errors from prepare unchanged and deletes the key', async () => {
+ const error = apiError('session_reverification_required');
+ clerk.user.__experimental_prepareBiometricCredential.mockRejectedValue(error);
+
+ await expectBiometricApiError(renderBiometricCredentials().enroll(), error);
+ expect(biometrics.deleteKey).toHaveBeenCalledWith('key_new');
+ expect(biometrics.sign).not.toHaveBeenCalled();
+ expect(biometrics.saveRecord).not.toHaveBeenCalled();
});
- test('signs in through the native one-shot biometric-credential flow', async () => {
- mocks.nativeModule.signInWithTrustedDevice.mockResolvedValue({
- id: 'sia_123',
- status: 'complete',
- createdSessionId: 'sess_123',
- });
+ test('deletes the key when signing is canceled', async () => {
+ biometrics.sign.mockRejectedValue(moduleError('user_canceled'));
- const result = await renderBiometricCredentials().signIn({
- identifierHint: 'sean@example.com',
- reason: 'Use Face ID to sign in.',
+ await expect(renderBiometricCredentials().enroll()).rejects.toMatchObject({
+ code: 'biometric_authentication_canceled',
});
+ expect(biometrics.deleteKey).toHaveBeenCalledWith('key_new');
+ expect(clerk.user.__experimental_attemptBiometricCredential).not.toHaveBeenCalled();
+ });
- expect(mocks.nativeModule.signInWithTrustedDevice).toHaveBeenCalledWith(
- null,
- 'sean@example.com',
- 'Use Face ID to sign in.',
- );
- expect(result).toMatchObject({
- status: 'complete',
- createdSessionId: 'sess_123',
- signIn: mocks.jsSignIn,
- });
- expect(result.setActive).toBe(mocks.setActive);
+ test('deletes the key when the server rejects the attempt', async () => {
+ const error = apiError('form_param_invalid', 'signature');
+ clerk.user.__experimental_attemptBiometricCredential.mockRejectedValue(error);
+
+ await expectBiometricApiError(renderBiometricCredentials().enroll(), error);
+ expect(biometrics.deleteKey).toHaveBeenCalledWith('key_new');
+ expect(biometrics.saveRecord).not.toHaveBeenCalled();
+ expect(clerk.user.__experimental_revokeBiometricCredential).not.toHaveBeenCalled();
});
- test('keeps a completed native result authoritative when the current JS sign-in changes', async () => {
- mocks.nativeModule.signInWithTrustedDevice.mockResolvedValue({
- id: 'sia_native',
- status: 'complete',
- createdSessionId: 'sess_123',
- });
- Object.assign(mocks.jsSignIn, {
- id: 'sia_other',
- status: 'needs_second_factor',
- createdSessionId: 'sess_other',
+ test('revokes the server credential and deletes the key when the record cannot be saved', async () => {
+ biometrics.saveRecord.mockRejectedValue(moduleError('storage_failed', 'Keychain write failed'));
+
+ await expect(renderBiometricCredentials().enroll()).rejects.toMatchObject({
+ code: 'E_TRUSTED_DEVICE_ENROLLMENT_FAILED',
+ message: 'Keychain write failed',
});
+ expect(clerk.user.__experimental_revokeBiometricCredential).toHaveBeenCalledWith('td_new');
+ expect(biometrics.deleteKey).toHaveBeenCalledWith('key_new');
+ });
- const result = await renderBiometricCredentials().signIn();
+ test('keeps the save error when cleanup also fails', async () => {
+ biometrics.saveRecord.mockRejectedValue(moduleError('storage_failed'));
+ clerk.user.__experimental_revokeBiometricCredential.mockRejectedValue(new Error('offline'));
+ biometrics.deleteKey.mockRejectedValue(moduleError('unknown'));
- expect(result).toMatchObject({
- status: 'complete',
- createdSessionId: 'sess_123',
- signIn: mocks.jsSignIn,
+ await expect(renderBiometricCredentials().enroll()).rejects.toMatchObject({
+ code: 'E_TRUSTED_DEVICE_ENROLLMENT_FAILED',
});
});
+});
- test('accepts a completed sign-in when the synchronized client only contains its session', async () => {
- mocks.nativeModule.signInWithTrustedDevice.mockResolvedValue({
- id: 'sia_123',
- status: 'complete',
- createdSessionId: 'sess_123',
- });
- Object.assign(mocks.jsSignIn, {
- id: '',
- status: null,
- createdSessionId: null,
- });
+describe('revoke', () => {
+ beforeEach(() => {
+ signInClerkUser();
+ });
- const result = await renderBiometricCredentials().signIn();
+ test('revokes on the server, then deletes the matching local credential', async () => {
+ addLocalCredential();
+ addLocalCredential({ id: 'td_other', localKeyId: 'key_other' });
- expect(result).toMatchObject({
- status: 'complete',
- createdSessionId: 'sess_123',
- signIn: mocks.jsSignIn,
- });
+ const credential = await renderBiometricCredentials().revoke('td_1');
+
+ expect(clerk.user.__experimental_revokeBiometricCredential).toHaveBeenCalledWith('td_1');
+ expect(biometrics.deleteRecord).toHaveBeenCalledWith('key_1');
+ expect(biometrics.store.records.map(record => record.id)).toEqual(['td_other']);
+ expect(credential).toMatchObject({ id: 'td_1', status: 'revoked', revokedAt: new Date(1_700_000_300_000) });
});
- test('rejects a completed sign-in when its session is absent after synchronization', async () => {
- mocks.nativeModule.signInWithTrustedDevice.mockResolvedValue({
- id: 'sia_123',
- status: 'complete',
- createdSessionId: 'sess_missing',
- });
+ test('keeps local state when the server revocation fails', async () => {
+ addLocalCredential();
+ const error = apiError('session_reverification_required');
+ clerk.user.__experimental_revokeBiometricCredential.mockRejectedValue(error);
- await expect(renderBiometricCredentials().signIn()).rejects.toThrow(
- 'Unable to synchronize biometric sign-in with the Clerk JS client: the created session is missing.',
- );
+ await expectBiometricApiError(renderBiometricCredentials().revoke('td_1'), error);
+ expect(biometrics.deleteRecord).not.toHaveBeenCalled();
});
- test('waits for native client synchronization before biometric sign-in', async () => {
- let finishNativeSync!: () => void;
- const nativeSync = new Promise(resolve => {
- finishNativeSync = resolve;
+ test('returns the revoked credential when local cleanup fails', async () => {
+ addLocalCredential();
+ biometrics.deleteRecord.mockRejectedValue(moduleError('storage_failed'));
+
+ await expect(renderBiometricCredentials().revoke('td_1')).resolves.toMatchObject({ status: 'revoked' });
+ });
+});
+
+describe('signIn', () => {
+ test('signs the trusted device challenge and returns the completed sign-in', async () => {
+ addLocalCredential();
+
+ const result = await renderBiometricCredentials().signIn({ reason: 'Use Face ID to sign in.' });
+
+ expect(clerk.clientSignIn.create).toHaveBeenCalledWith({ strategy: 'trusted_device', trustedDeviceId: 'td_1' });
+ expect(biometrics.sign).toHaveBeenCalledWith('key_1', 'sign-in-client-data', 'Use Face ID to sign in.');
+ expect(clerk.createdSignIn.attemptFirstFactor).toHaveBeenCalledWith({
+ strategy: 'trusted_device',
+ trustedDeviceId: 'td_1',
+ clientData: 'sign-in-client-data',
+ signature: 'signature',
+ algorithm: 'ES256',
});
- trackPendingJsToNativeSync(nativeSync);
- mocks.nativeModule.signInWithTrustedDevice.mockResolvedValue({
- id: 'sia_123',
+ expect(result).toEqual({
status: 'complete',
- createdSessionId: 'sess_123',
+ createdSessionId: 'sess_new',
+ signIn: clerk.completedSignIn,
+ setActive: clerk.instance.setActive,
});
+ expect(clerk.instance.setActive).not.toHaveBeenCalled();
+ });
- const signIn = renderBiometricCredentials().signIn();
- await Promise.resolve();
+ test('uses the default prompt and the newest matching credential', async () => {
+ addLocalCredential({ id: 'td_old', localKeyId: 'key_old', createdAt: 1 });
+ addLocalCredential({ id: 'td_new', localKeyId: 'key_new', createdAt: 2 });
- expect(mocks.nativeModule.signInWithTrustedDevice).not.toHaveBeenCalled();
+ await renderBiometricCredentials().signIn();
- finishNativeSync();
- await expect(signIn).resolves.toMatchObject({ status: 'complete', createdSessionId: 'sess_123' });
- expect(mocks.nativeModule.signInWithTrustedDevice).toHaveBeenCalledTimes(1);
+ expect(clerk.clientSignIn.create).toHaveBeenCalledWith({ strategy: 'trusted_device', trustedDeviceId: 'td_new' });
+ expect(biometrics.sign).toHaveBeenCalledWith('key_new', 'sign-in-client-data', 'Use biometrics to sign in.');
});
- test.each([
- ['needs_second_factor', 'prepareSecondFactor'],
- ['needs_client_trust', 'attemptSecondFactor'],
- ['needs_new_password', 'resetPassword'],
- ] as const)('returns a continuable JS sign-in for %s', async (status, continuationMethod) => {
- mocks.nativeModule.signInWithTrustedDevice.mockResolvedValue({
- id: 'sia_mfa',
- status,
- createdSessionId: null,
- });
- mocks.synchronizeNativeClientToJs.mockImplementation(() => {
- Object.assign(mocks.jsSignIn, {
- id: 'sia_mfa',
- status,
- createdSessionId: null,
- });
- return Promise.resolve();
+ test('selects the credential matching the identifier hint', async () => {
+ addLocalCredential({ id: 'td_sean', localKeyId: 'key_sean', identifierHintSha256: hashHint('sean@example.com') });
+ addLocalCredential({
+ id: 'td_ana',
+ localKeyId: 'key_ana',
+ createdAt: 2,
+ identifierHintSha256: hashHint('ana@x.co'),
});
- const result = await renderBiometricCredentials().signIn();
+ await renderBiometricCredentials().signIn({ identifierHint: 'Sean@example.com' });
- expect(result).toMatchObject({
- status,
- createdSessionId: null,
- signIn: mocks.jsSignIn,
- });
- expect(result.signIn[continuationMethod]).toBe(mocks.jsSignIn[continuationMethod]);
+ expect(clerk.clientSignIn.create).toHaveBeenCalledWith({ strategy: 'trusted_device', trustedDeviceId: 'td_sean' });
});
- test('does not resolve a completed sign-in before native-to-JS synchronization', async () => {
- let finishSync!: () => void;
- mocks.nativeModule.signInWithTrustedDevice.mockResolvedValue({
- id: 'sia_123',
- status: 'complete',
- createdSessionId: 'sess_123',
- });
- mocks.synchronizeNativeClientToJs.mockReturnValue(
- new Promise(resolve => {
- finishSync = resolve;
- }),
- );
+ test.each(['needs_second_factor', 'needs_client_trust', 'needs_new_password'])(
+ 'returns a continuable sign-in for %s',
+ async status => {
+ addLocalCredential();
+ const continuable = { id: 'sia_1', status, createdSessionId: null, prepareSecondFactor: vi.fn() };
+ clerk.createdSignIn.attemptFirstFactor.mockResolvedValue(continuable as never);
- let didResolve = false;
- const signIn = renderBiometricCredentials()
- .signIn()
- .then(result => {
- didResolve = true;
- return result;
+ await expect(renderBiometricCredentials().signIn()).resolves.toMatchObject({
+ status,
+ createdSessionId: null,
+ signIn: continuable,
});
- await vi.waitFor(() => expect(mocks.synchronizeNativeClientToJs).toHaveBeenCalled());
- expect(didResolve).toBe(false);
+ },
+ );
+
+ test('rejects without contacting the server when no local credential is available', async () => {
+ const operation = renderBiometricCredentials().signIn();
- finishSync();
- await expect(signIn).resolves.toMatchObject({ createdSessionId: 'sess_123' });
+ await expect(operation).rejects.toMatchObject({ code: 'E_TRUSTED_DEVICE_SIGN_IN_FAILED' });
+ await expect(operation).rejects.toThrow('no_local_credential');
+ expect(clerk.clientSignIn.create).not.toHaveBeenCalled();
});
- test('rejects when native-to-JS synchronization returns a different sign-in attempt', async () => {
- mocks.nativeModule.signInWithTrustedDevice.mockResolvedValue({
- id: 'sia_native',
- status: 'needs_second_factor',
- createdSessionId: null,
- });
- Object.assign(mocks.jsSignIn, {
- id: 'sia_js',
- status: 'needs_second_factor',
- createdSessionId: null,
+ 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,
});
- await expect(renderBiometricCredentials().signIn()).rejects.toThrow(
- 'Unable to synchronize biometric sign-in with the Clerk JS client: the sign-in attempt does not match.',
- );
+ const operation = renderBiometricCredentials().signIn();
+
+ await expect(operation).rejects.toThrow('biometric_authentication_unavailable');
+ expect(clerk.clientSignIn.create).not.toHaveBeenCalled();
+ expect(biometrics.sign).not.toHaveBeenCalled();
});
- test('uses the Clerk instance from the React provider after synchronization', async () => {
- const providerSetActive = vi.fn();
- const providerSignIn = {
- ...mocks.jsSignIn,
- id: 'sia_provider',
- };
- mocks.nativeModule.signInWithTrustedDevice.mockResolvedValue({
- id: 'sia_provider',
- status: 'complete',
- createdSessionId: 'sess_provider',
- });
- mocks.useClerk.mockReturnValue({
- client: {
- signIn: providerSignIn,
- signedInSessions: [{ id: 'sess_provider' }],
- },
- setActive: providerSetActive,
- });
+ test('rejects when the Clerk client is unavailable', async () => {
+ addLocalCredential();
+ clerk.instance.client = undefined;
+
+ await expect(renderBiometricCredentials().signIn()).rejects.toThrow('client sign-in resource is unavailable');
+ });
- const result = await renderBiometricCredentials().signIn();
+ test('rejects when the server does not return a challenge', async () => {
+ addLocalCredential();
+ clerk.createdSignIn.firstFactorVerification.trustedDeviceChallenge = undefined as never;
- expect(result.signIn).toBe(providerSignIn);
- expect(result.setActive).toBe(providerSetActive);
+ await expect(renderBiometricCredentials().signIn()).rejects.toThrow(
+ 'Biometric sign-in did not return a matching challenge.',
+ );
+ expect(biometrics.sign).not.toHaveBeenCalled();
});
- test('rejects when the Clerk JS client is unavailable after synchronization', async () => {
- mocks.nativeModule.signInWithTrustedDevice.mockResolvedValue({
- id: 'sia_native',
- status: 'complete',
- createdSessionId: 'sess_native',
- });
- mocks.useClerk.mockReturnValue({
- client: undefined,
- setActive: mocks.setActive,
- });
+ test('rejects a challenge issued for another credential without prompting', async () => {
+ addLocalCredential();
+ clerk.createdSignIn.firstFactorVerification.trustedDeviceChallenge = {
+ clientData: 'sign-in-client-data',
+ trustedDeviceId: 'td_other',
+ } as never;
await expect(renderBiometricCredentials().signIn()).rejects.toThrow(
- 'Unable to synchronize biometric sign-in with the Clerk JS client: the client sign-in resource is unavailable.',
+ 'Biometric sign-in did not return a matching challenge.',
);
+ expect(biometrics.sign).not.toHaveBeenCalled();
});
- test('normalizes unknown resource values and preserves the synchronized JS sign-in status', async () => {
- mocks.nativeModule.listTrustedDevices.mockResolvedValue([
- {
- ...nativeBiometricCredential,
- platform: 'visionos',
- algorithm: 'ES384',
- status: 'pending_review',
- },
- ]);
- mocks.nativeModule.signInWithTrustedDevice.mockResolvedValue({
- id: 'sia_future',
- status: 'future_sign_in_status',
- createdSessionId: null,
- });
- Object.assign(mocks.jsSignIn, {
- id: 'sia_future',
- status: 'future_sign_in_status',
- createdSessionId: null,
- });
+ test('rejects an expired challenge without prompting', async () => {
+ addLocalCredential();
+ clerk.createdSignIn.firstFactorVerification.trustedDeviceChallenge = {
+ clientData: 'sign-in-client-data',
+ expiresAt: new Date(Date.now() - 1_000),
+ } as never;
- const biometricCredentials = renderBiometricCredentials();
- const [device] = await biometricCredentials.list();
- const signIn = await biometricCredentials.signIn();
+ await expect(renderBiometricCredentials().signIn()).rejects.toThrow('Biometric sign-in challenge has expired.');
+ expect(biometrics.sign).not.toHaveBeenCalled();
+ });
- expect(device).toMatchObject({
- platform: 'unknown',
- algorithm: 'ES384',
- status: 'unknown',
- });
- expect(signIn.status).toBe('future_sign_in_status');
+ test.each(['form_resource_not_found', 'trusted_device_not_registered'])(
+ 'forgets the local credential when sign-in creation fails with %s',
+ async code => {
+ addLocalCredential();
+ const error = apiError(code, 'trusted_device_id');
+ clerk.clientSignIn.create.mockRejectedValue(error);
+
+ await expectBiometricApiError(renderBiometricCredentials().signIn(), error);
+ expect(biometrics.deleteRecord).toHaveBeenCalledWith('key_1');
+ expect(biometrics.store.records).toEqual([]);
+ },
+ );
+
+ test('forgets the local credential when the attempt reports it missing', async () => {
+ addLocalCredential();
+ const error = apiError('trusted_device_not_registered', 'trusted_device_id');
+ clerk.createdSignIn.attemptFirstFactor.mockRejectedValue(error);
+
+ await expectBiometricApiError(renderBiometricCredentials().signIn(), error);
+ expect(biometrics.store.records).toEqual([]);
});
- test('preserves structured native errors', async () => {
- const nativeError = Object.assign(new Error('Biometric authentication was canceled.'), {
- code: 'biometric_authentication_canceled',
- });
- mocks.nativeModule.signInWithTrustedDevice.mockRejectedValue(nativeError);
+ test('keeps the local credential for unrelated server errors', async () => {
+ addLocalCredential();
+ const error = apiError('form_resource_not_found', 'sign_in_id');
+ clerk.createdSignIn.attemptFirstFactor.mockRejectedValue(error);
+
+ await expectBiometricApiError(renderBiometricCredentials().signIn(), error);
+ expect(biometrics.deleteRecord).not.toHaveBeenCalled();
+ });
+
+ test.each(['key_invalidated', 'key_not_found'])(
+ 'forgets the local credential when signing fails with %s',
+ async code => {
+ addLocalCredential();
+ biometrics.sign.mockRejectedValue(moduleError(code));
+
+ const operation = renderBiometricCredentials().signIn();
+
+ await expect(operation).rejects.toMatchObject({ code });
+ expect(biometrics.deleteRecord).toHaveBeenCalledWith('key_1');
+ expect(clerk.createdSignIn.attemptFirstFactor).not.toHaveBeenCalled();
+ },
+ );
+
+ test('keeps the local credential when the prompt is canceled', async () => {
+ addLocalCredential();
+ biometrics.sign.mockRejectedValue(moduleError('user_canceled', 'Canceled'));
const operation = renderBiometricCredentials().signIn();
- await expect(operation).rejects.toBe(nativeError);
+ await expect(operation).rejects.toMatchObject({ code: 'biometric_authentication_canceled', message: 'Canceled' });
await operation.catch(error => {
expect(isBiometricCredentialError(error)).toBe(true);
- if (isBiometricCredentialError(error)) {
- expect(error.code).toBe('biometric_authentication_canceled');
- }
});
+ expect(biometrics.deleteRecord).not.toHaveBeenCalled();
});
- test('explains that the development client must contain the native methods', async () => {
- const signInWithTrustedDevice = mocks.nativeModule.signInWithTrustedDevice;
- Object.assign(mocks.nativeModule, { signInWithTrustedDevice: undefined });
+ test('reconciles with the server when a user is already signed in', async () => {
+ signInClerkUser();
+ addLocalCredential();
+ clerk.user.__experimental_getBiometricCredentials.mockResolvedValue([]);
- try {
- await expect(renderBiometricCredentials().signIn()).rejects.toThrow(
- 'Biometric credentials require a development build containing a compatible version of @clerk/expo.',
- );
- } finally {
- Object.assign(mocks.nativeModule, { signInWithTrustedDevice });
- }
+ await expect(renderBiometricCredentials().signIn()).rejects.toThrow('server_credential_missing');
+ expect(biometrics.store.records).toEqual([]);
+ expect(clerk.clientSignIn.create).not.toHaveBeenCalled();
});
});
-describe('useBiometricCredentials on Android', () => {
- beforeEach(() => {
- vi.clearAllMocks();
+describe('API errors', () => {
+ test('surface a reverification-required error with its API code', async () => {
+ signInClerkUser();
+ clerk.user.__experimental_prepareBiometricCredential.mockRejectedValue(apiError('session_reverification_required'));
+
+ const operation = renderBiometricCredentials().enroll();
+
+ await expect(operation).rejects.toMatchObject({ code: 'session_reverification_required' });
+ await operation.catch(error => expect(isBiometricCredentialError(error)).toBe(true));
});
- test('uses the native biometric-credential bridge', async () => {
- mocks.nativeModule.getTrustedDeviceAvailability.mockResolvedValue({
- isAvailable: true,
- unavailableReason: null,
+ test('surface a trusted_device_not_registered error with its API code', async () => {
+ addLocalCredential();
+ clerk.clientSignIn.create.mockRejectedValue(apiError('trusted_device_not_registered', 'trusted_device_id'));
+
+ const operation = renderBiometricCredentials().signIn();
+
+ await expect(operation).rejects.toMatchObject({
+ code: 'trusted_device_not_registered',
+ message: 'trusted_device_not_registered long message',
});
- mocks.nativeModule.signInWithTrustedDevice.mockResolvedValue({
- id: 'sia_android',
- status: 'complete',
- createdSessionId: 'sess_android',
+ await operation.catch(error => expect(isBiometricCredentialError(error)).toBe(true));
+ });
+
+ test('fall back to the short message and the operation code', async () => {
+ signInClerkUser();
+ const withoutLongMessage = new ClerkAPIResponseError('native_api_disabled', {
+ data: [{ code: 'native_api_disabled', message: 'Native API is disabled', long_message: undefined as never }],
+ status: 403,
});
- Object.assign(mocks.jsSignIn, {
- id: 'sia_android',
- status: 'complete',
- createdSessionId: 'sess_android',
+ clerk.user.__experimental_getBiometricCredentials.mockRejectedValueOnce(withoutLongMessage);
+ clerk.user.__experimental_getBiometricCredentials.mockRejectedValueOnce(new Error('Network down'));
+ const biometricCredentials = renderBiometricCredentials();
+
+ await expect(biometricCredentials.list()).rejects.toMatchObject({
+ code: 'native_api_disabled',
+ message: 'Native API is disabled',
});
- mocks.jsSignedInSessions.splice(0, mocks.jsSignedInSessions.length, { id: 'sess_android' });
+ await expect(biometricCredentials.list()).rejects.toMatchObject({
+ code: 'E_TRUSTED_DEVICE_LIST_FAILED',
+ message: 'Network down',
+ });
+ });
+});
- const biometricCredentials = renderBiometricCredentials(useBiometricCredentialsOnAndroid);
+describe('missing @clerk/expo-biometrics', () => {
+ test.each(['getAvailability', 'list', 'enroll', 'revoke', 'signIn'] as const)(
+ '%s explains how to install the package',
+ async method => {
+ mocks.loadExpoBiometrics.mockReturnValue(null);
+ const biometricCredentials = renderBiometricCredentials();
- await expect(biometricCredentials.getAvailability({ identifierHint: 'sean@example.com' })).resolves.toEqual({
- isAvailable: true,
- unavailableReason: null,
+ await expect((biometricCredentials[method] as (arg?: string) => Promise)('td_1')).rejects.toThrow(
+ 'Biometric credentials require the @clerk/expo-biometrics package. Install it with `npx expo install @clerk/expo-biometrics`',
+ );
+ },
+ );
+
+ test('explains that the development build must include the native module', async () => {
+ biometrics.getAppIdentifier.mockImplementation(() => {
+ throw moduleError('native_module_unavailable');
});
- await expect(biometricCredentials.signIn({ reason: 'Confirm your identity to sign in.' })).resolves.toMatchObject({
- status: 'complete',
- createdSessionId: 'sess_android',
- signIn: mocks.jsSignIn,
- });
- expect(mocks.nativeModule.getTrustedDeviceAvailability).toHaveBeenCalledWith(null, 'sean@example.com');
- expect(mocks.nativeModule.signInWithTrustedDevice).toHaveBeenCalledWith(
- null,
- null,
- 'Confirm your identity to sign in.',
+
+ await expect(renderBiometricCredentials().signIn()).rejects.toThrow(
+ 'Biometric credentials require a development build that includes @clerk/expo-biometrics',
);
});
});
-describe('useBiometricCredentials on unsupported platforms', () => {
- test('returns stable operation identities', () => {
- const { result, rerender } = renderHook(() => useBiometricCredentialsOnUnsupportedPlatform());
- const biometricCredentials = result.current;
+describe('useBiometricCredentials', () => {
+ test.each([
+ ['iOS', useBiometricCredentialsOnIos],
+ ['Android', useBiometricCredentialsOnAndroid],
+ ['an unsupported platform', useBiometricCredentialsOnUnsupportedPlatform],
+ ])('returns stable operation identities on %s', (_, useHook) => {
+ const { result, rerender } = renderHook(() => useHook());
+ const initial = result.current;
rerender();
- expect(result.current).toBe(biometricCredentials);
+ expect(result.current).toBe(initial);
});
- test('reports unsupported availability without invoking native code', async () => {
+ test('reports unsupported availability on unsupported platforms without loading the module', async () => {
const biometricCredentials = renderBiometricCredentials(useBiometricCredentialsOnUnsupportedPlatform);
- const availability = await biometricCredentials.getAvailability();
- expect(availability).toEqual({
+ await expect(biometricCredentials.getAvailability()).resolves.toEqual({
isAvailable: false,
unavailableReason: 'unsupported_platform',
});
+ expect(mocks.loadExpoBiometrics).not.toHaveBeenCalled();
});
- test('rejects operations that require the native implementation', async () => {
+ test('rejects operations on unsupported platforms', async () => {
const biometricCredentials = renderBiometricCredentials(useBiometricCredentialsOnUnsupportedPlatform);
await expect(biometricCredentials.enroll()).rejects.toThrow(
@@ -623,3 +1030,186 @@ describe('useBiometricCredentials on unsupported platforms', () => {
);
});
});
+
+describe('reverify', () => {
+ beforeEach(() => {
+ signInClerkUser();
+ });
+
+ test('verifies the first factor with the biometric credential and refreshes the session token', async () => {
+ addLocalCredential();
+
+ const result = await renderBiometricCredentials().reverify({ reason: 'Confirm with Face ID.' });
+
+ expect(clerk.session.startVerification).toHaveBeenCalledWith({ level: 'first_factor' });
+ expect(clerk.session.prepareFirstFactorVerification).toHaveBeenCalledWith({
+ strategy: 'trusted_device',
+ trustedDeviceId: 'td_1',
+ });
+ expect(biometrics.sign).toHaveBeenCalledWith('key_1', 'reverification-client-data', 'Confirm with Face ID.');
+ expect(clerk.session.attemptFirstFactorVerification).toHaveBeenCalledWith({
+ strategy: 'trusted_device',
+ trustedDeviceId: 'td_1',
+ clientData: 'reverification-client-data',
+ signature: 'signature',
+ algorithm: 'ES256',
+ });
+ expect(clerk.session.clearCache).toHaveBeenCalled();
+ expect(clerk.session.getToken).toHaveBeenCalledWith({ skipCache: true });
+ expect(result).toEqual({ id: 'sessver_1', status: 'complete', level: 'multi_factor', session: clerk.session });
+ expect(clerk.session.prepareSecondFactorVerification).not.toHaveBeenCalled();
+ });
+
+ test('returns an outstanding second factor instead of signing with the same key again', async () => {
+ addLocalCredential();
+ clerk.session.attemptFirstFactorVerification.mockResolvedValueOnce(sessionVerification('needs_second_factor'));
+
+ const result = await renderBiometricCredentials().reverify({ level: 'multi_factor' });
+
+ expect(clerk.session.prepareSecondFactorVerification).not.toHaveBeenCalled();
+ expect(biometrics.sign).toHaveBeenCalledTimes(1);
+ expect(clerk.session.getToken).not.toHaveBeenCalled();
+ expect(result.status).toBe('needs_second_factor');
+ });
+
+ test('verifies only the second factor when the verification starts there', async () => {
+ addLocalCredential();
+ clerk.session.startVerification.mockResolvedValueOnce(sessionVerification('needs_second_factor'));
+
+ await renderBiometricCredentials().reverify({ level: 'second_factor' });
+
+ expect(clerk.session.prepareFirstFactorVerification).not.toHaveBeenCalled();
+ expect(clerk.session.prepareSecondFactorVerification).toHaveBeenCalled();
+ expect(biometrics.sign).toHaveBeenCalledWith(
+ 'key_1',
+ 'reverification-client-data',
+ 'Use biometrics to verify your identity.',
+ );
+ });
+
+ test('does not prompt when the verification is already complete', async () => {
+ addLocalCredential();
+ clerk.session.startVerification.mockResolvedValueOnce(sessionVerification('complete'));
+
+ const result = await renderBiometricCredentials().reverify();
+
+ expect(biometrics.sign).not.toHaveBeenCalled();
+ expect(clerk.session.getToken).toHaveBeenCalledWith({ skipCache: true });
+ expect(result.status).toBe('complete');
+ });
+
+ test('returns an incomplete verification without refreshing the session token', async () => {
+ addLocalCredential();
+ clerk.session.attemptFirstFactorVerification.mockResolvedValueOnce(sessionVerification('needs_first_factor'));
+
+ const result = await renderBiometricCredentials().reverify();
+
+ expect(result.status).toBe('needs_first_factor');
+ expect(clerk.session.clearCache).not.toHaveBeenCalled();
+ expect(clerk.session.getToken).not.toHaveBeenCalled();
+ });
+
+ test('rejects an invalid level before starting the verification', async () => {
+ addLocalCredential();
+
+ await expect(
+ renderBiometricCredentials().reverify({ level: 'everything' as 'first_factor' }),
+ ).rejects.toMatchObject({ code: 'invalid_reverification_level' });
+ expect(clerk.session.startVerification).not.toHaveBeenCalled();
+ });
+
+ test('requires a session with a user', async () => {
+ clerk.instance.session = null;
+
+ await expect(renderBiometricCredentials().reverify()).rejects.toMatchObject({
+ code: 'biometric_reverification_session_unavailable',
+ });
+ });
+
+ test('requires a local credential for the session user', async () => {
+ addLocalCredential({ userId: 'user_2' });
+
+ await expect(renderBiometricCredentials().reverify()).rejects.toMatchObject({
+ code: 'E_BIOMETRIC_REVERIFICATION_FAILED',
+ message: 'Biometric reverification is unavailable: no_local_credential.',
+ });
+ expect(clerk.session.startVerification).not.toHaveBeenCalled();
+ });
+
+ test('requires a credential bound to the current biometric set', async () => {
+ addLocalCredential({ policy: 'biometry_any' });
+
+ await expect(renderBiometricCredentials().reverify()).rejects.toMatchObject({
+ code: 'biometric_credential_policy_incompatible',
+ });
+ expect(clerk.session.startVerification).not.toHaveBeenCalled();
+ });
+
+ test('rejects a challenge issued for another credential without prompting', async () => {
+ addLocalCredential();
+ clerk.session.prepareFirstFactorVerification.mockResolvedValueOnce(
+ sessionVerification('needs_first_factor', {
+ firstFactorVerification: trustedDeviceVerification({ trustedDeviceId: 'td_other' }),
+ }),
+ );
+
+ await expect(renderBiometricCredentials().reverify()).rejects.toThrow(
+ 'Biometric reverification did not return a matching challenge.',
+ );
+ expect(biometrics.sign).not.toHaveBeenCalled();
+ });
+
+ test('rejects an expired challenge without prompting', async () => {
+ addLocalCredential();
+ clerk.session.prepareFirstFactorVerification.mockResolvedValueOnce(
+ sessionVerification('needs_first_factor', {
+ firstFactorVerification: trustedDeviceVerification({ expiresAt: new Date(Date.now() - 1_000) }),
+ }),
+ );
+
+ await expect(renderBiometricCredentials().reverify()).rejects.toThrow(
+ 'Biometric reverification challenge has expired.',
+ );
+ expect(biometrics.sign).not.toHaveBeenCalled();
+ });
+
+ test('forgets the local credential when its key was invalidated', async () => {
+ addLocalCredential();
+ biometrics.sign.mockRejectedValueOnce(moduleError('key_invalidated'));
+
+ await expect(renderBiometricCredentials().reverify()).rejects.toMatchObject({ code: 'key_invalidated' });
+ expect(biometrics.store.records).toEqual([]);
+ });
+
+ test('forgets the local credential when the server no longer has it', async () => {
+ addLocalCredential();
+ const cause = apiError('trusted_device_not_registered', 'trusted_device_id');
+ clerk.session.prepareFirstFactorVerification.mockRejectedValueOnce(cause);
+
+ await expectBiometricApiError(renderBiometricCredentials().reverify(), cause);
+ expect(biometrics.store.records).toEqual([]);
+ });
+
+ test('fails when the session token cannot be refreshed', async () => {
+ addLocalCredential();
+ clerk.session.getToken.mockResolvedValueOnce(null);
+
+ await expect(renderBiometricCredentials().reverify()).rejects.toThrow(
+ 'Unable to refresh the session token after biometric reverification.',
+ );
+ });
+
+ test('reports a failed session token refresh with its API code', async () => {
+ addLocalCredential();
+ const error = apiError('internal_clerk_error');
+ clerk.session.getToken.mockRejectedValueOnce(error);
+
+ await expectBiometricApiError(renderBiometricCredentials().reverify(), error);
+ });
+
+ test('rejects reverification on unsupported platforms', async () => {
+ await expect(renderBiometricCredentials(useBiometricCredentialsOnUnsupportedPlatform).reverify()).rejects.toThrow(
+ 'only available on iOS and Android',
+ );
+ });
+});
diff --git a/packages/expo/src/biometric-credentials/createBiometricCredentials.ts b/packages/expo/src/biometric-credentials/createBiometricCredentials.ts
new file mode 100644
index 00000000000..e26fa68049b
--- /dev/null
+++ b/packages/expo/src/biometric-credentials/createBiometricCredentials.ts
@@ -0,0 +1,669 @@
+import type { useClerk } from '@clerk/react';
+import { isClerkAPIResponseError } from '@clerk/shared/error';
+import type {
+ BiometricCredentialResource,
+ EnvironmentResource,
+ PrepareBiometricCredentialParams,
+ SessionResource,
+ SessionVerificationLevel,
+ SessionVerificationResource,
+ SignInResource,
+ TrustedDeviceChallengeResource,
+ UserResource,
+} from '@clerk/shared/types';
+import { Platform } from 'react-native';
+
+import { errorThrower } from '../utils/errors';
+import type { BiometricCredentialError, BiometricCredentialErrorCode } from './errors';
+import type { ExpoBiometricsModule, ExpoBiometricsRecord } from './loadExpoBiometrics';
+import { loadExpoBiometrics } from './loadExpoBiometrics';
+import type {
+ BiometricCredential,
+ BiometricCredentialPlatform,
+ BiometricCredentialPolicy,
+ BiometricCredentialStatus,
+ BiometricCredentialUnavailableReason,
+ UseBiometricCredentialsReturn,
+} from './types';
+
+type Clerk = ReturnType;
+
+type OperationErrorCode =
+ | 'E_TRUSTED_DEVICE_AVAILABILITY_FAILED'
+ | 'E_TRUSTED_DEVICE_LIST_FAILED'
+ | 'E_TRUSTED_DEVICE_ENROLLMENT_FAILED'
+ | 'E_TRUSTED_DEVICE_REVOCATION_FAILED'
+ | 'E_TRUSTED_DEVICE_SIGN_IN_FAILED'
+ | 'E_BIOMETRIC_REVERIFICATION_FAILED';
+
+type Biometrics = {
+ module: ExpoBiometricsModule;
+ appIdentifier: string;
+ fallbackCode: OperationErrorCode;
+};
+
+type LocalCredentialSelection =
+ | { record: ExpoBiometricsRecord; unavailableReason?: never }
+ | { record?: never; unavailableReason: BiometricCredentialUnavailableReason };
+
+const DEFAULT_POLICY: BiometricCredentialPolicy = 'biometry_current_set';
+const POLICIES: ReadonlySet = new Set([
+ 'biometry_current_set',
+ 'biometry_any',
+ 'biometry_or_device_passcode',
+]);
+const DEFAULT_ENROLLMENT_REASON = 'Use biometrics to enroll this device.';
+const DEFAULT_SIGN_IN_REASON = 'Use biometrics to sign in.';
+const DEFAULT_REVERIFICATION_REASON = 'Use biometrics to verify your identity.';
+const REVERIFICATION_LEVELS = new Set(['first_factor', 'second_factor', 'multi_factor']);
+
+const EXPO_BIOMETRICS_INSTALL_INSTRUCTIONS =
+ 'Install it with `npx expo install @clerk/expo-biometrics`, then rebuild your development build.';
+
+const MISSING_CREDENTIAL_ERROR_CODES = new Set(['form_resource_not_found', 'trusted_device_not_registered']);
+const TRUSTED_DEVICE_ID_PARAM = 'trusted_device_id';
+
+const MODULE_ERROR_CODES: Record = {
+ user_canceled: 'biometric_authentication_canceled',
+ system_canceled: 'biometric_authentication_canceled',
+ user_fallback: 'biometric_authentication_canceled',
+ authentication_failed: 'biometric_authentication_failed',
+ biometry_not_available: 'biometric_authentication_unavailable',
+ 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',
+ signing_failed: 'signing_failed',
+};
+
+function biometricCredentialError(
+ code: BiometricCredentialErrorCode,
+ message: string,
+ cause?: unknown,
+): BiometricCredentialError {
+ return Object.assign(new Error(message), { code }, cause === undefined ? {} : { cause });
+}
+
+function moduleErrorCode(error: unknown): string | undefined {
+ const code = (error as { code?: unknown } | null)?.code;
+ return typeof code === 'string' ? code : undefined;
+}
+
+function toBiometricCredentialError(error: unknown, fallbackCode: OperationErrorCode): BiometricCredentialError {
+ const code = moduleErrorCode(error);
+ const message = error instanceof Error ? error.message : String(error);
+ return biometricCredentialError((code && MODULE_ERROR_CODES[code]) || fallbackCode, message, error);
+}
+
+async function callModule(biometrics: Biometrics, operation: (module: ExpoBiometricsModule) => T | Promise) {
+ try {
+ return await operation(biometrics.module);
+ } catch (error) {
+ throw toBiometricCredentialError(error, biometrics.fallbackCode);
+ }
+}
+
+function requireBiometrics(fallbackCode: OperationErrorCode): Biometrics {
+ const module = loadExpoBiometrics();
+ if (!module) {
+ return errorThrower.throw(
+ `Biometric credentials require the @clerk/expo-biometrics package. ${EXPO_BIOMETRICS_INSTALL_INSTRUCTIONS}`,
+ );
+ }
+ try {
+ return { module, appIdentifier: module.getAppIdentifier(), fallbackCode };
+ } catch (error) {
+ if (moduleErrorCode(error) === 'native_module_unavailable') {
+ return errorThrower.throw(
+ `Biometric credentials require a development build that includes @clerk/expo-biometrics, and are not available in Expo Go. ${EXPO_BIOMETRICS_INSTALL_INSTRUCTIONS}`,
+ );
+ }
+ throw toBiometricCredentialError(error, fallbackCode);
+ }
+}
+
+function normalizeIdentifierHint(identifierHint: string | null | undefined): string | null {
+ const normalized = identifierHint?.trim().toLowerCase();
+ return normalized ? normalized : null;
+}
+
+async function identifierHintMatcher(
+ biometrics: Biometrics,
+ identifierHint: string | undefined,
+): Promise<(record: ExpoBiometricsRecord) => boolean> {
+ const normalizedHint = normalizeIdentifierHint(identifierHint);
+ if (!normalizedHint) {
+ return () => true;
+ }
+ const hash = await callModule(biometrics, module => module.hashIdentifierHint(normalizedHint));
+ return record => record.identifierHintSha256 === hash;
+}
+
+function newestFirst(a: ExpoBiometricsRecord, b: ExpoBiometricsRecord): number {
+ if (a.createdAt !== b.createdAt) {
+ return b.createdAt - a.createdAt;
+ }
+ if (a.updatedAt !== b.updatedAt) {
+ return b.updatedAt - a.updatedAt;
+ }
+ return a.id < b.id ? 1 : a.id > b.id ? -1 : 0;
+}
+
+function toBiometricCredentialPlatform(platform: string): BiometricCredentialPlatform {
+ return platform === 'ios' || platform === 'android' ? platform : 'unknown';
+}
+
+function toBiometricCredentialStatus(status: string): BiometricCredentialStatus {
+ return status === 'active' || status === 'revoked' ? status : 'unknown';
+}
+
+function toBiometricCredential(credential: BiometricCredentialResource): BiometricCredential {
+ return {
+ id: credential.id,
+ object: 'trusted_device',
+ platform: toBiometricCredentialPlatform(credential.platform),
+ appIdentifier: credential.appIdentifier,
+ name: credential.name ?? null,
+ algorithm: credential.algorithm,
+ status: toBiometricCredentialStatus(credential.status),
+ createdAt: credential.createdAt,
+ updatedAt: credential.updatedAt,
+ lastUsedAt: credential.lastUsedAt ?? null,
+ revokedAt: credential.revokedAt ?? null,
+ };
+}
+
+function toApiBiometricCredentialError(error: unknown, fallbackCode: OperationErrorCode): unknown {
+ if (isClerkAPIResponseError(error)) {
+ const apiError = error.errors[0];
+ return biometricCredentialError(
+ apiError?.code ?? fallbackCode,
+ apiError?.longMessage ?? apiError?.message ?? error.message,
+ error,
+ );
+ }
+ if (error instanceof Error && typeof (error as { code?: unknown }).code === 'string') {
+ return error;
+ }
+ return biometricCredentialError(fallbackCode, error instanceof Error ? error.message : String(error), error);
+}
+
+async function callApi(fallbackCode: OperationErrorCode, request: () => Promise): Promise {
+ try {
+ return await request();
+ } catch (error) {
+ throw toApiBiometricCredentialError(error, fallbackCode);
+ }
+}
+
+function isMissingCredentialError(error: unknown): boolean {
+ return (
+ isClerkAPIResponseError(error) &&
+ error.errors.some(
+ apiError =>
+ MISSING_CREDENTIAL_ERROR_CODES.has(apiError.code) && apiError.meta?.paramName === TRUSTED_DEVICE_ID_PARAM,
+ )
+ );
+}
+
+export function createBiometricCredentials(clerk: Clerk): UseBiometricCredentialsReturn {
+ function featureUnavailableReason(): BiometricCredentialUnavailableReason | null {
+ const environment = (clerk as { __internal_environment?: EnvironmentResource | null }).__internal_environment;
+ const nativeSettings = environment?.authConfig?.nativeSettings;
+ if (!nativeSettings) {
+ return 'environment_unavailable';
+ }
+ if (!nativeSettings.apiEnabled) {
+ return 'native_api_disabled';
+ }
+ if (!nativeSettings.trustedDeviceSignInEnabled) {
+ return 'feature_disabled';
+ }
+ return null;
+ }
+
+ function requireUser(fallbackCode: OperationErrorCode): UserResource {
+ const user = clerk.user;
+ if (!user) {
+ throw biometricCredentialError(fallbackCode, 'Biometric credential management requires a signed-in user.');
+ }
+ return user;
+ }
+
+ async function deleteLocalCredential(biometrics: Biometrics, record: ExpoBiometricsRecord): Promise {
+ await callModule(biometrics, module => module.deleteRecord(record.localKeyId));
+ }
+
+ async function ignoreErrors(operation: () => Promise): Promise {
+ try {
+ await operation();
+ } catch {
+ // Cleanup must not mask the error that triggered it.
+ }
+ }
+
+ async function forgetLocalCredentialIfMissing(
+ biometrics: Biometrics,
+ record: ExpoBiometricsRecord,
+ error: unknown,
+ ): Promise {
+ if (isMissingCredentialError(error)) {
+ await ignoreErrors(() => deleteLocalCredential(biometrics, record));
+ }
+ return toApiBiometricCredentialError(error, biometrics.fallbackCode);
+ }
+
+ async function signChallenge(
+ biometrics: Biometrics,
+ record: ExpoBiometricsRecord,
+ clientData: string,
+ reason: string,
+ ): Promise {
+ try {
+ return await biometrics.module.sign(record.localKeyId, clientData, reason);
+ } catch (error) {
+ const biometricError = toBiometricCredentialError(error, biometrics.fallbackCode);
+ if (biometricError.code === 'key_invalidated' || biometricError.code === 'key_not_found') {
+ await ignoreErrors(() => deleteLocalCredential(biometrics, record));
+ }
+ throw biometricError;
+ }
+ }
+
+ async function localCredentialCandidates(
+ biometrics: Biometrics,
+ id: string | undefined,
+ identifierHint: string | undefined,
+ ): Promise {
+ const unavailableReason = featureUnavailableReason();
+ if (unavailableReason) {
+ return unavailableReason;
+ }
+
+ const device = await callModule(biometrics, module => module.getAvailability());
+ if (!device.secureKeyStorageAvailable) {
+ return 'biometric_authentication_unavailable';
+ }
+
+ const matchesIdentifierHint = await identifierHintMatcher(biometrics, identifierHint);
+ const records = (await callModule(biometrics, module => module.listRecords()))
+ .filter(
+ record =>
+ record.appIdentifier === biometrics.appIdentifier &&
+ (id === undefined || record.id === id) &&
+ matchesIdentifierHint(record),
+ )
+ .sort(newestFirst);
+ if (records.length === 0) {
+ return 'no_local_credential';
+ }
+
+ const recordsWithKeys: ExpoBiometricsRecord[] = [];
+ for (const record of records) {
+ if (await callModule(biometrics, module => module.hasKey(record.localKeyId))) {
+ recordsWithKeys.push(record);
+ } else {
+ await deleteLocalCredential(biometrics, record);
+ }
+ }
+ if (recordsWithKeys.length === 0) {
+ return 'local_key_missing';
+ }
+
+ const supportedRecords = recordsWithKeys.filter(record =>
+ record.policy === 'biometry_or_device_passcode' ? device.canEvaluateDeviceOwner : device.canEvaluateBiometrics,
+ );
+ if (supportedRecords.length === 0) {
+ return 'biometric_authentication_unavailable';
+ }
+ return supportedRecords;
+ }
+
+ async function selectLocalCredential(
+ biometrics: Biometrics,
+ id: string | undefined,
+ identifierHint: string | undefined,
+ ): Promise {
+ const candidates = await localCredentialCandidates(biometrics, id, identifierHint);
+ if (typeof candidates === 'string') {
+ return { unavailableReason: candidates };
+ }
+
+ const session = clerk.session;
+ const activeUser = session?.status === 'active' ? session.user : null;
+ if (!activeUser?.id) {
+ return { record: candidates[0] };
+ }
+
+ const activeUserRecords = candidates.filter(record => record.userId === activeUser.id);
+ if (activeUserRecords.length === 0) {
+ return { unavailableReason: 'no_local_credential' };
+ }
+
+ const serverCredentials = await callApi(biometrics.fallbackCode, () =>
+ activeUser.__experimental_getBiometricCredentials(),
+ );
+ let firstUnavailableReason: BiometricCredentialUnavailableReason | null = null;
+ for (const record of activeUserRecords) {
+ const serverCredential = serverCredentials.find(credential => credential.id === record.id);
+ if (!serverCredential) {
+ await deleteLocalCredential(biometrics, record);
+ firstUnavailableReason ??= 'server_credential_missing';
+ continue;
+ }
+ if (serverCredential.status !== 'active') {
+ await deleteLocalCredential(biometrics, record);
+ firstUnavailableReason ??= 'server_credential_revoked';
+ continue;
+ }
+ return { record };
+ }
+ return { unavailableReason: firstUnavailableReason ?? 'server_credential_missing' };
+ }
+
+ async function reverificationCredential(biometrics: Biometrics, userId: string): Promise {
+ const candidates = await localCredentialCandidates(biometrics, undefined, undefined);
+ if (typeof candidates === 'string') {
+ throw biometricCredentialError(
+ biometrics.fallbackCode,
+ `Biometric reverification is unavailable: ${candidates}.`,
+ );
+ }
+ const userRecords = candidates.filter(record => record.userId === userId);
+ if (userRecords.length === 0) {
+ throw biometricCredentialError(
+ biometrics.fallbackCode,
+ 'Biometric reverification is unavailable: no_local_credential.',
+ );
+ }
+ const record = userRecords.find(candidate => candidate.policy === 'biometry_current_set');
+ if (!record) {
+ throw biometricCredentialError(
+ 'biometric_credential_policy_incompatible',
+ 'This biometric credential cannot be used for reverification. Verify your identity using another method.',
+ );
+ }
+ return record;
+ }
+
+ function usableChallenge(
+ biometrics: Biometrics,
+ record: ExpoBiometricsRecord,
+ challenge: TrustedDeviceChallengeResource | null | undefined,
+ flow: string,
+ ): TrustedDeviceChallengeResource {
+ if (!challenge || (challenge.trustedDeviceId && challenge.trustedDeviceId !== record.id)) {
+ throw biometricCredentialError(biometrics.fallbackCode, `${flow} did not return a matching challenge.`);
+ }
+ if (challenge.expiresAt && challenge.expiresAt.getTime() <= Date.now()) {
+ throw biometricCredentialError(biometrics.fallbackCode, `${flow} challenge has expired.`);
+ }
+ return challenge;
+ }
+
+ async function verifySessionFactor(
+ biometrics: Biometrics,
+ session: SessionResource,
+ record: ExpoBiometricsRecord,
+ factor: 'first' | 'second',
+ reason: string,
+ ): Promise {
+ let prepared: SessionVerificationResource;
+ try {
+ const config = { strategy: 'trusted_device', trustedDeviceId: record.id } as const;
+ prepared =
+ factor === 'first'
+ ? await session.prepareFirstFactorVerification(config)
+ : await session.prepareSecondFactorVerification(config);
+ } catch (error) {
+ throw await forgetLocalCredentialIfMissing(biometrics, record, error);
+ }
+
+ const verification = factor === 'first' ? prepared.firstFactorVerification : prepared.secondFactorVerification;
+ const challenge = usableChallenge(
+ biometrics,
+ record,
+ verification?.strategy === 'trusted_device' ? verification.trustedDeviceChallenge : null,
+ 'Biometric reverification',
+ );
+
+ const signature = await signChallenge(biometrics, record, challenge.clientData, reason);
+
+ try {
+ const attempt = {
+ strategy: 'trusted_device',
+ trustedDeviceId: record.id,
+ clientData: challenge.clientData,
+ signature,
+ algorithm: 'ES256',
+ } as const;
+ return factor === 'first'
+ ? await session.attemptFirstFactorVerification(attempt)
+ : await session.attemptSecondFactorVerification(attempt);
+ } catch (error) {
+ throw await forgetLocalCredentialIfMissing(biometrics, record, error);
+ }
+ }
+
+ return {
+ getAvailability: async params => {
+ const biometrics = requireBiometrics('E_TRUSTED_DEVICE_AVAILABILITY_FAILED');
+ const selection = await selectLocalCredential(biometrics, params?.id, params?.identifierHint);
+ return selection.record
+ ? { isAvailable: true, unavailableReason: null }
+ : { isAvailable: false, unavailableReason: selection.unavailableReason };
+ },
+
+ list: async () => {
+ const biometrics = requireBiometrics('E_TRUSTED_DEVICE_LIST_FAILED');
+ const user = requireUser(biometrics.fallbackCode);
+ const credentials = await callApi(biometrics.fallbackCode, () => user.__experimental_getBiometricCredentials());
+ return credentials.map(toBiometricCredential);
+ },
+
+ enroll: async params => {
+ const biometrics = requireBiometrics('E_TRUSTED_DEVICE_ENROLLMENT_FAILED');
+ const session = clerk.session;
+ if (!session || (session.status !== 'active' && session.status !== 'pending') || !session.user) {
+ throw biometricCredentialError(
+ biometrics.fallbackCode,
+ 'Unable to enroll a biometric credential without an active or pending Clerk session.',
+ );
+ }
+ const user = session.user;
+ const unavailableReason = featureUnavailableReason();
+ if (unavailableReason) {
+ throw biometricCredentialError(
+ unavailableReason === 'environment_unavailable' ? unavailableReason : biometrics.fallbackCode,
+ `Unable to enroll a biometric credential: ${unavailableReason}.`,
+ );
+ }
+
+ const policy = params?.policy ?? DEFAULT_POLICY;
+ if (!POLICIES.has(policy)) {
+ throw biometricCredentialError(
+ 'invalid_trusted_device_policy',
+ `Invalid biometric-credential policy: ${policy}.`,
+ );
+ }
+ const key = await callModule(biometrics, module => module.createKey(policy));
+ const enrollment: PrepareBiometricCredentialParams = {
+ platform: Platform.OS === 'android' ? 'android' : 'ios',
+ appIdentifier: biometrics.appIdentifier,
+ algorithm: 'ES256',
+ publicKeyJwk: key.publicKeyJwk,
+ ...(params?.name === undefined ? {} : { name: params.name }),
+ };
+
+ let credential: BiometricCredentialResource;
+ try {
+ const challenge = await callApi(biometrics.fallbackCode, () =>
+ user.__experimental_prepareBiometricCredential(enrollment),
+ );
+ const signature = await callModule(biometrics, module =>
+ module.sign(key.localKeyId, challenge.clientData, params?.reason ?? DEFAULT_ENROLLMENT_REASON),
+ );
+ credential = await callApi(biometrics.fallbackCode, () =>
+ user.__experimental_attemptBiometricCredential({
+ ...enrollment,
+ clientData: challenge.clientData,
+ signature,
+ }),
+ );
+ } catch (error) {
+ await ignoreErrors(() => biometrics.module.deleteKey(key.localKeyId));
+ throw error;
+ }
+
+ const identifierHint = normalizeIdentifierHint(params?.identifierHint);
+ try {
+ await callModule(biometrics, module =>
+ module.saveRecord(
+ {
+ id: credential.id,
+ localKeyId: key.localKeyId,
+ userId: user.id,
+ appIdentifier: biometrics.appIdentifier,
+ ...(identifierHint ? { identifierHint } : {}),
+ policy,
+ createdAt: credential.createdAt.getTime(),
+ updatedAt: credential.updatedAt.getTime(),
+ },
+ { removeOtherRecordsForApp: true },
+ ),
+ );
+ } catch (error) {
+ await ignoreErrors(() => user.__experimental_revokeBiometricCredential(credential.id));
+ await ignoreErrors(() => biometrics.module.deleteKey(key.localKeyId));
+ throw error;
+ }
+ return toBiometricCredential(credential);
+ },
+
+ revoke: async id => {
+ const biometrics = requireBiometrics('E_TRUSTED_DEVICE_REVOCATION_FAILED');
+ const user = requireUser(biometrics.fallbackCode);
+ const credential = await callApi(biometrics.fallbackCode, () =>
+ user.__experimental_revokeBiometricCredential(id),
+ );
+ await ignoreErrors(async () => {
+ const records = await biometrics.module.listRecords();
+ const localKeyIds = new Set(records.filter(record => record.id === id).map(record => record.localKeyId));
+ for (const localKeyId of localKeyIds) {
+ await biometrics.module.deleteRecord(localKeyId);
+ }
+ });
+ return toBiometricCredential(credential);
+ },
+
+ signIn: async params => {
+ const biometrics = requireBiometrics('E_TRUSTED_DEVICE_SIGN_IN_FAILED');
+ const clientSignIn = clerk.client?.signIn;
+ if (!clientSignIn) {
+ throw biometricCredentialError(
+ biometrics.fallbackCode,
+ 'Biometric sign-in requires a loaded Clerk client: the client sign-in resource is unavailable.',
+ );
+ }
+
+ const selection = await selectLocalCredential(biometrics, params?.id, params?.identifierHint);
+ if (!selection.record) {
+ throw biometricCredentialError(
+ biometrics.fallbackCode,
+ `Biometric sign-in is unavailable: ${selection.unavailableReason}.`,
+ );
+ }
+ const record = selection.record;
+
+ let signIn: SignInResource;
+ try {
+ signIn = await clientSignIn.create({ strategy: 'trusted_device', trustedDeviceId: record.id });
+ } catch (error) {
+ throw await forgetLocalCredentialIfMissing(biometrics, record, error);
+ }
+
+ const challenge = usableChallenge(
+ biometrics,
+ record,
+ signIn.firstFactorVerification?.trustedDeviceChallenge,
+ 'Biometric sign-in',
+ );
+
+ const signature = await signChallenge(
+ biometrics,
+ record,
+ challenge.clientData,
+ params?.reason ?? DEFAULT_SIGN_IN_REASON,
+ );
+
+ try {
+ signIn = await signIn.attemptFirstFactor({
+ strategy: 'trusted_device',
+ trustedDeviceId: record.id,
+ clientData: challenge.clientData,
+ signature,
+ algorithm: 'ES256',
+ });
+ } catch (error) {
+ throw await forgetLocalCredentialIfMissing(biometrics, record, error);
+ }
+
+ if (!signIn.status) {
+ throw biometricCredentialError(biometrics.fallbackCode, 'Biometric sign-in did not return a status.');
+ }
+ return {
+ status: signIn.status,
+ createdSessionId: signIn.createdSessionId,
+ signIn,
+ setActive: clerk.setActive,
+ };
+ },
+
+ reverify: async params => {
+ const biometrics = requireBiometrics('E_BIOMETRIC_REVERIFICATION_FAILED');
+ const level = params?.level ?? 'first_factor';
+ if (!REVERIFICATION_LEVELS.has(level)) {
+ throw biometricCredentialError(
+ 'invalid_reverification_level',
+ 'Biometric reverification level must be first_factor, second_factor, or multi_factor.',
+ );
+ }
+ const session = clerk.session;
+ if (!session || (session.status !== 'active' && session.status !== 'pending') || !session.user) {
+ throw biometricCredentialError(
+ 'biometric_reverification_session_unavailable',
+ 'Biometric reverification requires an active or pending session with a user.',
+ );
+ }
+ const record = await reverificationCredential(biometrics, session.user.id);
+ const reason = params?.reason ?? DEFAULT_REVERIFICATION_REASON;
+
+ let verification = await callApi(biometrics.fallbackCode, () => session.startVerification({ level }));
+ if (verification.status === 'needs_first_factor') {
+ verification = await verifySessionFactor(biometrics, session, record, 'first', reason);
+ } else if (verification.status === 'needs_second_factor') {
+ verification = await verifySessionFactor(biometrics, session, record, 'second', reason);
+ } else if (verification.status !== 'complete') {
+ throw biometricCredentialError(
+ biometrics.fallbackCode,
+ 'The server returned an unsupported reverification status.',
+ );
+ }
+
+ if (verification.status === 'complete') {
+ session.clearCache();
+ const token = await callApi(biometrics.fallbackCode, () => session.getToken({ skipCache: true }));
+ if (!token) {
+ throw biometricCredentialError(
+ biometrics.fallbackCode,
+ 'Unable to refresh the session token after biometric reverification.',
+ );
+ }
+ }
+ return { id: verification.id ?? null, status: verification.status, level: verification.level, session };
+ },
+ };
+}
diff --git a/packages/expo/src/biometric-credentials/deprecatedRootExport.ts b/packages/expo/src/biometric-credentials/deprecatedRootExport.ts
new file mode 100644
index 00000000000..3fe8e54c109
--- /dev/null
+++ b/packages/expo/src/biometric-credentials/deprecatedRootExport.ts
@@ -0,0 +1,12 @@
+import { deprecated } from '@clerk/shared/deprecated';
+
+import type { UseBiometricCredentialsReturn } from './types';
+import { useBiometricCredentials as useBiometricCredentialsBase } from './useBiometricCredentials';
+
+/**
+ * @deprecated Import `useBiometricCredentials` from `@clerk/expo/biometrics` instead. This export will be removed in the next major version.
+ */
+export function useBiometricCredentials(): UseBiometricCredentialsReturn {
+ deprecated('useBiometricCredentials from `@clerk/expo`', 'Import it from `@clerk/expo/biometrics` instead.');
+ return useBiometricCredentialsBase();
+}
diff --git a/packages/expo/src/biometric-credentials/loadExpoBiometrics.ts b/packages/expo/src/biometric-credentials/loadExpoBiometrics.ts
new file mode 100644
index 00000000000..4cf4c6290ad
--- /dev/null
+++ b/packages/expo/src/biometric-credentials/loadExpoBiometrics.ts
@@ -0,0 +1,15 @@
+import type * as ExpoBiometrics from '@clerk/expo-biometrics';
+
+export type ExpoBiometricsRecord = ExpoBiometrics.StoredBiometricCredentialRecord;
+
+export type ExpoBiometricsModule = typeof ExpoBiometrics;
+
+export function loadExpoBiometrics(): ExpoBiometricsModule | null {
+ try {
+ // Synchronous require() in try/catch so Metro treats @clerk/expo-biometrics as an optional dependency.
+ // eslint-disable-next-line @typescript-eslint/no-require-imports
+ return require('@clerk/expo-biometrics') as ExpoBiometricsModule;
+ } catch {
+ return null;
+ }
+}
diff --git a/packages/expo/src/biometric-credentials/types.ts b/packages/expo/src/biometric-credentials/types.ts
index 302f2f8d613..80817ab6a5e 100644
--- a/packages/expo/src/biometric-credentials/types.ts
+++ b/packages/expo/src/biometric-credentials/types.ts
@@ -68,7 +68,7 @@ export type ReverifyWithBiometricsParams = {
reason?: string;
};
-/** The verification outcome and synchronized session, without creating or activating a session. */
+/** The verification outcome and its session, without creating or activating a session. */
export type BiometricReverificationResult = {
id: string | null;
status: SessionVerificationStatus | (string & {});
@@ -79,7 +79,7 @@ export type BiometricReverificationResult = {
export type BiometricSignInResult = {
status: SignInStatus | (string & {});
createdSessionId: string | null;
- /** The synchronized JS sign-in resource used to continue any remaining authentication steps. */
+ /** The sign-in resource used to continue any remaining authentication steps. */
signIn: SignInResource;
/** Activates a session after the sign-in reaches `complete`. */
setActive: SetActive;
diff --git a/packages/expo/src/biometric-credentials/useBiometricCredentials.shared.ts b/packages/expo/src/biometric-credentials/useBiometricCredentials.shared.ts
index 3e92e5287be..166d1a9071c 100644
--- a/packages/expo/src/biometric-credentials/useBiometricCredentials.shared.ts
+++ b/packages/expo/src/biometric-credentials/useBiometricCredentials.shared.ts
@@ -1,187 +1,13 @@
import { useClerk } from '@clerk/react';
import { useMemo } from 'react';
-import { synchronizeNativeClientToJs, waitForPendingJsToNativeSync } from '../provider/nativeClientSyncCoordinator';
-import type { NativeBiometricCredential, NativeBiometricCredentialModule } from '../specs/NativeClerkModule.types';
-import { errorThrower } from '../utils/errors';
-import { ClerkExpoModule } from '../utils/native-module';
-import type {
- BiometricCredential,
- BiometricCredentialPlatform,
- BiometricCredentialStatus,
- UseBiometricCredentialsReturn,
-} from './types';
-
-const DEFAULT_POLICY = 'biometry_current_set';
-
-function toBiometricCredentialPlatform(platform: string): BiometricCredentialPlatform {
- return platform === 'ios' || platform === 'android' ? platform : 'unknown';
-}
-
-function toBiometricCredentialStatus(status: string): BiometricCredentialStatus {
- return status === 'active' || status === 'revoked' ? status : 'unknown';
-}
-
-function getNativeModule(): NativeBiometricCredentialModule {
- const nativeModule = ClerkExpoModule;
-
- if (
- !nativeModule?.getTrustedDeviceAvailability ||
- !nativeModule.listTrustedDevices ||
- !nativeModule.enrollTrustedDevice ||
- !nativeModule.revokeTrustedDevice ||
- !nativeModule.signInWithTrustedDevice
- ) {
- return errorThrower.throw(
- 'Biometric credentials require a development build containing a compatible version of @clerk/expo.',
- );
- }
-
- return nativeModule as NativeBiometricCredentialModule;
-}
-
-function toBiometricCredential(credential: NativeBiometricCredential): BiometricCredential {
- return {
- ...credential,
- platform: toBiometricCredentialPlatform(credential.platform),
- status: toBiometricCredentialStatus(credential.status),
- createdAt: new Date(credential.createdAt),
- updatedAt: new Date(credential.updatedAt),
- lastUsedAt: credential.lastUsedAt == null ? null : new Date(credential.lastUsedAt),
- revokedAt: credential.revokedAt == null ? null : new Date(credential.revokedAt),
- };
-}
-
-function createBiometricCredentials(clerk: ReturnType): UseBiometricCredentialsReturn {
- return {
- getAvailability: async params => {
- const nativeModule = getNativeModule();
- await waitForPendingJsToNativeSync();
- return nativeModule.getTrustedDeviceAvailability(params?.id ?? null, params?.identifierHint ?? null);
- },
- list: async () => {
- const nativeModule = getNativeModule();
- await waitForPendingJsToNativeSync();
- const credentials = await nativeModule.listTrustedDevices();
- return credentials.map(toBiometricCredential);
- },
- enroll: async params => {
- const nativeModule = getNativeModule();
- await waitForPendingJsToNativeSync();
- const credential = await nativeModule.enrollTrustedDevice(
- params?.name ?? null,
- params?.identifierHint ?? null,
- params?.reason ?? null,
- params?.policy ?? DEFAULT_POLICY,
- );
- return toBiometricCredential(credential);
- },
- revoke: async id => {
- const nativeModule = getNativeModule();
- await waitForPendingJsToNativeSync();
- const credential = await nativeModule.revokeTrustedDevice(id);
- return toBiometricCredential(credential);
- },
- reverify: async params => {
- const nativeModule = getNativeModule();
- if (typeof nativeModule.reverifyWithBiometrics !== 'function') {
- return errorThrower.throw(
- 'Biometric reverification requires a development build containing a compatible version of @clerk/expo.',
- );
- }
- const level = params?.level ?? 'first_factor';
- if (level !== 'first_factor' && level !== 'second_factor' && level !== 'multi_factor') {
- return errorThrower.throw(
- 'Biometric reverification level must be first_factor, second_factor, or multi_factor.',
- );
- }
- const session = clerk.session;
- if (!session) {
- return errorThrower.throw('Biometric reverification requires an active session.');
- }
- await waitForPendingJsToNativeSync();
- if (clerk.session?.id !== session.id) {
- return errorThrower.throw('The active session changed before biometric reverification started.');
- }
- const verification = await nativeModule.reverifyWithBiometrics(session.id, level, params?.reason ?? null);
- if (verification.sessionId !== session.id) {
- return errorThrower.throw('Biometric reverification returned a different session.');
- }
- if (verification.status === 'complete') {
- session.clearCache();
- }
- await synchronizeNativeClientToJs();
- const synchronizedSession = clerk.session;
- if (synchronizedSession?.id !== session.id) {
- return errorThrower.throw('The active session changed during biometric reverification.');
- }
- if (verification.status === 'complete') {
- synchronizedSession.clearCache();
- const token = await synchronizedSession.getToken({ skipCache: true });
- if (!token) {
- return errorThrower.throw('Unable to refresh the session token after biometric reverification.');
- }
- if (clerk.session?.id !== session.id) {
- return errorThrower.throw('The active session changed during biometric reverification.');
- }
- }
- return {
- id: verification.id,
- status: verification.status,
- level: verification.level,
- session: synchronizedSession,
- };
- },
- signIn: async params => {
- const nativeModule = getNativeModule();
- await waitForPendingJsToNativeSync();
- const nativeSignIn = await nativeModule.signInWithTrustedDevice(
- params?.id ?? null,
- params?.identifierHint ?? null,
- params?.reason ?? null,
- );
- await synchronizeNativeClientToJs();
-
- const client = clerk.client;
- const signIn = client?.signIn;
- if (!client || !signIn) {
- return errorThrower.throw(
- 'Unable to synchronize biometric sign-in with the Clerk JS client: the client sign-in resource is unavailable.',
- );
- }
-
- const isComplete = nativeSignIn.status === 'complete';
- if (isComplete) {
- if (
- !nativeSignIn.createdSessionId ||
- !client.signedInSessions.some(session => session.id === nativeSignIn.createdSessionId)
- ) {
- return errorThrower.throw(
- 'Unable to synchronize biometric sign-in with the Clerk JS client: the created session is missing.',
- );
- }
- } else if (!signIn.id || signIn.id !== nativeSignIn.id) {
- return errorThrower.throw(
- 'Unable to synchronize biometric sign-in with the Clerk JS client: the sign-in attempt does not match.',
- );
- }
-
- return {
- status: isComplete ? nativeSignIn.status : (signIn.status ?? nativeSignIn.status),
- createdSessionId: isComplete
- ? nativeSignIn.createdSessionId
- : (signIn.createdSessionId ?? nativeSignIn.createdSessionId),
- signIn,
- setActive: clerk.setActive,
- };
- },
- };
-}
+import { createBiometricCredentials } from './createBiometricCredentials';
+import type { UseBiometricCredentialsReturn } from './types';
/**
* Accesses biometric credential enrollment, sign-in, and session reverification on iOS and Android.
*
- * The private key and biometric prompt are managed by Clerk's native SDK.
+ * Requires the `@clerk/expo-biometrics` package, which keeps the private key on the device, in a development build.
*/
export function useBiometricCredentials(): UseBiometricCredentialsReturn {
const clerk = useClerk();
diff --git a/packages/expo/src/biometric-credentials/useBiometricCredentials.ts b/packages/expo/src/biometric-credentials/useBiometricCredentials.ts
index bb3a824e016..bba07d38590 100644
--- a/packages/expo/src/biometric-credentials/useBiometricCredentials.ts
+++ b/packages/expo/src/biometric-credentials/useBiometricCredentials.ts
@@ -26,7 +26,8 @@ const biometricCredentials: UseBiometricCredentialsReturn = Object.freeze({
/**
* Accesses biometric credential enrollment, sign-in, and session reverification.
*
- * Biometric credentials are currently supported on iOS and Android.
+ * Biometric credentials are supported on iOS and Android. They require the `@clerk/expo-biometrics` package in a
+ * development build.
*/
export function useBiometricCredentials(): UseBiometricCredentialsReturn {
return biometricCredentials;
diff --git a/packages/expo/src/biometrics/index.ts b/packages/expo/src/biometrics/index.ts
new file mode 100644
index 00000000000..c0646273507
--- /dev/null
+++ b/packages/expo/src/biometrics/index.ts
@@ -0,0 +1 @@
+export * from '../biometric-credentials';
diff --git a/packages/expo/src/index.ts b/packages/expo/src/index.ts
index cefa57de840..aa9223501c0 100644
--- a/packages/expo/src/index.ts
+++ b/packages/expo/src/index.ts
@@ -13,7 +13,9 @@ export { getClerkInstance } from './provider/singleton';
export * from './provider/ClerkProvider';
export * from './hooks';
export * from './components';
-export * from './biometric-credentials';
+export * from './biometric-credentials/errors';
+export * from './biometric-credentials/types';
+export { useBiometricCredentials } from './biometric-credentials/deprecatedRootExport';
export * from './trusted-devices';
// Override Clerk React error thrower to show that errors come from @clerk/expo
diff --git a/packages/shared/src/types/authConfig.ts b/packages/shared/src/types/authConfig.ts
index e0919100434..a3156a02fc8 100644
--- a/packages/shared/src/types/authConfig.ts
+++ b/packages/shared/src/types/authConfig.ts
@@ -22,5 +22,20 @@ export interface AuthConfigResource extends ClerkResource {
*/
preferredChannels: Record | null;
sessionMinter: boolean;
+ /**
+ * Native application settings, such as trusted device (biometric) sign-in.
+ * @experimental
+ */
+ nativeSettings: NativeSettingsResource | null;
__internal_toSnapshot: () => AuthConfigJSONSnapshot;
}
+
+/**
+ * @experimental
+ */
+export interface NativeSettingsResource {
+ apiEnabled: boolean;
+ trustedDeviceSignInEnabled: boolean;
+ trustedDeviceEnrollmentPromptAfterSignInEnabled: boolean;
+ trustedDeviceEnrollmentPromptAfterSignUpEnabled: boolean;
+}
diff --git a/packages/shared/src/types/biometricCredential.ts b/packages/shared/src/types/biometricCredential.ts
new file mode 100644
index 00000000000..32c7174e047
--- /dev/null
+++ b/packages/shared/src/types/biometricCredential.ts
@@ -0,0 +1,98 @@
+import type { ClerkResource } from './resource';
+import type { BiometricCredentialJSONSnapshot } from './snapshots';
+
+/**
+ * The signing algorithm used by trusted device (biometric) credentials.
+ * @experimental
+ */
+export type TrustedDeviceAlgorithm = 'ES256';
+
+/**
+ * The native platform a biometric credential was enrolled on.
+ * @experimental
+ */
+export type BiometricCredentialPlatform = 'ios' | 'android';
+
+/**
+ * @experimental
+ */
+export type BiometricCredentialStatus = 'active' | 'revoked';
+
+/**
+ * A P-256 public key in JWK format.
+ * @experimental
+ */
+export type BiometricCredentialPublicKeyJWK = {
+ kty: 'EC';
+ crv: 'P-256';
+ x: string;
+ y: string;
+};
+
+/**
+ * A challenge issued by Clerk that must be signed with the device's private key.
+ * @experimental
+ */
+export interface TrustedDeviceChallengeResource {
+ challenge: string;
+ challengeId: string;
+ /**
+ * The ID of the trusted device the challenge was issued for. Only present on sign-in and session reverification challenges.
+ */
+ trustedDeviceId: string | null;
+ /**
+ * The exact string that must be signed by the device's private key.
+ */
+ clientData: string;
+ expiresAt: Date | null;
+ algorithm: TrustedDeviceAlgorithm;
+}
+
+/**
+ * A biometric credential (trusted device) enrolled by the current user on a native device.
+ * @experimental This is an experimental API for native apps and is subject to change.
+ */
+export interface BiometricCredentialResource extends ClerkResource {
+ id: string;
+ platform: BiometricCredentialPlatform;
+ appIdentifier: string;
+ name: string | null;
+ algorithm: TrustedDeviceAlgorithm;
+ status: BiometricCredentialStatus;
+ lastUsedAt: Date | null;
+ revokedAt: Date | null;
+ createdAt: Date;
+ updatedAt: Date;
+ __internal_toSnapshot: () => BiometricCredentialJSONSnapshot;
+}
+
+/**
+ * @experimental
+ */
+export type PrepareBiometricCredentialParams = {
+ platform: BiometricCredentialPlatform;
+ /**
+ * The iOS bundle identifier or Android package name of the app.
+ */
+ appIdentifier: string;
+ name?: string;
+ algorithm: TrustedDeviceAlgorithm;
+ /**
+ * The device public key as a JWK, or its JSON string.
+ */
+ publicKeyJwk: BiometricCredentialPublicKeyJWK | string;
+};
+
+/**
+ * @experimental
+ */
+export type AttemptBiometricCredentialParams = PrepareBiometricCredentialParams & {
+ /**
+ * The `clientData` string from the challenge returned by the prepare step.
+ */
+ clientData: string;
+ /**
+ * The base64url-encoded raw (r||s) signature of `clientData`.
+ */
+ signature: string;
+};
diff --git a/packages/shared/src/types/factors.ts b/packages/shared/src/types/factors.ts
index 765f76fbcaf..4531ebf7249 100644
--- a/packages/shared/src/types/factors.ts
+++ b/packages/shared/src/types/factors.ts
@@ -1,3 +1,4 @@
+import type { TrustedDeviceAlgorithm } from './biometricCredential';
import type { PublicKeyCredentialWithAuthenticatorAssertionResponse } from './passkey';
import type { PhoneCodeChannel } from './phoneCodeChannel';
import type {
@@ -12,6 +13,7 @@ import type {
ResetPasswordEmailCodeStrategy,
ResetPasswordPhoneCodeStrategy,
TOTPStrategy,
+ TrustedDeviceStrategy,
Web3Strategy,
} from './strategies';
@@ -333,6 +335,46 @@ export type PasskeyAttempt = {
publicKeyCredential: PublicKeyCredentialWithAuthenticatorAssertionResponse;
};
+/**
+ * @experimental
+ */
+export type TrustedDeviceConfig = {
+ /**
+ * The strategy type.
+ */
+ strategy: TrustedDeviceStrategy;
+ /**
+ * The ID of the trusted device (biometric credential) to verify with.
+ */
+ trustedDeviceId: string;
+};
+
+/**
+ * @experimental
+ */
+export type TrustedDeviceAttempt = {
+ /**
+ * The strategy type.
+ */
+ strategy: TrustedDeviceStrategy;
+ /**
+ * The ID of the trusted device (biometric credential) used to sign in or reverify the session.
+ */
+ trustedDeviceId: string;
+ /**
+ * The `clientData` string from the verification's `trustedDeviceChallenge`.
+ */
+ clientData: string;
+ /**
+ * The base64url-encoded raw (r||s) signature of `clientData`.
+ */
+ signature: string;
+ /**
+ * The signing algorithm.
+ */
+ algorithm: TrustedDeviceAlgorithm;
+};
+
/** @generateWithEmptyComment */
export type Web3Attempt = {
/**
diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.ts
index c8985107b0e..164dff618f8 100644
--- a/packages/shared/src/types/index.ts
+++ b/packages/shared/src/types/index.ts
@@ -5,6 +5,7 @@ export type * from './authConfig';
export type * from './authObject';
export type * from './backupCode';
export type * from './billing';
+export type * from './biometricCredential';
export type * from './clerk';
export type * from './client';
export type * from './commerceSettings';
diff --git a/packages/shared/src/types/json.ts b/packages/shared/src/types/json.ts
index 2128d95f8e2..9c0fd4e5cba 100644
--- a/packages/shared/src/types/json.ts
+++ b/packages/shared/src/types/json.ts
@@ -12,6 +12,11 @@ import type {
BillingSubscriptionPlanPeriod,
BillingSubscriptionStatus,
} from './billing';
+import type {
+ BiometricCredentialPlatform,
+ BiometricCredentialStatus,
+ TrustedDeviceAlgorithm,
+} from './biometricCredential';
import type { CommerceSettingsJSON } from './commerceSettings';
import type { DisplayConfigJSON } from './displayConfig';
import type { EnterpriseProtocol, EnterpriseProvider } from './enterpriseAccount';
@@ -360,6 +365,54 @@ export interface AuthConfigJSON extends ClerkResourceJSON {
reverification: boolean;
preferred_channels?: Record;
session_minter?: boolean;
+ /**
+ * @experimental
+ */
+ native_settings?: NativeSettingsJSON | null;
+}
+
+/**
+ * @experimental
+ */
+export interface NativeSettingsJSON {
+ object: 'native_settings';
+ api_enabled: boolean;
+ trusted_device_sign_in_enabled: boolean;
+ trusted_device_enrollment_prompt_after_sign_in_enabled: boolean;
+ trusted_device_enrollment_prompt_after_sign_up_enabled: boolean;
+}
+
+/**
+ * @experimental
+ */
+export interface TrustedDeviceChallengeJSON {
+ object: 'trusted_device_challenge';
+ challenge: string;
+ challenge_id: string;
+ trusted_device_id?: string;
+ client_data: string;
+ /**
+ * Unix timestamp in seconds.
+ */
+ expires_at: number;
+ algorithm: TrustedDeviceAlgorithm;
+}
+
+/**
+ * @experimental
+ */
+export interface BiometricCredentialJSON extends ClerkResourceJSON {
+ object: 'trusted_device';
+ id: string;
+ platform: BiometricCredentialPlatform;
+ app_identifier: string;
+ name: string | null;
+ algorithm: TrustedDeviceAlgorithm;
+ status: BiometricCredentialStatus;
+ created_at: number;
+ updated_at: number;
+ last_used_at: number | null;
+ revoked_at: number | null;
}
export interface VerificationJSON extends ClerkResourceJSON {
@@ -373,6 +426,10 @@ export interface VerificationJSON extends ClerkResourceJSON {
expire_at: number;
channel?: PhoneCodeChannel;
error: ClerkAPIErrorJSON;
+ /**
+ * @experimental
+ */
+ trusted_device_challenge?: TrustedDeviceChallengeJSON | null;
}
export interface SignUpVerificationsJSON {
diff --git a/packages/shared/src/types/session.ts b/packages/shared/src/types/session.ts
index 878fd6e8ecb..a492a586be0 100644
--- a/packages/shared/src/types/session.ts
+++ b/packages/shared/src/types/session.ts
@@ -11,6 +11,8 @@ import type {
PhoneCodeConfig,
PhoneCodeSecondFactorConfig,
TOTPAttempt,
+ TrustedDeviceAttempt,
+ TrustedDeviceConfig,
} from './factors';
import type { ActClaim, AgentActClaim } from './jwtv2';
import type {
@@ -532,13 +534,33 @@ export type SessionVerifyPrepareFirstFactorParams =
/**
* @experimental
*/
- | Omit;
+ | Omit
+ /**
+ * @experimental
+ */
+ | TrustedDeviceConfig;
export type SessionVerifyAttemptFirstFactorParams =
| EmailCodeAttempt
| PhoneCodeAttempt
| PasswordAttempt
- | PasskeyAttempt;
+ | PasskeyAttempt
+ /**
+ * @experimental
+ */
+ | TrustedDeviceAttempt;
-export type SessionVerifyPrepareSecondFactorParams = PhoneCodeSecondFactorConfig;
-export type SessionVerifyAttemptSecondFactorParams = PhoneCodeAttempt | TOTPAttempt | BackupCodeAttempt;
+export type SessionVerifyPrepareSecondFactorParams =
+ | PhoneCodeSecondFactorConfig
+ /**
+ * @experimental
+ */
+ | TrustedDeviceConfig;
+export type SessionVerifyAttemptSecondFactorParams =
+ | PhoneCodeAttempt
+ | TOTPAttempt
+ | BackupCodeAttempt
+ /**
+ * @experimental
+ */
+ | TrustedDeviceAttempt;
diff --git a/packages/shared/src/types/signInCommon.ts b/packages/shared/src/types/signInCommon.ts
index 844376484f2..922686321bc 100644
--- a/packages/shared/src/types/signInCommon.ts
+++ b/packages/shared/src/types/signInCommon.ts
@@ -28,6 +28,7 @@ import type {
ResetPasswordPhoneCodeFactorConfig,
TOTPAttempt,
TOTPFactor,
+ TrustedDeviceAttempt,
Web3Attempt,
Web3SignatureConfig,
Web3SignatureFactor,
@@ -53,6 +54,7 @@ import type {
ResetPasswordPhoneCodeStrategy,
TicketStrategy,
TOTPStrategy,
+ TrustedDeviceStrategy,
Web3Strategy,
} from './strategies';
import type { StartEmailLinkFlowParams } from './verification';
@@ -113,7 +115,8 @@ export type AttemptFirstFactorParams =
| PasswordAttempt
| Web3Attempt
| ResetPasswordPhoneCodeAttempt
- | ResetPasswordEmailCodeAttempt;
+ | ResetPasswordEmailCodeAttempt
+ | TrustedDeviceAttempt;
export type PrepareSecondFactorParams = PhoneCodeSecondFactorConfig | EmailCodeSecondFactorConfig | EmailLinkConfig;
@@ -146,6 +149,13 @@ export type SignInCreateParams = (
identifier: string;
}
| { strategy: PasskeyStrategy }
+ | {
+ /**
+ * @experimental
+ */
+ strategy: TrustedDeviceStrategy;
+ trustedDeviceId: string;
+ }
| {
strategy:
| PhoneCodeStrategy
@@ -201,7 +211,8 @@ export type SignInStrategy =
| TOTPStrategy
| BackupCodeStrategy
| OAuthStrategy
- | EnterpriseSSOStrategy;
+ | EnterpriseSSOStrategy
+ | TrustedDeviceStrategy;
export interface SignInAuthenticateWithSolanaParams {
walletName: string;
diff --git a/packages/shared/src/types/snapshots.ts b/packages/shared/src/types/snapshots.ts
index a1d239c329f..fafb7c91264 100644
--- a/packages/shared/src/types/snapshots.ts
+++ b/packages/shared/src/types/snapshots.ts
@@ -5,6 +5,7 @@ import type { CommerceSettingsJSON } from './commerceSettings';
import type { DisplayConfigJSON } from './displayConfig';
import type {
AuthConfigJSON,
+ BiometricCredentialJSON,
ClientJSON,
ClientTrustState,
EmailAddressJSON,
@@ -146,6 +147,8 @@ export type OrganizationSettingsJSONSnapshot = OrganizationSettingsJSON;
export type OrganizationCreationDefaultsJSONSnapshot = OrganizationCreationDefaultsJSON;
+export type BiometricCredentialJSONSnapshot = BiometricCredentialJSON;
+
export type PasskeyJSONSnapshot = Override;
export type PhoneNumberJSONSnapshot = Override<
diff --git a/packages/shared/src/types/strategies.ts b/packages/shared/src/types/strategies.ts
index 2055c1a5056..b47b321a84b 100644
--- a/packages/shared/src/types/strategies.ts
+++ b/packages/shared/src/types/strategies.ts
@@ -7,6 +7,11 @@ export type GoogleOneTapStrategy = 'google_one_tap';
export type AppleIdTokenStrategy = 'oauth_token_apple';
/** @inline */
export type PasskeyStrategy = 'passkey';
+/**
+ * @experimental
+ * @inline
+ */
+export type TrustedDeviceStrategy = 'trusted_device';
/** @inline */
export type PasswordStrategy = 'password';
/** @inline */
diff --git a/packages/shared/src/types/user.ts b/packages/shared/src/types/user.ts
index 3bd639571d3..1d935a5ab98 100644
--- a/packages/shared/src/types/user.ts
+++ b/packages/shared/src/types/user.ts
@@ -1,5 +1,11 @@
import type { BackupCodeResource } from './backupCode';
import type { BillingPayerMethods } from './billing';
+import type {
+ AttemptBiometricCredentialParams,
+ BiometricCredentialResource,
+ PrepareBiometricCredentialParams,
+ TrustedDeviceChallengeResource,
+} from './biometricCredential';
import type { DeletedObjectResource } from './deletedObject';
import type { EmailAddressResource } from './emailAddress';
import type { EnterpriseAccountResource } from './enterpriseAccount';
@@ -334,6 +340,30 @@ export interface UserResource extends ClerkResource, BillingPayerMethods {
* @returns A [`BackupCodeResource`](https://clerk.com/docs/reference/types/backup-code-resource) object.
*/
createBackupCode: () => Promise;
+ /**
+ * Lists the biometric credentials (trusted devices) enrolled by the user.
+ * @experimental This is an experimental API for native apps and is subject to change.
+ */
+ __experimental_getBiometricCredentials: () => Promise;
+ /**
+ * Starts enrolling a biometric credential and returns the challenge the device must sign. Requires a recently verified session.
+ * @experimental This is an experimental API for native apps and is subject to change.
+ */
+ __experimental_prepareBiometricCredential: (
+ params: PrepareBiometricCredentialParams,
+ ) => Promise;
+ /**
+ * Completes enrolling a biometric credential with the signed challenge.
+ * @experimental This is an experimental API for native apps and is subject to change.
+ */
+ __experimental_attemptBiometricCredential: (
+ params: AttemptBiometricCredentialParams,
+ ) => Promise;
+ /**
+ * Revokes one of the user's biometric credentials. Requires a recently verified session.
+ * @experimental This is an experimental API for native apps and is subject to change.
+ */
+ __experimental_revokeBiometricCredential: (biometricCredentialId: string) => Promise;
get verifiedExternalAccounts(): ExternalAccountResource[];
diff --git a/packages/shared/src/types/verification.ts b/packages/shared/src/types/verification.ts
index 4f1d3fe0863..8b4087099e4 100644
--- a/packages/shared/src/types/verification.ts
+++ b/packages/shared/src/types/verification.ts
@@ -1,3 +1,4 @@
+import type { TrustedDeviceChallengeResource } from './biometricCredential';
import type { ClerkAPIError } from './errors';
import type { PublicKeyCredentialCreationOptionsWithoutExtensions } from './passkey';
import type { PhoneCodeChannel } from './phoneCodeChannel';
@@ -16,6 +17,11 @@ export interface VerificationResource extends ClerkResource {
verifiedAtClient: string | null;
verifiedFromTheSameClient: () => boolean;
channel?: PhoneCodeChannel;
+ /**
+ * The challenge to sign when the verification uses the `trusted_device` strategy.
+ * @experimental
+ */
+ trustedDeviceChallenge?: TrustedDeviceChallengeResource | null;
__internal_toSnapshot: () => VerificationJSONSnapshot;
}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2ac1019b40b..a9c773b275d 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -653,6 +653,9 @@ importers:
specifier: catalog:repo
version: 2.8.1
devDependencies:
+ '@clerk/expo-biometrics':
+ specifier: workspace:*
+ version: link:../expo-biometrics
'@clerk/expo-google-signin':
specifier: workspace:*
version: link:../expo-google-signin
@@ -693,6 +696,12 @@ importers:
specifier: ^0.86.0
version: 0.86.0(@babel/core@7.29.7)(@react-native-community/cli@12.3.7(bufferutil@4.1.0)(utf-8-validate@5.0.10))(@types/react@18.3.28)(bufferutil@4.1.0)(react@18.3.1)(utf-8-validate@5.0.10)
+ packages/expo-biometrics:
+ devDependencies:
+ expo:
+ specifier: ~54.0.36
+ version: 54.0.36(@babel/core@7.29.7)(bufferutil@4.1.0)(graphql@16.14.1)(react-native@0.86.0(@babel/core@7.29.7)(@react-native-community/cli@12.3.7(bufferutil@4.1.0)(utf-8-validate@5.0.10))(@types/react@18.3.28)(bufferutil@4.1.0)(react@18.3.1)(utf-8-validate@5.0.10))(react@18.3.1)(typescript@5.9.3)(utf-8-validate@5.0.10)
+
packages/expo-google-signin:
devDependencies:
'@expo/config-plugins':