react-native-nitro-storage 0.4.1 → 0.4.3

package/README.md

@@ -47,6 +47,8 @@ Every feature in this package is documented with at least one runnable example i
 - Transactions — see Transactions and Atomic Balance Transfer
 - Migrations (`registerMigration`, `migrateToLatest`) — see Migrations
 - MMKV migration (`migrateFromMMKV`) — see MMKV Migration and Migrating From MMKV
+- Raw string API (`getString`, `setString`, `deleteString`) — see Raw String API
+- Keychain locked detection (`isKeychainLockedError`) — see `isKeychainLockedError(err)`
 - Auth storage factory (`createSecureAuthStorage`) — see Auth Token Management
 
 ## Requirements
@@ -280,6 +282,9 @@ import { storage, StorageScope } from "react-native-nitro-storage";
 | `storage.setSecureWritesAsync(enabled)`  | Toggle async secure writes on Android (`false` by default)                   |
 | `storage.flushSecureWrites()`            | Force flush of queued secure writes when coalescing is enabled               |
 | `storage.setKeychainAccessGroup(group)`  | Set keychain access group for app sharing (native only)                      |
+| `storage.getString(key, scope)`          | Read a raw string value directly (bypasses serialization)                    |
+| `storage.setString(key, value, scope)`   | Write a raw string value directly (bypasses serialization)                   |
+| `storage.deleteString(key, scope)`       | Delete a raw string value by key                                             |
 | `storage.import(data, scope)`            | Bulk-load a `Record<string, string>` of raw key/value pairs into a scope     |
 | `storage.setMetricsObserver(observer?)`  | Subscribe to per-operation timing events                                     |
 | `storage.getMetricsSnapshot()`           | Get aggregate counters/latency stats keyed by operation                      |
@@ -509,6 +514,40 @@ const migrated = migrateFromMMKV(mmkv, myStorageItem, true);
 
 ---
 
+### Raw String API
+
+For cases where you want to bypass `createStorageItem` serialization entirely and work with raw key/value strings:
+
+```ts
+import { storage, StorageScope } from "react-native-nitro-storage";
+
+storage.setString("raw-key", "raw-value", StorageScope.Disk);
+const value = storage.getString("raw-key", StorageScope.Disk); // "raw-value" | undefined
+storage.deleteString("raw-key", StorageScope.Disk);
+```
+
+These are synchronous and go directly to the native backend without any serialize/deserialize step.
+
+---
+
+### `isKeychainLockedError(err)`
+
+Utility to detect iOS Keychain locked errors and Android key invalidation errors in secure storage operations. Returns `true` if the error was caused by a locked keychain (device locked, first unlock not yet performed, etc.) or an Android `KeyPermanentlyInvalidatedException` / `InvalidKeyException`. Always returns `false` on web.
+
+```ts
+import { isKeychainLockedError } from "react-native-nitro-storage";
+
+try {
+  secureItem.get();
+} catch (err) {
+  if (isKeychainLockedError(err)) {
+    // device is locked — retry after unlock
+  }
+}
+```
+
+---
+
 ### Enums
 
 #### `AccessControl`

package/android/build.gradle

@@ -14,19 +14,11 @@ def reactNativeArchitectures() {
   return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
 }
 
-def isNewArchitectureEnabled() {
-  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
-}
-
 apply plugin: "com.android.library"
 apply plugin: "org.jetbrains.kotlin.android"
 // Apply autolinking script for Nitro
 apply from: "../nitrogen/generated/android/NitroStorage+autolinking.gradle"
 
-if (isNewArchitectureEnabled()) {
-  apply plugin: "com.facebook.react"
-}
-
 def getExtOrDefault(name) {
   return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["NitroStorage_" + name]
 }
