react-native-nitro-storage 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -6,6 +6,37 @@ 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.15.0] - 2026-10-07
+
+### Breaking changes
+
+None.
+
+### Added
+
+- `migrateSecureAccessControl(level, options?)` sets the default Secure access control level and rewrites existing Secure items so each iOS Keychain item moves to that accessibility class. It reads each stored string and writes it back unchanged, and it never deletes a value. It returns `{ migrated, locked, missing, skipped, failed, enumerationLocked }`: a key whose read or write fails with `keychain_locked` stays untouched and is listed in `locked`; other failures are listed in `failed` with their error code; biometric-protected items, including a key whose biometric check is `keychain_locked`, are listed in `skipped` and are not read. It first runs `flushSecureWrites()`. When that flush or the listing of the Secure keys fails with `keychain_locked`, nothing changes, including the default level, and `enumerationLocked` is `true`; any other listing error is thrown with state unchanged. `options.keys` limits the keys to rewrite. On Android and web it validates the level, records the default, and lists every Secure key in `skipped`. Each rewrite emits a change event with an unchanged value. It runs in JavaScript on the existing native surface, so it works with a 0.14 native binary.
+- `storage.isProtectedDataAvailable()` reports whether iOS protected data is available, from a cached value that is never read on the calling thread. The state starts unknown and unknown reports `false`; the first read on the main thread usually lands within milliseconds and fires the listeners when data is available. A cold background launch inside the lock grace window can read `true` until the app next becomes active, so treat `keychain_locked` and the success of the actual read as the source of truth in background-only code. The value is re-read when the app becomes active or enters the foreground. `storage.onProtectedDataAvailable(listener)` calls `listener` each time protected data becomes available again and returns an unsubscribe function. In an iOS app extension, where `UIApplication` is unavailable, the value is `true`. On Android and web the value is always `true` and the listener never fires. Both need the 0.15.0 native module: rebuild the app. On an older native binary `isProtectedDataAvailable()` returns `true` and `onProtectedDataAvailable` returns a no-op unsubscribe instead of throwing. Both are also on the `react-native-nitro-storage/testing` entry, where availability is `true` until `setMockProtectedDataAvailable(false)` simulates a locked device (`true` fires the listeners; `resetNitroStorageMock()` restores `true` and drops every `onProtectedDataAvailable` listener).
+- New exported types: `SecureAccessControlMigrationOptions` and `SecureAccessControlMigrationResult`.
+
+### Documentation
+
+- README explains the `setAccessControl` lifecycle (per process, call before the first Secure write, writes only, no effect on Android), when to run `migrateSecureAccessControl`, the protected-data APIs, and how to avoid `keychain_locked` by deferring Secure reads until protected data is available rather than weakening the access class. It compares `AfterFirstUnlock` and `AfterFirstUnlockThisDeviceOnly`, including backup and device-transfer behavior, and notes that raw `storage.getString` has no `fallbackToCacheOnReadError`. It warns that an app extension sharing the Keychain access group can race the read-then-rewrite in `migrateSecureAccessControl`; run it while extensions are idle.
+
+## [0.14.0] - 2026-10-03
+
+### Breaking changes
+
+- Transaction and migration callbacks must finish synchronously. Promise and thenable results now throw `TypeError`, roll back writes made through the transaction context, and leave migration versions unchanged. Context methods reject calls after the callback ends. Migration: finish asynchronous work before entering the callback and keep all context access inside it. TypeScript now rejects direct async callbacks.
+
+### Added
+
+- `storage.setScheduledFlushErrorObserver()` reports scheduled Disk and Secure flush failures with their scope and backend adapter error. Failed writes stay queued for retry. Explicit flush calls still throw to their caller, and scheduled failures still propagate when no observer is installed.
+
+### Documentation
+
+- `flushSecureWrites()` drains the JavaScript queue; it is not an Android `apply()` durability barrier. Select synchronous secure-write mode before writes that need synchronous native persistence.
+- Biometric policy documentation now distinguishes iOS Keychain prompts from Android authentication when a protected store first opens and its cached keyset on later access.
+
 ## [0.13.0] - 2026-10-01
 
 ### Breaking changes

