react-native-nitro-storage 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -6,6 +6,53 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 Breaking changes are always listed first in each release section.
 
+## [0.13.0] - 2026-10-01
+
+### Breaking changes
+
+- **Android no longer deletes a corrupt Disk database.** In 0.12.0, Android replaced a corrupt Disk database with an empty one when it opened. Now the file is kept and every Disk call fails with `storage_corruption`, as on iOS, until the app calls `storage.clear(StorageScope.Disk)` or `storage.clearAll()`. Migration: catch `storage_corruption` on Disk calls and call `storage.clear(StorageScope.Disk)` when the app can continue without the stored data.
+- **iOS reports undecodable Secure data as `storage_corruption`.** Reading a Secure or biometric item whose Keychain data is empty or is not UTF-8 text failed with an untagged `failed with status 0` error. It now fails with the `storage_corruption` code. The item can still be deleted or replaced. Migration: handle `storage_corruption` on Secure reads if you matched the old message.
+
+### Added
+
+- `storage.clear(StorageScope.Disk)` and `storage.clearAll()` recover a corrupt Disk database on iOS and Android: they delete the database and its journal files and create an empty store. `clear` with `except`, namespace clears, and `removeByPrefix` need to read keys and still fail on a corrupt database.
+- `storage.clear(StorageScope.Disk)` works on a full device. When the delete fails with `storage_full`, the database is deleted and created again, which frees its space.
+
+### Changed
+
+- Android Disk uses SQLite WAL. 0.12.0 documented WAL but did not enable it. An existing database converts on first open and keeps its rows. If the conversion cannot run, for example on a full device, the database opens without WAL so reads keep working, and the next launch tries again. With WAL and `synchronous=NORMAL`, a power loss can drop the most recent commits; an app kill cannot. This matches iOS.
+- `getKeysByPrefix` on Disk uses the key index instead of reading every key, on iOS and Android. On iOS, `size(StorageScope.Disk)` no longer builds the full key list. Results are unchanged.
+
+### Fixed
+
+- `storage.clear(StorageScope.Disk)` no longer fails before it reaches native storage when a Disk listener or event observer is registered and the stored values cannot be read, or when pending async Disk writes cannot be flushed. The pending writes are dropped and listeners receive a `clear` batch with no key changes.
+- Android: `setBatch`, `removeBatch`, and the first-launch import report a full Disk database with the `storage_full` code. They used to fail with an untagged `cannot rollback` error.
+- Android: Disk values larger than 2 MiB can be read. They could be written but not read.
+- Android: a Disk I/O error that occurs with less than 1 MiB of free space carries the `storage_full` code. Read errors do not.
+- iOS: Disk I/O errors caused by a full device or an exceeded quota carry the `storage_full` code, including while the database opens.
+- iOS: a Disk read of a legacy value that is not yet migrated no longer fails when the Disk database is full.
+- iOS: `clearSecureBiometric` reports an unavailable Keychain with the `keychain_locked` code.
+- iOS: the Disk WAL file is truncated after checkpoints on every SQLite build.
+- iOS: a Disk key that is not valid UTF-8 is rejected before anything is written or removed.
+- `removeByPrefix("", scope)` rejects an invalid scope.
+- Unknown native failures in `hasSecureBiometric`, `setSecureAccessControl`, `setSecureWritesAsync`, and `setKeychainAccessGroup` surface as a `NitroStorage: … failed (unknown error)` error.
+- The Android library declares its unit-test dependencies only inside the repository, so consumer builds do not resolve them.
+
+## [0.12.0] - 2026-10-01
+
+### Breaking changes
+
+- **Disk failures carry error codes.** A full device or database reports the new `storage_full` code, and a corrupt or unreadable Disk database reports `storage_corruption`, which until now came only from Secure storage. Android still deletes and recreates a database that is already corrupt when it opens; only corruption found after that reports the code. The message starts with the `[nitro-error:<code>]` tag. Migration: add `storage_full` if your `StorageErrorCode` switch is exhaustive, and check the storage scope before you treat `storage_corruption` as a Secure failure.
+- **Android Disk errors use the iOS message format.** SQLite failures read `NitroStorage: Disk SQLite <operation> failed: <platform message>` instead of the raw Android exception text; the original exception is kept as the cause. Migration: match on the error code instead of the message text.
+
+### Added
+
+- `storage_full` error code. iOS and Android report it when SQLite returns `SQLITE_FULL`, for writes and for deletes. Web reports it when the Disk or Secure backend throws `QuotaExceededError`. Use `isStorageError(error, "storage_full")` to treat a full device as an expected condition.
+
+### Fixed
+
+- Android opens the Disk database on first Disk use instead of at app start, so a full or corrupt database surfaces as a Disk error instead of crashing the app at launch. A failed open closes the database handle and the next Disk call retries.
+
 ## [0.11.0] - 2026-09-30
 
 ### Breaking changes

