@algorandfoundation/react-native-passkey-autofill 1.0.0-canary.2 → 1.0.0-canary.21

package/android/src/main/java/co/algorand/passkeyautofill/Prf.kt

@@ -0,0 +1,184 @@
+package co.algorand.passkeyautofill
+
+import android.util.Base64 as AndroidBase64
+import java.security.MessageDigest
+import javax.crypto.Mac
+import javax.crypto.spec.SecretKeySpec
+import org.json.JSONObject
+
+/**
+ * WebAuthn PRF (`prf`) extension helpers, backed by the authenticator
+ * `hmac-secret` mechanism (CTAP2.1).
+ *
+ * Output formula per the WebAuthn spec:
+ *
+ *     output = HMAC-SHA256(credRandom, SHA256("WebAuthn PRF" || 0x00 || salt))
+ *
+ * `credRandom` is a per-credential 32-byte secret. We derive it
+ * deterministically (HKDF-SHA256) from the wallet HD root secret, the
+ * relying-party identifier, and the user handle — the same inputs that
+ * produce the deterministic signing key. This avoids a storage migration
+ * and ensures restoring the wallet seed reproduces the same PRF outputs
+ * on another device.
+ */
+object Prf {
+  private const val CRED_RANDOM_INFO = "WebAuthn-PRF-credRandom"
+  private val SALT_PREFIX: ByteArray = "WebAuthn PRF".toByteArray(Charsets.UTF_8) + byteArrayOf(0x00)
+
+  /**
+   * Derive a 32-byte per-credential PRF secret from the HD root secret.
+   * Deterministic over `(hdRootSecret, rpId, userHandle)`.
+   */
+  fun credRandom(
+    hdRootSecret: ByteArray,
+    relyingPartyIdentifier: String,
+    userHandle: String,
+  ): ByteArray {
+    val salt = relyingPartyIdentifier.lowercase().toByteArray(Charsets.UTF_8) +
+      byteArrayOf(0x00) +
+      userHandle.lowercase().toByteArray(Charsets.UTF_8)
+    return hkdfSha256(
+      ikm = hdRootSecret,
+      salt = salt,
+      info = CRED_RANDOM_INFO.toByteArray(Charsets.UTF_8),
+      length = 32,
+    )
+  }
+
+  /**
+   * Evaluate the PRF for a single salt. Returns 32 bytes of output material.
+   *
+   * Per the WebAuthn spec the value the authenticator HMACs is
+   * `SHA-256("WebAuthn PRF" || 0x00 || rpSalt)`. The Chromium-on-Android
+   * client manager performs this hashing on behalf of the RP and passes the
+   * result through the `prfAlreadyHashed` extension; in that case the
+   * `salt` is already the inner hash and we must NOT hash again. Standard
+   * `prf` requests send the raw RP salt and require hashing.
+   */
+  fun evaluate(credRandom: ByteArray, salt: ByteArray, alreadyHashed: Boolean = true): ByteArray {
+    val macInput = if (alreadyHashed) {
+      salt
+    } else {
+      MessageDigest.getInstance("SHA-256").digest(SALT_PREFIX + salt)
+    }
+    val mac = Mac.getInstance("HmacSHA256").apply {
+      init(SecretKeySpec(credRandom, "HmacSHA256"))
+    }
+    return mac.doFinal(macInput)
+  }
+
+  /**
+   * Parsed PRF inputs from the relying party. Reduced to at most two salts
+   * (first + optional second) — already resolved against `evalByCredential`
+   * for the credential the user is asserting with.
+   *
+   * @property alreadyHashed `true` when the salts have already been passed
+   *   through `SHA-256("WebAuthn PRF" || 0x00 || ...)` by the platform (the
+   *   case for both the Chromium `prfAlreadyHashed` extension on Android
+   *   and Apple's `ASAuthorizationPublicKeyCredentialPRFAssertionInput`).
+   */
+  data class Input(val first: ByteArray, val second: ByteArray?, val alreadyHashed: Boolean)
+
+  /**
+   * Parse PRF eval salts out of a WebAuthn request JSON.
+   *
+   * Recognises:
+   *  - `extensions.prf.eval` / `extensions.prf.evalByCredential[<credId>]`
+   *    — raw RP-supplied salts that still need to be hashed before HMAC.
+   *  - `extensions.prfAlreadyHashed.eval` /
+   *    `extensions.prfAlreadyHashed.evalByCredential[<credId>]` — Chromium
+   *    on Android emits this when forwarding a `prf` request to a credential
+   *    provider so the provider doesn't need to know the spec-mandated hash
+   *    prefix. The salts here are already 32-byte SHA-256 outputs and must
+   *    not be re-hashed.
+   *
+   * @param requestJson the inner `publicKey` request JSON object.
+   * @param credentialIdB64Url base64url-encoded credentialId we're asserting
+   *   with (used to look up the per-credential salts).
+   */
+  fun parseInput(requestJson: JSONObject, credentialIdB64Url: String?): Input? {
+    val extensions = requestJson.optJSONObject("extensions") ?: return null
+
+    // Pre-hashed form wins — when Chromium sends both for compatibility,
+    // honour the already-hashed values to match what the browser expects.
+    extensions.optJSONObject("prfAlreadyHashed")?.let { node ->
+      parseExtensionNode(node, credentialIdB64Url, alreadyHashed = true)?.let { return it }
+    }
+    extensions.optJSONObject("prf")?.let { node ->
+      parseExtensionNode(node, credentialIdB64Url, alreadyHashed = false)?.let { return it }
+    }
+    return null
+  }
+
+  private fun parseExtensionNode(
+    node: JSONObject,
+    credentialIdB64Url: String?,
+    alreadyHashed: Boolean,
+  ): Input? {
+    // Per-credential salts win over the global `eval` block.
+    if (credentialIdB64Url != null) {
+      val byCred = node.optJSONObject("evalByCredential")
+      if (byCred != null) {
+        for (key in byCred.keys()) {
+          if (normalizeBase64Url(key) == normalizeBase64Url(credentialIdB64Url)) {
+            byCred.optJSONObject(key)?.let { return parseSalts(it, alreadyHashed) }
+          }
+        }
+      }
+    }
+    return node.optJSONObject("eval")?.let { parseSalts(it, alreadyHashed) }
+  }
+
+  private fun parseSalts(obj: JSONObject, alreadyHashed: Boolean): Input? {
+    val first = obj.optString("first", "").takeIf { it.isNotEmpty() } ?: return null
+    val firstBytes = decodeBase64UrlOrBase64(first)
+    val secondBytes = obj.optString("second", "")
+      .takeIf { it.isNotEmpty() }
+      ?.let { decodeBase64UrlOrBase64(it) }
+    return Input(firstBytes, secondBytes, alreadyHashed)
+  }
+
+  private fun normalizeBase64Url(value: String): String =
+    value.trim().trimEnd('=').replace('+', '-').replace('/', '_')
+
+  private fun decodeBase64UrlOrBase64(value: String): ByteArray {
+    val flags = AndroidBase64.URL_SAFE or AndroidBase64.NO_WRAP or AndroidBase64.NO_PADDING
+    return try {
+      AndroidBase64.decode(value, flags)
+    } catch (e: IllegalArgumentException) {
+      AndroidBase64.decode(value, AndroidBase64.NO_WRAP)
+    }
+  }
+
+  /** Encode a 32-byte PRF output for inclusion in a WebAuthn response JSON. */
+  fun encodeOutput(bytes: ByteArray): String =
+    AndroidBase64.encodeToString(bytes, AndroidBase64.URL_SAFE or AndroidBase64.NO_WRAP or AndroidBase64.NO_PADDING)
+
+  // RFC 5869 HKDF-SHA256.
+  private fun hkdfSha256(ikm: ByteArray, salt: ByteArray, info: ByteArray, length: Int): ByteArray {
+    val mac = Mac.getInstance("HmacSHA256")
+    val effectiveSalt = if (salt.isEmpty()) ByteArray(32) else salt
+    // Extract.
+    mac.init(SecretKeySpec(effectiveSalt, "HmacSHA256"))
+    val prk = mac.doFinal(ikm)
+    // Expand.
+    mac.init(SecretKeySpec(prk, "HmacSHA256"))
+    val output = ByteArray(length)
+    var t = ByteArray(0)
+    var offset = 0
+    var counter: Byte = 1
+    while (offset < length) {
+      mac.reset()
+      mac.init(SecretKeySpec(prk, "HmacSHA256"))
+      mac.update(t)
+      mac.update(info)
+      mac.update(counter)
+      t = mac.doFinal()
+      val take = minOf(t.size, length - offset)
+      System.arraycopy(t, 0, output, offset, take)
+      offset += take
+      counter++
+    }
+    return output
+  }
+}