@@ -45,7 +37,6 @@ android {
   defaultConfig {
     minSdkVersion getExtOrIntegerDefault("minSdkVersion")
     targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
-    buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
     consumerProguardFiles "consumer-rules.pro"
 
     externalNativeBuild {
@@ -76,9 +67,6 @@ android {
   sourceSets {
     main {
       java.srcDirs += ["src/main/java"]
-      if (isNewArchitectureEnabled()) {
-        java.srcDirs += ["${project.buildDir}/generated/source/codegen/java"]
-      }
     }
   }
 }

package/android/consumer-rules.pro

@@ -1,4 +1,26 @@
-# Keep AndroidStorageAdapter and all its methods - accessed via JNI reflection
--keep class com.nitrostorage.AndroidStorageAdapter { *; }
--keepclassmembers class com.nitrostorage.AndroidStorageAdapter { *; }
--keepclassmembers class com.nitrostorage.AndroidStorageAdapter$Companion { *; }
+# NitroStorage - JNI-callable methods must survive R8/ProGuard shrinking
+
+-keep class com.nitrostorage.AndroidStorageAdapter {
+    public static *** set*(...);
+    public static *** get*(...);
+    public static *** delete*(...);
+    public static *** has*(...);
+    public static *** clear*(...);
+    public static *** size*(...);
+    public static *** flush*(...);
+    public static void init(android.content.Context);
+    public static void setSecureWritesAsync(boolean);
+    public static void setSecureAccessControl(int);
+    public static void removeByPrefix(java.lang.String, int);
+}
+-keep class com.nitrostorage.AndroidStorageAdapter$Companion {
+    public <methods>;
+}
+-keep class com.nitrostorage.NitroStoragePackage {
+    <init>();
+    <clinit>();
+    *;
+}
+-keep class com.nitrostorage.NitroStoragePackage$Companion {
+    *;
+}

package/android/src/main/cpp/AndroidStorageAdapterCpp.cpp

@@ -34,26 +34,23 @@ std::vector<std::optional<std::string>> fromNullableJavaStringArray(alias_ref<Ja
 }
 
 std::vector<std::string> fromJavaStringArray(alias_ref<JavaStringArray> values) {
+    if (!values) return {};
+    const jsize size = values->size();
     std::vector<std::string> result;
-    if (!values) return result;
-
-    const jsize size = static_cast<jsize>(values->size());
     result.reserve(size);
     for (jsize i = 0; i < size; ++i) {
         auto currentValue = values->getElement(i);
-        if (currentValue) {
-            result.push_back(currentValue->toStdString());
-        }
+        // Preserve null as empty string to maintain index alignment with caller
+        result.push_back(currentValue ? currentValue->toStdString() : std::string());
     }
     return result;
 }
 
 } // namespace
 
-AndroidStorageAdapterCpp::AndroidStorageAdapterCpp(alias_ref<JObject> context) {
-    if (!context) [[unlikely]] {
-        throw std::runtime_error("NitroStorage: Android Context is null");
-    }
+AndroidStorageAdapterCpp::AndroidStorageAdapterCpp(alias_ref<JObject> /*context*/) {
+    // Context is validated by AndroidStorageAdapter.getContext() on the Java side.
+    // The adapter calls static Java methods directly via fbjni.
 }
 
 AndroidStorageAdapterCpp::~AndroidStorageAdapterCpp() = default;

package/android/src/main/cpp/AndroidStorageAdapterCpp.hpp

@@ -6,10 +6,6 @@
 
 namespace NitroStorage {
 
-struct JContext : facebook::jni::JavaClass<JContext> {
-  static constexpr auto kJavaDescriptor = "Landroid/content/Context;";
-};
-
 struct AndroidStorageAdapterJava : facebook::jni::JavaClass<AndroidStorageAdapterJava> {
   static constexpr auto kJavaDescriptor = "Lcom/nitrostorage/AndroidStorageAdapter;";
   

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

@@ -8,15 +8,29 @@ import androidx.security.crypto.MasterKey
 import java.security.KeyStore
 import javax.crypto.AEADBadTagException
 
+private fun Throwable.hasCause(type: Class<*>): Boolean {
+    var current: Throwable? = this
+    while (current != null) {
+        if (type.isInstance(current)) return true
+        current = current.cause
+    }
+    return false
+}
+
 class AndroidStorageAdapter private constructor(private val context: Context) {
-    private val sharedPreferences: SharedPreferences = 
+    private val sharedPreferences: SharedPreferences =
         context.getSharedPreferences("NitroStorage", Context.MODE_PRIVATE)
 
     private val masterKeyAlias = "${context.packageName}.nitro_storage.master_key"
-    private val masterKey: MasterKey = MasterKey.Builder(context, masterKeyAlias)
-        .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
-        .build()
-    
+
+    private val masterKey: MasterKey = try {
+        MasterKey.Builder(context, masterKeyAlias)
+            .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
+            .build()
+    } catch (e: Exception) {
+        throw RuntimeException("NitroStorage: Cannot create encryption key. Device may not support AES256-GCM.", e)
+    }
+
     private val encryptedPreferences: SharedPreferences = initializeEncryptedPreferences("NitroStorageSecure", masterKey)
 
     private val biometricMasterKeyAlias = "${context.packageName}.nitro_storage.biometric_key"
@@ -29,8 +43,9 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
                 .build()
             initializeEncryptedPreferences("NitroStorageBiometric", bioKey)
         } catch (e: Exception) {
-            Log.w("NitroStorage", "Biometric storage unavailable, falling back to regular encrypted storage: ${e.message}")
-            encryptedPreferences
+            Log.e("NitroStorage", "Biometric storage unavailable: ${e.message}")
+            throw RuntimeException("NitroStorage: Biometric storage is not available on this device. " +
+                "Ensure biometric hardware is present and credentials are enrolled.", e)
         }
     }
 
@@ -39,47 +54,63 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
 
     @Volatile
     private var secureKeysCache: Array<String>? = null
-    
+
     private fun initializeEncryptedPreferences(name: String, key: MasterKey): SharedPreferences {
         return try {
             EncryptedSharedPreferences.create(
-                context,
-                name,
-                key,
+                context, name, key,
                 EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
                 EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
             )
         } catch (e: Exception) {
-            if (e is AEADBadTagException || e.cause is AEADBadTagException) {
-                Log.w("NitroStorage", "Detected corrupted encryption keys for $name, clearing...")
-                clearCorruptedStorage(name, key)
-                EncryptedSharedPreferences.create(
-                    context,
-                    name,
-                    key,
-                    EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
-                    EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
-                )
-            } else {
-                throw RuntimeException(
-                    "NitroStorage: Failed to initialize $name. " +
-                    "This may be due to corrupted encryption keys. " +
-                    "Try clearing app data or reinstalling the app.", e
-                )
+            when {
+                e.hasCause(AEADBadTagException::class.java) -> {
+                    Log.w("NitroStorage", "Corrupted encryption keys for $name, attempting recovery...")
+                    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()
+                    try {
+                        EncryptedSharedPreferences.create(
+                            context, name, freshKey,
+                            EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
+                            EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
+                        )
+                    } catch (retryEx: Exception) {
+                        throw RuntimeException("NitroStorage: Unrecoverable storage corruption in $name", retryEx)
+                    }
+                }
+                else -> {
+                    // Don't wipe on non-corruption failures (e.g., locked keystore)
+                    throw RuntimeException(
+                        "NitroStorage: Failed to initialize $name (${e::class.simpleName}). " +
+                        "This may be a temporary keystore issue. If it persists, clear app data.", e
+                    )
+                }
             }
         }
     }
-    
+
     private fun clearCorruptedStorage(name: String, key: MasterKey) {
         try {
             context.deleteSharedPreferences(name)
             val keyStore = KeyStore.getInstance("AndroidKeyStore")
             keyStore.load(null)
-            val alias = if (key === masterKey) masterKeyAlias else biometricMasterKeyAlias
+            val alias = when {
+                name == "NitroStorageSecure" -> masterKeyAlias
+                name == "NitroStorageBiometric" -> biometricMasterKeyAlias
+                else -> masterKeyAlias
+            }
             keyStore.deleteEntry(alias)
             Log.i("NitroStorage", "Cleared corrupted storage: $name")
         } catch (e: Exception) {
-            Log.e("NitroStorage", "Failed to clear corrupted storage: $name", e)
+            Log.e("NitroStorage", "Failed to clear corrupted storage $name: ${e.message}", e)
         }
     }
 
@@ -87,7 +118,7 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         return try {
             prefs.getString(key, null)
         } catch (e: Exception) {
-            if (e is AEADBadTagException || e.cause is AEADBadTagException) {
+            if (e.hasCause(AEADBadTagException::class.java)) {
                 Log.w("NitroStorage", "Corrupt entry for key '$key', removing")
                 prefs.edit().remove(key).commit()
                 null
@@ -98,15 +129,21 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
     }
 
     private fun applySecureEditor(editor: SharedPreferences.Editor) {
-        if (secureWritesAsync) {
-            editor.apply()
-        } else {
-            editor.commit()
+        try {
+            if (secureWritesAsync) {
+                editor.apply()
+            } else {
+                editor.commit()
+            }
+        } catch (e: Exception) {
+            throw RuntimeException("NitroStorage: Failed to write to secure storage: ${e.message}", e)
         }
     }
 
     private fun invalidateSecureKeysCache() {
-        secureKeysCache = null
+        synchronized(this) {
+            secureKeysCache = null
+        }
     }
 
     private fun getSecureKeysCached(): Array<String> {
@@ -120,15 +157,20 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
             if (existing != null) {
                 return existing
             }
+            val INTERNAL_PREFIX = "__androidx_security_crypto_encrypted_prefs_"
             val keys = linkedSetOf<String>()
-            keys.addAll(encryptedPreferences.all.keys)
-            keys.addAll(biometricPreferences.all.keys)
+            keys.addAll(encryptedPreferences.all.keys.filter { !it.startsWith(INTERNAL_PREFIX) })
+            try {
+                keys.addAll(biometricPreferences.all.keys.filter { !it.startsWith(INTERNAL_PREFIX) })
+            } catch (e: Exception) {
+                Log.d("NitroStorage", "Biometric storage unavailable: ${e.message}")
+            }
             val built = keys.toTypedArray()
             secureKeysCache = built
             return built
         }
     }
-    
+
     companion object {
         @Volatile
         private var instance: AndroidStorageAdapter? = null
@@ -162,7 +204,7 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         }
 
         // --- Disk ---
-        
+
         @JvmStatic
         fun setDisk(key: String, value: String) {
             getInstanceOrThrow().sharedPreferences.edit().putString(key, value).apply()
@@ -177,7 +219,7 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
             }
             editor.apply()
         }
-        
+
         @JvmStatic
         fun getDisk(key: String): String? {
             return getInstanceOrThrow().sharedPreferences.getString(key, null)
@@ -190,7 +232,7 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
                 prefs.getString(keys[index], null)
             }
         }
-        
+
         @JvmStatic
         fun deleteDisk(key: String) {
             getInstanceOrThrow().sharedPreferences.edit().remove(key).apply()
@@ -233,30 +275,35 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         }
 
         // --- Secure (sync commit by default, async apply when enabled) ---
-        
+
         @JvmStatic
         fun setSecure(key: String, value: String) {
             val inst = getInstanceOrThrow()
-            val editor = inst.encryptedPreferences.edit().putString(key, value)
-            inst.applySecureEditor(editor)
-            inst.invalidateSecureKeysCache()
+            synchronized(inst) {
+                val editor = inst.encryptedPreferences.edit().putString(key, value)
+                inst.applySecureEditor(editor)
+                inst.invalidateSecureKeysCache()
+            }
         }
 
         @JvmStatic
         fun setSecureBatch(keys: Array<String>, values: Array<String>) {
             val inst = getInstanceOrThrow()
-            val editor = inst.encryptedPreferences.edit()
-            val count = minOf(keys.size, values.size)
-            for (index in 0 until count) {
-                editor.putString(keys[index], values[index])
+            synchronized(inst) {
+                val editor = inst.encryptedPreferences.edit()
+                val count = minOf(keys.size, values.size)
+                for (index in 0 until count) {
+                    editor.putString(keys[index], values[index])
+                }
+                inst.applySecureEditor(editor)
+                inst.invalidateSecureKeysCache()
             }
-            inst.applySecureEditor(editor)
-            inst.invalidateSecureKeysCache()
         }
-        
+
         @JvmStatic
         fun getSecure(key: String): String? {
-            return getInstanceOrThrow().getSecureSafe(getInstanceOrThrow().encryptedPreferences, key)
+            val inst = getInstanceOrThrow()
+            return inst.getSecureSafe(inst.encryptedPreferences, key)
         }
 
         @JvmStatic
@@ -266,33 +313,54 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
                 inst.getSecureSafe(inst.encryptedPreferences, keys[index])
             }
         }
-        
+
         @JvmStatic
         fun deleteSecure(key: String) {
             val inst = getInstanceOrThrow()
-            inst.applySecureEditor(inst.encryptedPreferences.edit().remove(key))
-            inst.applySecureEditor(inst.biometricPreferences.edit().remove(key))
-            inst.invalidateSecureKeysCache()
+            synchronized(inst) {
+                inst.applySecureEditor(inst.encryptedPreferences.edit().remove(key))
+                try {
+                    inst.applySecureEditor(inst.biometricPreferences.edit().remove(key))
+                } catch (e: Exception) {
+                    Log.d("NitroStorage", "Biometric storage unavailable: ${e.message}")
+                }
+                inst.invalidateSecureKeysCache()
+            }
         }
 
         @JvmStatic
         fun deleteSecureBatch(keys: Array<String>) {
             val inst = getInstanceOrThrow()
-            val secureEditor = inst.encryptedPreferences.edit()
-            val biometricEditor = inst.biometricPreferences.edit()
-            for (key in keys) {
-                secureEditor.remove(key)
-                biometricEditor.remove(key)
+            synchronized(inst) {
+                val editor = inst.encryptedPreferences.edit()
+                for (key in keys) {
+                    editor.remove(key)
+                }
+                inst.applySecureEditor(editor)
+                try {
+                    val biometricEditor = inst.biometricPreferences.edit()
+                    for (key in keys) {
+                        biometricEditor.remove(key)
+                    }
+                    inst.applySecureEditor(biometricEditor)
+                } catch (e: Exception) {
+                    Log.d("NitroStorage", "Biometric storage unavailable: ${e.message}")
+                }
+                inst.invalidateSecureKeysCache()
             }
-            inst.applySecureEditor(secureEditor)
-            inst.applySecureEditor(biometricEditor)
-            inst.invalidateSecureKeysCache()
         }
 
         @JvmStatic
         fun hasSecure(key: String): Boolean {
             val inst = getInstanceOrThrow()
-            return inst.encryptedPreferences.contains(key) || inst.biometricPreferences.contains(key)
+            val hasInEncrypted = inst.encryptedPreferences.contains(key)
+            val hasInBiometric = try {
+                inst.biometricPreferences.contains(key)
+            } catch (e: Exception) {
+                Log.d("NitroStorage", "Biometric storage unavailable: ${e.message}")
+                false
+            }
+            return hasInEncrypted || hasInBiometric
         }
 
         @JvmStatic
@@ -315,7 +383,11 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         fun clearSecure() {
             val inst = getInstanceOrThrow()
             inst.applySecureEditor(inst.encryptedPreferences.edit().clear())
-            inst.applySecureEditor(inst.biometricPreferences.edit().clear())
+            try {
+                inst.applySecureEditor(inst.biometricPreferences.edit().clear())
+            } catch (e: Exception) {
+                Log.d("NitroStorage", "Biometric storage unavailable: ${e.message}")
+            }
             inst.invalidateSecureKeysCache()
         }
 
@@ -329,33 +401,56 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         @JvmStatic
         fun setSecureBiometricWithLevel(key: String, value: String, @Suppress("UNUSED_PARAMETER") level: Int) {
             val inst = getInstanceOrThrow()
-            val editor = inst.biometricPreferences.edit().putString(key, value)
-            inst.applySecureEditor(editor)
-            inst.invalidateSecureKeysCache()
+            try {
+                val editor = inst.biometricPreferences.edit().putString(key, value)
+                inst.applySecureEditor(editor)
+                inst.invalidateSecureKeysCache()
+            } catch (e: Exception) {
+                throw RuntimeException("NitroStorage: Biometric storage unavailable on this device", e)
+            }
         }
 
         @JvmStatic
         fun getSecureBiometric(key: String): String? {
-            return getInstanceOrThrow().getSecureSafe(getInstanceOrThrow().biometricPreferences, key)
+            val inst = getInstanceOrThrow()
+            return try {
+                inst.getSecureSafe(inst.biometricPreferences, key)
+            } catch (e: Exception) {
+                Log.d("NitroStorage", "Biometric storage unavailable: ${e.message}")
+                null
+            }
         }
 
         @JvmStatic
         fun deleteSecureBiometric(key: String) {
             val inst = getInstanceOrThrow()
-            inst.applySecureEditor(inst.biometricPreferences.edit().remove(key))
-            inst.invalidateSecureKeysCache()
+            try {
+                inst.applySecureEditor(inst.biometricPreferences.edit().remove(key))
+                inst.invalidateSecureKeysCache()
+            } catch (e: Exception) {
+                Log.d("NitroStorage", "Biometric storage unavailable: ${e.message}")
+            }
         }
 
         @JvmStatic
         fun hasSecureBiometric(key: String): Boolean {
-            return getInstanceOrThrow().biometricPreferences.contains(key)
+            return try {
+                getInstanceOrThrow().biometricPreferences.contains(key)
+            } catch (e: Exception) {
+                Log.d("NitroStorage", "Biometric storage unavailable: ${e.message}")
+                false
+            }
         }
 
         @JvmStatic
         fun clearSecureBiometric() {
             val inst = getInstanceOrThrow()
-            inst.applySecureEditor(inst.biometricPreferences.edit().clear())
-            inst.invalidateSecureKeysCache()
+            try {
+                inst.applySecureEditor(inst.biometricPreferences.edit().clear())
+                inst.invalidateSecureKeysCache()
+            } catch (e: Exception) {
+                Log.d("NitroStorage", "Biometric storage unavailable: ${e.message}")
+            }
         }
     }
 }