feat(expo): add biometric reverification

.changeset/biometric-session-reverification.md

@@ -0,0 +1,7 @@
+---
+'@clerk/expo': minor
+---
+
+Add `useBiometricCredentials().reverify()` for first-, second-, and multi-factor verification of the active session on iOS and Android. If the first factor still requires a second factor, reverification continues the same attempt automatically. Successful verification refreshes the JavaScript session token without creating a new session.
+
+New biometric enrollments default to `biometry_current_set`, requiring biometrics without device-passcode fallback. Existing credentials keep their original policy; reverification on iOS and Android requires the stronger policy and returns `biometric_credential_policy_incompatible` for older, weaker credentials. Apps should offer another verification method in that case. Reverification requires an updated native development build.

packages/expo/README.md

@@ -48,49 +48,6 @@ You'll learn how to create an Expo application, install `@clerk/expo`, set up yo
 
 For further information, guides, and examples visit the [Expo reference documentation](https://clerk.com/docs/references/expo/overview?utm_source=github&utm_medium=clerk_expo).
 
-### Biometric sign-in
-
-Biometric credential enrollment and sign-in are supported in development builds on iOS and Android. Android requires Android 9 (API 28) or later and an enrolled Class 3 biometric.
-
-Biometric credential operations preserve Clerk API and native biometric error codes. Use `isBiometricCredentialError(error)` to safely inspect `error.code`; unrecognized error codes remain available for forward compatibility, while unfamiliar platform and status values are normalized to `unknown`.
-
-`useTrustedDevices()` and the trusted-device types remain available as deprecated compatibility aliases. New code should use `useBiometricCredentials()` and the biometric credential types; the previous `deviceName` enrollment option is forwarded to `name`.
-
-#### Face ID on iOS
-
-Apps that use Face ID for biometric credential enrollment or sign-in must provide `NSFaceIDUsageDescription`. You can have the Clerk config plugin add it during prebuild:
-
-```json
-{
-  "expo": {
-    "plugins": [
-      [
-        "@clerk/expo",
-        {
-          "faceIDPermission": "Allow $(PRODUCT_NAME) to use Face ID for secure sign-in."
-        }
-      ]
-    ]
-  }
-}
-```
-
-The plugin only adds the permission when `faceIDPermission` is provided and does not overwrite `ios.infoPlist.NSFaceIDUsageDescription` if your app already defines it.
-
-You can also configure the key directly:
-
-```json
-{
-  "expo": {
-    "ios": {
-      "infoPlist": {
-        "NSFaceIDUsageDescription": "Allow $(PRODUCT_NAME) to use Face ID for secure sign-in."
-      }
-    }
-  }
-}
-```
-
 ## Support
 
 For help, visit our [support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_expo).

packages/expo/android/src/main/java/expo/modules/clerk/ClerkExpoModule.kt

@@ -18,6 +18,9 @@ import com.clerk.api.biometriccredential.BiometricCredential
 import com.clerk.api.biometriccredential.BiometricCredentialAvailability
 import com.clerk.api.biometriccredential.BiometricCredentialKeyManagerException
 import com.clerk.api.biometriccredential.BiometricCredentialPolicy
+import com.clerk.api.session.SessionVerification
+import com.clerk.api.session.startVerification
+import com.clerk.api.session.verifyWithBiometrics
 import com.clerk.api.ui.ClerkColors
 import com.clerk.api.ui.ClerkDesign
 import com.clerk.api.ui.ClerkTheme
@@ -28,6 +31,8 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.TimeoutCancellationException
+import kotlinx.coroutines.currentCoroutineContext
+import kotlinx.coroutines.ensureActive
 import kotlinx.coroutines.flow.combine
 import kotlinx.coroutines.flow.distinctUntilChanged
 import kotlinx.coroutines.flow.first
@@ -103,6 +108,43 @@ internal fun biometricCredentialPolicy(policy: String): BiometricCredentialPolic
     }
 }
 
