react-native-nitro-storage 0.12.0 → 0.14.0

package/cpp/core/SqliteDiskStore.hpp

@@ -20,7 +20,10 @@ public:
 
     static SqliteDiskStore& shared(const std::string& path);
     static void resetShared();
+    static void recreateShared(const std::string& path);
+    static void removeDatabaseFiles(const std::string& path);
     static std::string defaultPath();
+    static bool isValidUtf8(const std::string& value);
 
     const std::string& path() const { return path_; }
 
@@ -44,10 +47,14 @@ public:
         const std::string& name,
         const std::vector<std::pair<std::string, std::string>>& entries
     );
+    void recreate();
     void limitPageCountForTesting(int pages);
+    void limitValueLengthForTesting(int bytes);
 
 private:
     void openLocked();
+    void reopenLocked();
+    void ensureOpenLocked();
     void closeLocked();
     void execLocked(const char* sql);
     void beginLocked();
@@ -68,7 +75,9 @@ private:
     sqlite3_stmt* removeStmt_ = nullptr;
     sqlite3_stmt* hasStmt_ = nullptr;
     sqlite3_stmt* keysStmt_ = nullptr;
-    sqlite3_stmt* prefixStmt_ = nullptr;
+    sqlite3_stmt* prefixRangeStmt_ = nullptr;
+    sqlite3_stmt* prefixFromStmt_ = nullptr;
+    sqlite3_stmt* prefixLikeStmt_ = nullptr;
     sqlite3_stmt* sizeStmt_ = nullptr;
     sqlite3_stmt* clearStmt_ = nullptr;
     sqlite3_stmt* insertAbsentStmt_ = nullptr;

package/docs/api-reference.md

@@ -112,49 +112,50 @@ See [react-hooks.md](react-hooks.md).
 
 `storage` exposes raw and cross-item utilities:
 