package/README.md

@@ -91,7 +91,7 @@ before installing this package, then rebuild the native app so the generated
 Nitro bindings and native runtime use the same major-minor version:
 
 ```sh
-bun add react-native-nitro-modules@0.37.1 react-native-nitro-storage@0.11.0
+bun add react-native-nitro-modules@0.37.1 react-native-nitro-storage@0.13.0
 bunx expo prebuild
 ```
 
@@ -752,20 +752,80 @@ Native and web adapters tag classified failures with stable error codes. Use
 Errors never swallow the underlying cause silently: the original platform
 message is preserved on the error for diagnostics.
 
-| Code                          | Meaning                                                                                                                 |
-| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `keychain_locked`             | The protected store is locked. Retry after the device unlocks.                                                          |
-| `authentication_required`     | The item needs user authentication, or the user cancelled the prompt.                                                   |
-| `key_invalidated`             | The protecting key was invalidated, for example by a biometric enrolment change.                                        |
-| `biometric_unavailable`       | The requested biometric level is not available on this device or OS version.                                            |
-| `storage_corruption`          | Stored secure data could not be decrypted, or (Android) the Secure master key or store cannot be created. Do not retry. |
-| `storage_compensation_failed` | A multi-step write failed and restoring the previous state also failed.                                                 |
-| `unsupported`                 | The operation is not available on this platform or environment.                                                         |
-| `invalid_key`                 | The storage key is empty. Keys must be non-empty strings.                                                               |
+| Code                          | Meaning                                                                                                                                             |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `keychain_locked`             | The protected store is locked. Retry after the device unlocks.                                                                                      |
+| `authentication_required`     | The item needs user authentication, or the user cancelled the prompt.                                                                               |
+| `key_invalidated`             | The protecting key was invalidated, for example by a biometric enrolment change.                                                                    |
+| `biometric_unavailable`       | The requested biometric level is not available on this device or OS version.                                                                        |
+| `storage_corruption`          | Stored secure data could not be decoded, the Disk database is corrupt, or (Android) the Secure master key or store cannot be created. Do not retry. |
+| `storage_compensation_failed` | A multi-step write failed and restoring the previous state also failed.                                                                             |
+| `unsupported`                 | The operation is not available on this platform or environment.                                                                                     |
+| `storage_full`                | The device or database is out of space, or the web storage quota is exceeded. Free space before retrying.                                           |
+| `invalid_key`                 | The storage key is empty. Keys must be non-empty strings.                                                                                           |
 
 Invalid scopes and non-finite numeric levels are rejected with untagged errors
 before they reach native storage.
 