package/android/src/main/java/co/algorand/passkeyautofill/ReactNativePasskeyAutofillModule.kt

@@ -3,8 +3,13 @@ package co.algorand.passkeyautofill
 import expo.modules.kotlin.modules.Module
 import expo.modules.kotlin.modules.ModuleDefinition
 import co.algorand.passkeyautofill.credentials.CredentialRepository
-import com.tencent.mmkv.MMKV
+import co.algorand.passkeyautofill.service.PasskeyAutofillCredentialProviderService
+import android.content.ComponentName
 import android.content.Context
+import android.content.Intent
+import android.net.Uri
+import android.os.Build
+import android.provider.Settings
 import android.util.Log
 import org.bouncycastle.jce.provider.BouncyCastleProvider
 import java.security.Security
@@ -12,9 +17,13 @@ import java.security.Security
 class ReactNativePasskeyAutofillModule : Module() {
   private val credentialRepository = CredentialRepository()
 
+  companion object {
+    var instance: ReactNativePasskeyAutofillModule? = null
+  }
+
   init {
     Security.removeProvider(BouncyCastleProvider.PROVIDER_NAME)
-    Security.addProvider(BouncyCastleProvider())
+    Security.insertProviderAt(BouncyCastleProvider(), 1)
   }
 
   // Each module class must implement the definition function. The definition consists of components
@@ -26,6 +35,16 @@ class ReactNativePasskeyAutofillModule : Module() {
     // The module will be accessible from `requireNativeModule('ReactNativeLiquidAuth')` in JavaScript.
     Name("ReactNativePasskeyAutofill")
 
+    OnCreate {
+      instance = this@ReactNativePasskeyAutofillModule
+    }
+
+    OnDestroy {
+      instance = null
+    }
+
+    Events("onPasskeyAdded", "onPasskeyAuthenticated")
+
     AsyncFunction("setMasterKey") { secret: String ->
       val context = (appContext.reactContext ?: appContext.hostingRuntimeContext) as? Context
       if (context != null) {
@@ -60,11 +79,180 @@ class ReactNativePasskeyAutofillModule : Module() {
       credentialRepository.clearCredentials(context)
     }
 
+    AsyncFunction("deleteCredential") { credentialId: String ->
+      val context = (appContext.reactContext ?: appContext.hostingRuntimeContext) as? Context
+        ?: return@AsyncFunction Unit
+      credentialRepository.deleteCredential(context, credentialId)
+    }
+
     AsyncFunction("configureIntentActions") { getPasskeyAction: String, createPasskeyAction: String ->
       val context = (appContext.reactContext ?: appContext.hostingRuntimeContext) as? Context
       if (context != null) {
         credentialRepository.configureIntentActions(context, getPasskeyAction, createPasskeyAction)
       }
     }
+
+    // NoOp on Android. iOS uses ASCredentialIdentityStore to advertise
+    // credentials to the system AutoFill UI; Android's Credential Manager
+    // queries the provider service on demand instead, so there is no
+    // equivalent identity store to populate.
+    AsyncFunction("replaceCredentialIdentities") { _: List<Map<String, Any?>> ->
+      // No-op: see comment above.
+    }
+
+    // NoOp on Android. See `replaceCredentialIdentities` above.
+    AsyncFunction("refreshCredentialIdentities") {
+      // No-op: see comment above.
+    }
+
+    // NoOp on Android. The iOS implementation returns credentials stored in
+    // the shared App Group keychain used by the AutoFill extension. On
+    // Android, credentials are managed by the CredentialProviderService and
+    // are not exposed back to JS through this module.
+    AsyncFunction("getStoredCredentials") {
+      emptyList<Map<String, Any?>>()
+    }
+
+    // NoOp on Android. iOS exposes diagnostics from the shared App Group
+    // store; there is no equivalent on Android yet.
+    AsyncFunction("getDiagnostics") {
+      emptyList<String>()
+    }
+
+    AsyncFunction("isProviderActive") {
+      val context = (appContext.reactContext ?: appContext.hostingRuntimeContext) as? Context
+        ?: return@AsyncFunction false
+      isProviderEnabled(context)
+    }
+
+    AsyncFunction("openProviderSettings") {
+      val context = (appContext.reactContext ?: appContext.hostingRuntimeContext) as? Context
+        ?: return@AsyncFunction false
+      openCredentialProviderSettings(context)
+    }
+
+    AsyncFunction("getStoredCredentials") {
+      val context = (appContext.reactContext ?: appContext.hostingRuntimeContext) as? Context
+        ?: return@AsyncFunction emptyList<Map<String, Any>>()
+      credentialRepository.getAllCredentials(context).map { credential ->
+        mapOf(
+          "credentialId" to credential.credentialId,
+          "relyingPartyIdentifier" to credential.origin,
+          "userName" to credential.userHandle,
+          "userHandle" to credential.userHandle,
+          "publicKey" to credential.publicKey,
+        )
+      }
+    }
+
+    // The iOS AutoFill identity store (ASCredentialIdentityStore) has no
+    // Android analogue: our CredentialProviderService answers each
+    // BeginGetCredentialRequest from MMKV on demand, so there is no store to
+    // pre-populate. This is a no-op purely to satisfy the shared JS API.
+    AsyncFunction("refreshCredentialIdentities") {
+      // no-op on Android
+    }
+  }
+
+  /**
+   * Returns `true` when this app's [PasskeyAutofillCredentialProviderService]
+   * is registered as an active credential provider for the current user.
+   *
+   * On API 34+ (UpsideDownCake) we use the official
+   * [android.credentials.CredentialManager.isEnabledCredentialProviderService]
+   * API, which reflects the user's current toggle in Settings in real time.
+   *
+   * On older devices we fall back to a best-effort read of the `@hide`
+   * `credential_service` / `credential_service_primary` Secure settings. These
+   * typically throw `SecurityException` for non-system apps on Android 12+,
+   * in which case we conservatively return `false` rather than guess.
+   */
+  private fun isProviderEnabled(context: Context): Boolean {
+    val component = ComponentName(
+      context.packageName,
+      PasskeyAutofillCredentialProviderService::class.java.name,
+    )
+    val expected = component.flattenToString()
+
+    // Preferred path (API 34+, UpsideDownCake): ask the platform
+    // `CredentialManager` system service whether our component is enabled.
+    // This is the official, real-time-accurate signal and is trusted
+    // exclusively on supported OS versions.
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+      return try {
+        val cm = context.getSystemService(android.credentials.CredentialManager::class.java)
+        cm != null && cm.isEnabledCredentialProviderService(component)
+      } catch (e: Throwable) {
+        Log.d("ReactNativePasskeyAutofill", "CredentialManager.isEnabledCredentialProviderService failed: ${e.message}")
+        false
+      }
+    }
+
+    // Pre-API-34 best-effort: try the (often `@hide`) Secure settings keys.
+    val resolver = context.contentResolver
+    val keys = arrayOf("credential_service", "credential_service_primary")
+    for (key in keys) {
+      val value = try {
+        Settings.Secure.getString(resolver, key)
+      } catch (e: SecurityException) {
+        Log.d("ReactNativePasskeyAutofill", "Secure key $key not readable: ${e.message}")
+        null
+      } ?: continue
+      if (value.isEmpty()) continue
+      val enabled = value.split(':').any { it.equals(expected, ignoreCase = true) } ||
+        value.contains(expected, ignoreCase = true)
+      if (enabled) return true
+    }
+    return false
+  }
+
+  /**
+   * Best-effort deep link into the user's credential-provider preferences so
+   * they can toggle our service on. Falls back to the app-details page when
+   * the credential provider screen is not available on the device.
+   */
+  private fun openCredentialProviderSettings(context: Context): Boolean {
+    // The system action for the Credential Manager provider picker is
+    // `android.settings.CREDENTIAL_PROVIDER` (`Settings.ACTION_CREDENTIAL_PROVIDER`,
+    // API 34+). Some OEM Settings builds additionally accept a
+    // `:settings:fragment_args_key` extra so the screen scrolls directly to
+    // our app's row instead of the generic list. We also include a legacy
+    // autofill-service picker fallback for devices where the Credential
+    // Manager screen isn't a directly launchable activity.
+    val component = ComponentName(
+      context.packageName,
+      PasskeyAutofillCredentialProviderService::class.java.name,
+    ).flattenToString()
+    val intents = listOf(
+      // Preferred: Credential Manager provider settings, deep-linked to our row.
+      Intent("android.settings.CREDENTIAL_PROVIDER").apply {
+        putExtra(":settings:fragment_args_key", component)
+        putExtra(
+          ":settings:show_fragment_args",
+          android.os.Bundle().apply { putString(":settings:fragment_args_key", component) },
+        )
+      },
+      // Same screen without the deep-link extras (some OEMs ignore them).
+      Intent("android.settings.CREDENTIAL_PROVIDER"),
+      // Legacy / fallback: the system autofill provider picker, which on
+      // pre-14 devices is the closest "pick a passkey provider" screen.
+      Intent(Settings.ACTION_REQUEST_SET_AUTOFILL_SERVICE).apply {
+        data = Uri.parse("package:${context.packageName}")
+      },
+      // Last-resort fallback: this app's details page.
+      Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS).apply {
+        data = Uri.fromParts("package", context.packageName, null)
+      },
+    )
+    for (intent in intents) {
+      intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+      try {
+        context.startActivity(intent)
+        return true
+      } catch (e: Exception) {
+        Log.w("ReactNativePasskeyAutofill", "Failed to open ${intent.action}: ${e.message}")
+      }
+    }
+    return false
   }
 }

