react-native-nitro-storage 0.10.3 → 0.11.0

package/CHANGELOG.md

@@ -6,6 +6,74 @@ 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.11.0] - 2026-09-30
+
+### Breaking changes
+
+- **React Native 0.77 or newer is required.** The `react-native` peer range is now `>=0.77.0` (was `>=0.75.0`), matching the minimum for Nitro Modules 0.37, whose Android package does not compile against React Native 0.76. Supported: React Native 0.77+ / Expo SDK 53+; tested on React Native 0.86.3 / Expo SDK 57. Migration: upgrade to React Native 0.77 or Expo SDK 53 or newer.
+- **iOS `has()` on Secure keys throws instead of returning `false`.** `item.has()` and `storage.has(key, StorageScope.Secure)` throw `keychain_locked` while the keychain is locked and a Keychain status error for any other unexpected status, matching `hasSecureBiometric` and Android. A biometric item that needs authentication counts as present. Migration: wrap Secure existence checks that can run while the device is locked in `try`/`catch` and retry after unlock when `isStorageError(error, "keychain_locked")`.
+- **iOS Secure key listing throws on unexpected Keychain statuses.** `getAllKeys`, `size`, `getKeysByPrefix`, and `getByPrefix` for Secure scope throw a Keychain status error (for example a misconfigured access group) instead of returning an empty result. Migration: catch errors around Secure enumeration and check the Keychain access group.
+- **Android permanent Secure store failures report `storage_corruption`.** When the default Secure master key or store cannot be created, Secure calls throw `storage_corruption` instead of `authentication_required`. Migration: do not retry these errors; tell the user that secure data must be reset.
+- **`fallbackToCacheOnReadError` applies only to `keychain_locked`.** Other read errors such as `authentication_required`, `key_invalidated`, and `storage_corruption` now throw instead of returning the cached value. Only iOS reports `keychain_locked`, so the option has no effect on Android or web. Migration: catch those codes where you relied on the fallback, and handle them explicitly (prompt the user, or recreate the credential).
+- **Native `getCapabilities().backend.disk` is `"sqlite"`.** It was `"platform-preferences"`, although native Disk has used SQLite WAL since 0.10.3. Migration: compare against `"sqlite"` if you branch on this string.
+- **Empty storage keys are rejected.** `createStorageItem({ key: "" })` (also with a `namespace`), `setString("")`, `deleteString("")`, and `import({ "": value })` throw an error with the new `invalid_key` code. On native an empty key was also the clear signal, so writing it cleared pending writes and caches for the whole scope. Migration: rename any empty key; handle `invalid_key` if your `StorageErrorCode` switch is exhaustive.
+- **Deprecated:** the root export of `createIndexedDBBackend`. Migration: import it from `react-native-nitro-storage/indexeddb-backend`. The root export still works in this release.
+
+### Fixed
+
+- Deleting an item, `deleteString()`, and transaction rollbacks read the previous value only when an event listener or an unredacted event observer needs it. Deleting or expiring a biometric item no longer shows a Face ID or passcode prompt on iOS, and a cancelled prompt no longer blocks the delete.
+- Memory `setBatch()` keeps string values that start with the reserved escape prefix intact.
+- Memory `clear(scope, { except })` and `deleteString()` drop TTL deadlines, so a later write to the same key no longer expires early or fires `onExpired`.
+- A late native change notification for an older write no longer overwrites a newer cached value for `readCache` items and their subscribers.
+- Reads fill the Disk/Secure raw cache only for items with `readCache` or `fallbackToCacheOnReadError`, so other Secure reads no longer keep plaintext values in the JavaScript heap.
+- Web: when one backend instance is registered for both Disk and Secure, Disk enumeration and export skip Secure keys, `clear()` removes only the cleared scope's keys, and backend `subscribe()` events (for example from another tab) reach only the scope that owns the key.
+- Web: window `storage` events update a scope only while it uses the default `localStorage` backend, and only for events from `localStorage`. Writes to `localStorage` in another tab no longer add phantom keys to IndexedDB-backed scopes.
+- Web IndexedDB backend: cross-tab messages that arrive during startup hydration are applied after the snapshot instead of being overwritten.
+- `react-native-nitro-storage/testing` notifies Disk and Secure subscribers, so hooks re-render for those scopes, and it exports the web backend setters, getters, and `flushWebStorageBackends` as no-ops like the native entry.
+- `describeWebBackendCapabilities`, `isIndexedDBWebBackend`, and `WebBackendCapabilities` are exported from the main entry types.
+- iOS Secure writes update `kSecAttrAccessible` on existing Keychain items, so a changed access control level reaches items that already exist.
+- iOS Secure batch writes notify listeners for the keys that were applied before a failure is rethrown.
+- iOS resolves the Disk database path once instead of on every Disk call, runs the legacy Disk migration on first Disk use instead of at module creation, and a corrupt Disk database no longer leaks a file descriptor per call or blocks Memory and Secure scopes.
+- Android creates the Secure master key and preferences on first Secure use instead of at app start, so a Keystore failure surfaces as a Secure error instead of crashing the app at launch.
+- Android biometric reads and existence checks open stores in the order `BiometryOrPasscode`, legacy biometric, `BiometryOnly` and stop at the first hit (previously `BiometryOnly` first), so reading a `BiometryOrPasscode` item needs only a device-credential authentication. Biometric writes still snapshot every existing store and remove the key from every other store, so no stale duplicates remain.
+- Android Disk deletes also remove the key from the legacy `NitroStorage` SharedPreferences, and `clear(Disk)` clears them, so a logout wipe leaves no pre-SQLite copy. The legacy file is otherwise kept for downgrade safety, like the iOS suite domain.
+- The podspec uses React Native's minimum iOS version and excludes test sources; the Android build no longer pins `kotlin-stdlib`.
+- The Expo config plugin loads `expo/config-plugins`, and `expo` (`>=53.0.0`) is declared as an optional peer dependency.
+- The `/testing` and `/indexeddb-backend` subpaths ship stub `package.json` folders, so they resolve when Metro package exports are disabled (the default before React Native 0.79).
+- The IndexedDB backend no longer installs `pagehide` and `visibilitychange` listeners; they started no IndexedDB work.
+
+### Documentation
+
+- Android biometric protection is checked when a biometric store is first opened in a process; later reads in that process do not authenticate again, and the package never shows a prompt on Android. Apps must run their own `BiometricPrompt` before gated reads. The previous "30-second window" wording was wrong.
+- iOS biometric reads block the JavaScript thread while the system prompt is visible.
+- README web backend example uses separate stores for Disk and Secure, the events example uses the `(namespace, scope, listener)` signature, the auth-token example no longer enables `fallbackToCacheOnReadError`, and the error code table lists every code.
+- Compatibility: supports React Native 0.77+ / Expo SDK 53+ (Nitro Modules 0.37 minimum); tested on React Native 0.86.3 / Expo SDK 57.
+- `SECURITY.md` names the supported `0.11.x` line and private vulnerability reporting.
+
+## [0.10.5] - 2026-09-30
+
+### Breaking changes
+
+- None.
+
+### Fixed
+
+- iOS no longer re-reads the whole UserDefaults suite and re-imports it into SQLite on every cold start. The import now runs once and records completion in the SQLite `meta` table, like Android. Existing values stay readable, and the suite domain is kept so a downgrade still sees its data.
+
+## [0.10.4] - 2026-09-27
+
+### Breaking changes
+
+- None.
+
+### Fixed
+
+- Disk prefix queries and namespace removal now distinguish ASCII case, so clearing `user` does not remove `User` keys.
+- Android Disk and Secure storage preserve embedded NUL characters in keys and values across scalar and batch operations, preventing truncated-key collisions.
+- iOS Secure storage preserves embedded NUL keys and values, and legacy Disk migration no longer aliases a shorter host-app defaults key when a key contains NUL.
+- Memory prefix reads return the original raw string, including values beginning with the reserved internal prefix.
+- Raw enumeration, export, and set items preserve arbitrary keys such as `__proto__`, `constructor`, and `toString` as own properties.
+
 ## [0.10.3] - 2026-09-18
 
 ### Breaking changes