-| Method                                           | Purpose                                                                                   |
-| ------------------------------------------------ | ----------------------------------------------------------------------------------------- |
-| `clear(scope, options?)`                         | Clear one scope, optionally preserving selected keys.                                     |
-| `clearAll()`                                     | Clear Memory, Disk, and Secure scopes.                                                    |
-| `clearNamespace(namespace, scope)`               | Remove keys under `namespace:`.                                                           |
-| `clearGroup(group)`                              | Remove registered items in a group across their scopes.                                   |
-| `getGroupItems(group)`                           | List registered items in a group.                                                         |
-| `subscribeExpired(scope, listener)`              | Receive item events caused by TTL expiry.                                                 |
-| `findDuplicateKeys()`                            | Find duplicate registered `(scope, key)` definitions.                                     |
-| `getRegisteredKeys()`                            | List registered `(scope, key)` definitions.                                               |
-| `subscribe(scope, listener)`                     | Subscribe to raw scope-level change events.                                               |
-| `subscribeKey(scope, key, listener)`             | Subscribe to raw events for one key.                                                      |
-| `subscribePrefix(scope, prefix, listener)`       | Subscribe to raw events for matching key prefixes.                                        |
-| `subscribeNamespace(namespace, scope, listener)` | Subscribe to raw events for `namespace:` keys.                                            |
-| `setEventObserver(observer, options?)`           | Receive all change events for devtools or logging. Secure values are redacted by default. |
-| `clearBiometric()`                               | Clear biometric Secure entries.                                                           |
-| `has(key, scope)`                                | Check for a raw key.                                                                      |
-| `getAllKeys(scope)`                              | List raw keys.                                                                            |
-| `getKeysByPrefix(prefix, scope)`                 | List raw keys with a prefix.                                                              |
-| `getByPrefix(prefix, scope)`                     | Read raw string values by prefix.                                                         |
-| `getAll(scope)`                                  | Read all raw string values in a scope.                                                    |
-| `size(scope)`                                    | Return approximate scope entry count.                                                     |
-| `setAccessControl(accessControl)`                | Set the default Secure access control level.                                              |
-| `setSecureWritesAsync(enabled)`                  | Toggle Android secure writes between sync and async modes.                                |
-| `setDiskWritesAsync(enabled)`                    | Toggle coalesced Disk write behavior.                                                     |
-| `flushDiskWrites()`                              | Flush pending Disk writes.                                                                |
-| `flushSecureWrites()`                            | Flush pending Secure writes.                                                              |
-| `setKeychainAccessGroup(group)`                  | Configure iOS Keychain access group.                                                      |
-| `setMetricsObserver(observer)`                   | Receive operation timing events.                                                          |
-| `getMetricsSnapshot()`                           | Read aggregated metrics.                                                                  |
-| `getScopedMetricsSnapshot()`                     | Read metrics grouped by storage scope.                                                    |
-| `resetMetrics()`                                 | Clear metrics counters.                                                                   |
-| `getCacheMetrics()`                              | Read raw-cache hits, misses, live entries, and estimated bytes.                           |
-| `getCapabilities()`                              | Read runtime storage capabilities. Native `backend.disk` is `"sqlite"`.                   |
-| `getSecurityCapabilities()`                      | Read secure backend capability metadata.                                                  |
-| `getSecureMetadata(key)`                         | Read secure metadata for one key without returning its value.                             |
-| `getAllSecureMetadata()`                         | Read secure metadata for all secure keys without values.                                  |
-| `getString(key, scope)`                          | Read a raw string.                                                                        |
-| `setString(key, value, scope)`                   | Write a raw string.                                                                       |
-| `deleteString(key, scope)`                       | Remove a raw key.                                                                         |
-| `export(scope, options?)`                        | Snapshot raw strings from one scope. Secure scope requires explicit unsafe opt-in.        |
-| `exportSecureUnsafe()`                           | Snapshot raw Secure strings for short-lived migration workflows.                          |
-| `import(data, scope)`                            | Bulk import raw strings.                                                                  |
+| Method                                           | Purpose                                                                                                                        |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `clear(scope, options?)`                         | Clear one scope, optionally preserving selected keys.                                                                          |
+| `clearAll()`                                     | Clear Memory, Disk, and Secure scopes.                                                                                         |
+| `clearNamespace(namespace, scope)`               | Remove keys under `namespace:`.                                                                                                |
+| `clearGroup(group)`                              | Remove registered items in a group across their scopes.                                                                        |
+| `getGroupItems(group)`                           | List registered items in a group.                                                                                              |
+| `subscribeExpired(scope, listener)`              | Receive item events caused by TTL expiry.                                                                                      |
+| `findDuplicateKeys()`                            | Find duplicate registered `(scope, key)` definitions.                                                                          |
+| `getRegisteredKeys()`                            | List registered `(scope, key)` definitions.                                                                                    |
+| `subscribe(scope, listener)`                     | Subscribe to raw scope-level change events.                                                                                    |
+| `subscribeKey(scope, key, listener)`             | Subscribe to raw events for one key.                                                                                           |
+| `subscribePrefix(scope, prefix, listener)`       | Subscribe to raw events for matching key prefixes.                                                                             |
+| `subscribeNamespace(namespace, scope, listener)` | Subscribe to raw events for `namespace:` keys.                                                                                 |
+| `setEventObserver(observer, options?)`           | Receive all change events for devtools or logging. Secure values are redacted by default.                                      |
+| `clearBiometric()`                               | Clear biometric Secure entries.                                                                                                |
+| `has(key, scope)`                                | Check for a raw key.                                                                                                           |
+| `getAllKeys(scope)`                              | List raw keys.                                                                                                                 |
+| `getKeysByPrefix(prefix, scope)`                 | List raw keys with a prefix.                                                                                                   |
+| `getByPrefix(prefix, scope)`                     | Read raw string values by prefix.                                                                                              |
+| `getAll(scope)`                                  | Read all raw string values in a scope.                                                                                         |
+| `size(scope)`                                    | Return approximate scope entry count.                                                                                          |
+| `setAccessControl(accessControl)`                | Set the default Secure access control level.                                                                                   |
+| `setSecureWritesAsync(enabled)`                  | Toggle Android secure writes between sync and async modes.                                                                     |
+| `setDiskWritesAsync(enabled)`                    | Toggle coalesced Disk write behavior.                                                                                          |
+| `flushDiskWrites()`                              | Flush pending Disk writes.                                                                                                     |
+| `flushSecureWrites()`                            | Drain queued Secure writes into the backend; not an Android `apply()` persistence barrier.                                     |
+| `setScheduledFlushErrorObserver(observer)`       | Observe scheduled Disk/Secure flush failures; pass `undefined` to restore uncaught failures. Explicit flush calls still throw. |
+| `setKeychainAccessGroup(group)`                  | Configure iOS Keychain access group.                                                                                           |
+| `setMetricsObserver(observer)`                   | Receive operation timing events.                                                                                               |
+| `getMetricsSnapshot()`                           | Read aggregated metrics.                                                                                                       |
+| `getScopedMetricsSnapshot()`                     | Read metrics grouped by storage scope.                                                                                         |
+| `resetMetrics()`                                 | Clear metrics counters.                                                                                                        |
+| `getCacheMetrics()`                              | Read raw-cache hits, misses, live entries, and estimated bytes.                                                                |
+| `getCapabilities()`                              | Read runtime storage capabilities. Native `backend.disk` is `"sqlite"`.                                                        |
+| `getSecurityCapabilities()`                      | Read secure backend capability metadata.                                                                                       |
+| `getSecureMetadata(key)`                         | Read secure metadata for one key without returning its value.                                                                  |
+| `getAllSecureMetadata()`                         | Read secure metadata for all secure keys without values.                                                                       |
+| `getString(key, scope)`                          | Read a raw string.                                                                                                             |
+| `setString(key, value, scope)`                   | Write a raw string.                                                                                                            |
+| `deleteString(key, scope)`                       | Remove a raw key.                                                                                                              |
+| `export(scope, options?)`                        | Snapshot raw strings from one scope. Secure scope requires explicit unsafe opt-in.                                             |
+| `exportSecureUnsafe()`                           | Snapshot raw Secure strings for short-lived migration workflows.                                                               |
+| `import(data, scope)`                            | Bulk import raw strings.                                                                                                       |
 
 Raw string APIs bypass item serialization and validation. Prefer `StorageItem<T>` unless you are migrating, exporting/importing, or writing a custom integration.
 
