@algorandfoundation/react-native-passkey-autofill 1.0.0-canary.16 → 1.0.0-canary.17

package/CHANGELOG.md

@@ -1,14 +1,27 @@
-# [1.0.0-canary.16](https://github.com/algorandfoundation/react-native-passkey-autofill/compare/v1.0.0-canary.15...v1.0.0-canary.16) (2026-05-15)
+# [1.0.0-canary.17](https://github.com/algorandfoundation/react-native-passkey-autofill/compare/v1.0.0-canary.16...v1.0.0-canary.17) (2026-05-28)
 
 
 ### Bug Fixes
 
-* align ios autofill root key flow ([1287f57](https://github.com/algorandfoundation/react-native-passkey-autofill/commit/1287f57952b41829032ef368bad826624375e9a3))
+* allow configurable AAGUID ([d5a8176](https://github.com/algorandfoundation/react-native-passkey-autofill/commit/d5a81765ba150e9873e18875f0ac9f7bc4aede93))
+* **Android:** add NoOp methods for iOS-specific functionality ([e2c64db](https://github.com/algorandfoundation/react-native-passkey-autofill/commit/e2c64db479cda70c7c61b7ab3021b70db949a15b))
+* compile issue ([16b939c](https://github.com/algorandfoundation/react-native-passkey-autofill/commit/16b939cb555e75bd052ce57a41a838810a2770cd))
+
+
+### Features
+
+* configurable credential requirement ([dc09916](https://github.com/algorandfoundation/react-native-passkey-autofill/commit/dc09916d1ee5c8c9d33e53b57f00171472f4f665))
+* record lastUsedAt/count and fix error handling ([47b40ab](https://github.com/algorandfoundation/react-native-passkey-autofill/commit/47b40abf692c0f7cffee6f2266c66f61f8006a65))
+
+# [1.0.0-canary.16](https://github.com/algorandfoundation/react-native-passkey-autofill/compare/v1.0.0-canary.15...v1.0.0-canary.16) (2026-05-15)
+
+### Bug Fixes
 
+- align ios autofill root key flow ([1287f57](https://github.com/algorandfoundation/react-native-passkey-autofill/commit/1287f57952b41829032ef368bad826624375e9a3))
 
 ### Features
 
-* add iOS passkey autofill provider ([9aad8f8](https://github.com/algorandfoundation/react-native-passkey-autofill/commit/9aad8f8ceb2ad54cf53847b60dd6e70d5b2a1f2b))
+- add iOS passkey autofill provider ([9aad8f8](https://github.com/algorandfoundation/react-native-passkey-autofill/commit/9aad8f8ceb2ad54cf53847b60dd6e70d5b2a1f2b))
 
 # [1.0.0-canary.15](https://github.com/algorandfoundation/react-native-passkey-autofill/compare/v1.0.0-canary.14...v1.0.0-canary.15) (2026-04-10)
 

package/README.md

@@ -44,6 +44,23 @@ If you are using Expo, you can configure the plugin in your `app.json` or `app.c
 
 - `site`: The URL of your FIDO server (default: `https://debug.liquidauth.com`).
 - `label`: The name of the credential provider as it appears in Android settings (default: `My Credential Provider`).
+- `aaguid`: Optional authenticator AAGUID (UUID string) embedded in attestation responses to identify your authenticator to relying parties. When omitted, iOS uses the module's built-in default and Android uses the all-zero AAGUID emitted by the platform. Set the same value across all your apps (iOS, Android, web) so they present one identity.
+- `biometricRequirement`: Controls which authenticators satisfy passkey user verification. See [Biometric Requirement](#biometric-requirement) below.
+
+#### Biometric Requirement
+
+`biometricRequirement` is an optional string property that controls which authenticators are accepted for user verification during passkey creation and authentication.
+
+| Value                          | Android                                                                                  | iOS                                 |
+| ------------------------------ | ---------------------------------------------------------------------------------------- | ----------------------------------- |
+| `strong`                       | Strong biometric only                                                                    | Biometrics only (passcode rejected) |
+| `strongOrCredential` (default) | Strong biometric or device PIN/pattern/password                                          | Biometrics or device passcode       |
+| `weakOrCredential`             | Weak biometric or device credential (key is **not** crypto-bound — a security trade-off) | Biometrics or device passcode       |
+
+**Notes:**
+
+- Android cannot gate a hardware-backed key on weak biometrics, so `weakOrCredential` stores the key without user-authentication binding and uses the biometric prompt as a UI gate only. Use it only when you accept that trade-off.
+- The default `strongOrCredential` is more permissive than the previous strong-only behavior; integrators upgrading will additionally allow the device credential on Android (iOS behavior is unchanged).
 
 ### Configure for iOS
 

package/android/build.gradle

@@ -46,6 +46,9 @@ android {
   }
   testOptions {
     unitTests.includeAndroidResources = true
+    // Let unmocked android.jar calls (e.g. android.util.Log) return defaults instead of throwing
+    // "Stub!" in JVM unit tests.
+    unitTests.returnDefaultValues = true
   }
   packagingOptions {
     pickFirst '**/libc++_shared.so'

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

@@ -22,6 +22,7 @@ import androidx.credentials.provider.ProviderCreateCredentialRequest
 import androidx.credentials.webauthn.AuthenticatorAttestationResponse
 import androidx.credentials.webauthn.FidoPublicKeyCredential
 import androidx.credentials.webauthn.PublicKeyCredentialCreationOptions
+import co.algorand.passkeyautofill.auth.BiometricRequirement
 import co.algorand.passkeyautofill.credentials.CredentialRepository
 import co.algorand.passkeyautofill.credentials.Credential
 import co.algorand.passkeyautofill.utils.PasskeyUtils
@@ -282,7 +283,7 @@ class CreatePasskeyActivity : AppCompatActivity() {
             val cipherToUse = systemUnlockedCipher ?: run {
                 if (biometricPromptResult != null) {
                     try {
-                        val fallback = credentialRepository.getBiometricCipherForEncryption()
+                        val fallback = credentialRepository.getBiometricCipherForEncryption(this@CreatePasskeyActivity, BiometricRequirement.resolve(this@CreatePasskeyActivity))
                         Log.i(TAG, "Successfully obtained fallback cipher from repository (Single Tap timeout)")
                         fallback
                     } catch (e: Exception) {
@@ -424,6 +425,15 @@ class CreatePasskeyActivity : AppCompatActivity() {
             val clientDataJSONb64 = AndroidBase64.encodeToString(clientDataJSONString.toByteArray(), AndroidBase64.URL_SAFE or AndroidBase64.NO_WRAP or AndroidBase64.NO_PADDING)
             respJson.put("clientDataJSON", clientDataJSONb64)
 
+            WebAuthn.configuredAaguid(this@CreatePasskeyActivity)?.let { aaguid ->
+                try {
+                    val patched = WebAuthn.injectAaguid(respJson.getString("attestationObject"), aaguid)
+                    respJson.put("attestationObject", patched)
+                } catch (e: Exception) {
+                    Log.w(TAG, "Failed to inject AAGUID into attestationObject", e)
+                }
+            }
+
             val createResponse = CreatePublicKeyCredentialResponse(fullJson.toString())
             Log.d(TAG, "CreatePublicKeyCredentialResponse: ${fullJson.toString()}")
             
@@ -447,6 +457,7 @@ class CreatePasskeyActivity : AppCompatActivity() {
     }
 
     private suspend fun biometrics(needsCipher: Boolean): BiometricPrompt.AuthenticationResult? {
+        val requirement = BiometricRequirement.resolve(this)
         return suspendCoroutine { continuation ->
             val biometricPrompt = BiometricPrompt(
                 this,
@@ -465,16 +476,19 @@ class CreatePasskeyActivity : AppCompatActivity() {
                     }
                 }
             )
-            val promptInfo = BiometricPrompt.PromptInfo.Builder()
+            val promptInfoBuilder = BiometricPrompt.PromptInfo.Builder()
                 .setTitle("Create Passkey")
                 .setSubtitle("Authenticate to save your passkey")
-                .setNegativeButtonText("Cancel")
-                .setAllowedAuthenticators(androidx.biometric.BiometricManager.Authenticators.BIOMETRIC_STRONG)
-                .build()
-            
-            if (needsCipher) {
+                .setAllowedAuthenticators(requirement.allowedAuthenticators)
+            // A negative button is illegal when DEVICE_CREDENTIAL is allowed; the system shows its own.
+            if (!requirement.allowsDeviceCredential) {
+                promptInfoBuilder.setNegativeButtonText("Cancel")
+            }
+            val promptInfo = promptInfoBuilder.build()
+
+            if (needsCipher && requirement.isCryptoBound) {
                 try {
-                    val cipher = credentialRepository.getBiometricCipherForEncryption()
+                    val cipher = credentialRepository.getBiometricCipherForEncryption(this, requirement)
                     biometricPrompt.authenticate(promptInfo, BiometricPrompt.CryptoObject(cipher))
                 } catch (e: Exception) {
                     Log.e(TAG, "Failed to initialize biometric prompt with cipher", e)

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

@@ -23,12 +23,14 @@ import androidx.credentials.provider.ProviderGetCredentialRequest
 import androidx.credentials.webauthn.AuthenticatorAssertionResponse
 import androidx.credentials.webauthn.FidoPublicKeyCredential
 import androidx.credentials.webauthn.PublicKeyCredentialRequestOptions
+import co.algorand.passkeyautofill.auth.BiometricRequirement
 import co.algorand.passkeyautofill.credentials.CredentialRepository
 import co.algorand.passkeyautofill.credentials.Credential
 import co.algorand.passkeyautofill.utils.PasskeyUtils
 import java.security.KeyPair
 import java.security.MessageDigest
 import android.util.Base64 as AndroidBase64
+import androidx.biometric.BiometricManager
 import androidx.biometric.BiometricPrompt
 import androidx.core.content.ContextCompat
 import androidx.lifecycle.lifecycleScope
@@ -251,13 +253,115 @@ class GetPasskeyActivity : AppCompatActivity() {
         layout.addView(cancelButton)
 
         setContentView(layout)
-        
+
         // Ensure the activity is focusable and can receive touches
         layout.isFocusable = true
         layout.isFocusableInTouchMode = true
         layout.requestFocus()
     }
 
+    private fun setupErrorUI(message: String, allowRetry: Boolean) {
+        if (isFinishing || isDestroyed) return
+
+        val layout = LinearLayout(this).apply {
+            val padding = (32 * resources.displayMetrics.density).toInt()
+            orientation = LinearLayout.VERTICAL
+            setPadding(padding, padding, padding, padding)
+            gravity = Gravity.CENTER_HORIZONTAL
+            setBackgroundColor(Color.WHITE)
+        }
+
+        try {
+            val appInfo = packageManager.getApplicationInfo(packageName, 0)
+            val appIcon = packageManager.getApplicationIcon(appInfo)
+            val appLabel = packageManager.getApplicationLabel(appInfo)
+
+            val density = resources.displayMetrics.density
+            val iconSize = (48 * density).toInt()
+            val iconMargin = (12 * density).toInt()
+            val headerPadding = (40 * density).toInt()
+
+            val header = LinearLayout(this).apply {
+                orientation = LinearLayout.HORIZONTAL
+                gravity = Gravity.CENTER_VERTICAL
+                setPadding(0, 0, 0, headerPadding)
+            }
+
+            val iconView = ImageView(this).apply {
+                setImageDrawable(appIcon)
+                layoutParams = LinearLayout.LayoutParams(iconSize, iconSize).apply {
+                    marginEnd = iconMargin
+                }
+            }
+            header.addView(iconView)
+
+            val providerLabel = TextView(this).apply {
+                text = appLabel
+                textSize = 16f
+                typeface = Typeface.DEFAULT_BOLD
+                setTextColor(Color.DKGRAY)
+            }
+            header.addView(providerLabel)
+            layout.addView(header)
+        } catch (e: Exception) {
+        }
+
+        val title = TextView(this).apply {
+            text = "Couldn't sign in"
+            textSize = 28f
+            typeface = Typeface.DEFAULT_BOLD
+            setPadding(0, 0, 0, (8 * resources.displayMetrics.density).toInt())
+            setTextColor(Color.BLACK)
+        }
+        layout.addView(title)
+
+        val description = TextView(this).apply {
+            text = message
+            textSize = 16f
+            setPadding(0, 0, 0, (40 * resources.displayMetrics.density).toInt())
+            gravity = Gravity.CENTER_HORIZONTAL
+            setTextColor(Color.GRAY)
+        }
+        layout.addView(description)
+
+        if (allowRetry) {
+            val retryButton = Button(this).apply {
+                text = "Try Again"
+                contentDescription = "get-passkey-retry"
+                setOnClickListener {
+                    handleAssertion()
+                }
+                layoutParams = LinearLayout.LayoutParams(
+                    LinearLayout.LayoutParams.MATCH_PARENT,
+                    LinearLayout.LayoutParams.WRAP_CONTENT
+                ).apply {
+                    setMargins(0, 0, 0, (8 * resources.displayMetrics.density).toInt())
+                }
+            }
+            layout.addView(retryButton)
+        }
+
+        val closeButton = Button(this, null, android.R.attr.borderlessButtonStyle).apply {
+            text = "Close"
+            contentDescription = "get-passkey-cancel"
+            setOnClickListener {
+                setResult(RESULT_CANCELED)
+                finish()
+            }
+            layoutParams = LinearLayout.LayoutParams(
+                LinearLayout.LayoutParams.MATCH_PARENT,
+                LinearLayout.LayoutParams.WRAP_CONTENT
+            )
+        }
+        layout.addView(closeButton)
+
+        setContentView(layout)
+
+        layout.isFocusable = true
+        layout.isFocusableInTouchMode = true
+        layout.requestFocus()
+    }
+
     @SuppressLint("RestrictedApi")
     private fun handleAssertion() {
         if (isHandling) return
@@ -271,10 +375,11 @@ class GetPasskeyActivity : AppCompatActivity() {
             val cipherToUse = systemUnlockedCipher ?: run {
                 if (biometricPromptResult != null) {
                     try {
+                        val requirement = BiometricRequirement.resolve(this@GetPasskeyActivity)
                         val fallback = if (biometricIv != null) {
-                            credentialRepository.getBiometricCipherForDecryption(AndroidBase64.decode(biometricIv, AndroidBase64.DEFAULT))
+                            credentialRepository.getBiometricCipherForDecryption(this@GetPasskeyActivity, AndroidBase64.decode(biometricIv, AndroidBase64.DEFAULT), requirement)
                         } else {
-                            credentialRepository.getBiometricCipherForEncryption()
+                            credentialRepository.getBiometricCipherForEncryption(this@GetPasskeyActivity, requirement)
                         }
                         Log.i(TAG, "Successfully obtained fallback cipher from repository (Single Tap timeout)")
                         fallback
@@ -294,7 +399,20 @@ class GetPasskeyActivity : AppCompatActivity() {
                     Log.d(TAG, "Manual biometrics result: $result")
                     if (result == null) {
                         Log.w(TAG, "Biometrics failed or was canceled")
-                        setupUI() // Show UI as fallback
+                        val requirement = BiometricRequirement.resolve(this@GetPasskeyActivity)
+                        val canUseBiometrics =
+                            BiometricManager.from(this@GetPasskeyActivity)
+                                .canAuthenticate(
+                                    requirement.allowedAuthenticators,
+                                ) == BiometricManager.BIOMETRIC_SUCCESS
+                        if (canUseBiometrics) {
+                            setupUI()
+                        } else {
+                            setupErrorUI(
+                                "This device has no screen lock or biometric set up, which passkeys require. Add one in your device settings, then try again.",
+                                allowRetry = false,
+                            )
+                        }
                         isHandling = false
                         return@launch
                     }
@@ -469,19 +587,25 @@ class GetPasskeyActivity : AppCompatActivity() {
 
             setResult(Activity.RESULT_OK, resultIntent)
             Log.d(TAG, "Result set to OK")
+            credentialRepository.recordCredentialUsage(this@GetPasskeyActivity, credId)
             ReactNativePasskeyAutofillModule.instance?.sendEvent("onPasskeyAuthenticated", Bundle().apply {
                 putBoolean("success", true)
+                putString("credentialId", credentialIdEnc)
             })
             finish()
         } catch (e: Exception) {
             Log.e(TAG, "Error during passkey assertion", e)
-            setupUI() // Show UI on error
+            setupErrorUI(
+                "Something went wrong while signing in. Please try again.",
+                allowRetry = true,
+            )
             isHandling = false
         }
     }
     }
 
     private suspend fun biometrics(iv: String?): BiometricPrompt.AuthenticationResult? {
+        val requirement = BiometricRequirement.resolve(this)
         return suspendCoroutine { continuation ->
             val biometricPrompt = BiometricPrompt(
                 this,
@@ -502,17 +626,19 @@ class GetPasskeyActivity : AppCompatActivity() {
                     }
                 }
             )
-            val promptInfo = BiometricPrompt.PromptInfo.Builder()
+            val promptInfoBuilder = BiometricPrompt.PromptInfo.Builder()
                 .setTitle("Sign In")
                 .setSubtitle("Authenticate to use your passkey")
-                .setNegativeButtonText("Cancel")
-                .setAllowedAuthenticators(androidx.biometric.BiometricManager.Authenticators.BIOMETRIC_STRONG)
-                .build()
-            
-            if (iv != null) {
+                .setAllowedAuthenticators(requirement.allowedAuthenticators)
+            if (!requirement.allowsDeviceCredential) {
+                promptInfoBuilder.setNegativeButtonText("Cancel")
+            }
+            val promptInfo = promptInfoBuilder.build()
+
+            if (iv != null && requirement.isCryptoBound) {
                 try {
                     val ivBytes = AndroidBase64.decode(iv, AndroidBase64.DEFAULT)
-                    val cipher = credentialRepository.getBiometricCipherForDecryption(ivBytes)
+                    val cipher = credentialRepository.getBiometricCipherForDecryption(this, ivBytes, requirement)
                     biometricPrompt.authenticate(promptInfo, BiometricPrompt.CryptoObject(cipher))
                 } catch (e: Exception) {
                     Log.e(TAG, "Failed to initialize biometric prompt with cipher", e)

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

@@ -93,6 +93,33 @@ class ReactNativePasskeyAutofillModule : Module() {
       }
     }
 
+    // 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
@@ -104,6 +131,28 @@ class ReactNativePasskeyAutofillModule : Module() {
         ?: 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
+    }
   }
 
   /**

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)
+        }
+    }
+}