@@ -169,14 +237,17 @@ Breaking changes are always listed first in each release section.
 ### 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.
+- The IndexedDB backend reports affected keys when `flush()` fails and adds `pagehide` and hidden-visibility listeners. Those listeners started no IndexedDB work and were removed in 0.11.0.
 - `setIfVersion()` is documented as optimistic (no backend-level atomicity); CAS guarantees are covered by race tests.
 
 ## [0.7.0] - 2026-07-30
 
+### Breaking changes
+
+- Android secure key discovery, existence checks, and cleanup now surface locked, unavailable, or invalidated biometric-store errors instead of treating inaccessible protected values as absent. Catch storage errors around these operations and use `isKeychainLockedError()` when retrying after device authentication is appropriate.
+
 ### Changes
 
-- **Breaking change:** Android secure key discovery, existence checks, and cleanup now surface locked, unavailable, or invalidated biometric-store errors instead of treating inaccessible protected values as absent. Catch storage errors around these operations and use `isKeychainLockedError()` when retrying after device authentication is appropriate.
 - Upgrade the validated package baseline to Expo SDK 57, React Native 0.86.2, and Nitro Modules/Nitrogen 0.36.4.
 - Preserve each item/value relationship in heterogeneous `setBatch()` calls so TypeScript rejects values assigned to the wrong storage item.
 - Serialize native key-index hydration with concurrent mutations so `has`, `size`, and key queries cannot remain stale after a racing write.