@@ -234,6 +235,9 @@ runTransaction(StorageScope.Disk, (tx) => {
 ```
 
 If the callback throws, previously changed keys in that transaction are rolled back synchronously.
+Promise or thenable results are rejected with `TypeError` and rollback. Context
+methods are valid only during the synchronous callback. Finish awaited work
+before entering the transaction.
 
 ## Migrations
 
@@ -249,6 +253,8 @@ migrateToLatest(StorageScope.Disk);
 ```
 
 Migration versions are tracked per scope.
+Migration callbacks must be synchronous. An async callback is rejected without
+advancing its version, and the next migration run retries that step.
 
 ## Secure Auth Storage
 
@@ -276,17 +282,17 @@ the native or web adapter. `isStorageError(error, code)` matches one exact code
 without parsing platform message text. See [secure-storage.md](secure-storage.md)
 for recovery semantics.
 
-| Code                          | Raised when                                                                                                                                           |
-| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `keychain_locked`             | The protected store is locked.                                                                                                                        |
-| `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, 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`                 | A storage key is empty.                                                                                                                               |
+| Code                          | Raised when                                                                                                                                         |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `keychain_locked`             | The protected store is locked.                                                                                                                      |
+| `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`                 | A storage key is empty.                                                                                                                             |
 
 `StorageCompositeError` and `StorageCompensationError` describe errors that
 carry a primary failure plus secondary failures from reconciliation or

package/docs/batch-transactions-migrations.md

@@ -126,6 +126,11 @@ Transaction context methods:
 
 If the callback throws, Nitro Storage restores the keys it changed during that transaction and emits exactly one typed `rollback` batch event so observers and the global event observer can react to the rollback.
 
+Callbacks must return synchronously. A Promise or thenable result throws a
+`TypeError` and triggers the same rollback. Context methods reject access after
+the callback finishes, including from an async continuation. Complete awaited
+work before the transaction and never retain its context for later use.
+
 Memory-scope batch removes are atomic: all keys are deleted before listeners fire, and scope, key, and prefix subscribers receive a single `removeBatch` event.
 
 ## Migrations
@@ -160,6 +165,8 @@ migrateToLatest(StorageScope.Disk);
 Migration context methods work with raw strings. Use item serializers manually when migrating structured data.
 
 Each migration step runs inside its own transaction together with the version marker write. A step that throws rolls back both its data changes and the version marker, so the scope stays on the last completed version and rerunning `migrateToLatest()` retries deterministically.
+Migration callbacks follow the same synchronous contract as transactions. An
+async migration does not advance its version marker.
 
 ```ts
 registerMigration(3, (ctx) => {

package/docs/native-libraries.md

@@ -28,6 +28,34 @@ wipe leaves no pre-SQLite copy behind. Later Disk reads and writes use SQLite.
 | RocksDB / LevelDB | Rejected. Heavy native footprint for small preference-sized values.                                                                    |
 | yyjson            | Rejected for Disk. Typed TTL/JSON envelopes stay in JavaScript.                                                                        |
 
+## Limits and durability
+
+- Disk writes wait up to 5 seconds for another connection that holds the
+  SQLite write lock. The library uses one connection per process, so this wait
+  only happens when another process (for example an app extension in the same
+  container) is writing. Reads do not wait in WAL mode. Five seconds gives the
+  other writer time to finish and stays below the iOS and Android
+  unresponsive-app limits.
+- If the Disk database file is deleted while the app runs, the open connection
+  keeps reading and writing the deleted file, and the next launch starts with
+  an empty database. The library does not check for this on each call, because
+  the check costs a system call on every write. Do not delete
+  `nitro-storage-disk.sqlite` yourself; call
+  `storage.clear(StorageScope.Disk)`.
+- Each platform keeps its system SQLite checkpoint settings. iOS checkpoints
+  every 1000 pages and truncates the WAL to 32 KiB; these values are set in
+  code so they do not depend on the SQLite build. Android checkpoints every
+  100 pages with a 512 KiB limit, applied by the Android framework to every
+  pooled connection.
+- Android opens the Disk database in WAL mode. If that open fails for a reason
+  other than corruption (for example a full device while an older database
+  converts to WAL), it opens once without WAL and uses `synchronous=FULL`, so
+  reads keep working; the next launch tries WAL again. If WAL is active and the
+  device is so full that the WAL shared-memory file cannot be created, reads
+  fail with `storage_full` until space is free. iOS has the same limit.
+- With WAL and `synchronous=NORMAL`, an app kill never loses a committed
+  write. A power loss can lose the most recent commits.
+
 ## Compatibility
 
 - Public Disk APIs (`get`/`set`/`setBatch`/`getKeysByPrefix`/`import`) are

package/docs/qa/agent-device-replay.md

@@ -0,0 +1,70 @@
+# Storage agent-device replay
+
+Run these flows only against an already installed release example that matches
+the source revision under test. Select the platform and exact device every time:
+
+```sh
+bun run example:replay --platform ios --udid <exact-udid>
+bun run example:replay --platform android --serial <exact-serial>
+```
+
+To run selected manifest suites, pass `--flow <id>`. The runner accepts this
+option more than once for distinct suite IDs:
+
+```sh
+bun run example:replay --platform ios --udid <exact-udid> --flow integrity
+bun run example:replay --platform android --serial <exact-serial> --flow keychain --flow persistence-relaunch
+```
+
+Use an installed release build from the source being checked. The replay does
+not start Metro, prebuild, or build an app. A development client, a different
+source revision, an inferred device, or a run without the exact platform and
+device selector is not release replay evidence. The task owner must separately
+authorize device work after the required package implementations are ready.
+
+Before replay, check that the example source and replay manifest match the
+committed source lock. If a flow, status ID, or expected value changes, update
+`e2e/storage-replay-coverage.json` and refresh that lock with the repository's
+replay maintenance command. Run the checker again before the device command:
+
+```sh
+bun run example:replay:refresh
+bun run example:replay:check
+bun run example:replay:test
+```
+
+The runner supplies a fresh UUID as `RUN_ID` to each replay. The persistence
+flow writes one `RUN_ID`-scoped Disk key, closes and relaunches the installed
+app with the same ID, compares the stored value with the expected value, and
+deletes that key. Other smoke and lab cases use reserved QA keys and clean only
+those keys. The default replay never clears a whole storage scope or the app's
+data.
+
+Each run uses a unique session and an artifact directory under the OS temporary
+directory. `agent-device test` closes each attempt session itself, including
+on failure.
+
+A replay passes only when each suite reaches its finished status and every
+required status ID contains its expected public API value. A `fail=0` summary by
+itself is not sufficient. Smoke and integrity rows are asserted through the
+on-screen `smoke-results` and `e2e-integrity-results` labels because
+agent-device `.ad` waits only see on-screen elements. The keychain suite runs one no-prompt Secure
+roundtrip and keeps biometric, lock, corruption, and hardware-backed checks
+explicitly pending. The smoke test's constructed `storage_full` error is read
+through the public `/testing` entrypoint; it proves error-code classification
+at that test adapter boundary only.
+
+The native smoke flow requires 39 passing cases out of 41, zero failures, and
+the two expected web-only skips. Update that expected summary when cases change;
+do not accept a new native skip as coverage. The integrity flow also checks that
+a Promise-returning transaction rolls back and closes its context on Memory,
+Disk, and Secure.
+
+Native replay rows identify the public runtime platform and backend capability,
+then assert values returned through the default package entrypoint. This
+supports installed-app Disk and Secure behavior claims for that target. It does
+not prove hardware-backed keys, biometrics, locked-device behavior, corruption
+recovery, or a native Disk/Secure write failure. Those checks need controlled
+native or hardware prerequisites and remain pending in the coverage manifest.
+Unit tests for an injected adapter boundary are useful logic evidence, but they
+do not close a native-runtime prerequisite.

package/docs/secure-storage.md

@@ -206,12 +206,18 @@ refreshTokenItem.set("opaque-refresh-token");
 ```
 
 Coalesced secure item writes remain in a last-write-wins queue until the next
-microtask or an explicit `flushSecureWrites()`. A failed flush throws and keeps
-failed and unattempted writes queued for a later retry. Call
-`flushSecureWrites()` before assertions, namespace clears, or any boundary that
-requires deterministic persistence. `storage.clearBiometric()` is also a
-durability barrier: it flushes pending Secure writes before clearing biometric
-entries, and surfaces native clear failures.
+microtask or an explicit `flushSecureWrites()`. An explicit flush failure throws
+and keeps failed and unattempted writes queued for retry. Scheduled failures
+propagate unless `storage.setScheduledFlushErrorObserver()` is installed; it
+receives `{ scope, error }` while the failed writes remain queued.
+
+`flushSecureWrites()` drains the JavaScript queue into the backend. It does not
+wait for Android `apply()` persistence. Use the default synchronous mode or
+select `storage.setSecureWritesAsync(false)` before writes that need synchronous
+native persistence. Changing the mode is not a barrier for earlier `apply()`
+calls. `storage.clearBiometric()` drains pending Secure writes before clearing
+biometric entries and surfaces native clear failures; it also cannot wait for
+earlier Android `apply()` calls.
 
 ## iOS Legacy Disk Migration
 

package/ios/IOSStorageAdapterCpp.mm

@@ -363,9 +363,9 @@ std::string diskStorePathForTesting() {
 // --- Disk ---
 
 void IOSStorageAdapterCpp::setDisk(const std::string& key, const std::string& value) {
+    NSString* nsKey = nsStringFromStdString(key);
     ensureDiskMigrated();
     NitroSqliteDiskStore().set(key, value);
-    NSString* nsKey = nsStringFromStdString(key);
     NSUserDefaults* defaults = NitroDiskDefaults();
     NSUserDefaults* standard = [NSUserDefaults standardUserDefaults];
     if (defaults != standard && [standard objectForKey:nsKey] != nil) {
@@ -383,14 +383,17 @@ std::optional<std::string> IOSStorageAdapterCpp::getDisk(const std::string& key)
     NSString* result = migrateLegacyDiskValue(nsKey);
     if (!result) return std::nullopt;
     const std::string value = stdStringFromNSString(result);
-    NitroSqliteDiskStore().set(key, value);
+    try {
+        NitroSqliteDiskStore().set(key, value);
+    } catch (const std::exception&) {
+    }
     return value;
 }
 
 void IOSStorageAdapterCpp::deleteDisk(const std::string& key) {
+    NSString* nsKey = nsStringFromStdString(key);
     ensureDiskMigrated();
     NitroSqliteDiskStore().remove(key);
-    NSString* nsKey = nsStringFromStdString(key);
     NSUserDefaults* defaults = NitroDiskDefaults();
     [defaults removeObjectForKey:nsKey];
     NSUserDefaults* standard = [NSUserDefaults standardUserDefaults];
@@ -445,13 +448,33 @@ std::vector<std::string> IOSStorageAdapterCpp::getAllKeysDisk() {
     return keys;
 }
 
+static std::vector<std::string> legacyDefaultsDiskKeys() {
+    std::vector<std::string> keys;
+    NSUserDefaults* defaults = NitroDiskDefaults();
+    NSDictionary<NSString*, id>* entries = [defaults persistentDomainForName:kDiskSuiteName] ?: @{};
+    NSUserDefaults* standard = [NSUserDefaults standardUserDefaults];
+    for (NSString* key in entries) {
+        if (!isInternalDiskKey(key)) {
+            keys.push_back(stdStringFromNSString(key));
+        }
+    }
+    for (NSString* key in [registeredLegacyDiskKeys() allObjects]) {
+        if ([entries objectForKey:key] == nil &&
+            [standard stringForKey:key] != nil) {
+            keys.push_back(stdStringFromNSString(key));
+        }
+    }
+    return keys;
+}
+
 std::vector<std::string> IOSStorageAdapterCpp::getKeysByPrefixDisk(const std::string& prefix) {
     ensureDiskMigrated();
     std::unordered_set<std::string> combined;
     for (const auto& key : NitroSqliteDiskStore().getKeysByPrefix(prefix)) {
         combined.insert(key);
     }
-    for (const auto& key : getAllKeysDisk()) {
+    const auto remaining = SqliteDiskStore::isValidUtf8(prefix) ? legacyDefaultsDiskKeys() : getAllKeysDisk();
+    for (const auto& key : remaining) {
         if (key.rfind(prefix, 0) == 0) {
             combined.insert(key);
         }
@@ -466,20 +489,31 @@ std::vector<std::string> IOSStorageAdapterCpp::getKeysByPrefixDisk(const std::st
 
 size_t IOSStorageAdapterCpp::sizeDisk() {
     ensureDiskMigrated();
-    return getAllKeysDisk().size();
+    auto& store = NitroSqliteDiskStore();
+    size_t count = store.size();
+    std::unordered_set<std::string> counted;
+    for (const auto& key : legacyDefaultsDiskKeys()) {
+        if (counted.insert(key).second && !store.has(key)) {
+            count += 1;
+        }
+    }
+    return count;
 }
 
 void IOSStorageAdapterCpp::setDiskBatch(
     const std::vector<std::string>& keys,
     const std::vector<std::string>& values
 ) {
+    NSMutableArray<NSString*>* nsKeys = [NSMutableArray arrayWithCapacity:keys.size()];
+    for (size_t i = 0; i < keys.size() && i < values.size(); ++i) {
+        [nsKeys addObject:nsStringFromStdString(keys[i])];
+    }
     ensureDiskMigrated();
     NitroSqliteDiskStore().setBatch(keys, values);
     NSUserDefaults* defaults = NitroDiskDefaults();
     NSUserDefaults* standard = [NSUserDefaults standardUserDefaults];
     NSMutableArray* legacyKeysToRemove = [NSMutableArray array];
-    for (size_t i = 0; i < keys.size() && i < values.size(); ++i) {
-        NSString* nsKey = nsStringFromStdString(keys[i]);
+    for (NSString* nsKey in nsKeys) {
         if (defaults != standard && [standard objectForKey:nsKey] != nil) {
             [legacyKeysToRemove addObject:nsKey];
         }
@@ -503,10 +537,13 @@ std::vector<std::optional<std::string>> IOSStorageAdapterCpp::getDiskBatch(
 }
 
 void IOSStorageAdapterCpp::deleteDiskBatch(const std::vector<std::string>& keys) {
+    NSMutableArray<NSString*>* nsKeys = [NSMutableArray arrayWithCapacity:keys.size()];
+    for (const auto& key : keys) {
+        [nsKeys addObject:nsStringFromStdString(key)];
+    }
     ensureDiskMigrated();
     NitroSqliteDiskStore().removeBatch(keys);
-    for (const auto& key : keys) {
-        NSString* nsKey = nsStringFromStdString(key);
+    for (NSString* nsKey in nsKeys) {
         NSUserDefaults* defaults = NitroDiskDefaults();
         [defaults removeObjectForKey:nsKey];
         NSUserDefaults* standard = [NSUserDefaults standardUserDefaults];
@@ -517,9 +554,13 @@ void IOSStorageAdapterCpp::deleteDiskBatch(const std::vector<std::string>& keys)
     }
 }
 
-void IOSStorageAdapterCpp::clearDisk() {
-    ensureDiskMigrated();
-    NitroSqliteDiskStore().clear();
+static bool isRecoverableByDiskClear(const std::exception& error) {
+    const std::string message = error.what();
+    return message.rfind("[nitro-error:storage_corruption] NitroStorage: Disk SQLite ", 0) == 0 ||
+        message.rfind("[nitro-error:storage_full] NitroStorage: Disk SQLite ", 0) == 0;
+}
+
+static void clearDiskDefaults() {
     NSUserDefaults* defaults = NitroDiskDefaults();
     NSDictionary<NSString*, id>* entries = [defaults persistentDomainForName:kDiskSuiteName] ?: @{};
     NSMutableSet* legacyKeys = [registeredLegacyDiskKeys() mutableCopy];
@@ -545,6 +586,25 @@ void IOSStorageAdapterCpp::clearDisk() {
     [defaults removeObjectForKey:kLegacyDiskKeysRegistryKey];
 }
 
+void IOSStorageAdapterCpp::clearDisk() {
+    bool recreate = false;
+    try {
+        ensureDiskMigrated();
+        NitroSqliteDiskStore().clear();
+    } catch (const std::exception& error) {
+        if (!isRecoverableByDiskClear(error)) {
+            throw;
+        }
+        recreate = true;
+    }
+    clearDiskDefaults();
+    if (recreate) {
+        SqliteDiskStore::recreateShared(NitroDiskStorePath());
+        std::lock_guard<std::mutex> lock(diskMigrationMutex_);
+        diskMigrated_.store(false, std::memory_order_release);
+    }
+}
+
 // --- Secure (Keychain) ---
 
 static NSMutableDictionary* baseKeychainQuery(NSString* key, NSString* service, NSString* accessGroup) {
@@ -695,6 +755,18 @@ static void setSecureValue(
     throw keychainStatusError(status, "Secure set");
 }
 
+static std::string decodeKeychainText(CFTypeRef result, const std::string& operation) {
+    NSData* data = (__bridge_transfer NSData*)result;
+    NSString* text = data ? [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding] : nil;
+    if (!text) {
+        throw taggedStorageError(
+            "storage_corruption",
+            "NitroStorage: " + operation + " failed: the Keychain item has no data or is not valid UTF-8 text."
+        );
+    }
+    return stdStringFromNSString(text);
+}
+
 static std::optional<std::string> getSecureValue(NSString* nsKey, NSString* group) {
     NSMutableDictionary* query = baseKeychainQuery(nsKey, kKeychainService, group);
     query[(__bridge id)kSecReturnData] = @YES;
@@ -703,10 +775,8 @@ static std::optional<std::string> getSecureValue(NSString* nsKey, NSString* grou
 
     CFTypeRef result = NULL;
     OSStatus status = SecItemCopyMatching((__bridge CFDictionaryRef)query, &result);
-    if (status == errSecSuccess && result) {
-        NSData* data = (__bridge_transfer NSData*)result;
-        NSString* str = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
-        if (str) return stdStringFromNSString(str);
+    if (status == errSecSuccess) {
+        return decodeKeychainText(result, "Secure get");
     }
     if (status == errSecInteractionNotAllowed) {
         throw taggedStorageError(
@@ -1169,10 +1239,8 @@ std::optional<std::string> IOSStorageAdapterCpp::getSecureBiometric(const std::s
 
     CFTypeRef result = NULL;
     OSStatus status = SecItemCopyMatching((__bridge CFDictionaryRef)query, &result);
-    if (status == errSecSuccess && result) {
-        NSData* data = (__bridge_transfer NSData*)result;
-        NSString* str = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
-        if (str) return stdStringFromNSString(str);
+    if (status == errSecSuccess) {
+        return decodeKeychainText(result, "Biometric get");
     }
     if (status == errSecInteractionNotAllowed) {
         throw taggedStorageError(
@@ -1251,8 +1319,7 @@ void IOSStorageAdapterCpp::clearSecureBiometric() {
                 "NitroStorage: Cannot clear biometric storage: keychain is locked (errSecInteractionNotAllowed)"
             );
         }
-        throw std::runtime_error(
-            std::string("NitroStorage: clearSecureBiometric failed with status ") + std::to_string(status));
+        throw keychainStatusError(status, "clearSecureBiometric");
     }
     {
         std::lock_guard<std::mutex> lock(secureKeysMutex_);

package/lib/commonjs/Storage.types.js

@@ -26,9 +26,11 @@ let AccessControl = exports.AccessControl = /*#__PURE__*/function (AccessControl
 let BiometricLevel = exports.BiometricLevel = /*#__PURE__*/function (BiometricLevel) {
   /** No biometric requirement (default). */
   BiometricLevel[BiometricLevel["None"] = 0] = "None";
-  /** Require biometric or passcode for each access. */
+  /** iOS: Keychain user presence. Android: recent authentication when opening
+   * the protected store; later access uses its cached keyset. Web: no biometric enforcement. */
   BiometricLevel[BiometricLevel["BiometryOrPasscode"] = 1] = "BiometryOrPasscode";
-  /** Require biometric only (no passcode fallback). */
+  /** Biometric-only Keychain/Keystore policy, without passcode fallback.
+   * Android authenticates when opening the store, not each access. Web: no biometric enforcement. */
   BiometricLevel[BiometricLevel["BiometryOnly"] = 2] = "BiometryOnly";
   return BiometricLevel;
 }({});

package/lib/commonjs/Storage.types.js.map

@@ -1 +1 @@
-{"version":3,"names":["StorageScope","exports","AccessControl","BiometricLevel"],"sourceRoot":"../../src","sources":["Storage.types.ts"],"mappings":";;;;;;IAAYA,YAAY,GAAAC,OAAA,CAAAD,YAAA,0BAAZA,YAAY;EAAZA,YAAY,CAAZA,YAAY;EAAZA,YAAY,CAAZA,YAAY;EAAZA,YAAY,CAAZA,YAAY;EAAA,OAAZA,YAAY;AAAA;AAAA,IAMZE,aAAa,GAAAD,OAAA,CAAAC,aAAA,0BAAbA,aAAa;EACvB;EADUA,aAAa,CAAbA,aAAa;EAGvB;EAHUA,aAAa,CAAbA,aAAa;EAKvB;EALUA,aAAa,CAAbA,aAAa;EAOvB;EAPUA,aAAa,CAAbA,aAAa;EASvB;EATUA,aAAa,CAAbA,aAAa;EAAA,OAAbA,aAAa;AAAA;AAAA,IAabC,cAAc,GAAAF,OAAA,CAAAE,cAAA,0BAAdA,cAAc;EACxB;EADUA,cAAc,CAAdA,cAAc;EAGxB;EAHUA,cAAc,CAAdA,cAAc;EAKxB;EALUA,cAAc,CAAdA,cAAc;EAAA,OAAdA,cAAc;AAAA","ignoreList":[]}
+{"version":3,"names":["StorageScope","exports","AccessControl","BiometricLevel"],"sourceRoot":"../../src","sources":["Storage.types.ts"],"mappings":";;;;;;IAAYA,YAAY,GAAAC,OAAA,CAAAD,YAAA,0BAAZA,YAAY;EAAZA,YAAY,CAAZA,YAAY;EAAZA,YAAY,CAAZA,YAAY;EAAZA,YAAY,CAAZA,YAAY;EAAA,OAAZA,YAAY;AAAA;AAAA,IAMZE,aAAa,GAAAD,OAAA,CAAAC,aAAA,0BAAbA,aAAa;EACvB;EADUA,aAAa,CAAbA,aAAa;EAGvB;EAHUA,aAAa,CAAbA,aAAa;EAKvB;EALUA,aAAa,CAAbA,aAAa;EAOvB;EAPUA,aAAa,CAAbA,aAAa;EASvB;EATUA,aAAa,CAAbA,aAAa;EAAA,OAAbA,aAAa;AAAA;AAAA,IAabC,cAAc,GAAAF,OAAA,CAAAE,cAAA,0BAAdA,cAAc;EACxB;EADUA,cAAc,CAAdA,cAAc;EAGxB;AACF;EAJYA,cAAc,CAAdA,cAAc;EAMxB;AACF;EAPYA,cAAc,CAAdA,cAAc;EAAA,OAAdA,cAAc;AAAA","ignoreList":[]}