package/README.md

@@ -68,7 +68,7 @@ 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` |
+| React Native `0.86.3` / Expo SDK `57.0.27` | 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
@@ -82,7 +82,7 @@ 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.26`, React Native
+example uses Expo SDK `57.0.27`, 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.
 
@@ -91,7 +91,7 @@ before installing this package, then rebuild the native app so the generated
 Nitro bindings and native runtime use the same major-minor version:
 
 ```sh
-bun add react-native-nitro-modules@0.37.1 react-native-nitro-storage@0.13.0
+bun add react-native-nitro-modules@0.37.1 react-native-nitro-storage@0.15.0
 bunx expo prebuild
 ```
 
@@ -491,9 +491,12 @@ explicitly opt into `{ includeSecureValues: true }`.
 
 Android secure writes default to synchronous `commit()` durability. Call
 `storage.setSecureWritesAsync(true)` only when asynchronous `apply()` writes are
-acceptable. After opting into async writes, call `storage.flushSecureWrites()`
-before a deterministic persistence boundary. A failed secure flush throws and
-keeps failed or unattempted queued writes available for retry.
+acceptable. `storage.flushSecureWrites()` drains the JavaScript write queue into
+the native backend; it does not wait for Android `apply()` to reach disk. Keep
+the default synchronous mode, or call `storage.setSecureWritesAsync(false)`
+before the writes that need synchronous native persistence. Changing the mode
+does not make earlier `apply()` calls durable retroactively. A failed explicit
+flush throws and keeps failed or unattempted queued writes available for retry.
 `storage.clearBiometric()`
 flushes pending Secure writes before clearing biometric entries and surfaces
 native clear failures.
@@ -538,6 +541,227 @@ Biometric behaviour differs by platform:
   before every read that must be gated. Reading a `BiometryOrPasscode` item
   opens only that store, so a device-credential authentication is enough.
 