+internal fun biometricReverificationLevel(level: String): SessionVerification.Level? = when (level) {
+    "first_factor" -> SessionVerification.Level.FIRST_FACTOR
+    "second_factor" -> SessionVerification.Level.SECOND_FACTOR
+    "multi_factor" -> SessionVerification.Level.MULTI_FACTOR
+    else -> null
+}
+
+internal fun biometricReverificationPayload(
+    verification: SessionVerification,
+    sessionId: String
+): Map<String, Any?> = mapOf(
+    "id" to verification.id,
+    "status" to verification.status.name.lowercase(),
+    "level" to verification.level.value,
+    "sessionId" to (verification.session?.id ?: sessionId)
+)
+
+internal suspend fun verifyBiometricReverification(
+    started: SessionVerification,
+    verify: suspend (SessionVerification.Level) -> ClerkResult<SessionVerification, ClerkErrorResponse>
+): ClerkResult<SessionVerification, ClerkErrorResponse> = when (started.status) {
+    SessionVerification.Status.NEEDS_FIRST_FACTOR -> {
+        val result = verify(SessionVerification.Level.FIRST_FACTOR)
+        if (result is ClerkResult.Success && result.value.status == SessionVerification.Status.NEEDS_SECOND_FACTOR) {
+            currentCoroutineContext().ensureActive()
+            verify(SessionVerification.Level.SECOND_FACTOR)
+        } else {
+            result
+        }
+    }
+    SessionVerification.Status.NEEDS_SECOND_FACTOR -> verify(SessionVerification.Level.SECOND_FACTOR)
+    SessionVerification.Status.COMPLETE -> ClerkResult.success(started)
+    SessionVerification.Status.UNKNOWN -> ClerkResult.unknownFailure(
+        IllegalStateException("The server returned an unsupported reverification status.")
+    )
+}
+
 internal data class BiometricCredentialBridgeError(
     val code: String,
     val message: String
@@ -271,6 +313,14 @@ class ClerkExpoModule : Module() {
                 promise: Promise ->
             signInWithBiometrics(id, identifierHint, reason, promise)
         }
+
+        AsyncFunction("reverifyWithBiometrics") {
+                sessionId: String,
+                level: String,
+                reason: String?,
+                promise: Promise ->
+            reverifyWithBiometrics(sessionId, level, reason, promise)
+        }
     }
 
     private val reactContext: Context?
@@ -756,6 +806,54 @@ class ClerkExpoModule : Module() {
         }
     }
 