@@ -185,6 +256,15 @@ Breaking changes are always listed first in each release section.
 
 ## [0.6.0] - 2026-06-15
 
+### Breaking changes
+
+All new APIs are additive — existing code keeps working. These behavior and
+type changes can affect advanced consumers:
+
+- TTL expiry now emits a `"expire"` change event instead of `"remove"`. Previously, a disk/secure value expiring on read emitted `operation: "remove"` and an expiring memory value emitted no event at all. If you subscribe to storage events and branch on `operation === "remove"` to detect expiry, also handle `"expire"` (or use the new `storage.subscribeExpired()`).
+- `StorageChangeOperation` gained the `"expire"` and `"clearGroup"` members. Exhaustive `switch` statements over a change event's `operation` need cases for the new members.
+- `useStorage()` now returns a three-element tuple `[value, setter, actions]` (was two). Array destructuring such as `const [value, setStore] = useStorage(item)` is unaffected; only code that annotated the result with an explicit two-element tuple type needs to widen the annotation.
+
 ### Added
 
 - Object-state ergonomics on `StorageItem<T>`: `item.merge(partial)` for shallow object updates, `item.reset()` to return to the default value, and `item.setOrDelete(value)` which deletes on `null`/`undefined` and sets otherwise.
@@ -200,16 +280,7 @@ Breaking changes are always listed first in each release section.
 
 ### Changed
 
-- Faster writes when nothing is subscribed: the native write/notify path now takes a lock-free fast path (per-scope atomic listener counts) and skips locking and copying the listener vector when a scope has no listeners. Applies to both iOS and Android via the shared C++ `HybridStorage`, and is thread-safe (verified under the C++ AddressSanitizer, ThreadSanitizer, and UndefinedBehaviorSanitizer suites).
-
-### Breaking Changes
-
-All new APIs are additive — existing code keeps working. These behavior and
-type changes can affect advanced consumers:
-
-- TTL expiry now emits a `"expire"` change event instead of `"remove"`. Previously, a disk/secure value expiring on read emitted `operation: "remove"` and an expiring memory value emitted no event at all. If you subscribe to storage events and branch on `operation === "remove"` to detect expiry, also handle `"expire"` (or use the new `storage.subscribeExpired()`).
-- `StorageChangeOperation` gained the `"expire"` and `"clearGroup"` members. Exhaustive `switch` statements over a change event's `operation` need cases for the new members.
-- `useStorage()` now returns a three-element tuple `[value, setter, actions]` (was two). Array destructuring such as `const [value, setStore] = useStorage(item)` is unaffected; only code that annotated the result with an explicit two-element tuple type needs to widen the annotation.
+- Writes skip listener locking when nothing is subscribed: the native write/notify path now takes a lock-free fast path (per-scope atomic listener counts) and skips locking and copying the listener vector when a scope has no listeners. Applies to both iOS and Android via the shared C++ `HybridStorage`, and is thread-safe (verified under the C++ AddressSanitizer, ThreadSanitizer, and UndefinedBehaviorSanitizer suites).
 
 ## [0.5.9] - 2026-06-11
 