+Scheduled Disk and Secure flush failures can be handled without losing the
+pending writes:
+
+```ts
+import {
+  storage,
+  type StorageScheduledFlushError,
+} from "react-native-nitro-storage";
+
+let lastFlushFailure: StorageScheduledFlushError | undefined;
+storage.setScheduledFlushErrorObserver((failure) => {
+  lastFlushFailure = failure;
+});
+
+// Call after resolving the failure, such as freeing space or unlocking storage.
+function retryPendingWrites() {
+  storage.flushDiskWrites();
+  storage.flushSecureWrites();
+  lastFlushFailure = undefined;
+}
+
+// Remove the observer when its owner is disposed.
+function stopObservingFlushErrors() {
+  storage.setScheduledFlushErrorObserver(undefined);
+}
+```
+
+The observer receives the failed scope and the error thrown by the backend
+adapter. Web adapters may wrap the underlying failure in an error with `cause`.
+It replaces
+the uncaught scheduled-flush error only while installed; without an observer,
+the error still propagates. Explicit flush calls always throw to their caller,
+and an observer that throws also propagates its error. Register one observer per
+storage instance and handle retry failures at the calling boundary. The observer
+reports the synchronous backend handoff; it cannot report a later Android
+`apply()` or IndexedDB persistence failure that the backend does not expose.
+
+### Access Control Lifecycle
+
+`storage.setAccessControl(level)` sets the default `AccessControl` for Secure
+writes. Follow these rules:
+
+- It is per process and is not persisted. Call it on every launch, before the
+  first Secure write, for example at module scope in your app entry.
+- It affects writes only. Reads never use the level, and an existing Keychain
+  item keeps its accessibility class until it is written again. On iOS every
+  Secure write, including an update of an existing item, sets
+  `kSecAttrAccessible`, so a rewrite moves the item to the current level.
+- An item created with its own `accessControl` option uses that level instead
+  of the default.
+- Android has no Keychain accessibility classes. `setAccessControl` only records
+  the JavaScript default there and changes no native behavior.
+- Raw `storage.setString(key, value, StorageScope.Secure)` writes use the same
+  default level.
+
+```ts
+import { AccessControl, storage } from "react-native-nitro-storage";
+
+storage.setAccessControl(AccessControl.AfterFirstUnlockThisDeviceOnly);
+```
+
+### Migrating Existing Secure Items
+
+Items written under `WhenUnlocked` stay unreadable while the device is locked,
+even after you change the default. `migrateSecureAccessControl(level, options?)`
+sets `level` as the default and rewrites each Secure item so the Keychain item
+gets the new class. It reads the stored string and writes the same string back,
+so values are never decoded, changed, or deleted.
+
+```ts
+import {
+  AccessControl,
+  migrateSecureAccessControl,
+} from "react-native-nitro-storage";
+
+const result = migrateSecureAccessControl(
+  AccessControl.AfterFirstUnlockThisDeviceOnly,
+);
+// { migrated: string[]; locked: string[]; missing: string[];
+//   skipped: string[]; failed: { key: string; code?: StorageErrorCode }[];
+//   enumerationLocked: boolean }
+
+if (result.locked.length > 0) {
+  // Retry only the locked keys once protected data is available.
+  migrateSecureAccessControl(AccessControl.AfterFirstUnlockThisDeviceOnly, {
+    keys: result.locked,
+  });
+}
+```
+
+- Run it while the device is unlocked, for example from a foreground user
+  action or after `storage.isProtectedDataAvailable()` returns `true`. Reading
+  or rewriting a `WhenUnlocked` item while locked fails with `keychain_locked`.
+- It first runs `flushSecureWrites()` so queued Secure writes land before the
+  rewrite, then (without `options.keys`) lists the Secure keys. If the flush or
+  the listing fails with `keychain_locked`, it changes nothing, including the
+  default level, and returns `enumerationLocked: true` with empty lists (the
+  queued writes stay queued). Call it again once
+  protected data is available. Any other listing error is thrown and also
+  leaves the default level unchanged.
+- A key whose read or write fails with `keychain_locked` is left unchanged and
+  listed in `locked`. Any other error leaves the key unchanged and lists it in
+  `failed` with its error code. The helper never deletes data.
+- `options.keys` limits the work to specific keys. Without it, every Secure key
+  is processed. Biometric-protected items are listed in `skipped` and are never
+  read, because reading them can show a biometric prompt. A key whose biometric
+  check fails with `keychain_locked` is also listed in `skipped`, not `locked`:
+  biometric items are never migrated.
+- The level becomes the default for later writes even when a key fails, so new
+  writes already use it.
+- Items that you configured with their own `accessControl` option are rewritten
+  with `level` too. Pass `options.keys` to leave them out.
+- On Android and web there is no accessibility class to change. The helper
+  validates the level, records the default, reads and writes nothing, and lists
+  every Secure key in `skipped`.
+- Each rewrite is a native write, so storage listeners and observers receive a
+  change event for every migrated key, even though the value is unchanged.
+- It reads each key and writes it back as separate steps. An app extension that
+  shares the Keychain access group and writes the same key between the two steps
+  can lose that write. Run the migration while extensions are idle.
+- `migrateSecureAccessControl` is JavaScript only and works with any
+  0.14-compatible native module. The protected-data APIs below need the 0.15.0
+  native module.
+- Its result has `enumerationLocked: boolean` besides the key lists.
+
+### Protected Data Availability
+
+On iOS, Keychain items in the `WhenUnlocked` classes (`WhenUnlocked`,
+`WhenUnlockedThisDeviceOnly`, and `WhenPasscodeSetThisDeviceOnly`) can be read
+only while protected data is available. Use these APIs to
+wait instead of catching `keychain_locked`:
+
+```ts
+import { storage } from "react-native-nitro-storage";
+
+const available: boolean = storage.isProtectedDataAvailable();
+
+const unsubscribe = storage.onProtectedDataAvailable(() => {
+  // Protected data became available again.
+});
+unsubscribe();
+```
+
+- `isProtectedDataAvailable()` returns a cached value and never blocks. The
+  state starts unknown, and unknown reports `false`, so a locked device is never
+  reported as open. The first value is read from `UIApplication` on the main
+  thread: synchronously when the native module is created on the main thread,
+  otherwise asynchronously on the main queue, usually within a few
+  milliseconds. Until then the first calls can report `false` even when data is
+  available. When the read finds protected data available, listeners fire, so
+  gate on `onProtectedDataAvailable` instead of treating an early `false` as
+  final. iOS keeps the value current from the
+  `UIApplicationProtectedDataDidBecomeAvailable` and
+  `UIApplicationProtectedDataWillBecomeUnavailable` notifications, and
+  re-reads `UIApplication` when the app becomes active or enters the
+  foreground, because the available notification is not guaranteed when the
+  user unlocks inside the short window before protected data drops.
+- Residual cases. A cold background launch that happens inside the grace
+  window after the device locks reads `true` until the app next becomes active,
+  because `UIApplication` still reports available during that window. A
+  background-only consumer can also keep a `false` cache after an unlock inside
+  the grace window until the next foreground. Treat `keychain_locked` and the
+  success of the actual read as the source of truth, not the cached value.
+  Before `UIApplication` exists (before `UIApplicationMain`), the state stays
+  unknown and reports `false` until the app becomes active.
+- `onProtectedDataAvailable(listener)` calls `listener` each time protected data
+  changes from unavailable or unknown to available, and returns an unsubscribe
+  function. It does not call the listener on subscribe. Subscribe first, then
+  check `isProtectedDataAvailable()`, so a change between the two calls is not
+  missed.
+- Both functions need the 0.15.0 native module. On an older native binary,
+  `isProtectedDataAvailable()` returns `true` and `onProtectedDataAvailable`
+  returns a no-op unsubscribe. Rebuild the app to get real values.
+- In an iOS app extension `UIApplication` is not available. The module cannot
+  read the state there, so `isProtectedDataAvailable()` returns `true` and
+  `keychain_locked` remains the signal.
+- Android and web always return `true`, and the listener never fires.
+
+### Handling keychain_locked
+
+When a production app sees `keychain_locked` because Secure reads run while the
+device is locked, for example during a background launch, defer those reads
+until protected data is available. This keeps the default `WhenUnlocked`
+protection.
+
+```ts
+import { storage } from "react-native-nitro-storage";
+
+export function whenProtectedDataAvailable(run: () => void): () => void {
+  let done = false;
+  const runOnce = () => {
+    if (done) return;
+    done = true;
+    unsubscribe();
+    run();
+  };
+  const unsubscribe = storage.onProtectedDataAvailable(runOnce);
+  if (storage.isProtectedDataAvailable()) runOnce();
+  return unsubscribe;
+}
+```
+
+Moving items to `AfterFirstUnlock` or `AfterFirstUnlockThisDeviceOnly` removes
+the lock failure after the first unlock following a restart, but it weakens
+protection: the items stay readable while the device is locked. Choose the
+`ThisDeviceOnly` variant when items must not leave the device:
+
+| Level                            | Readable while locked after first unlock | Included in backups and device transfer |
+| -------------------------------- | ---------------------------------------- | --------------------------------------- |
+| `WhenUnlocked`                   | No                                       | Yes                                     |
+| `AfterFirstUnlock`               | Yes                                      | Yes                                     |
+| `AfterFirstUnlockThisDeviceOnly` | Yes                                      | No                                      |
+
+Items in a `ThisDeviceOnly` class are not restored onto a new device from a
+backup or device transfer, so the user must sign in again there.
+
+Raw `storage.getString(key, StorageScope.Secure)` has no
+`fallbackToCacheOnReadError`. It throws `keychain_locked` while the Keychain is
+locked. Only typed items created with `fallbackToCacheOnReadError: true` return
+their last cached value for that error.
+
 ## Batch Operations
 
 `getBatch()` preserves tuple value types, so IDEs infer each result from the