package/android/src/main/java/co/algorand/passkeyautofill/WebAuthn.kt

@@ -0,0 +1,135 @@
+package co.algorand.passkeyautofill
+
+import android.content.Context
+import android.util.Base64
+import java.nio.ByteBuffer
+import java.util.UUID
+
+/**
+ * WebAuthn attestation helpers.
+ *
+ * The AndroidX credentials library (`AuthenticatorAttestationResponse`) always emits an
+ * all-zero AAGUID. To present the same authenticator identity as the iOS provider and the
+ * native Pera apps, we splice a configured AAGUID into the attestationObject after AndroidX
+ * builds it. The value is injected by the Expo config plugin (`aaguid` prop) as the
+ * `passkey_autofill_aaguid` string resource.
+ */
+object WebAuthn {
+    private const val AAGUID_RESOURCE = "passkey_autofill_aaguid"
+    private const val AAGUID_LENGTH = 16
+
+    // authData layout: rpIdHash(32) + flags(1) + signCount(4) then attestedCredentialData,
+    // which begins with the 16-byte AAGUID.
+    private const val AAGUID_OFFSET_IN_AUTH_DATA = 37
+
+    private const val BASE64_FLAGS = Base64.URL_SAFE or Base64.NO_WRAP or Base64.NO_PADDING
+
+    private val ZERO_AAGUID = ByteArray(AAGUID_LENGTH)
+
+    /** Returns the configured AAGUID bytes, or null when unset/blank/all-zero/malformed. */
+    fun configuredAaguid(context: Context): ByteArray? {
+        val resId = context.resources.getIdentifier(AAGUID_RESOURCE, "string", context.packageName)
+        if (resId == 0) return null
+        val raw = context.getString(resId).trim()
+        if (raw.isEmpty()) return null
+        val bytes = try {
+            uuidToBytes(UUID.fromString(raw))
+        } catch (e: IllegalArgumentException) {
+            return null
+        }
+        return if (bytes.contentEquals(ZERO_AAGUID)) null else bytes
+    }
+
+    /**
+     * Overwrites the 16-byte AAGUID inside the attestationObject's authData with [aaguid].
+     * Returns the re-encoded (base64url, no padding) attestationObject.
+     */
+    fun injectAaguid(attestationObjectB64Url: String, aaguid: ByteArray): String {
+        require(aaguid.size == AAGUID_LENGTH) { "AAGUID must be $AAGUID_LENGTH bytes" }
+        val bytes = Base64.decode(attestationObjectB64Url, BASE64_FLAGS)
+        val authDataStart = findAuthDataContentStart(bytes)
+        val offset = authDataStart + AAGUID_OFFSET_IN_AUTH_DATA
+        require(offset + AAGUID_LENGTH <= bytes.size) {
+            "attestationObject is too short to contain an AAGUID"
+        }
+        System.arraycopy(aaguid, 0, bytes, offset, AAGUID_LENGTH)
+        return Base64.encodeToString(bytes, BASE64_FLAGS)
+    }
+
+    private fun uuidToBytes(uuid: UUID): ByteArray =
+        ByteBuffer.allocate(AAGUID_LENGTH)
+            .putLong(uuid.mostSignificantBits)
+            .putLong(uuid.leastSignificantBits)
+            .array()
+
+    // --- Minimal CBOR reader: locate the "authData" byte-string value in the top-level map ---
+
+    private class Cursor(val buf: ByteArray) {
+        var pos = 0
+    }
+
+    private fun findAuthDataContentStart(buf: ByteArray): Int {
+        val c = Cursor(buf)
+        val (major, count) = readHead(c)
+        require(major == 5) { "attestationObject is not a CBOR map" }
+        repeat(count.toInt()) {
+            val key = readTextString(c)
+            if (key == "authData") {
+                val (valueMajor, valueLen) = readHead(c)
+                require(valueMajor == 2) { "authData is not a CBOR byte string" }
+                val start = c.pos
+                c.pos += valueLen.toInt()
+                return start
+            }
+            skipItem(c)
+        }
+        throw IllegalArgumentException("authData not found in attestationObject")
+    }
+
+    /** Reads a CBOR item head, returning (majorType, argument) and advancing the cursor. */
+    private fun readHead(c: Cursor): Pair<Int, Long> {
+        val initial = c.buf[c.pos].toInt() and 0xff
+        c.pos += 1
+        val major = initial ushr 5
+        val additional = initial and 0x1f
+        val argument = when {
+            additional < 24 -> additional.toLong()
+            additional == 24 -> readUInt(c, 1)
+            additional == 25 -> readUInt(c, 2)
+            additional == 26 -> readUInt(c, 4)
+            additional == 27 -> readUInt(c, 8)
+            else -> throw IllegalArgumentException("Unsupported CBOR additional info: $additional")
+        }
+        return Pair(major, argument)
+    }
+
+    private fun readUInt(c: Cursor, byteCount: Int): Long {
+        var value = 0L
+        repeat(byteCount) {
+            value = (value shl 8) or (c.buf[c.pos].toLong() and 0xff)
+            c.pos += 1
+        }
+        return value
+    }
+
+    private fun readTextString(c: Cursor): String {
+        val (major, length) = readHead(c)
+        require(major == 3) { "Expected a CBOR text-string map key" }
+        val value = String(c.buf, c.pos, length.toInt(), Charsets.UTF_8)
+        c.pos += length.toInt()
+        return value
+    }
+
+    private fun skipItem(c: Cursor) {
+        val (major, argument) = readHead(c)
+        when (major) {
+            0, 1 -> Unit // unsigned/negative integer: value is the head argument
+            2, 3 -> c.pos += argument.toInt() // byte/text string
+            4 -> repeat(argument.toInt()) { skipItem(c) } // array
+            5 -> repeat(argument.toInt()) { skipItem(c); skipItem(c) } // map: key + value
+            6 -> skipItem(c) // tag: skip the tagged item
+            7 -> Unit // simple value / float: width already consumed by readHead
+            else -> throw IllegalArgumentException("Unsupported CBOR major type: $major")
+        }
+    }
+}

