react-native-nitro-storage 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to this project are documented in this file.
 
 The format follows Keep a Changelog and the project adheres to SemVer.
 
+## 0.8.0 - 2026-08-12
+
+### Breaking changes
+
+- None. `getMetricsSnapshot()` keeps its unscoped, cross-scope aggregate keys.
+  Use the new `getScopedMetricsSnapshot()` when per-scope counters are needed.
+
+### Added
+
+- Exported `PlatformStorage` and `PlatformScope` types from the native, web,
+  and testing entrypoints so shared consumer code can verify platform parity
+  without duplicating the package contract.
+- Added `getScopedMetricsSnapshot()` with keys such as `item:set:1`, without
+  changing established dashboards that consume `getMetricsSnapshot()`.
+
+### Fixed
+
+- **Data-loss prevention:** `storage.import()` now flushes pending coalesced Disk and Secure writes before writing, so a later scheduled flush can never overwrite imported values.
+- **Biometric parity:** promoting a value to biometric storage removes the plain secure copy on iOS and web, matching Android; plain reads can no longer return stale values after promotion.
+- **iOS legacy disk data:** Disk enumeration, size, prefix queries, and clear now cover both the suite domain and legacy `standardUserDefaults` values, so deleted legacy values cannot reappear.
+- **Failure-atomic migrations:** each migration step runs in its own transaction with its version marker; a failed step rolls back its data and marker, and rerunning `migrateToLatest()` retries from the last completed version.
+- **Transaction events:** failed transactions emit exactly one typed `rollback` batch event with pre-rollback and restored raw values.
+- **Atomic memory batch removes:** `removeBatch()` in Memory scope mutates all keys first and emits a single `removeBatch` event.
+- **Stable error classification:** storage error codes now come only from `[nitro-error:<code>]` tags produced by the native and web adapters; message-text scraping was removed and every public code has a producer.
+- **Encoding collisions:** reserved primitive tokens and the native batch missing sentinel are escaped in the stored encoding; legacy reads are preserved and raw API round-trips are unchanged.
+
+### Changed
+
+- `getCapabilities().writeBuffering` now reports real per-mode durability: native Secure writes report buffering only while `setSecureWritesAsync(true)` is active on Android, and web backends report buffering only for IndexedDB-based backends.
+- The IndexedDB backend reports affected keys when `flush()` fails and starts a best-effort flush on `pagehide` and hidden visibility changes.
+- `setIfVersion()` is documented as optimistic (no backend-level atomicity); CAS guarantees are covered by race tests.
+
 ## 0.7.0 - 2026-07-30
 
 ### Changes

package/README.md

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

package/SECURITY.md

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

package/docs/api-reference.md

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

package/docs/batch-transactions-migrations.md