@@ -242,7 +313,7 @@ type changes can affect advanced consumers:
 
 ### Changed
 
-- Speed up iOS Secure batch operations by reusing the resolved Keychain access group and access-control level across each batch instead of re-reading configuration per key.
+- iOS Secure batch operations reuse the resolved Keychain access group and access-control level across each batch instead of re-reading configuration per key.
 - Refactor iOS Secure set/get/delete helpers so single-item and batch paths share Keychain status handling and cache updates.
 - Strengthen TypeScript inference parity on web by exporting `StorageSetter` and preserving tuple value types from `getBatch()`.
 
@@ -428,7 +499,7 @@ type changes can affect advanced consumers:
 - Group secure raw batch writes by per-item access control so secure batch paths stay fast even with mixed access-control settings.
 - Optimize C++ batch listener dispatch by copying scoped listeners once per batch operation.
 - Avoid duplicate secure biometric clearing calls by relying on secure clear paths that already include biometric cleanup.
-- Optimize web secure/disk key bookkeeping with an indexed key cache (faster `size`, `getAllKeys`, and namespace clears without repeated `localStorage` scans).
+- Optimize web secure/disk key bookkeeping with an indexed key cache (`size`, `getAllKeys`, and namespace clears no longer rescan `localStorage`).
 - Improve iOS secure key union performance by deduplicating with an `unordered_set`.
 - Extract shared React hooks into `src/storage-hooks.ts` to reduce native/web entrypoint duplication.
 - Expand benchmark coverage to include Disk and Secure scope throughput checks and tighten regression thresholds.

package/README.md

