react-native-nitro-storage 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,49 @@ All notable changes to this project are documented in this file.
 
 The format follows Keep a Changelog and the project adheres to SemVer.
 
+## 0.8.0 - 2026-08-12
+
+### Breaking changes
+
+- None. `getMetricsSnapshot()` keeps its unscoped, cross-scope aggregate keys.
+  Use the new `getScopedMetricsSnapshot()` when per-scope counters are needed.
+
+### Added
+
+- Exported `PlatformStorage` and `PlatformScope` types from the native, web,
+  and testing entrypoints so shared consumer code can verify platform parity
+  without duplicating the package contract.
+- Added `getScopedMetricsSnapshot()` with keys such as `item:set:1`, without
+  changing established dashboards that consume `getMetricsSnapshot()`.
+
+### Fixed
+
+- **Data-loss prevention:** `storage.import()` now flushes pending coalesced Disk and Secure writes before writing, so a later scheduled flush can never overwrite imported values.
+- **Biometric parity:** promoting a value to biometric storage removes the plain secure copy on iOS and web, matching Android; plain reads can no longer return stale values after promotion.
+- **iOS legacy disk data:** Disk enumeration, size, prefix queries, and clear now cover both the suite domain and legacy `standardUserDefaults` values, so deleted legacy values cannot reappear.
+- **Failure-atomic migrations:** each migration step runs in its own transaction with its version marker; a failed step rolls back its data and marker, and rerunning `migrateToLatest()` retries from the last completed version.
+- **Transaction events:** failed transactions emit exactly one typed `rollback` batch event with pre-rollback and restored raw values.
+- **Atomic memory batch removes:** `removeBatch()` in Memory scope mutates all keys first and emits a single `removeBatch` event.
+- **Stable error classification:** storage error codes now come only from `[nitro-error:<code>]` tags produced by the native and web adapters; message-text scraping was removed and every public code has a producer.
+- **Encoding collisions:** reserved primitive tokens and the native batch missing sentinel are escaped in the stored encoding; legacy reads are preserved and raw API round-trips are unchanged.
+
+### Changed
+
+- `getCapabilities().writeBuffering` now reports real per-mode durability: native Secure writes report buffering only while `setSecureWritesAsync(true)` is active on Android, and web backends report buffering only for IndexedDB-based backends.
+- The IndexedDB backend reports affected keys when `flush()` fails and starts a best-effort flush on `pagehide` and hidden visibility changes.
+- `setIfVersion()` is documented as optimistic (no backend-level atomicity); CAS guarantees are covered by race tests.
+
+## 0.7.0 - 2026-07-30
+
+### Changes
+
+- **Breaking change:** Android secure key discovery, existence checks, and cleanup now surface locked, unavailable, or invalidated biometric-store errors instead of treating inaccessible protected values as absent. Catch storage errors around these operations and use `isKeychainLockedError()` when retrying after device authentication is appropriate.
+- Upgrade the validated package baseline to Expo SDK 57, React Native 0.86.2, and Nitro Modules/Nitrogen 0.36.4.
+- Preserve each item/value relationship in heterogeneous `setBatch()` calls so TypeScript rejects values assigned to the wrong storage item.
+- Serialize native key-index hydration with concurrent mutations so `has`, `size`, and key queries cannot remain stale after a racing write.
+- Enforce Android biometric policy levels with distinct Keystore keys, propagate locked or invalidated biometric failures, and keep secure preference files excluded from backup.
+- Preflight biometric store access before aggregate secure mutations and surface native commit or corruption-recovery failures.
+
 ## 0.6.0 - 2026-06-15
 
 ### Added

package/README.md

