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

package/ARCHITECTURE.md

@@ -18,7 +18,7 @@ The module provides an interface to interact with native Passkey AutoFill capabi
 ### TypeScript Layer (`src/`)
 
 - `index.ts`: The entry point for the module, re-exporting the native module.
-- `ReactNativePasskeyAutofillModule.ts`: Defines the `ReactNativePasskeyAutofillModule` class and its methods (`setMasterKey`, `setHdRootKeyId`, `getHdRootKeyId`, etc.).
+- `ReactNativePasskeyAutofillModule.ts`: Defines the `ReactNativePasskeyAutofillModule` class and its methods (`setMasterKey`, `setMainKeyId`, `getMainKeyId`, etc.).
 - `ReactNativePasskeyAutofill.types.ts`: Defines types and interfaces used by the module.
 
 ### Android Implementation (`android/`)
@@ -58,9 +58,9 @@ The iOS part is implemented using Swift.
 
 The following methods are exposed to the JavaScript layer:
 
-- `setMasterKey(secret: string)`: Sets the master key for credential encryption/decryption.
-- `setHdRootKeyId(id: string)`: Sets the ID for the HD root key.
-- `getHdRootKeyId()`: Retrieves the current HD root key ID.
+- `setMasterKey(secret: Uint8Array)`: Sets the master key for credential encryption/decryption. Takes raw bytes (not a hex string) so the secret never becomes a non-zeroable JS string.
+- `setMainKeyId(id: string)`: Sets the ID for the P-256 main key (the parent secret for passkey derivation). The legacy `setHdRootKeyId` remains as a deprecated alias.
+- `getMainKeyId()`: Retrieves the current P-256 main key ID.
 - `configureIntentActions(getPasskeyAction: string, createPasskeyAction: string)`: Configures the intent actions used for Passkey flows.
 - `clearCredentials()`: Clears all stored credentials.
 - `isProviderActive()`: Returns `true` if this app is the user-selected system credential/autofill provider. Uses Android's `Settings.Secure("credential_service"[_primary])` (API 34+) and iOS's `ASCredentialIdentityStore.getState`. Useful both for gating passkey UI at runtime and for E2E tests, which need to confirm that an OS passkey prompt is served by _this_ provider rather than any other installed one.
@@ -68,7 +68,7 @@ The following methods are exposed to the JavaScript layer:
 
 ## Security Considerations
 