@@ -80,7 +80,7 @@ const snapshot = storage.export(StorageScope.Disk);
 storage.import(snapshot, StorageScope.Disk);
 ```
 
-For Memory scope, import is atomic: all keys are written before listeners fire. For Disk and Secure, import delegates to native or web batch paths.
+For Memory scope, import is atomic: all keys are written before listeners fire. Disk and Secure imports flush pending coalesced writes first, so the imported snapshot cannot be overwritten by an earlier pending flush, then delegate to native or web batch paths.
 
 Secure exports contain raw secret values. `storage.export(StorageScope.Secure)` requires `{ includeSecureValues: true }`; `storage.exportSecureUnsafe()` is the explicit equivalent. Do not log Secure exports or include them in diagnostics, analytics, crash reports, or support bundles.
 
@@ -124,7 +124,9 @@ Transaction context methods:
 - `setItem(item, value)`
 - `removeItem(item)`
 
-If the callback throws, Nitro Storage restores the keys it changed during that transaction.
+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.
+
+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
 
@@ -157,6 +159,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.
+
 ```ts
 registerMigration(3, (ctx) => {
   const raw = ctx.getRaw("settings");
@@ -198,3 +202,5 @@ const didWrite = themeItem.setIfVersion(
 ```
 
 `setIfVersion()` returns `false` if another write changed the item after `getWithVersion()`.
+
+Compare-and-set is optimistic: the version is read, compared, and written without backend-level atomicity. Two writers on different runtimes can both pass the check between their reads and writes, so use it for single-runtime coordination or last-writer-wins-tolerant flows. There is no native compare-and-swap primitive.

package/docs/benchmarks.md

@@ -2,36 +2,40 @@
 
 Benchmarks are release checks, not product promises. Use them to catch regressions on the local machine and CI image used by this repo.
 
-Run:
+Run from the repo root:
 
 ```sh
-bun run benchmark -- --filter=react-native-nitro-storage
+bun run build
+bun run benchmark
 ```
 
-The benchmark script checks representative synchronous read/write paths and fails when results drift beyond the configured threshold.
+## Scope: Web Only
+
+`benchmark` loads `lib/commonjs/index.web.js` and measures the web entry against the localStorage backend. The `disk:` and `secure:` labels describe web scopes, not native Disk or Secure storage.
+
+Native Disk/Secure baselines require a device or simulator run and are not part of this gate. Do not compare these numbers against native storage.
 
 ## Interpreting Results
 
 - Compare results on the same machine and Node/Bun version.
-- Treat large deltas as a prompt to inspect recent storage-runtime, serialization, native bridge, or cache changes.
+- Treat large deltas as a prompt to inspect recent storage-runtime, serialization, cache, or event changes.
 - Do not compare web backend numbers against native secure storage numbers; they measure different systems.
-- Secure storage performance depends on platform state, device lock state, biometric prompts, and Keystore/Keychain behavior.
 
 ## Release Checklist
 
 Before publishing:
 
 ```sh
-bun run lint -- --filter=react-native-nitro-storage
-bun run format:check -- --filter=react-native-nitro-storage
-bun run typecheck -- --filter=react-native-nitro-storage
-bun run test:types -- --filter=react-native-nitro-storage
-bun run test -- --filter=react-native-nitro-storage
-bun run test:cpp -- --filter=react-native-nitro-storage
-bun run build -- --filter=react-native-nitro-storage
-bun run benchmark -- --filter=react-native-nitro-storage
-(cd packages/react-native-nitro-storage && bun run check:pack)
-npm publish --dry-run
+bun run codegen:check
+bun run lint:check
+bun run format:check
+bun run typecheck
+bun run test:types
+bun run test
+bun run test:cpp
+bun run build
+bun run benchmark
+bun run --cwd packages/react-native-nitro-storage check:pack
 ```
 
 Keep the dry-publish output in the release notes when validating a version locally.

package/docs/web-backends.md

@@ -38,7 +38,7 @@ Optional methods improve performance and observability:
 
 `subscribe(listener)` should report `{ key, newValue }` changes. Use `key: null` when the whole backend is cleared.
 
-`close()` should release backend-owned resources such as database handles or broadcast channels. Nitro Storage calls it when a configured Disk or Secure backend is replaced.
+`close()` should release backend-owned resources such as database handles or broadcast channels. A replaced backend is retired instead of closed on the spot: `flushWebStorageBackends()` flushes it and then closes it, so queued async writes can commit before the connection goes away. Backends without `flush()` are closed immediately on replacement, and a retired backend whose flush fails stays retired for a later explicit retry.
 
 ## Disk Backend
 
@@ -100,6 +100,23 @@ Reads are synchronous because they are served from memory after initial load. Wr
 
 The IndexedDB backend exposes `close()` and rejects later synchronous operations after it is closed.
 
+### Persistence Lifecycle
+
+IndexedDB transactions cannot block a page unload, so in-flight writes may be aborted when the page closes. The backend mitigates this by starting a flush on `pagehide` and on `visibilitychange` (hidden), and `flush()` awaits every pending transaction. When persistence fails, `flush()` throws an error that names the affected keys, and `onError` receives each individual failure.
+
+```ts
+const backend = await createIndexedDBBackend("app-secure", "keyvalue", {
+  onError: (error) => {
+    console.error("IndexedDB secure storage failed", error);
+  },
+});
+
+// Before assertions, navigation, or lifecycle boundaries:
+await flushWebStorageBackends();
+```
+
+Treat IndexedDB persistence as best-effort under abrupt termination: keep a durable copy of critical values elsewhere if they must survive an immediate page close.
+
 ## Cross-tab Updates
 
 The IndexedDB backend uses `BroadcastChannel` when available. Other tabs receive cache invalidation events and update their in-memory copy.

package/ios/IOSStorageAdapterCpp.mm

@@ -8,6 +8,8 @@ namespace NitroStorage {
 static NSString* const kKeychainService = @"com.nitrostorage.keychain";
 static NSString* const kBiometricKeychainService = @"com.nitrostorage.biometric";
 static NSString* const kDiskSuiteName = @"com.nitrostorage.disk";
+static NSString* const kLegacyDiskKeysRegistryKey =
+    @"__nitro_storage_legacy_disk_keys__";
 
 static std::runtime_error taggedStorageError(const char* code, const std::string& message) {
     return std::runtime_error(
@@ -15,11 +17,69 @@ static std::runtime_error taggedStorageError(const char* code, const std::string
     );
 }
 
+// Unknown keychain statuses are surfaced untagged (matching Android's
+// cause-based wrapping), except errSecNotAvailable which means the keychain
+// is unavailable until the device is first unlocked — a locked condition.
+static std::runtime_error keychainStatusError(OSStatus status, const std::string& operation) {
+    if (status == errSecNotAvailable) {
+        return taggedStorageError(
+            "keychain_locked",
+            std::string("NitroStorage: ") + operation + " failed: keychain is unavailable until the device is unlocked (errSecNotAvailable)."
+        );
+    }
+    return std::runtime_error(
+        std::string("NitroStorage: ") + operation + " failed with status " + std::to_string(status)
+    );
+}
+
 static NSUserDefaults* NitroDiskDefaults() {
     static NSUserDefaults* defaults = [[NSUserDefaults alloc] initWithSuiteName:kDiskSuiteName];
     return defaults ?: [NSUserDefaults standardUserDefaults];
 }
 
+// --- Legacy disk key registry ---
+// Versions before the suite domain stored Disk values in standardUserDefaults.
+// The registry records legacy keys observed through the storage API so that
+// clearDisk can remove both stores and deleted legacy values cannot reappear.
+// Only keys observed through the storage API are ever registered; the host
+// app's own standard defaults keys are never enumerated or touched.
+
+static NSSet<NSString*>* registeredLegacyDiskKeys() {
+    NSArray* stored = [NitroDiskDefaults() stringArrayForKey:kLegacyDiskKeysRegistryKey];
+    return stored ? [NSSet setWithArray:stored] : [NSSet set];
+}
+
+static void persistLegacyDiskKeys(NSSet<NSString*>* keys) {
+    if (keys.count == 0) {
+        [NitroDiskDefaults() removeObjectForKey:kLegacyDiskKeysRegistryKey];
+        return;
+    }
+    [NitroDiskDefaults() setObject:[keys allObjects] forKey:kLegacyDiskKeysRegistryKey];
+}
+
+static void registerLegacyDiskKey(NSString* key) {
+    NSMutableSet* keys = [registeredLegacyDiskKeys() mutableCopy];
+    [keys addObject:key];
+    persistLegacyDiskKeys(keys);
+}
+
+static void unregisterLegacyDiskKeys(NSArray<NSString*>* keys) {
+    if (keys.count == 0) {
+        return;
+    }
+    NSMutableSet* registered = [registeredLegacyDiskKeys() mutableCopy];
+    BOOL changed = NO;
+    for (NSString* key in keys) {
+        if ([registered containsObject:key]) {
+            [registered removeObject:key];
+            changed = YES;
+        }
+    }
+    if (changed) {
+        persistLegacyDiskKeys(registered);
+    }
+}
+
 // Prevents the Keychain from showing auth UI. On iOS 14+ kSecUseAuthenticationUIFail is
 // deprecated; the correct replacement is an LAContext with interactionNotAllowed = YES.
 static void disableKeychainInteraction(NSMutableDictionary* query) {
@@ -52,6 +112,7 @@ void IOSStorageAdapterCpp::setDisk(const std::string& key, const std::string& va
     NSUserDefaults* standard = [NSUserDefaults standardUserDefaults];
     if ([standard objectForKey:nsKey] != nil) {
         [standard removeObjectForKey:nsKey];
+        unregisterLegacyDiskKeys(@[nsKey]);
     }
 }
 
@@ -66,6 +127,7 @@ std::optional<std::string> IOSStorageAdapterCpp::getDisk(const std::string& key)
         if (legacyValue) {
             [defaults setObject:legacyValue forKey:nsKey];
             [legacyDefaults removeObjectForKey:nsKey];
+            unregisterLegacyDiskKeys(@[nsKey]);
             result = legacyValue;
         }
     }
@@ -81,22 +143,40 @@ void IOSStorageAdapterCpp::deleteDisk(const std::string& key) {
     if ([standard objectForKey:nsKey] != nil) {
         [standard removeObjectForKey:nsKey];
     }
+    unregisterLegacyDiskKeys(@[nsKey]);
 }
 
 bool IOSStorageAdapterCpp::hasDisk(const std::string& key) {
     NSString* nsKey = [NSString stringWithUTF8String:key.c_str()];
     if ([NitroDiskDefaults() objectForKey:nsKey] != nil) return true;
     // Check legacy standardUserDefaults for un-migrated keys
-    return [[NSUserDefaults standardUserDefaults] stringForKey:nsKey] != nil;
+    if ([[NSUserDefaults standardUserDefaults] stringForKey:nsKey] != nil) {
+        registerLegacyDiskKey(nsKey);
+        return true;
+    }
+    return false;
 }
 
 std::vector<std::string> IOSStorageAdapterCpp::getAllKeysDisk() {
     NSUserDefaults* defaults = NitroDiskDefaults();
     NSDictionary<NSString*, id>* entries = [defaults persistentDomainForName:kDiskSuiteName] ?: @{};
-    std::vector<std::string> keys;
-    keys.reserve(entries.count);
+    std::unordered_set<std::string> combined;
     for (NSString* key in entries) {
-        keys.push_back(std::string([key UTF8String]));
+        if (![key isEqualToString:kLegacyDiskKeysRegistryKey]) {
+            combined.insert(std::string([key UTF8String]));
+        }
+    }
+    // Only keys observed through the storage API are registered legacy keys;
+    // arbitrary host-app standard defaults keys are never enumerated.
+    for (NSString* key in [registeredLegacyDiskKeys() allObjects]) {
+        if (entries[key] == nil && ![key isEqualToString:kLegacyDiskKeysRegistryKey]) {
+            combined.insert(std::string([key UTF8String]));
+        }
+    }
+    std::vector<std::string> keys;
+    keys.reserve(combined.size());
+    for (const auto& key : combined) {
+        keys.push_back(key);
     }
     return keys;
 }
@@ -114,8 +194,7 @@ std::vector<std::string> IOSStorageAdapterCpp::getKeysByPrefixDisk(const std::st
 }
 
 size_t IOSStorageAdapterCpp::sizeDisk() {
-    NSDictionary<NSString*, id>* entries = [NitroDiskDefaults() persistentDomainForName:kDiskSuiteName] ?: @{};
-    return entries.count;
+    return getAllKeysDisk().size();
 }
 
 void IOSStorageAdapterCpp::setDiskBatch(
@@ -136,6 +215,7 @@ void IOSStorageAdapterCpp::setDiskBatch(
     for (NSString* key in legacyKeysToRemove) {
         [standard removeObjectForKey:key];
     }
+    unregisterLegacyDiskKeys(legacyKeysToRemove);
 }
 
 std::vector<std::optional<std::string>> IOSStorageAdapterCpp::getDiskBatch(
@@ -158,9 +238,26 @@ void IOSStorageAdapterCpp::deleteDiskBatch(const std::vector<std::string>& keys)
 void IOSStorageAdapterCpp::clearDisk() {
     NSUserDefaults* defaults = NitroDiskDefaults();
     NSDictionary<NSString*, id>* entries = [defaults persistentDomainForName:kDiskSuiteName] ?: @{};
+    // Capture the registry before clearing the suite domain, which removes it.
+    NSMutableSet* legacyKeys = [registeredLegacyDiskKeys() mutableCopy];
     for (NSString* key in entries) {
         [defaults removeObjectForKey:key];
     }
+    // Clear the standard-defaults copies of every storage-owned key so legacy
+    // values deleted here cannot reappear through the read-time migration path.
+    NSUserDefaults* standard = [NSUserDefaults standardUserDefaults];
+    for (NSString* key in entries) {
+        if ([standard objectForKey:key] != nil) {
+            [standard removeObjectForKey:key];
+            [legacyKeys removeObject:key];
+        }
+    }
+    for (NSString* key in legacyKeys) {
+        if ([standard objectForKey:key] != nil) {
+            [standard removeObjectForKey:key];
+        }
+    }
+    [defaults removeObjectForKey:kLegacyDiskKeysRegistryKey];
 }
 
 // --- Secure (Keychain) ---
@@ -228,9 +325,7 @@ static void setSecureValue(
                 "The item is not accessible until the device is unlocked."
             );
         }
-        throw std::runtime_error(
-            "NitroStorage: Secure set failed with status " + std::to_string(addStatus)
-        );
+        throw keychainStatusError(addStatus, "Secure set");
     }
 
     if (status == errSecInteractionNotAllowed) {
@@ -240,9 +335,7 @@ static void setSecureValue(
             "The item is not accessible until the device is unlocked."
         );
     }
-    throw std::runtime_error(
-        "NitroStorage: Secure set failed with status " + std::to_string(status)
-    );
+    throw keychainStatusError(status, "Secure set");
 }
 
 static std::optional<std::string> getSecureValue(NSString* nsKey, NSString* group) {
@@ -290,6 +383,20 @@ static void deleteSecureValue(NSString* nsKey, NSString* group) {
     }
 }
 
+// Deletes only the plain (non-biometric) keychain copy. Promotion to biometric
+// storage must remove the plain copy so stale plain reads cannot resurrect it.
+static void deletePlainSecureValue(NSString* nsKey, NSString* group) {
+    NSMutableDictionary* secureQuery = baseKeychainQuery(nsKey, kKeychainService, group);
+    OSStatus secureStatus = SecItemDelete((__bridge CFDictionaryRef)secureQuery);
+    if (secureStatus == errSecInteractionNotAllowed) {
+        throw taggedStorageError(
+            "keychain_locked",
+            "NitroStorage: Keychain is locked (errSecInteractionNotAllowed). "
+            "The item is not accessible until the device is unlocked."
+        );
+    }
+}
+
 static std::vector<std::string> keychainAccountsForService(NSString* service, NSString* accessGroup) {
     NSMutableDictionary* query = allAccountsQuery(service, accessGroup);
     disableKeychainInteraction(query);
@@ -490,8 +597,7 @@ void IOSStorageAdapterCpp::clearSecure() {
                 "NitroStorage: Cannot clear secure storage: keychain is locked (errSecInteractionNotAllowed)"
             );
         }
-        throw std::runtime_error(
-            std::string("NitroStorage: clearSecure failed with status ") + std::to_string(secStatus));
+        throw keychainStatusError(secStatus, "clearSecure");
     }
 
     NSMutableDictionary* biometricQuery = [@{
@@ -509,8 +615,7 @@ void IOSStorageAdapterCpp::clearSecure() {
                 "NitroStorage: Cannot clear biometric storage: keychain is locked (errSecInteractionNotAllowed)"
             );
         }
-        throw std::runtime_error(
-            std::string("NitroStorage: clearSecureBiometric failed with status ") + std::to_string(bioStatus));
+        throw keychainStatusError(bioStatus, "clearSecureBiometric");
     }
     clearSecureKeyCache();  // Only clears cache AFTER confirmed deletion
 }
@@ -627,12 +732,52 @@ void IOSStorageAdapterCpp::setSecureBiometricWithLevel(const std::string& key, c
                 "The item is not accessible until the device is unlocked."
             );
         }
-        throw std::runtime_error(
+        if (addStatus == errSecNotAvailable) {
+            throw taggedStorageError(
+                "keychain_locked",
+                "NitroStorage: Biometric set failed: keychain is unavailable until the device is unlocked (errSecNotAvailable)."
+            );
+        }
+        throw taggedStorageError(
+            "biometric_unavailable",
             std::string("NitroStorage: Biometric set failed with status ") +
             std::to_string(addStatus) +
             (backup.has_value() ? " (previous value restored to non-biometric keychain)" : " (no previous value)"));
     }
+
+    // Promotion contract: the plain secure copy must not survive a biometric
+    // write, or plain reads would return a stale value (Android removes it too).
+    // If removing the plain copy fails after the biometric write succeeded,
+    // roll the biometric write back so the promotion either fully succeeds or
+    // leaves the previous state intact, then rethrow the original error.
+    try {
+        deletePlainSecureValue(nsKey, group);
+    } catch (const std::exception& plainDeleteError) {
+        if (backup.has_value()) {
+            CFErrorRef restoreError = NULL;
+            SecAccessControlRef restoreAccess = SecAccessControlCreateWithFlags(
+                kCFAllocatorDefault,
+                kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
+                flags,
+                &restoreError
+            );
+            if (restoreAccess && !restoreError) {
+                NSMutableDictionary* restoreQuery = baseKeychainQuery(nsKey, kBiometricKeychainService, group);
+                restoreQuery[(__bridge id)kSecValueData] = [nsStringFromStdString(*backup) dataUsingEncoding:NSUTF8StringEncoding];
+                restoreQuery[(__bridge id)kSecAttrAccessControl] = (__bridge_transfer id)restoreAccess;
+                SecItemAdd((__bridge CFDictionaryRef)restoreQuery, NULL);
+            } else {
+                if (restoreError) CFRelease(restoreError);
+                if (restoreAccess) CFRelease(restoreAccess);
+            }
+        } else {
+            NSMutableDictionary* rollbackQuery = baseKeychainQuery(nsKey, kBiometricKeychainService, group);
+            SecItemDelete((__bridge CFDictionaryRef)rollbackQuery);
+        }
+        throw;
+    }
     markBiometricKeySet(key);
+    markSecureKeyRemoved(key);
 }
 
 std::optional<std::string> IOSStorageAdapterCpp::getSecureBiometric(const std::string& key) {

package/lib/commonjs/capabilities.js

@@ -0,0 +1,26 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.resolveNativeWriteBuffering = resolveNativeWriteBuffering;
+exports.resolveWebWriteBuffering = resolveWebWriteBuffering;
+function resolveWebWriteBuffering(diskBackendName, secureBackendName) {
+  return {
+    disk: isIndexedDBWebBackendByName(diskBackendName),
+    secure: isIndexedDBWebBackendByName(secureBackendName)
+  };
+}
+function isIndexedDBWebBackendByName(backendName) {
+  if (!backendName) {
+    return false;
+  }
+  return backendName.startsWith("indexeddb:");
+}
+function resolveNativeWriteBuffering(platform, secureWritesAsync) {
+  return {
+    disk: true,
+    secure: platform === "android" ? secureWritesAsync : false
+  };
+}
+//# sourceMappingURL=capabilities.js.map

package/lib/commonjs/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["resolveWebWriteBuffering","diskBackendName","secureBackendName","disk","isIndexedDBWebBackendByName","secure","backendName","startsWith","resolveNativeWriteBuffering","platform","secureWritesAsync"],"sourceRoot":"../../src","sources":["capabilities.ts"],"mappings":";;;;;;;AAUO,SAASA,wBAAwBA,CACtCC,eAAmC,EACnCC,iBAAqC,EACrB;EAChB,OAAO;IACLC,IAAI,EAAEC,2BAA2B,CAACH,eAAe,CAAC;IAClDI,MAAM,EAAED,2BAA2B,CAACF,iBAAiB;EACvD,CAAC;AACH;AAEA,SAASE,2BAA2BA,CAACE,WAA+B,EAAW;EAC7E,IAAI,CAACA,WAAW,EAAE;IAChB,OAAO,KAAK;EACd;EACA,OAAOA,WAAW,CAACC,UAAU,CAAC,YAAY,CAAC;AAC7C;AAEO,SAASC,2BAA2BA,CACzCC,QAA2B,EAC3BC,iBAA0B,EACV;EAChB,OAAO;IACLP,IAAI,EAAE,IAAI;IACVE,MAAM,EAAEI,QAAQ,KAAK,SAAS,GAAGC,iBAAiB,GAAG;EACvD,CAAC;AACH","ignoreList":[]}