@@ -4,9 +4,9 @@
 [![npm downloads](https://img.shields.io/npm/dm/react-native-nitro-storage?color=22c55e&label=downloads)](https://www.npmjs.com/package/react-native-nitro-storage)
 [![CI](https://github.com/JoaoPauloCMarra/react-native-nitro-storage/actions/workflows/ci.yml/badge.svg)](https://github.com/JoaoPauloCMarra/react-native-nitro-storage/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/react-native-nitro-storage?color=007ec6)](https://github.com/JoaoPauloCMarra/react-native-nitro-storage/blob/main/LICENSE)
-[![React Native](https://img.shields.io/badge/react--native-%3E%3D0.75-61dafb)](https://reactnative.dev/)
-[![Expo](https://img.shields.io/badge/expo-SDK%2056-000020)](https://docs.expo.dev/)
-[![Nitro Modules](https://img.shields.io/badge/nitro--modules-%3E%3D0.35.7-black)](https://nitro.margelo.com/)
+[![React Native](https://img.shields.io/badge/react--native-%3E%3D0.75-61dafb)](https://reactnative.dev/docs/0.86/getting-started-without-a-framework)
+[![Expo](https://img.shields.io/badge/expo-SDK%2057-000020)](https://docs.expo.dev/versions/v57.0.0/)
+[![Nitro Modules](https://img.shields.io/badge/nitro--modules-%3E%3D0.36.5%20%3C0.37.0-black)](https://nitro.margelo.com/)
 [![TypeScript](https://img.shields.io/badge/typescript-6.0-3178c6)](https://www.typescriptlang.org/)
 
 Synchronous Memory, Disk, and Secure storage for React Native, Expo development
@@ -53,13 +53,16 @@ bun add react-native-nitro-storage react-native-nitro-modules
 
 Peer dependencies:
 
-| Package                      | Version    |
-| ---------------------------- | ---------- |
-| `react`                      | `>=18.2.0` |
-| `react-native`               | `>=0.75.0` |
-| `react-native-nitro-modules` | `>=0.35.7` |
+| Package                      | Version            |
+| ---------------------------- | ------------------ |
+| `react`                      | `>=18.2.0`         |
+| `react-native`               | `>=0.75.0`         |
+| `react-native-nitro-modules` | `>=0.36.5 <0.37.0` |
 
-Nitro peer requirement: `react-native-nitro-modules >=0.35.7`.
+Nitro peer requirement: `react-native-nitro-modules >=0.36.5 <0.37.0`.
+
+Validated example baseline: Expo SDK 57, React Native 0.86.2, React 19.2.3,
+and Nitro Modules 0.36.5.
 
 For Expo development builds:
 
@@ -180,7 +183,7 @@ const config = diskItem<{ theme: "light" | "dark"; compact: boolean }>({
 });
 
 config.merge({ compact: true }); // shallow object update
-config.reset(); // back to the default value
+config.reset(); // deletes the stored key; the next read returns the default value
 const loginMethod = memoryItem<string | null>({
   key: "loginMethod",
   defaultValue: null,
@@ -371,10 +374,22 @@ exporting secure values unless you are intentionally doing a short-lived
 in-memory migration. `storage.export(StorageScope.Secure)` throws unless you
 explicitly opt into `{ includeSecureValues: true }`.
 
+On Android 11 and newer, `BiometricLevel.BiometryOnly` and
+`BiometricLevel.BiometryOrPasscode` use separate Keystore policies. Android 10
+and older support `BiometryOrPasscode`; `BiometryOnly` throws
+`biometric_unavailable` because those releases cannot safely enforce the
+biometric-only distinction. Promoting a value to biometric storage removes the
+plain secure copy on every platform, so plain reads cannot return a stale
+value. Secure existence, discovery, and cleanup operations
+can also throw when a protected store is locked or its key is invalidated. Catch
+those failures and use `isKeychainLockedError()` when authentication-aware retry
+behavior is appropriate.
+
 ## Batch Operations
 
 `getBatch()` preserves tuple value types, so IDEs infer each result from the
-matching item.
+matching item. `setBatch()` validates every item/value pair independently,
+including heterogeneous batches.
 
 ```ts
 import { getBatch, removeBatch, setBatch } from "react-native-nitro-storage";
@@ -418,10 +433,15 @@ storage.setMetricsObserver((event) => {
 });
 
 const metrics = storage.getMetricsSnapshot();
+const scopedMetrics = storage.getScopedMetricsSnapshot();
 storage.resetMetrics();
 unsubscribe();
 ```
 
+`getMetricsSnapshot()` aggregates each operation across scopes for backward
+compatibility. `getScopedMetricsSnapshot()` adds the numeric scope suffix for
+per-scope analysis, for example `item:set:1`.
+
 Secure event observer values are redacted by default. Pass
 `{ redactSecureValues: false }` only in trusted debug tooling where raw values
 are safe to inspect.
@@ -471,7 +491,11 @@ migrateFromMMKV(mmkvInstance, themeItem);
 ```
 
 `runTransaction(scope, callback)` rolls back every write made through the `tx`
-context if the callback throws.
+context if the callback throws, then emits one typed `rollback` batch event.
+
+Each migration step runs in its own transaction with its version marker, so a
+failed step leaves the scope on the last completed version and rerunning
+`migrateToLatest()` retries deterministically.
 
 ## Web Backends
 

package/SECURITY.md

@@ -6,8 +6,8 @@ Security fixes are shipped for the latest published `0.x` release line.
 
 | Version | Supported |
 | ------- | --------- |
-| `0.5.x` | Yes       |
-| `<0.5`  | No        |
+| `0.8.x` | Yes       |
+| `<0.8`  | No        |
 
 ## Reporting a Vulnerability
 

package/android/src/main/java/com/nitrostorage/AndroidStorageAdapter.kt

@@ -3,7 +3,10 @@
 package com.nitrostorage
 
 import android.content.Context
+import android.os.Build
+import android.security.keystore.KeyGenParameterSpec
 import android.security.keystore.KeyPermanentlyInvalidatedException
+import android.security.keystore.KeyProperties
 import android.security.keystore.UserNotAuthenticatedException
 import android.content.SharedPreferences
 import androidx.security.crypto.EncryptedSharedPreferences
@@ -60,33 +63,113 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         throw RuntimeException("NitroStorage: Cannot create encryption key. Device may not support AES256-GCM.", e)
     }
 
-    private val encryptedPreferences: SharedPreferences = initializeEncryptedPreferences("NitroStorageSecure", masterKey)
+    private val encryptedPreferences: SharedPreferences = initializeEncryptedPreferences(
+        "NitroStorageSecure",
+        masterKey,
+        masterKeyAlias,
+        ::createDefaultMasterKey,
+    )
 
     private val biometricMasterKeyAlias = "${context.packageName}.nitro_storage.biometric_key"
+    private val biometricOrPasscodeMasterKeyAlias =
+        "${context.packageName}.nitro_storage.biometric_or_passcode_key"
+    private val biometricOnlyMasterKeyAlias =
+        "${context.packageName}.nitro_storage.biometric_only_key"
+
+    private val legacyBiometricPreferences: SharedPreferences by lazy {
+        createBiometricPreferences(
+            "NitroStorageBiometric",
+            biometricMasterKeyAlias,
+            1,
+        )
+    }
 
-    private val biometricPreferences: SharedPreferences by lazy {
-        try {
-            val bioKey = MasterKey.Builder(context, biometricMasterKeyAlias)
-                .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
-                .setUserAuthenticationRequired(true, 30)
+    private val biometricOrPasscodePreferences: SharedPreferences by lazy {
+        createBiometricPreferences(
+            "NitroStorageBiometricOrPasscode",
+            biometricOrPasscodeMasterKeyAlias,
+            1,
+        )
+    }
+
+    private val biometricOnlyPreferences: SharedPreferences by lazy {
+        createBiometricPreferences(
+            "NitroStorageBiometricOnly",
+            biometricOnlyMasterKeyAlias,
+            2,
+        )
+    }
+
+    @Volatile
+    private var secureWritesAsync = false
+
+    @Volatile
+    private var secureKeysCache: Array<String>? = null
+
+    private fun createDefaultMasterKey(): MasterKey {
+        return MasterKey.Builder(context, masterKeyAlias)
+            .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
+            .build()
+    }
+
+    private fun createBiometricMasterKey(alias: String, level: Int): MasterKey {
+        if (level == 2 && Build.VERSION.SDK_INT < Build.VERSION_CODES.R) {
+            throw RuntimeException(
+                "[nitro-error:biometric_unavailable] NitroStorage: BiometryOnly requires Android 11 or newer.",
+            )
+        }
+
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            val authenticationTypes = if (level == 1) {
+                KeyProperties.AUTH_BIOMETRIC_STRONG or KeyProperties.AUTH_DEVICE_CREDENTIAL
+            } else {
+                KeyProperties.AUTH_BIOMETRIC_STRONG
+            }
+            val keySpec = KeyGenParameterSpec.Builder(
+                alias,
+                KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT,
+            )
+                .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+                .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+                .setKeySize(256)
+                .setUserAuthenticationRequired(true)
+                .setUserAuthenticationParameters(30, authenticationTypes)
+                .setInvalidatedByBiometricEnrollment(level == 2)
+                .build()
+            return MasterKey.Builder(context, alias)
+                .setKeyGenParameterSpec(keySpec)
                 .build()
-            initializeEncryptedPreferences("NitroStorageBiometric", bioKey)
+        }
+
+        return MasterKey.Builder(context, alias)
+            .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
+            .setUserAuthenticationRequired(true, 30)
+            .build()
+    }
+
+    private fun createBiometricPreferences(
+        name: String,
+        alias: String,
+        level: Int,
+    ): SharedPreferences {
+        return try {
+            val keyFactory = { createBiometricMasterKey(alias, level) }
+            initializeEncryptedPreferences(name, keyFactory(), alias, keyFactory)
         } catch (e: Exception) {
             throw e.wrapStorageException(
                 "NitroStorage: Biometric storage is not available on this device. " +
-                    "Ensure biometric hardware is present and credentials are enrolled.",
+                    "Ensure supported authentication is enrolled.",
                 defaultCode = "biometric_unavailable",
             )
         }
     }
 
-    @Volatile
-    private var secureWritesAsync = false
-
-    @Volatile
-    private var secureKeysCache: Array<String>? = null
-
-    private fun initializeEncryptedPreferences(name: String, key: MasterKey): SharedPreferences {
+    private fun initializeEncryptedPreferences(
+        name: String,
+        key: MasterKey,
+        alias: String,
+        keyFactory: () -> MasterKey,
+    ): SharedPreferences {
         return try {
             EncryptedSharedPreferences.create(
                 context, name, key,
@@ -96,16 +179,8 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         } catch (e: Exception) {
             when {
                 e.hasCause(AEADBadTagException::class.java) -> {
-                    clearCorruptedStorage(name, key)
-                    val freshAlias = if (name == "NitroStorageBiometric") biometricMasterKeyAlias else masterKeyAlias
-                    val freshKey = MasterKey.Builder(context, freshAlias)
-                        .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
-                        .apply {
-                            if (name == "NitroStorageBiometric") {
-                                setUserAuthenticationRequired(true, 30)
-                            }
-                        }
-                        .build()
+                    clearCorruptedStorage(name, alias)
+                    val freshKey = keyFactory()
                     try {
                         EncryptedSharedPreferences.create(
                             context, name, freshKey,
@@ -120,7 +195,6 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
                     }
                 }
                 else -> {
-                    // Don't wipe on non-corruption failures (e.g., locked keystore)
                     throw e.wrapStorageException(
                         "NitroStorage: Failed to initialize $name (${e::class.simpleName}). " +
                             "This may be a temporary keystore issue. If it persists, clear app data.",
@@ -130,18 +204,58 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         }
     }
 
-    private fun clearCorruptedStorage(name: String, key: MasterKey) {
-        try {
-            context.deleteSharedPreferences(name)
-            val keyStore = KeyStore.getInstance("AndroidKeyStore")
-            keyStore.load(null)
-            val alias = when {
-                name == "NitroStorageSecure" -> masterKeyAlias
-                name == "NitroStorageBiometric" -> biometricMasterKeyAlias
-                else -> masterKeyAlias
-            }
-            keyStore.deleteEntry(alias)
-        } catch (_: Exception) {
+    private fun clearCorruptedStorage(name: String, alias: String) {
+        context.deleteSharedPreferences(name)
+        val keyStore = KeyStore.getInstance("AndroidKeyStore")
+        keyStore.load(null)
+        keyStore.deleteEntry(alias)
+    }
+
+    private fun preferencesFileExists(name: String): Boolean {
+        return context.getSharedPreferences(name, Context.MODE_PRIVATE).all.isNotEmpty()
+    }
+
+    private fun existingBiometricPreferences(): List<SharedPreferences> {
+        val stores = mutableListOf<SharedPreferences>()
+        if (preferencesFileExists("NitroStorageBiometricOnly")) {
+            stores.add(biometricOnlyPreferences)
+        }
+        if (preferencesFileExists("NitroStorageBiometricOrPasscode")) {
+            stores.add(biometricOrPasscodePreferences)
+        }
+        if (preferencesFileExists("NitroStorageBiometric")) {
+            stores.add(legacyBiometricPreferences)
+        }
+        for (preferences in stores) {
+            preferences.all
+        }
+        return stores
+    }
+
+    private fun biometricPreferencesForLevel(level: Int): SharedPreferences {
+        return when (level) {
+            1 -> biometricOrPasscodePreferences
+            2 -> biometricOnlyPreferences
+            else -> throw IllegalArgumentException(
+                "NitroStorage: Invalid biometric level. Expected 0, 1, or 2.",
+            )
+        }
+    }
+
+    private fun removeBiometricKey(
+        key: String,
+        preferencesList: List<SharedPreferences> = existingBiometricPreferences(),
+    ) {
+        for (preferences in preferencesList) {
+            applySecureEditor(preferences.edit().remove(key))
+        }
+    }
+
+    private fun clearBiometricStores(
+        preferencesList: List<SharedPreferences> = existingBiometricPreferences(),
+    ) {
+        for (preferences in preferencesList) {
+            applySecureEditor(preferences.edit().clear())
         }
     }
 
@@ -162,8 +276,8 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         try {
             if (secureWritesAsync) {
                 editor.apply()
-            } else {
-                editor.commit()
+            } else if (!editor.commit()) {
+                throw IllegalStateException("SharedPreferences commit returned false")
             }
         } catch (e: Exception) {
             throw e.wrapStorageException(
@@ -192,9 +306,8 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
             val INTERNAL_PREFIX = "__androidx_security_crypto_encrypted_prefs_"
             val keys = linkedSetOf<String>()
             keys.addAll(encryptedPreferences.all.keys.filter { !it.startsWith(INTERNAL_PREFIX) })
-            try {
-                keys.addAll(biometricPreferences.all.keys.filter { !it.startsWith(INTERNAL_PREFIX) })
-            } catch (_: Exception) {
+            for (preferences in existingBiometricPreferences()) {
+                keys.addAll(preferences.all.keys.filter { !it.startsWith(INTERNAL_PREFIX) })
             }
             val built = keys.toTypedArray()
             secureKeysCache = built
@@ -361,11 +474,9 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         fun deleteSecure(key: String) {
             val inst = getInstanceOrThrow()
             synchronized(inst) {
+                val biometricPreferences = inst.existingBiometricPreferences()
                 inst.applySecureEditor(inst.encryptedPreferences.edit().remove(key))
-                try {
-                    inst.applySecureEditor(inst.biometricPreferences.edit().remove(key))
-                } catch (_: Exception) {
-                }
+                inst.removeBiometricKey(key, biometricPreferences)
                 inst.invalidateSecureKeysCache()
             }
         }
@@ -374,18 +485,18 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         fun deleteSecureBatch(keys: Array<String>) {
             val inst = getInstanceOrThrow()
             synchronized(inst) {
+                val biometricPreferences = inst.existingBiometricPreferences()
                 val editor = inst.encryptedPreferences.edit()
                 for (key in keys) {
                     editor.remove(key)
                 }
                 inst.applySecureEditor(editor)
-                try {
-                    val biometricEditor = inst.biometricPreferences.edit()
+                for (preferences in biometricPreferences) {
+                    val biometricEditor = preferences.edit()
                     for (key in keys) {
                         biometricEditor.remove(key)
                     }
                     inst.applySecureEditor(biometricEditor)
-                } catch (_: Exception) {
                 }
                 inst.invalidateSecureKeysCache()
             }
@@ -394,13 +505,10 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         @JvmStatic
         fun hasSecure(key: String): Boolean {
             val inst = getInstanceOrThrow()
-            val hasInEncrypted = inst.encryptedPreferences.contains(key)
-            val hasInBiometric = try {
-                inst.biometricPreferences.contains(key)
-            } catch (_: Exception) {
-                false
+            if (inst.encryptedPreferences.contains(key)) {
+                return true
             }
-            return hasInEncrypted || hasInBiometric
+            return inst.existingBiometricPreferences().any { it.contains(key) }
         }
 
         @JvmStatic
@@ -422,12 +530,12 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         @JvmStatic
         fun clearSecure() {
             val inst = getInstanceOrThrow()
-            inst.applySecureEditor(inst.encryptedPreferences.edit().clear())
-            try {
-                inst.applySecureEditor(inst.biometricPreferences.edit().clear())
-            } catch (_: Exception) {
+            synchronized(inst) {
+                val biometricPreferences = inst.existingBiometricPreferences()
+                inst.applySecureEditor(inst.encryptedPreferences.edit().clear())
+                inst.clearBiometricStores(biometricPreferences)
+                inst.invalidateSecureKeysCache()
             }
-            inst.invalidateSecureKeysCache()
         }
 
         // --- Biometric (separate encrypted store, requires recent biometric auth on Android) ---
@@ -438,12 +546,32 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         }
 
         @JvmStatic
-        fun setSecureBiometricWithLevel(key: String, value: String, @Suppress("UNUSED_PARAMETER") level: Int) {
+        fun setSecureBiometricWithLevel(key: String, value: String, level: Int) {
             val inst = getInstanceOrThrow()
             try {
-                val editor = inst.biometricPreferences.edit().putString(key, value)
-                inst.applySecureEditor(editor)
-                inst.invalidateSecureKeysCache()
+                synchronized(inst) {
+                    val biometricPreferences = inst.existingBiometricPreferences()
+                    if (level == 0) {
+                        inst.removeBiometricKey(key, biometricPreferences)
+                        inst.applySecureEditor(
+                            inst.encryptedPreferences.edit().putString(key, value),
+                        )
+                    } else {
+                        val targetPreferences = inst.biometricPreferencesForLevel(level)
+                        inst.applySecureEditor(
+                            targetPreferences.edit().putString(key, value),
+                        )
+                        inst.applySecureEditor(
+                            inst.encryptedPreferences.edit().remove(key),
+                        )
+                        for (preferences in biometricPreferences) {
+                            if (preferences !== targetPreferences) {
+                                inst.applySecureEditor(preferences.edit().remove(key))
+                            }
+                        }
+                    }
+                    inst.invalidateSecureKeysCache()
+                }
             } catch (e: Exception) {
                 throw e.wrapStorageException(
                     "NitroStorage: Biometric storage unavailable on this device",
@@ -456,9 +584,17 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         fun getSecureBiometric(key: String): String? {
             val inst = getInstanceOrThrow()
             return try {
-                inst.getSecureSafe(inst.biometricPreferences, key)
-            } catch (_: Exception) {
+                for (preferences in inst.existingBiometricPreferences()) {
+                    val value = inst.getSecureSafe(preferences, key)
+                    if (value != null) {
+                        return value
+                    }
+                }
                 null
+            } catch (e: Exception) {
+                throw e.wrapStorageException(
+                    "NitroStorage: Failed to read biometric storage: ${e.message}",
+                )
             }
         }
 
@@ -466,18 +602,26 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         fun deleteSecureBiometric(key: String) {
             val inst = getInstanceOrThrow()
             try {
-                inst.applySecureEditor(inst.biometricPreferences.edit().remove(key))
-                inst.invalidateSecureKeysCache()
-            } catch (_: Exception) {
+                synchronized(inst) {
+                    inst.removeBiometricKey(key)
+                    inst.invalidateSecureKeysCache()
+                }
+            } catch (e: Exception) {
+                throw e.wrapStorageException(
+                    "NitroStorage: Failed to delete biometric storage: ${e.message}",
+                )
             }
         }
 
         @JvmStatic
         fun hasSecureBiometric(key: String): Boolean {
+            val inst = getInstanceOrThrow()
             return try {
-                getInstanceOrThrow().biometricPreferences.contains(key)
-            } catch (_: Exception) {
-                false
+                inst.existingBiometricPreferences().any { it.contains(key) }
+            } catch (e: Exception) {
+                throw e.wrapStorageException(
+                    "NitroStorage: Failed to inspect biometric storage: ${e.message}",
+                )
             }
         }
 
@@ -485,9 +629,14 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         fun clearSecureBiometric() {
             val inst = getInstanceOrThrow()
             try {
-                inst.applySecureEditor(inst.biometricPreferences.edit().clear())
-                inst.invalidateSecureKeysCache()
-            } catch (_: Exception) {
+                synchronized(inst) {
+                    inst.clearBiometricStores()
+                    inst.invalidateSecureKeysCache()
+                }
+            } catch (e: Exception) {
+                throw e.wrapStorageException(
+                    "NitroStorage: Failed to clear biometric storage: ${e.message}",
+                )
             }
         }
     }

package/app.plugin.js

@@ -15,6 +15,8 @@ const FULL_BACKUP_CONTENT_RESOURCE = "@xml/nitro_storage_full_backup_content";
 const secureSharedPrefs = [
   "NitroStorageSecure.xml",
   "NitroStorageBiometric.xml",
+  "NitroStorageBiometricOrPasscode.xml",
+  "NitroStorageBiometricOnly.xml",
 ];
 
 function sharedPrefsExcludes(indent = "    ") {

package/cpp/bindings/HybridStorage.cpp

@@ -672,12 +672,10 @@ void HybridStorage::ensureKeyIndexHydrated(int scope) {
         return;
     }
 
-    {
-        std::lock_guard<std::mutex> lock(keyIndexMutex_);
-        auto hydratedIt = keyIndexHydrated_.find(scope);
-        if (hydratedIt != keyIndexHydrated_.end() && hydratedIt->second) {
-            return;
-        }
+    std::lock_guard<std::mutex> lock(keyIndexMutex_);
+    auto hydratedIt = keyIndexHydrated_.find(scope);
+    if (hydratedIt != keyIndexHydrated_.end() && hydratedIt->second) {
+        return;
     }
 
     ensureAdapter();
@@ -694,12 +692,6 @@ void HybridStorage::ensureKeyIndexHydrated(int scope) {
         throw std::runtime_error("NitroStorage: Key index hydration failed (unknown error)");
     }
 
-    std::lock_guard<std::mutex> lock(keyIndexMutex_);
-    // Double-check: another thread may have hydrated while we fetched
-    auto hydratedIt = keyIndexHydrated_.find(scope);
-    if (hydratedIt != keyIndexHydrated_.end() && hydratedIt->second) {
-        return; // discard our results
-    }
     auto& index = keyIndex_[scope];
     index.clear();
     for (const auto& key : keys) {

package/docs/api-reference.md

@@ -152,7 +152,7 @@ storage.setEventObserver((event) => {
 
 `setEventObserver()` redacts Secure `oldValue` and `newValue` fields by default. Pass `{ redactSecureValues: false }` only for in-memory debugging paths that never persist logs. Raw `subscribe*()` APIs preserve values for state integrations.
 
-Local batch APIs emit one `type: "batch"` envelope to scope and prefix/namespace listeners. Key subscribers receive the matching per-key change so direct key integrations do not need to unpack batch envelopes. Secure events can include raw secret values; do not log Secure event payloads in production.
+Local batch APIs emit one `type: "batch"` envelope to scope and prefix/namespace listeners. Key subscribers receive the matching per-key change so direct key integrations do not need to unpack batch envelopes. Failed transactions emit one batch envelope with `operation: "rollback"` whose changes carry the pre-rollback and restored raw values. Secure events can include raw secret values; do not log Secure event payloads in production.
 
 ## Batch Operations
 
@@ -280,5 +280,15 @@ Common public types:
 - `WebSecureStorageBackend`
 - `WebStorageChangeEvent`
 - `WebStorageScope`
+- `PlatformStorage`
+- `PlatformScope`
+- `WebBackendCapabilities`
+
+`getCapabilities().writeBuffering` describes real per-mode durability:
+
+- Native: Disk writes are buffered by the platform (`SharedPreferences.apply()` on Android, `NSUserDefaults` on iOS). Secure writes are buffered only when `setSecureWritesAsync(true)` is active on Android; iOS Keychain writes are synchronous.
+- Web: buffering follows the configured backend; IndexedDB backends are buffered, localStorage backends are synchronous.
+
+`describeWebBackendCapabilities(backend)` reports a backend's `buffered`, `flushable`, `closable`, and `subscribable` capabilities from the same typed contract used by the built-in backends.
 
 The IndexedDB subpath exports `createIndexedDBBackend()` and `IndexedDBBackendOptions`.