package/android/src/main/java/co/algorand/passkeyautofill/auth/BiometricRequirement.kt

@@ -0,0 +1,86 @@
+package co.algorand.passkeyautofill.auth
+
+import android.content.Context
+import android.content.pm.PackageManager
+import android.security.keystore.KeyProperties
+import android.util.Log
+import androidx.biometric.BiometricManager.Authenticators
+
+/**
+ * The set of authenticators a passkey operation will accept. Configured at build time via the
+ * `biometricRequirement` config-plugin prop and read from app `<meta-data>` at runtime.
+ */
+enum class BiometricRequirement {
+    /** Strong biometric only. Crypto-bound key. */
+    STRONG,
+
+    /** Strong biometric OR device credential (PIN/pattern/password). Crypto-bound key. Default. */
+    STRONG_OR_CREDENTIAL,
+
+    /**
+     * Weak biometric OR device credential. NOT crypto-bound: Android cannot gate a Keystore key on
+     * weak biometrics, so the key is not user-auth-required and the prompt is a UI-only gate.
+     */
+    WEAK_OR_CREDENTIAL;
+
+    /** Authenticators to pass to `BiometricPrompt.PromptInfo` / `BiometricPromptData`. */
+    val allowedAuthenticators: Int
+        get() = when (this) {
+            STRONG -> Authenticators.BIOMETRIC_STRONG
+            STRONG_OR_CREDENTIAL -> Authenticators.BIOMETRIC_STRONG or Authenticators.DEVICE_CREDENTIAL
+            WEAK_OR_CREDENTIAL -> Authenticators.BIOMETRIC_WEAK or Authenticators.DEVICE_CREDENTIAL
+        }
+
+    /** True when device credential is accepted; a negative button must NOT be set in that case. */
+    val allowsDeviceCredential: Boolean
+        get() = when (this) {
+            STRONG -> false
+            STRONG_OR_CREDENTIAL, WEAK_OR_CREDENTIAL -> true
+        }
+
+    /** True when the Keystore key is user-auth-bound and prompts use a `CryptoObject`. */
+    val isCryptoBound: Boolean
+        get() = when (this) {
+            STRONG, STRONG_OR_CREDENTIAL -> true
+            WEAK_OR_CREDENTIAL -> false
+        }
+
+    /** Auth type for `KeyGenParameterSpec.setUserAuthenticationParameters` (only when [isCryptoBound]). */
+    val keystoreAuthType: Int
+        get() = when (this) {
+            STRONG -> KeyProperties.AUTH_BIOMETRIC_STRONG
+            STRONG_OR_CREDENTIAL -> KeyProperties.AUTH_BIOMETRIC_STRONG or KeyProperties.AUTH_DEVICE_CREDENTIAL
+            WEAK_OR_CREDENTIAL -> 0 // no auth binding — key is not user-auth-required
+        }
+
+    companion object {
+        private const val TAG = "BiometricRequirement"
+        const val META_DATA_KEY = "co.algorand.passkeyautofill.BIOMETRIC_REQUIREMENT"
+
+        fun fromValue(value: String?): BiometricRequirement = when (val trimmed = value?.trim()) {
+            "strong" -> STRONG
+            "strongOrCredential" -> STRONG_OR_CREDENTIAL
+            "weakOrCredential" -> WEAK_OR_CREDENTIAL
+            else -> {
+                if (!trimmed.isNullOrEmpty()) {
+                    Log.w(TAG, "Unknown biometricRequirement value '$trimmed', using default STRONG_OR_CREDENTIAL")
+                }
+                STRONG_OR_CREDENTIAL
+            }
+        }
+
+        /** Reads the build-time configured requirement from app `<meta-data>`; defaults on any failure. */
+        fun resolve(context: Context): BiometricRequirement {
+            val value = try {
+                context.packageManager
+                    .getApplicationInfo(context.packageName, PackageManager.GET_META_DATA)
+                    .metaData
+                    ?.getString(META_DATA_KEY)
+            } catch (e: Exception) {
+                Log.w(TAG, "Failed to read $META_DATA_KEY meta-data, using default", e)
+                null
+            }
+            return fromValue(value)
+        }
+    }
+}

package/android/src/main/java/co/algorand/passkeyautofill/credentials/Credential.kt

@@ -7,5 +7,6 @@ data class Credential(
     val userId: String,
     val publicKey: String,
     val privateKey: String,
-    val count: Int
+    val count: Int,
+    val biometricIv: String? = null
 )