react-native-nitro-storage 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -6,6 +6,22 @@ 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

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.14.0
+bun add react-native-nitro-modules@0.37.1 react-native-nitro-storage@0.15.0
 bunx expo prebuild
 ```
 
@@ -578,6 +578,190 @@ 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
@@ -759,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 {
@@ -780,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

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,50 +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()`                            | 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.                                                                                                       |
+| 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.
 
@@ -256,6 +258,12 @@ 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
 
 ```ts
@@ -319,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
@@ -348,6 +365,8 @@ enum BiometricLevel {
 Common public types:
 
 - `Storage`
+- `SecureAccessControlMigrationOptions`
+- `SecureAccessControlMigrationResult`
 - `Validator<T>`
 - `ExpirationConfig`
 - `StorageItem<T>`

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

@@ -37,8 +37,42 @@ The runner supplies a fresh UUID as `RUN_ID` to each replay. The persistence
 flow writes one `RUN_ID`-scoped Disk key, closes and relaunches the installed
 app with the same ID, compares the stored value with the expected value, and
 deletes that key. Other smoke and lab cases use reserved QA keys and clean only
-those keys. The default replay never clears a whole storage scope or the app's
-data.
+those keys. Only the final `clear-all` suite clears whole scopes.
+
+The `clear-all` suite (`e2e/qa-clear-all.ad`) seeds one reserved key in Memory,
+Disk, and Secure, then calls `storage.clearAll()`. This wipes all example
+storage in every scope on the target install, not only QA keys. It is the last
+suite in the manifest, and the runner passes suites to `agent-device test` in
+manifest order, so it runs after every other suite. Run it only on a disposable
+example install. Use `--flow` to skip it when the install holds data you need.
+
+The `api-extended` suite (`e2e/qa-api-extended.ad`) opens a run-on-load screen
+and asserts its results through the on-screen `e2e-ext-results` label, which
+joins one `;`-terminated token per check. It covers item `merge` and
+`setOrDelete`, Set `toggle` and `values`, `clearGroup`, TTL `onExpired` and
+`subscribeExpired`, Secure metadata and export inventory, default access
+control, coalesced Secure writes, the `invalid_key` error, scoped metrics,
+native Disk key events, the React hooks, and `createSecureAuthStorage` TTL. It
+uses reserved `__e2e_ext_`, `__e2e_inv_`, and `__e2e_auth` keys and restores the
+default access control to `WhenUnlocked` after each access-control check. Its
+passcode access-control row is a gating probe for later iOS biometric work: the
+flow asserts only that a `passcode-acl=` result rendered. A device without a
+passcode can reject that write, and the row is not a pass for passcode-protected
+storage.
+
+The `biometric-ios` suite (`e2e/qa-biometric-ios.ad`) runs only with
+`--platform ios`; its manifest entry sets `platforms: ["ios"]`, the runner skips
+it for Android, and `--flow biometric-ios` with `--platform android` fails before
+any device command. It enrolls simulator Face ID, opens the run-on-load
+`e2e-biometric` route with `RUN_ID`, and writes one `__e2e_bio_<RUN_ID>` item
+with `biometric: true` and the default level. The `e2e-biometric-results` label
+then shows the seed and metadata tokens and `bio:read=prompting;`. After a fixed
+1500 ms wait, `settings faceid match` resolves the blocked read, and the flow
+expects `bio:read=value-matched;` and `bio:cleanup=missing;` before it unenrolls
+Face ID. Cleanup calls `storage.clearBiometric()`, which removes every
+biometric Secure item in the example install. This is simulator evidence only,
+not Secure Enclave hardware evidence. Android biometrics and iOS nonmatch or
+cancel outcomes remain pending.
 
 Each run uses a unique session and an artifact directory under the OS temporary
 directory. `agent-device test` closes each attempt session itself, including
@@ -50,7 +84,8 @@ itself is not sufficient. Smoke and integrity rows are asserted through the
 on-screen `smoke-results` and `e2e-integrity-results` labels because
 agent-device `.ad` waits only see on-screen elements. The keychain suite runs one no-prompt Secure
 roundtrip and keeps biometric, lock, corruption, and hardware-backed checks
-explicitly pending. The smoke test's constructed `storage_full` error is read
+explicitly pending; only the iOS simulator Face ID match path is asserted, by
+`biometric-ios`. The smoke test's constructed `storage_full` error is read
 through the public `/testing` entrypoint; it proves error-code classification
 at that test adapter boundary only.
 
@@ -62,8 +97,9 @@ Disk, and Secure.
 
 Native replay rows identify the public runtime platform and backend capability,
 then assert values returned through the default package entrypoint. This
-supports installed-app Disk and Secure behavior claims for that target. It does
-not prove hardware-backed keys, biometrics, locked-device behavior, corruption
+supports installed-app Disk and Secure behavior claims for that target. Apart
+from the iOS simulator Face ID match in `biometric-ios`, it does not prove
+hardware-backed keys, biometrics, locked-device behavior, corruption
 recovery, or a native Disk/Secure write failure. Those checks need controlled
 native or hardware prerequisites and remain pending in the coverage manifest.
 Unit tests for an injected adapter boundary are useful logic evidence, but they

package/ios/IOSStorageAdapterCpp.hpp

@@ -2,6 +2,9 @@
 
 #include "../core/NativeStorageAdapter.hpp"
 #include <atomic>
+#include <functional>
+#include <optional>
+#include <memory>
 #include <mutex>
 #include <unordered_set>
 
@@ -9,7 +12,10 @@ namespace NitroStorage {
 
 class IOSStorageAdapterCpp : public NativeStorageAdapter {
 public:
+    using ProtectedDataReader = std::function<std::optional<bool>()>;
+
     IOSStorageAdapterCpp();
+    explicit IOSStorageAdapterCpp(ProtectedDataReader protectedDataReader);
     ~IOSStorageAdapterCpp() override;
     
     void setDisk(const std::string& key, const std::string& value) override;
@@ -48,7 +54,13 @@ public:
     bool hasSecureBiometric(const std::string& key) override;
     void clearSecureBiometric() override;
 
+    bool isProtectedDataAvailable() override;
+    std::function<void()> addProtectedDataAvailableListener(std::function<void()> listener) override;
+
 private:
+    struct ProtectedDataState;
+    std::shared_ptr<ProtectedDataState> protectedData_;
+
     int accessControlLevel_ = 0;
     std::string keychainAccessGroup_;
     mutable std::mutex secureKeysMutex_;