@@ -666,10 +890,16 @@ migrateFromMMKV(mmkvInstance, themeItem);
 
 `runTransaction(scope, callback)` rolls back every write made through the `tx`
 context if the callback throws, then emits one typed `rollback` batch event.
+Callbacks must be synchronous. A Promise or thenable return throws a `TypeError`
+and rolls back changes made through the context. Every context method becomes
+unavailable when the callback ends, including for a continuation after `await`.
+Complete asynchronous work before calling `runTransaction()` or registering a
+migration; do not retain the context outside its callback.
 
 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.
+An asynchronous migration is rejected without advancing its version marker.
 
 ## Web Backends
 
@@ -713,7 +943,10 @@ 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.
+no-ops). Mock the package with it, or use it directly. To simulate a locked
+device, call `setMockProtectedDataAvailable(false)`; `true` fires the
+`onProtectedDataAvailable` listeners, and `resetNitroStorageMock()` restores
+`true` and drops every `onProtectedDataAvailable` listener.
 
 ```ts
 import {
@@ -734,6 +967,18 @@ beforeEach(() => {
 const { storage, memoryItem } = createNitroStorageMock();
 ```
 
+```ts
+import {
+  setMockProtectedDataAvailable,
+  storage,
+} from "react-native-nitro-storage/testing";
+
+const stop = storage.onProtectedDataAvailable(() => loadSession());
+setMockProtectedDataAvailable(false); // storage.isProtectedDataAvailable() === false
+setMockProtectedDataAvailable(true); // listener fires once
+stop();
+```
+
 ## API
 
 The package exposes named `storage`, `createStorageItem`, the scoped item