@@ -35,6 +35,7 @@ pagination, conflict resolution, or remote synchronization.
 - [Legacy Key Migration And Secure Resilience](#legacy-key-migration-and-secure-resilience)
 - [React Hooks](#react-hooks)
 - [Storage Scopes](#storage-scopes)
+- [Prefix Queries](#prefix-queries)
 - [Secure Storage](#secure-storage)
 - [Batch Operations](#batch-operations)
 - [Events And Observability](#events-and-observability)
@@ -60,15 +61,28 @@ Peer dependencies:
 | Package                      | Version            |
 | ---------------------------- | ------------------ |
 | `react`                      | `>=18.2.0`         |
-| `react-native`               | `>=0.75.0`         |
+| `react-native`               | `>=0.77.0`         |
 | `react-native-nitro-modules` | `>=0.37.0 <0.38.0` |
 
 Nitro peer requirement: `react-native-nitro-modules >=0.37.0 <0.38.0`.
 
+| Tested on                                  | Supported floor                     |
+| ------------------------------------------ | ----------------------------------- |
+| React Native `0.86.3` / Expo SDK `57.0.26` | React Native `0.77` / Expo SDK `53` |
+
+Nitro Storage supports React Native 0.77 or newer and Expo SDK 53 or newer,
+which is the minimum for Nitro Modules 0.37: its Android package does not
+compile against React Native 0.76. It is tested on React Native 0.86.3 and Expo
+SDK 57.
+
+The `react-native-nitro-storage/testing` and
+`react-native-nitro-storage/indexeddb-backend` subpaths also resolve when Metro
+package exports are disabled (the default before React Native 0.79).
+
 The package gate uses React Native `0.86.3` and the Strict TypeScript API.
 `check:ci` also compiles the public source against React Native `0.87.0`'s
 Strict TypeScript API; this does not change the runtime baseline. The Expo
-example uses Expo SDK `57.0.24`, React Native
+example uses Expo SDK `57.0.26`, React Native
 `0.86.3`, React `19.2.3`, and Nitro Modules `0.37.1`, which is the React Native
 version supported by that Expo SDK. Do not override Expo's React Native version.
 
@@ -77,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.10.3
+bun add react-native-nitro-modules@0.37.1 react-native-nitro-storage@0.11.0
 bunx expo prebuild
 ```
 
@@ -124,11 +138,15 @@ Add the config plugin before prebuilding native iOS and Android projects:
 }
 ```
 
-| Option                    | Default                  | What it does                                                   |
-| ------------------------- | ------------------------ | -------------------------------------------------------------- |
-| `faceIDPermission`        | Built-in Face ID message | Sets `NSFaceIDUsageDescription`.                               |
-| `addBiometricPermissions` | `false`                  | Adds Android biometric and fingerprint permissions.            |
-| `configureAndroidBackup`  | `true`                   | Writes Android backup rules that exclude secure storage files. |
+| Option                    | Default                  | What it does                                                    |
+| ------------------------- | ------------------------ | --------------------------------------------------------------- |
+| `faceIDPermission`        | Built-in Face ID message | Sets `NSFaceIDUsageDescription`.                                |
+| `addBiometricPermissions` | `false`                  | Adds Android `USE_BIOMETRIC` and `USE_FINGERPRINT` permissions. |
+| `configureAndroidBackup`  | `true`                   | Writes Android backup rules that exclude secure storage files.  |
+
+Nitro Storage does not show a biometric prompt on Android. Enable
+`addBiometricPermissions` when your app runs its own `BiometricPrompt` before it
+reads biometric items; the permissions are for that prompt.
 
 Android adapter initialization is owned by the package through an Android
 manifest initializer, so apps should not edit `MainApplication` to call
@@ -164,7 +182,10 @@ application state.
 Native storage calls are synchronous JSI operations. Keep values and batches
 small enough for the JavaScript event loop; native and configured web-backend
 failures throw errors. Secure cache fallback is opt-in through
-`fallbackToCacheOnReadError`.
+`fallbackToCacheOnReadError` and applies only to `keychain_locked` read errors,
+which only iOS reports.
+Storage keys must be non-empty strings; an empty key throws an `invalid_key`
+error before it reaches native storage.
 
 ## Auth Tokens
 
@@ -193,9 +214,9 @@ boundary. `createSecureAuthStorage` already namespaces keys, notifies
 subscribers, and migrates legacy keys.
 
 Do not enable `fallbackToCacheOnReadError` for access or refresh tokens unless
-the application explicitly accepts stale or revoked credentials. Handle
-temporary secure-storage errors and retry from application lifecycle state
-instead.
+the application explicitly accepts stale credentials while the keychain is
+locked. Handle temporary secure-storage errors and retry from application
+lifecycle state instead.
 
 ## Typed Storage Items
 
@@ -309,8 +330,11 @@ storage.clear(StorageScope.Disk, {
 ## Legacy Key Migration And Secure Resilience
 
 `renameFrom` migrates an old key to a new one on first read and deletes the
-legacy entry. Secure items can fall back to the last cached value when the
-keychain is locked instead of throwing.
+legacy entry. Secure items that set `fallbackToCacheOnReadError` return the last
+value read in this process when a read fails with `keychain_locked`. Every other
+read error, such as `authentication_required`, `key_invalidated`, or
+`storage_corruption`, still throws. Only iOS reports `keychain_locked`, so the fallback has an effect only on iOS; Android and web never use it. Use the fallback for values where a stale
+copy is acceptable, not for credentials.
 
 ```ts
 import {
@@ -318,11 +342,11 @@ import {
   createSecureAuthStorage,
 } from "react-native-nitro-storage";
 
-const accessToken = secureItem<string>({
-  key: "accessToken",
-  namespace: "auth",
-  defaultValue: "",
-  renameFrom: "authToken", // copied + cleaned up on first read
+const cachedProfile = secureItem<{ name: string } | null>({
+  key: "profile",
+  namespace: "account",
+  defaultValue: null,
+  renameFrom: "userProfile", // copied + cleaned up on first read
   fallbackToCacheOnReadError: true,
   onReadError: (error) => reportSecureReadError(error),
 });
@@ -332,7 +356,7 @@ const auth = createSecureAuthStorage(
     accessToken: { renameFrom: "authToken" },
     refreshToken: { renameFrom: "refreshToken" },
   },
-  { namespace: "auth", group: "session", fallbackToCacheOnReadError: true },
+  { namespace: "auth", group: "session" },
 );
 ```
 
@@ -393,6 +417,26 @@ const tokenActions = useStorageActions(tokenItem); // { set, merge, reset, remov
 | `StorageScope.Disk`   | SQLite WAL on iOS/Android (imports UserDefaults / SharedPreferences once); configured web backend | Preferences, feature flags, onboarding state, and non-secret persisted data. |
 | `StorageScope.Secure` | Keychain on iOS, Android Keystore-backed preferences                                              | Refresh tokens, credentials, API tokens, and biometric-protected values.     |
 
+## Prefix Queries
+
+Prefix queries use literal, case-sensitive matching on every backend. `User::`
+and `user::` are separate namespaces; `%`, `_`, and `\\` are literal characters.
+Raw enumeration returns the original strings and preserves arbitrary keys as own
+properties on an ordinary object, including `__proto__`.
+
+Disk and Secure strings preserve embedded NUL characters in keys and values,
+including batch operations. Earlier versions could truncate strings at Android
+JNI or iOS Foundation boundaries; this fix cannot reconstruct previously lost
+suffixes. iOS legacy Disk migration also preserves full keys without aliasing
+shorter host-app defaults keys.
+
+```ts
+storage.setString("User::theme", "dark", StorageScope.Disk);
+storage.setString("user::theme", "light", StorageScope.Disk);
+const settings = storage.getByPrefix("User::", StorageScope.Disk);
+// settings["User::theme"] === "dark"; no lowercase namespace entries.
+```
+
 ## Secure Storage
 
 ```ts
@@ -467,6 +511,33 @@ can also throw when a protected store is locked or its key is invalidated. Use
 `authentication_required`, and rebuild the affected credential for
 `key_invalidated`.
 
+Changing the access control level applies to later writes of existing items
+too: on iOS every Secure write now updates `kSecAttrAccessible` of an item that
+already exists. On iOS, `item.has()` and `storage.has(key, StorageScope.Secure)` throw
+`keychain_locked` while the keychain is locked, and a Keychain status error for
+any other unexpected status, instead of returning `false`. A biometric item that
+the Keychain reports as needing authentication counts as present, so `has()` on
+a biometric item returns `true` without a prompt; while the device is locked the
+same status also returns `true`. Listing, counting, and prefix queries on Secure
+keys throw a Keychain status error for unexpected statuses instead of returning
+an empty result. Deleting an item reads its previous value only when an event listener
+or an unredacted event observer needs it, so deleting a biometric item does not
+show a biometric prompt.
+
+Biometric behaviour differs by platform:
+
+- **iOS:** `getSecureBiometric` reads run through the Keychain with user
+  interaction allowed. The system shows the Face ID, Touch ID, or passcode sheet
+  and the synchronous JSI call blocks the JavaScript thread until the user
+  answers. Read biometric items from a user action, not during render.
+- **Android:** Nitro Storage never shows a prompt. Each biometric store is an
+  `EncryptedSharedPreferences` file whose Keystore key requires recent user
+  authentication. The key is checked only when the store is first opened in a
+  process; later reads and writes in that process use the already-decrypted
+  keyset and do not check authentication again. Run your own `BiometricPrompt`
+  before every read that must be gated. Reading a `BiometryOrPasscode` item
+  opens only that store, so a device-credential authentication is enough.
+
 ## Batch Operations
 
 `getBatch()` preserves tuple value types, so IDEs infer each result from the
@@ -506,9 +577,17 @@ removeBatch([themeItem, localeItem], StorageScope.Disk);
 ## Events And Observability
 
 ```ts
-const unsubscribe = storage.subscribeNamespace("settings", (event) => {
-  console.log(event.key, event.operation, event.source);
-});
+const unsubscribe = storage.subscribeNamespace(
+  "settings",
+  StorageScope.Disk,
+  (event) => {
+    if (event.type === "key") {
+      console.log(event.key, event.operation, event.source);
+    } else {
+      console.log(event.changes.length, event.operation, event.source);
+    }
+  },
+);
 
 storage.setEventObserver((event) => {
   console.log(event.type, event.scope);
@@ -528,9 +607,10 @@ 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`. `getCacheMetrics()` reports live
-Disk/Secure raw-cache hits, misses, entries, and estimated bytes. The cache is
-unbounded; `resetMetrics()` zeros the hit/miss counters and leaves entries in
-place.
+Disk/Secure raw-cache hits, misses, entries, and estimated bytes. Reads fill
+the cache only for items with `readCache` or `fallbackToCacheOnReadError`. The
+cache is unbounded; `resetMetrics()` zeros the hit/miss counters and leaves
+entries in place.
 
 The example app includes hidden integrity, keychain, and Disk/Secure stress
 labs at `nitrostorage://e2e-integrity`, `nitrostorage://e2e-keychain`, and
@@ -600,12 +680,19 @@ import {
 } from "react-native-nitro-storage";
 import { createIndexedDBBackend } from "react-native-nitro-storage/indexeddb-backend";
 
-const backend = await createIndexedDBBackend("app-storage", "kv");
+const diskBackend = await createIndexedDBBackend("app-storage", "disk");
+const secureBackend = await createIndexedDBBackend("app-storage", "secure");
 
-setWebDiskStorageBackend(backend);
-setWebSecureStorageBackend(backend);
+setWebDiskStorageBackend(diskBackend);
+setWebSecureStorageBackend(secureBackend);
 ```
 
+Use one backend instance per scope. If one instance is registered for both
+scopes, Disk enumeration skips Secure keys and each scope's `clear()` removes
+only its own keys, but separate stores keep the two scopes fully isolated.
+Import `createIndexedDBBackend` from the `react-native-nitro-storage/indexeddb-backend`
+subpath; the root export is deprecated.
+
 Web reads and mutations stay synchronous against the backend's in-memory
 contract; use `flushWebStorageBackends()` for asynchronous persistence
 boundaries. The native entry keeps the web backend setters, getters, and flush
@@ -614,11 +701,19 @@ function as typed no-ops for cross-platform code.
 Browser storage cannot provide iOS Keychain or Android Keystore guarantees. Web
 Secure scope is only as strong as the backend you configure.
 
+Cross-tab `storage` events update a scope only while that scope uses the
+default `localStorage` backend. Custom backends sync through their own
+`subscribe()` channel; the IndexedDB backend uses a `BroadcastChannel`.
+
 ## Testing
 
-The `react-native-nitro-storage/testing` entrypoint is a faithful in-memory
-implementation of the full public surface, so unit tests and Storybook run
-without native modules. Mock the package with it, or use it directly.
+The `react-native-nitro-storage/testing` entrypoint is an in-memory
+implementation with the same runtime exports as the main entry, so unit tests
+and Storybook run without native modules. Item subscribers and hooks re-render
+for Memory, Disk, and Secure writes. It does not model platform behaviour:
+there are no keychain locks, biometric prompts, access-control levels,
+coalesced native write timing, or web backends (the web backend functions are
+no-ops). Mock the package with it, or use it directly.
 
 ```ts
 import {
@@ -653,13 +748,23 @@ backends. The full reference lives in
 ## Error Contract
 
 Native and web adapters tag classified failures with stable error codes. Use
-`getStorageErrorCode(error)` or `isStorageError(error, code)` to branch on them:
-`keychain_locked` reports a locked Keychain that a retry can recover after
-authentication, secure-scope write or biometric failures carry their own
-codes, and invalid inputs (bad scope, malformed keys, numeric guard
-violations) are rejected before reaching native storage. Errors never swallow
-the underlying cause silently: the original platform message is preserved on
-the error for diagnostics.
+`getStorageErrorCode(error)` or `isStorageError(error, code)` to branch on them.
+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.                                                               |
+
+Invalid scopes and non-finite numeric levels are rejected with untagged errors
+before they reach native storage.
 
 ## Platform Support
 
@@ -695,8 +800,10 @@ the error for diagnostics.
   upgrading the package so the Android manifest initializer is merged.
 - **Secure values fail after Android restore:** keep `configureAndroidBackup:
 true` or provide equivalent backup exclusions.
-- **Biometric prompt does not appear:** set `biometric: true` on the item and
-  add native biometric permissions when your app needs them.
+- **Biometric prompt does not appear on Android:** this is expected. The
+  package never prompts on Android; run `BiometricPrompt` in your app before
+  reading the item, and enable `addBiometricPermissions` for that prompt. On
+  iOS, set `biometric: true` on the item and a `faceIDPermission` message.
 - **Web secure storage is unavailable:** configure a secure backend before using
   Secure scope on web.
 - **TypeScript cannot infer `getBatch()` tuple values:** pass readonly tuples

package/SECURITY.md

@@ -4,14 +4,18 @@
 
 Security fixes are shipped for the latest published `0.x` release line.
 
-| Version | Supported |
-| ------- | --------- |
-| `0.8.x` | Yes       |
-| `<0.8`  | No        |
+| Version  | Supported |
+| -------- | --------- |
+| `0.11.x` | Yes       |
+| `< 0.11` | No        |
 
 ## Reporting a Vulnerability
 
-Report security issues through GitHub Security Advisories with:
+Report security issues privately through GitHub private vulnerability reporting: https://github.com/JoaoPauloCMarra/react-native-nitro-storage/security/advisories/new
+
+Never report vulnerabilities in public issues, pull requests, or discussions.
+
+Include:
 
 - affected package version
 - platform and OS version
@@ -23,4 +27,10 @@ Do not publish proof-of-concept exploit details until a fix is available.
 
 ## Storage Boundary
 
-Native Secure scope delegates encryption to platform storage APIs: iOS Keychain and Android Jetpack Security `EncryptedSharedPreferences`. Web Secure scope is API-compatible but defaults to namespaced `localStorage`; use a custom web secure backend when browser-side storage must meet a stricter threat model.
+Memory scope keeps values in process memory only.
+
+Native Disk scope stores values unencrypted in an app-private SQLite database in WAL mode on iOS and Android. Do not store secrets in Disk scope.
+
+Native Secure scope delegates encryption to platform storage APIs: iOS Keychain and Android Jetpack Security `EncryptedSharedPreferences`.
+
+Web Disk and Secure scopes default to namespaced `localStorage`, or to the custom backend set with `setWebDiskStorageBackend` / `setWebSecureStorageBackend`. Web Secure scope is API-compatible but not encrypted by default; use a custom web secure backend when browser-side storage must meet a stricter threat model.

package/android/build.gradle

@@ -82,6 +82,5 @@ dependencies {
   //noinspection GradleDynamicVersion
   implementation "com.facebook.react:react-native:+"
   implementation "androidx.security:security-crypto:1.1.0"
-  implementation "org.jetbrains.kotlin:kotlin-stdlib:1.9.0"
   implementation project(":react-native-nitro-modules")
 }

package/android/consumer-rules.pro

@@ -7,11 +7,8 @@
     public static *** has*(...);
     public static *** clear*(...);
     public static *** size*(...);
-    public static *** flush*(...);
     public static void init(android.content.Context);
     public static void setSecureWritesAsync(boolean);
-    public static void setSecureAccessControl(int);
-    public static void removeByPrefix(java.lang.String, int);
 }
 -keep class com.nitrostorage.AndroidStorageAdapter$Companion {
     public <methods>;