+A full device is an expected condition, not a bug. Disk writes and deletes both
+fail with `storage_full` until the user frees space:
+
+```ts
+import {
+  isStorageError,
+  storage,
+  StorageScope,
+} from "react-native-nitro-storage";
+
+function saveDraft(draft: string): "saved" | "storage_full" {
+  try {
+    storage.setString("draft", draft, StorageScope.Disk);
+    return "saved";
+  } catch (error) {
+    if (!isStorageError(error, "storage_full")) throw error;
+    return "storage_full";
+  }
+}
+```
+
+A full device does not block cleanup. `storage.clear(StorageScope.Disk)`
+deletes and recreates the Disk database when a normal delete fails with
+`storage_full`, which frees the space the database used. `remove` and
+`removeBatch` can still fail with `storage_full`, because a delete also writes
+to the database log.
+
+A corrupt Disk database is never deleted automatically. Every Disk call fails
+with `storage_corruption` until the app clears Disk storage:
+
+```ts
+import {
+  isStorageError,
+  storage,
+  StorageScope,
+} from "react-native-nitro-storage";
+
+function readDraft(): string | undefined {
+  try {
+    return storage.getString("draft", StorageScope.Disk);
+  } catch (error) {
+    if (!isStorageError(error, "storage_corruption")) throw error;
+    storage.clear(StorageScope.Disk);
+    return undefined;
+  }
+}
+```
+
+`storage.clear(StorageScope.Disk)` and `storage.clearAll()` are the recovery
+calls. `clear` with `except`, namespace clears, and `removeByPrefix` read keys
+first and fail on a corrupt database. A `clear` batch event with an empty
+`changes` array means every key in that scope was removed and the previous
+values could not be read; treat all keys in the scope as deleted.
+
+On Android, Disk values above 512 KiB are read in 512 KiB chunks, and read
+time grows faster than value size (about 30 ms for 5 MiB and 265 ms for 20 MiB
+in a host measurement; devices are slower). Keep single Disk values below about
+5 MiB.
+
 ## Platform Support
 
 | Platform               | Status                                             |

package/SECURITY.md

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

package/android/build.gradle

@@ -83,4 +83,9 @@ dependencies {
   implementation "com.facebook.react:react-native:+"
   implementation "androidx.security:security-crypto:1.1.0"
   implementation project(":react-native-nitro-modules")
+
+  if (file("src/test").exists()) {
+    testImplementation "junit:junit:4.13.2"
+    testImplementation "org.robolectric:robolectric:4.13"
+  }
 }

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

@@ -1,4 +1,5 @@
 #include "AndroidStorageAdapterCpp.hpp"
+#include "JniSize.hpp"
 
 #include <limits>
 #include <stdexcept>