@@ -850,6 +1095,7 @@ in a host measurement; devices are slower). Keep single Disk values below about
 | Native libraries                    | [docs/native-libraries.md](docs/native-libraries.md)                           |
 | Recipes                             | [docs/recipes.md](docs/recipes.md)                                             |
 | Benchmarks                          | [docs/benchmarks.md](docs/benchmarks.md)                                       |
+| Example replay coverage             | [docs/qa/agent-device-replay.md](docs/qa/agent-device-replay.md)               |
 | Security policy                     | [SECURITY.md](SECURITY.md)                                                     |
 
 ## Troubleshooting
@@ -887,6 +1133,13 @@ Nitro, secure storage, or packaging files. GitHub CI does not build the Android
 or iOS example. The package release path also validates package contents and
 dry-run publish behavior.
 
+Run `bun run example:replay:check` to check that replay coverage matches package
+and example sources. After reviewing affected assertions, use
+`bun run example:replay:refresh` to update the source lock. Device execution uses
+`bun run example:replay --platform ios --udid <exact-target>` or
+`--platform android --serial <exact-target>`; see the
+[replay guide](docs/qa/agent-device-replay.md) for prerequisites and coverage limits.
+
 `bun run benchmark` measures only the built web entry with an isolated private
 localStorage implementation; it is not a native Disk or Secure benchmark. See
 [docs/benchmarks.md](docs/benchmarks.md) for sampling and interpretation limits.

package/cpp/bindings/HybridStorage.cpp

@@ -535,6 +535,27 @@ void HybridStorage::clearSecureBiometric() {
     notifyListeners(static_cast<int>(Scope::Secure), kClearSentinelKey, std::nullopt);
 }
 