+    private fun reverifyWithBiometrics(
+        sessionId: String,
+        level: String,
+        reason: String?,
+        promise: Promise
+    ) {
+        if (!requireBiometricCredentialEnvironment(promise)) return
+        val requestedLevel = biometricReverificationLevel(level)
+        if (requestedLevel == null) {
+            promise.reject("invalid_reverification_level", "Invalid biometric reverification level: $level", null)
+            return
+        }
+        coroutineScope.launch {
+            try {
+                val session = Clerk.clientFlow.value?.sessions?.firstOrNull { it.id == sessionId }
+                if (session == null) {
+                    promise.reject(
+                        "biometric_reverification_session_unavailable",
+                        "The session to reverify is unavailable in the native Clerk client.",
+                        null
+                    )
+                    return@launch
+                }
+                if (!attachCurrentActivityForBiometricCredential(promise)) return@launch
+                val started = when (val result = session.startVerification(requestedLevel)) {
+                    is ClerkResult.Success -> result.value
+                    is ClerkResult.Failure -> {
+                        rejectBiometricCredentialFailure(promise, "E_BIOMETRIC_REVERIFICATION_FAILED",
+                            "Unable to start biometric reverification", result)
+                        return@launch
+                    }
+                }
+                val result = verifyBiometricReverification(started) { factor ->
+                    session.verifyWithBiometrics(promptSubtitle = reason, level = factor)
+                }
+                when (result) {
+                    is ClerkResult.Success -> promise.resolve(biometricReverificationPayload(result.value, sessionId))
+                    is ClerkResult.Failure -> rejectBiometricCredentialFailure(
+                        promise, "E_BIOMETRIC_REVERIFICATION_FAILED", "Unable to reverify with biometrics", result
+                    )
+                }
+            } catch (e: Exception) {
+                rejectBiometricCredentialException(promise, "E_BIOMETRIC_REVERIFICATION_FAILED",
+                    "Unable to reverify with biometrics", e)
+            }
+        }
+    }
+
     private fun requireBiometricCredentialEnvironment(promise: Promise): Boolean {
         val error = biometricCredentialEnvironmentError(Clerk.isInitialized.value) ?: return true
         promise.reject(error.code, error.message, null)

packages/expo/android/src/test/java/expo/modules/clerk/BiometricCredentialBridgeTest.kt

@@ -8,11 +8,137 @@ import com.clerk.api.biometriccredential.BiometricCredential
 import com.clerk.api.biometriccredential.BiometricCredentialAvailability
 import com.clerk.api.biometriccredential.BiometricCredentialKeyManagerException
 import com.clerk.api.biometriccredential.BiometricCredentialPolicy
+import com.clerk.api.session.SessionVerification
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.currentCoroutineContext
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.runBlocking
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertNull
+import org.junit.Assert.assertSame
+import org.junit.Assert.assertTrue
 import org.junit.Test
 
 class BiometricCredentialBridgeTest {
+    @Test
+    fun `continues the same attempt when the first factor requires a second factor`() = runBlocking {
+        val factors = mutableListOf<SessionVerification.Level>()
+        val started = SessionVerification(id = "stepup_test", status = SessionVerification.Status.NEEDS_FIRST_FACTOR,
+            level = SessionVerification.Level.MULTI_FACTOR)
+        val result = verifyBiometricReverification(started) { factor ->
+            factors.add(factor)
+            ClerkResult.success(started.copy(status = if (factor == SessionVerification.Level.FIRST_FACTOR)
+                SessionVerification.Status.NEEDS_SECOND_FACTOR else SessionVerification.Status.COMPLETE))
+        }
+        assertEquals(listOf(SessionVerification.Level.FIRST_FACTOR, SessionVerification.Level.SECOND_FACTOR), factors)
+        assertTrue(result is ClerkResult.Success)
+        assertEquals(started.id, (result as ClerkResult.Success).value.id)
+        assertEquals(SessionVerification.Status.COMPLETE, result.value.status)
+    }
+
+    @Test
+    fun `prompts only for the factors still required`() = runBlocking {
+        for (status in listOf(SessionVerification.Status.NEEDS_FIRST_FACTOR,
+            SessionVerification.Status.NEEDS_SECOND_FACTOR, SessionVerification.Status.COMPLETE)) {
+            val factors = mutableListOf<SessionVerification.Level>()
+            val started = SessionVerification(status = status, level = SessionVerification.Level.MULTI_FACTOR)
+            val result = verifyBiometricReverification(started) { factor ->
+                factors.add(factor)
+                ClerkResult.success(started.copy(status = SessionVerification.Status.COMPLETE))
+            }
+            val expected = when (status) {
+                SessionVerification.Status.NEEDS_FIRST_FACTOR -> listOf(SessionVerification.Level.FIRST_FACTOR)
+                SessionVerification.Status.NEEDS_SECOND_FACTOR -> listOf(SessionVerification.Level.SECOND_FACTOR)
+                else -> emptyList()
+            }
+            assertEquals(expected, factors)
+            assertEquals(SessionVerification.Status.COMPLETE, (result as ClerkResult.Success).value.status)
+        }
+    }
+
+    @Test
+    fun `does not retry an incomplete second factor`() = runBlocking {
+        val factors = mutableListOf<SessionVerification.Level>()
+        val started = SessionVerification(status = SessionVerification.Status.NEEDS_FIRST_FACTOR,
+            level = SessionVerification.Level.MULTI_FACTOR)
+        val result = verifyBiometricReverification(started) { factor ->
+            factors.add(factor)
+            ClerkResult.success(started.copy(status = SessionVerification.Status.NEEDS_SECOND_FACTOR))
+        }
+        assertEquals(listOf(SessionVerification.Level.FIRST_FACTOR, SessionVerification.Level.SECOND_FACTOR), factors)
+        assertEquals(SessionVerification.Status.NEEDS_SECOND_FACTOR, (result as ClerkResult.Success).value.status)
+    }
+
+    @Test
+    fun `preserves first and second factor failures`() = runBlocking {
+        for (failingFactor in listOf(SessionVerification.Level.FIRST_FACTOR, SessionVerification.Level.SECOND_FACTOR)) {
+            val factors = mutableListOf<SessionVerification.Level>()
+            val failure = ClerkResult.apiFailure(ClerkErrorResponse(errors = listOf(
+                ClerkAPIError(code = "biometric_authentication_canceled", message = "Canceled")
+            )))
+            val started = SessionVerification(status = SessionVerification.Status.NEEDS_FIRST_FACTOR,
+                level = SessionVerification.Level.MULTI_FACTOR)
+            val result = verifyBiometricReverification(started) { factor ->
+                factors.add(factor)
+                if (factor == failingFactor) failure else
+                    ClerkResult.success(started.copy(status = SessionVerification.Status.NEEDS_SECOND_FACTOR))
+            }
+            assertSame(failure, result)
+            assertEquals(if (failingFactor == SessionVerification.Level.FIRST_FACTOR)
+                listOf(SessionVerification.Level.FIRST_FACTOR) else
+                listOf(SessionVerification.Level.FIRST_FACTOR, SessionVerification.Level.SECOND_FACTOR), factors)
+        }
+    }
+
+    @Test
+    fun `cancellation between factors stops continuation`() = runBlocking {
+        val factors = mutableListOf<SessionVerification.Level>()
+        val job = launch {
+            verifyBiometricReverification(SessionVerification(status = SessionVerification.Status.NEEDS_FIRST_FACTOR,
+                level = SessionVerification.Level.MULTI_FACTOR)) { factor ->
+                factors.add(factor)
+                currentCoroutineContext().cancel()
+                ClerkResult.success(SessionVerification(status = SessionVerification.Status.NEEDS_SECOND_FACTOR,
+                    level = SessionVerification.Level.MULTI_FACTOR))
+            }
+        }
+        job.join()
+        assertTrue(job.isCancelled)
+        assertEquals(listOf(SessionVerification.Level.FIRST_FACTOR), factors)
+    }
+
+    @Test
+    fun `unknown verification status does not prompt`() = runBlocking {
+        val result = verifyBiometricReverification(SessionVerification(status = SessionVerification.Status.UNKNOWN,
+            level = SessionVerification.Level.MULTI_FACTOR)) {
+            throw AssertionError("Unknown verification status must not prompt")
+        }
+        assertTrue(result is ClerkResult.Failure)
+    }
+
+    @Test
+    fun `maps biometric reverification requirements`() {
+        assertEquals(SessionVerification.Level.FIRST_FACTOR, biometricReverificationLevel("first_factor"))
+        assertEquals(SessionVerification.Level.SECOND_FACTOR, biometricReverificationLevel("second_factor"))
+        assertEquals(SessionVerification.Level.MULTI_FACTOR, biometricReverificationLevel("multi_factor"))
+        assertNull(biometricReverificationLevel("unknown"))
+    }
+
+    @Test
+    fun `maps reverification results without creating a session`() {
+        val result = SessionVerification(
+            id = "stepup_test",
+            status = SessionVerification.Status.COMPLETE,
+            level = SessionVerification.Level.MULTI_FACTOR
+        )
+        assertEquals(mapOf(
+            "id" to "stepup_test",
+            "status" to "complete",
+            "level" to "multi_factor",
+            "sessionId" to "sess_test"
+        ), biometricReverificationPayload(result, "sess_test"))
+    }
+
     private fun keyManagerException(
         code: BiometricCredentialKeyManagerException.Code,
         message: String

packages/expo/ios/ClerkExpoModule.swift

@@ -100,6 +100,26 @@ public class ClerkExpoModule: Module {
         promise: promise
       )
     }
+
+    AsyncFunction("reverifyWithBiometrics") {
+      (sessionId: String, level: String, reason: String?, promise: Promise) in
+      Task { @MainActor in
+        do {
+          let verification = try await ClerkNativeBridge.shared.reverifyWithBiometrics(
+            sessionId: sessionId,
+            level: level,
+            reason: reason
+          )
+          promise.resolve(verification)
+        } catch {
+          self.rejectBiometricCredentialError(
+            error,
+            fallbackCode: "E_BIOMETRIC_REVERIFICATION_FAILED",
+            promise: promise
+          )
+        }
+      }
+    }
   }
 
   // MARK: - configure