@@ -13,11 +14,8 @@ namespace {
 local_ref<JString> toJavaString(const std::string& value) {
     // fbjni's std::string overload uses c_str(), which truncates embedded NUL.
     if (value.find('\0') == std::string::npos) return make_jstring(value);
-    if (value.size() > static_cast<size_t>(std::numeric_limits<jsize>::max())) {
-        throw std::length_error("Storage string exceeds the Java array limit");
-    }
-    const auto size = static_cast<jsize>(value.size());
-    auto bytes = JArrayByte::newArray(size);
+    const jsize size = toJniSize(value.size(), "Storage string exceeds the Java array limit");
+    auto bytes = JArrayByte::newArray(value.size());
     bytes->setRegion(0, size, reinterpret_cast<const jbyte*>(value.data()));
     static auto constructor = JString::javaClassStatic()->getConstructor<
         jstring(jbyteArray, jstring)>();
@@ -26,10 +24,11 @@ local_ref<JString> toJavaString(const std::string& value) {
 }
 
 local_ref<JavaStringArray> toJavaStringArray(const std::vector<std::string>& values) {
-    auto javaArray = JavaStringArray::newArray(static_cast<jsize>(values.size()));
+    toJniSize(values.size(), "Storage batch exceeds the Java array limit");
+    auto javaArray = JavaStringArray::newArray(values.size());
     for (size_t i = 0; i < values.size(); ++i) {
         auto javaValue = toJavaString(values[i]);
-        javaArray->setElement(static_cast<jsize>(i), javaValue.get());
+        javaArray->setElement(i, javaValue.get());
     }
     return javaArray;
 }
@@ -38,9 +37,9 @@ std::vector<std::optional<std::string>> fromNullableJavaStringArray(alias_ref<Ja
     std::vector<std::optional<std::string>> parsedValues;
     if (!values) return parsedValues;
 
-    const jsize size = static_cast<jsize>(values->size());
+    const size_t size = values->size();
     parsedValues.reserve(size);
-    for (jsize i = 0; i < size; ++i) {
+    for (size_t i = 0; i < size; ++i) {
         auto currentValue = values->getElement(i);
         if (!currentValue) {
             parsedValues.push_back(std::nullopt);
@@ -53,10 +52,10 @@ 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();
+    const size_t size = values->size();
     std::vector<std::string> result;
     result.reserve(size);
-    for (jsize i = 0; i < size; ++i) {
+    for (size_t i = 0; i < size; ++i) {
         auto currentValue = values->getElement(i);
         // Null entries are dropped so a missing key can never surface as the
         // empty-string clear sentinel used by change listeners.
@@ -115,7 +114,7 @@ std::vector<std::string> AndroidStorageAdapterCpp::getKeysByPrefixDisk(const std
 
 size_t AndroidStorageAdapterCpp::sizeDisk() {
     static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<jint()>("sizeDisk");
-    return static_cast<size_t>(method(AndroidStorageAdapterJava::javaClassStatic()));
+    return fromJniSize(method(AndroidStorageAdapterJava::javaClassStatic()));
 }
 
 void AndroidStorageAdapterCpp::setDiskBatch(
@@ -199,7 +198,7 @@ std::vector<std::string> AndroidStorageAdapterCpp::getKeysByPrefixSecure(const s
 
 size_t AndroidStorageAdapterCpp::sizeSecure() {
     static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<jint()>("sizeSecure");
-    return static_cast<size_t>(method(AndroidStorageAdapterJava::javaClassStatic()));
+    return fromJniSize(method(AndroidStorageAdapterJava::javaClassStatic()));
 }
 
 void AndroidStorageAdapterCpp::setSecureBatch(

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

@@ -0,0 +1,21 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <limits>
+#include <stdexcept>
+
+namespace NitroStorage {
+
+inline int32_t toJniSize(size_t size, const char* what) {
+    if (size > static_cast<size_t>(std::numeric_limits<int32_t>::max())) {
+        throw std::length_error(what);
+    }
+    return static_cast<int32_t>(size);
+}
+
+inline size_t fromJniSize(int32_t size) {
+    return size > 0 ? static_cast<size_t>(size) : 0;
+}
+
+} // namespace NitroStorage

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

@@ -3,7 +3,12 @@
 package com.nitrostorage
 
 import android.content.Context
+import android.database.sqlite.SQLiteDatabaseCorruptException
+import android.database.sqlite.SQLiteDiskIOException
+import android.database.sqlite.SQLiteException
+import android.database.sqlite.SQLiteFullException
 import android.os.Build
+import android.os.StatFs
 import android.security.keystore.KeyGenParameterSpec
 import android.security.keystore.KeyPermanentlyInvalidatedException
 import android.security.keystore.KeyProperties
@@ -17,7 +22,7 @@ import java.security.KeyStore
 import java.security.KeyStoreException
 import javax.crypto.AEADBadTagException
 
-private fun Throwable.hasCause(type: Class<*>): Boolean {
+internal fun Throwable.hasCause(type: Class<*>): Boolean {
     var current: Throwable? = this
     while (current != null) {
         if (type.isInstance(current)) return true
@@ -26,14 +31,16 @@ private fun Throwable.hasCause(type: Class<*>): Boolean {
     return false
 }
 
-private fun Throwable.storageErrorCode(): String? {
+internal fun Throwable.storageErrorCode(): String? {
     val taggedCode = message
         ?.let { Regex("\\[nitro-error:([a-z_]+)]").find(it)?.groupValues?.get(1) }
     if (taggedCode == "storage_compensation_failed") {
         return taggedCode
     }
     return when {
-        hasCause(AEADBadTagException::class.java) -> "storage_corruption"
+        hasCause(SQLiteFullException::class.java) -> "storage_full"
+        hasCause(SQLiteDatabaseCorruptException::class.java) ||
+            hasCause(AEADBadTagException::class.java) -> "storage_corruption"
         hasCause(UserNotAuthenticatedException::class.java) ||
             hasCause(KeyStoreException::class.java) -> "authentication_required"
         hasCause(KeyPermanentlyInvalidatedException::class.java) ||
@@ -42,7 +49,34 @@ private fun Throwable.storageErrorCode(): String? {
     }
 }
 
-private fun Throwable.wrapStorageException(
+internal const val OUT_OF_SPACE_USABLE_BYTES = 1L shl 20
+
+private val sqliteExtendedCodePattern = Regex("\\(code (\\d+)")
+private const val SQLITE_IOERR_READ = 266
+private const val SQLITE_IOERR_SHORT_READ = 522
+
+internal fun isOutOfSpaceFailure(error: Throwable, usableBytes: Long): Boolean {
+    var current: Throwable? = error
+    while (current != null && current !is SQLiteDiskIOException) {
+        current = current.cause
+    }
+    val ioError = current ?: return false
+    val extendedCode = ioError.message
+        ?.let { sqliteExtendedCodePattern.find(it)?.groupValues?.get(1)?.toIntOrNull() }
+        ?: return false
+    if (extendedCode == SQLITE_IOERR_READ || extendedCode == SQLITE_IOERR_SHORT_READ) {
+        return false
+    }
+    return usableBytes in 0 until OUT_OF_SPACE_USABLE_BYTES
+}
+
+internal fun isRecoverableByRecreate(error: Throwable): Boolean {
+    val message = error.message ?: return false
+    return message.startsWith("[nitro-error:storage_corruption] NitroStorage: Disk SQLite ") ||
+        message.startsWith("[nitro-error:storage_full] NitroStorage: Disk SQLite ")
+}
+
+internal fun Throwable.wrapStorageException(
     defaultMessage: String,
     defaultCode: String? = null,
 ): RuntimeException {
@@ -61,7 +95,35 @@ private fun Throwable.wrapStorageException(
 class AndroidStorageAdapter private constructor(private val context: Context) {
     private val sharedPreferences: SharedPreferences =
         context.getSharedPreferences("NitroStorage", Context.MODE_PRIVATE)
-    private val diskStore: DiskSqliteStore = DiskSqliteStore(context, sharedPreferences)
+    private val diskStoreLock = Any()
+    private var openDiskStore: DiskSqliteStore? = null
+    private val diskStore: DiskSqliteStore
+        get() = synchronized(diskStoreLock) {
+            openDiskStore ?: DiskSqliteStore(context, sharedPreferences, diskDatabaseOpener)
+                .also { openDiskStore = it }
+        }
+
+    private fun recreateDiskStore() {
+        synchronized(diskStoreLock) {
+            openDiskStore?.let { store -> runCatching { store.close() } }
+            openDiskStore = null
+            DiskSqliteStore.deleteDatabaseFiles(context)
+            sharedPreferences.edit().clear().commit()
+            openDiskStore = DiskSqliteStore(context, sharedPreferences, diskDatabaseOpener)
+        }
+    }
+
+    private fun diskFullCodeFor(error: Throwable): String? {
+        if (!error.hasCause(SQLiteDiskIOException::class.java)) {
+            return null
+        }
+        val usableBytes = try {
+            StatFs(context.filesDir.path).availableBytes
+        } catch (statError: IllegalArgumentException) {
+            return null
+        }
+        return if (isOutOfSpaceFailure(error, usableBytes)) "storage_full" else null
+    }
 
     private val masterKeyAlias = "${context.packageName}.nitro_storage.master_key"
 
@@ -542,6 +604,9 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         @Volatile
         private var instance: AndroidStorageAdapter? = null
 
+        @Volatile
+        internal var diskDatabaseOpener: DiskDatabaseOpener = ::openDiskDatabase
+
         private fun getInstanceOrThrow(): AndroidStorageAdapter {
             return instance ?: throw IllegalStateException(
                 "NitroStorage not initialized. Call AndroidStorageAdapter.init(this) in your MainApplication.onCreate(), " +
@@ -572,59 +637,102 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
 
         // --- Disk ---
 
+        private inline fun <T> diskOperation(
+            operation: String,
+            block: DiskSqliteStore.() -> T,
+        ): T {
+            val instance = getInstanceOrThrow()
+            try {
+                val store = instance.diskStore
+                return try {
+                    store.block()
+                } catch (closed: IllegalStateException) {
+                    val current = instance.diskStore
+                    if (current === store) {
+                        throw closed
+                    }
+                    current.block()
+                }
+            } catch (e: SQLiteException) {
+                throw e.wrapStorageException(
+                    "NitroStorage: Disk SQLite $operation failed: ${e.message}",
+                    instance.diskFullCodeFor(e),
+                )
+            } catch (e: IllegalStateException) {
+                throw e.wrapStorageException(
+                    "NitroStorage: Disk SQLite $operation failed: ${e.message}",
+                )
+            }
+        }
+
         @JvmStatic
         fun setDisk(key: String, value: String) {
-            getInstanceOrThrow().diskStore.set(key, value)
+            diskOperation("set") { set(key, value) }
         }
 
         @JvmStatic
         fun setDiskBatch(keys: Array<String>, values: Array<String>) {
-            getInstanceOrThrow().diskStore.setBatch(keys, values)
+            diskOperation("set") { setBatch(keys, values) }
         }
 
         @JvmStatic
         fun getDisk(key: String): String? {
-            return getInstanceOrThrow().diskStore.get(key)
+            return diskOperation("get") { get(key) }
         }
 
         @JvmStatic
         fun getDiskBatch(keys: Array<String>): Array<String?> {
-            return getInstanceOrThrow().diskStore.getBatch(keys)
+            return diskOperation("get") { getBatch(keys) }
         }
 
         @JvmStatic
         fun deleteDisk(key: String) {
-            getInstanceOrThrow().diskStore.remove(key)
+            diskOperation("remove") { remove(key) }
         }
 
         @JvmStatic
         fun deleteDiskBatch(keys: Array<String>) {
-            getInstanceOrThrow().diskStore.removeBatch(keys)
+            diskOperation("remove") { removeBatch(keys) }
         }
 
         @JvmStatic
         fun hasDisk(key: String): Boolean {
-            return getInstanceOrThrow().diskStore.has(key)
+            return diskOperation("has") { has(key) }
         }
 
         @JvmStatic
         fun getAllKeysDisk(): Array<String> {
-            return getInstanceOrThrow().diskStore.getAllKeys()
+            return diskOperation("getAllKeys") { getAllKeys() }
         }
 
         @JvmStatic
         fun getKeysByPrefixDisk(prefix: String): Array<String> {
-            return getInstanceOrThrow().diskStore.getKeysByPrefix(prefix)
+            return diskOperation("getKeysByPrefix") { getKeysByPrefix(prefix) }
         }
 
         @JvmStatic
         fun sizeDisk(): Int {
-            return getInstanceOrThrow().diskStore.size()
+            return diskOperation("size") { size() }
         }
 
         @JvmStatic
         fun clearDisk() {
-            getInstanceOrThrow().diskStore.clear()
+            try {
+                diskOperation("clear") { clear() }
+            } catch (e: RuntimeException) {
+                if (!isRecoverableByRecreate(e)) {
+                    throw e
+                }
+                val instance = getInstanceOrThrow()
+                try {
+                    instance.recreateDiskStore()
+                } catch (recreateError: SQLiteException) {
+                    throw recreateError.wrapStorageException(
+                        "NitroStorage: Disk SQLite clear failed: ${recreateError.message}",
+                        instance.diskFullCodeFor(recreateError),
+                    )
+                }
+            }
         }
 
         // --- Secure (async apply by default, sync commit when requested) ---