+bool HybridStorage::isProtectedDataAvailable() {
+    ensureAdapter();
+    return runAdapterOperation(
+        [&] { return nativeAdapter_->isProtectedDataAvailable(); },
+        "Protected data availability");
+}
+
+std::function<void()> HybridStorage::onProtectedDataAvailable(const std::function<void()>& listener) {
+    ensureAdapter();
+    return runAdapterOperation(
+        [&] {
+            return nativeAdapter_->addProtectedDataAvailableListener([listener]() {
+                try {
+                    listener();
+                } catch (...) {
+                }
+            });
+        },
+        "Protected data subscription");
+}
+
 // --- Internal ---
 
 std::vector<HybridStorage::Listener> HybridStorage::copyListenersForScope(int scope) {

package/cpp/bindings/HybridStorage.hpp

@@ -56,6 +56,8 @@ public:
     void deleteSecureBiometric(const std::string& key) override;
     bool hasSecureBiometric(const std::string& key) override;
     void clearSecureBiometric() override;
+    bool isProtectedDataAvailable() override;
+    std::function<void()> onProtectedDataAvailable(const std::function<void()>& listener) override;
 
 private:
     enum class Scope {

package/cpp/core/NativeStorageAdapter.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
 #include <cstddef>
+#include <functional>
 #include <optional>
 #include <stdexcept>
 #include <string>
@@ -58,6 +59,11 @@ public:
     virtual void deleteSecureBiometric(const std::string& key) = 0;
     virtual bool hasSecureBiometric(const std::string& key) = 0;
     virtual void clearSecureBiometric() = 0;
+
+    virtual bool isProtectedDataAvailable() { return true; }
+    virtual std::function<void()> addProtectedDataAvailableListener(std::function<void()>) {
+        return []() {};
+    }
 };
 
 } // namespace NitroStorage

package/docs/api-reference.md

@@ -112,49 +112,52 @@ 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.                                                                                                                   |
+| `isProtectedDataAvailable()`                     | Read cached iOS protected-data availability; may report `false` briefly until the first read lands. Android, web, and 0.14 native binaries return `true`.      |
+| `onProtectedDataAvailable(listener)`             | Call `listener` when protected data becomes available (including the first known-available read); returns an unsubscribe function. Android and web never fire. |
+| `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 +237,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 +255,14 @@ 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 Access Control Migration
+
+| API                                           | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `migrateSecureAccessControl(level, options?)` | Set the default Secure access control level and rewrite each Secure item so its iOS Keychain item moves to that class. Returns `{ migrated, locked, missing, skipped, failed, enumerationLocked }`. It runs `flushSecureWrites()` first. `enumerationLocked: true` means that flush or listing the Secure keys failed with `keychain_locked`: nothing was changed, including the default level, and queued writes stay queued; retry later. Other enumeration errors are thrown with state unchanged. `options.keys` limits the keys. JavaScript only; Android and web record the default and list every key in `skipped`. |
 
 ## Secure Auth Storage
 
@@ -313,6 +327,15 @@ function as typed no-ops for shared code.
 
 See [web-backends.md](web-backends.md).
 
+## Testing Entry
+
+`react-native-nitro-storage/testing` exports an in-memory implementation of the public surface.
+
+| API                                        | Description                                                                                                                                                                                                |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `setMockProtectedDataAvailable(available)` | Set the mock protected-data availability (default `true`). `false` simulates a locked device; `true` after `false` fires the `onProtectedDataAvailable` listeners. Throws a `TypeError` for a non-boolean. |
+| `resetNitroStorageMock()`                  | Clear all mock data and observers, restore protected-data availability to `true`, and drop every `onProtectedDataAvailable` listener.                                                                      |
+
 ## Enums
 
 ```ts
@@ -342,6 +365,8 @@ enum BiometricLevel {
 Common public types:
 
 - `Storage`
+- `SecureAccessControlMigrationOptions`
+- `SecureAccessControlMigrationResult`
 - `Validator<T>`
 - `ExpirationConfig`
 - `StorageItem<T>`

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) => {