-As this module handles sensitive information (Passkeys), it is crucial to ensure that keys and secrets are handled securely in the native layers. Master keys should be stored in secure storage (like Android Keystore or iOS Keychain).
+As this module handles sensitive information (Passkeys), keys and secrets are handled securely in the native layers. The master key is stored in platform secure storage — never in plaintext: on Android it is AES/GCM-encrypted under the AndroidKeyStore, and on iOS it is held in the Keychain (`kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`) within a shared keychain access group so the app and the AutoFill extension can both read it. It is deliberately not biometric-gated, because the extension must read it to enumerate credentials before the user authenticates; biometric verification is applied at the assertion step instead. The master key crosses the JS↔native bridge as raw bytes (`Uint8Array`), never as a hex string.
 
 ## End-to-End Tests
 

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+# [1.0.0-canary.23](https://github.com/algorandfoundation/react-native-passkey-autofill/compare/v1.0.0-canary.22...v1.0.0-canary.23) (2026-08-13)
+
+### Features
+
+- keystore migrations ([00f01b6](https://github.com/algorandfoundation/react-native-passkey-autofill/commit/00f01b6ce17842a58e989a71696fe809d969b002))
+
+# [1.0.0-canary.22](https://github.com/algorandfoundation/react-native-passkey-autofill/compare/v1.0.0-canary.21...v1.0.0-canary.22) (2026-07-15)
+
+### Bug Fixes
+
+- write keychain group into the extension Info.plist so the extension can resolve it ([a98ea08](https://github.com/algorandfoundation/react-native-passkey-autofill/commit/a98ea0827164b5402a3f530579cd6908e52c0242))
+
+### Features
+
+- accept the master key as raw bytes instead of a hex string ([86f85a8](https://github.com/algorandfoundation/react-native-passkey-autofill/commit/86f85a8667489f938266188f7551598c3e14cc0c))
+- store the iOS master key in the Keychain instead of plaintext UserDefaults ([00dd362](https://github.com/algorandfoundation/react-native-passkey-autofill/commit/00dd362d7214e91296982e012aedd817b09ab83d))
+
 # [1.0.0-canary.21](https://github.com/algorandfoundation/react-native-passkey-autofill/compare/v1.0.0-canary.20...v1.0.0-canary.21) (2026-06-11)
 
 ### Bug Fixes

package/README.md

@@ -100,14 +100,16 @@ For iOS integration, make sure that:
 - The generated extension target can link `AuthenticationServices.framework`, `CryptoKit.framework`, `MMKVCore`, and the deterministic P-256 Swift package.
 - `NSFaceIDUsageDescription` is present when biometric authentication is used.
 
-At runtime, the app must provide the native side with the master key, identify the HD root key stored in MMKV, and keep the iOS identity store in sync:
+At runtime, the app must provide the native side with the master key, identify the P-256 main key (the parent secret for passkey derivation) stored in MMKV, and keep the iOS identity store in sync:
 
 ```typescript
-await ReactNativePasskeyAutofill.setMasterKey(masterKeyHex);
-await ReactNativePasskeyAutofill.setHdRootKeyId(hdRootKeyId);
+await ReactNativePasskeyAutofill.setMasterKey(masterKeyBytes);
+await ReactNativePasskeyAutofill.setMainKeyId(mainKeyId);
 await ReactNativePasskeyAutofill.refreshCredentialIdentities();
 ```
 
+The `mainKeyId` points at the keystore record whose sealed material is the 64-byte parent secret. The native side determines the derivation scheme from the record's metadata (`pbkdf2-p256` is preferred; legacy `bip32-ed25519` is also supported).
+
 Call `refreshCredentialIdentities()` after creating, importing, deleting, or restoring passkeys so iOS AutoFill sees the current credentials.
 
 ## Usage
@@ -115,11 +117,13 @@ Call `refreshCredentialIdentities()` after creating, importing, deleting, or res
 ```typescript
 import ReactNativePasskeyAutofill from "@algorandfoundation/react-native-passkey-autofill";
 
-// 1. Set the master key for encryption (hex string)
-await ReactNativePasskeyAutofill.setMasterKey(masterKeyHex);
+// 1. Set the master key for encryption (raw bytes — never a hex string, so
+//    the secret isn't materialized as a non-zeroable JS string)
+await ReactNativePasskeyAutofill.setMasterKey(masterKeyBytes);
 
-// 2. Set the HD root key ID if applicable
-await ReactNativePasskeyAutofill.setHdRootKeyId(hdRootKeyId);
+// 2. Set the P-256 main key ID (parent secret for passkey derivation).
+//    The legacy `setHdRootKeyId(id)` is a deprecated alias for this method.
+await ReactNativePasskeyAutofill.setMainKeyId(mainKeyId);
 
 // 3. Configure intent actions for the Passkey flows
 await ReactNativePasskeyAutofill.configureIntentActions(

package/android/build.gradle

@@ -80,6 +80,11 @@ dependencies {
 
   // Testing dependencies
   testImplementation "junit:junit:4.13.2"
+  // `unitTests.returnDefaultValues` stubs the whole android.jar, and that
+  // includes `org.json` — every JSONObject method then returns null, which the
+  // record-format tests cannot work with. Put the real implementation on the
+  // unit-test classpath instead.
+  testImplementation "org.json:json:20240303"
   testImplementation "org.robolectric:robolectric:4.11.1"
   testImplementation "io.mockk:mockk:1.13.8"
   testImplementation "org.jetbrains.kotlinx:kotlinx-coroutines-test:1.8.0"

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

@@ -342,7 +342,12 @@ class CreatePasskeyActivity : AppCompatActivity() {
             }
 
             Log.d(TAG, "Creating deterministic key pair")
-            val keyPair: KeyPair = credentialRepository.createDeterministicKeyPair(this@CreatePasskeyActivity, origin, userHandle)
+            // No requested scheme: a new credential takes the preferred parent
+            // (the wallet's deterministic-P256 main key), and records which one
+            // it got so every later assertion re-derives the same key.
+            val derived = credentialRepository.createDomainKeyPair(this@CreatePasskeyActivity, origin, userHandle)
+            val keyPair: KeyPair = derived.keyPair
+            Log.d(TAG, "Derived from parent ${derived.parentKeyId} (${derived.derivationScheme})")
             Log.d(TAG, "Generating credential ID")
             val credentialId = credentialRepository.generateCredentialId(keyPair)
             val credentialIdBase64 = AndroidBase64.encodeToString(credentialId, AndroidBase64.NO_WRAP)
@@ -354,7 +359,9 @@ class CreatePasskeyActivity : AppCompatActivity() {
                 userId = userId,
                 publicKey = AndroidBase64.encodeToString(keyPair.public.encoded, AndroidBase64.NO_WRAP),
                 privateKey = AndroidBase64.encodeToString(keyPair.private.encoded, AndroidBase64.NO_WRAP),
-                count = 0
+                count = 0,
+                parentKeyId = derived.parentKeyId,
+                derivationScheme = derived.derivationScheme
             )
             
             Log.d(TAG, "Saving credential to repository")

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

@@ -26,6 +26,8 @@ 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.credentials.KeystoreRecords
+import co.algorand.passkeyautofill.credentials.ParentSecretResult
 import co.algorand.passkeyautofill.utils.PasskeyUtils
 import java.security.KeyPair
 import java.security.MessageDigest
@@ -584,12 +586,19 @@ class GetPasskeyActivity : AppCompatActivity() {
                 )
                 val prfInput = Prf.parseInput(passkeyRequestJsonObj, credentialIdB64Url)
                 if (prfInput != null) {
-                    val hdRootSecret = credentialRepository.getHdRootSecret(this@GetPasskeyActivity)
-                    if (hdRootSecret == null) {
-                        Log.w(TAG, "PRF input present but HD root secret unavailable; skipping PRF output")
+                    // PRF is recomputed from the parent secret on EVERY assertion,
+                    // so it must use the very parent this credential was created
+                    // against — an unstamped credential predates the dp256 main
+                    // key and is pinned to the BIP32-Ed25519 root.
+                    val parent = credentialRepository.resolveParentSecret(
+                        this@GetPasskeyActivity,
+                        dbCred.derivationScheme ?: KeystoreRecords.SCHEME_BIP32_ED25519,
+                    )
+                    if (parent !is ParentSecretResult.Available) {
+                        Log.w(TAG, "PRF input present but parent secret unavailable (${parent.reason}); skipping PRF output")
                     } else {
                         val credRandom = Prf.credRandom(
-                            hdRootSecret = hdRootSecret,
+                            hdRootSecret = parent.secret.bytes,
                             relyingPartyIdentifier = displayOrigin,
                             userHandle = dbCred.userHandle,
                         )

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

@@ -45,7 +45,7 @@ class ReactNativePasskeyAutofillModule : Module() {
 
     Events("onPasskeyAdded", "onPasskeyAuthenticated")
 
-    AsyncFunction("setMasterKey") { secret: String ->
+    AsyncFunction("setMasterKey") { secret: ByteArray ->
       val context = (appContext.reactContext ?: appContext.hostingRuntimeContext) as? Context
       if (context != null) {
         credentialRepository.saveMasterKey(context, secret)
@@ -54,10 +54,34 @@ class ReactNativePasskeyAutofillModule : Module() {
       }
     }
 
+    // Points the passkey hierarchy at the wallet's deterministic-P256 main key.
+    // The scheme is not a parameter: it is read from the record's own metadata,
+    // so a wallet cannot mislabel which hierarchy it handed us.
+    AsyncFunction("setMainKeyId") { id: String ->
+      val context = (appContext.reactContext ?: appContext.hostingRuntimeContext) as? Context
+      if (context != null) {
+        credentialRepository.saveMainKeyId(context, id)
+      } else {
+        Log.e(CredentialRepository.TAG, "Could not get context to save main key ID")
+      }
+    }
+
+    AsyncFunction("getMainKeyId") {
+      val context = (appContext.reactContext ?: appContext.hostingRuntimeContext) as? Context
+      if (context != null) {
+        credentialRepository.getMainKeyId(context)
+      } else {
+        Log.e(CredentialRepository.TAG, "Could not get context to get main key ID")
+        null
+      }
+    }
+
+    // Deprecated aliases of the two above, kept because installed wallets still
+    // call them. They address the same slot — see `saveMainKeyId`.
     AsyncFunction("setHdRootKeyId") { id: String ->
       val context = (appContext.reactContext ?: appContext.hostingRuntimeContext) as? Context
       if (context != null) {
-        credentialRepository.saveHdRootKeyId(context, id)
+        credentialRepository.saveMainKeyId(context, id)
       } else {
         Log.e(CredentialRepository.TAG, "Could not get context to save HD root key ID")
       }
@@ -66,7 +90,7 @@ class ReactNativePasskeyAutofillModule : Module() {
     AsyncFunction("getHdRootKeyId") {
       val context = (appContext.reactContext ?: appContext.hostingRuntimeContext) as? Context
       if (context != null) {
-        credentialRepository.getHdRootKeyId(context)
+        credentialRepository.getMainKeyId(context)
       } else {
         Log.e(CredentialRepository.TAG, "Could not get context to get HD root key ID")
         null
@@ -141,6 +165,7 @@ class ReactNativePasskeyAutofillModule : Module() {
           "userName" to credential.userHandle,
           "userHandle" to credential.userHandle,
           "publicKey" to credential.publicKey,
+          "derivationScheme" to credential.derivationScheme,
         )
       }
     }

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

@@ -8,5 +8,26 @@ data class Credential(
     val publicKey: String,
     val privateKey: String,
     val count: Int,
-    val biometricIv: String? = null
+    val biometricIv: String? = null,
+    /** The root record this credential's key was derived from, when known. */
+    val parentKeyId: String? = null,
+    /**
+     * The derivation scheme this credential is pinned to for life
+     * ([KeystoreRecords.SCHEME_PBKDF2_P256] or
+     * [KeystoreRecords.SCHEME_BIP32_ED25519]).
+     *
+     * `null` on every credential created before the wallet exposed its
+     * deterministic-P256 main key, and those all derive from the BIP32-Ed25519
+     * root — re-deriving one against a different parent would produce a
+     * different key and silently break the passkey the relying party already
+     * trusts.
+     */
+    val derivationScheme: String? = null,
+    /**
+     * Which identity string this credential's material is derived from (see
+     * [PasskeyDerivation]). Records written before the field existed read back as
+     * [PasskeyDerivation.VERSION_LEGACY_LABEL], leaving their derivation
+     * unchanged.
+     */
+    val derivationVersion: Int = PasskeyDerivation.VERSION_LEGACY_LABEL,
 )