react-native-nitro-storage 0.5.4 → 0.5.6

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/react-native-nitro-storage)](https://www.npmjs.com/package/react-native-nitro-storage)
 [![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![React Native](https://img.shields.io/badge/react--native-%3E%3D0.75-61dafb)](https://reactnative.dev/)
-[![Nitro Modules](https://img.shields.io/badge/nitro--modules-%3E%3D0.35.5-black)](https://nitro.margelo.com/)
+[![Nitro Modules](https://img.shields.io/badge/nitro--modules-%3E%3D0.35.7-black)](https://nitro.margelo.com/)
 
 One storage layer for render-time state, persisted app state, and native secrets.
 
@@ -20,6 +20,7 @@ Use it when you want one storage API for React Native and web, with fast synchro
 - [Quick Start](#quick-start)
 - [Storage Scopes](#storage-scopes)
 - [Docs](#docs)
+- [TypeScript And IDE Safety](#typescript-and-ide-safety)
 - [Platform Support](#platform-support)
 - [Security Model](#security-model)
 - [Migration Paths](#migration-paths)
@@ -83,7 +84,8 @@ bunx expo install react-native-nitro-storage react-native-nitro-modules
         "react-native-nitro-storage",
         {
           "faceIDPermission": "Allow $(PRODUCT_NAME) to protect your secure data with Face ID",
-          "addBiometricPermissions": true
+          "addBiometricPermissions": true,
+          "configureAndroidBackup": true
         }
       ]
     ]
@@ -95,7 +97,9 @@ bunx expo install react-native-nitro-storage react-native-nitro-modules
 bunx expo prebuild
 ```
 
-The Expo plugin sets `NSFaceIDUsageDescription`, can opt into Android biometric permissions, and initializes the Android storage adapter in `MainApplication`.
+The example project is aligned with Expo SDK 56, React Native 0.85, and React 19.2.
+
+The Expo plugin sets `NSFaceIDUsageDescription`, can opt into Android biometric permissions, initializes the Android storage adapter in `MainApplication`, and writes Android backup rules that exclude Nitro Storage secure preference files from cloud backup and device transfer. Set `configureAndroidBackup: false` only when you maintain equivalent backup rules yourself.
 
 Bare React Native projects should install pods after adding the package:
 
@@ -122,18 +126,21 @@ Create storage items outside React render functions, then use them from anywhere
 import {
   createStorageItem,
   StorageScope,
+  type StorageItemConfig,
   useStorage,
 } from "react-native-nitro-storage";
 
 type Theme = "system" | "light" | "dark";
 
-export const themeItem = createStorageItem<Theme>({
+const themeConfig = {
   key: "theme",
   scope: StorageScope.Disk,
   defaultValue: "system",
   validate: (value): value is Theme =>
     value === "system" || value === "light" || value === "dark",
-});
+} satisfies StorageItemConfig<Theme>;
+
+export const themeItem = createStorageItem(themeConfig);
 
 export function ThemeButton() {
   const [theme, setTheme] = useStorage(themeItem);
@@ -199,7 +206,7 @@ const snapshot = storage.export(StorageScope.Disk);
 storage.import(snapshot, StorageScope.Disk);
 ```
 
-`storage.export(StorageScope.Secure)` returns raw secret values. Do not log Secure exports or include them in diagnostics, analytics, crash reports, or support bundles.
+`storage.export(StorageScope.Secure)` throws unless you pass `{ includeSecureValues: true }`. Prefer `storage.exportSecureUnsafe()` only for short-lived in-memory secure migration workflows. Do not log Secure exports or include them in diagnostics, analytics, crash reports, or support bundles.
 
 Subscribe to storage changes outside React:
 
@@ -284,6 +291,60 @@ The main building blocks are:
 
 See the full [API reference](docs/api-reference.md).
 
+## TypeScript And IDE Safety
+
+The public API is designed around typed storage items. Define the value type, default value, serializer, parser, and validator in one place so reads, writes, React hooks, batch APIs, migrations, and transactions all share the same contract.
+
+```ts
+import {
+  StorageScope,
+  createStorageItem,
+  type StorageItemConfig,
+} from "react-native-nitro-storage";
+
+type Preferences = {
+  theme: "system" | "light" | "dark";
+  compactMode: boolean;
+};
+
+function isPreferences(value: unknown): value is Preferences {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const candidate = value as Partial<Preferences>;
+  return (
+    (candidate.theme === "system" ||
+      candidate.theme === "light" ||
+      candidate.theme === "dark") &&
+    typeof candidate.compactMode === "boolean"
+  );
+}
+
+const preferencesConfig = {
+  key: "preferences",
+  scope: StorageScope.Disk,
+  defaultValue: { theme: "system", compactMode: false },
+  validate: isPreferences,
+} satisfies StorageItemConfig<Preferences>;
+
+const preferencesItem = createStorageItem(preferencesConfig);
+
+preferencesItem.set((current) => ({
+  ...current,
+  compactMode: !current.compactMode,
+}));
+```
+
+For web backend overrides, import the backend contracts instead of using loose object shapes:
+
+```ts
+import type {
+  WebDiskStorageBackend,
+  WebSecureStorageBackend,
+} from "react-native-nitro-storage";
+```
+
 ## Platform Support
 
 | Platform | Status    | Notes                                                                                                  |
@@ -293,11 +354,23 @@ See the full [API reference](docs/api-reference.md).
 | Expo     | Supported | Add the included config plugin before prebuild.                                                        |
 | Web      | Supported | Defaults to localStorage-style backends; IndexedDB backend is available for persistent Secure storage. |
 
+Tested release matrix:
+
+| Surface       | Version |
+| ------------- | ------- |
+| Expo example  | SDK 56  |
+| React Native  | 0.85.3  |
+| React         | 19.2.3  |
+| Nitro Modules | 0.35.7  |
+| TypeScript    | 6.0.3   |
+
+The iOS example build requires Xcode 26 or newer. GitHub Actions should use the `macos-26` runner image for SDK 56 iOS build validation.
+
 Peer dependencies:
 
 - `react >=18.2.0`
 - `react-native >=0.75.0`
-- `react-native-nitro-modules >=0.35.5`
+- `react-native-nitro-modules >=0.35.7`
 
 ## Security Model
 
@@ -390,6 +463,11 @@ bun run test -- --filter=react-native-nitro-storage
 bun run test:coverage -- --filter=react-native-nitro-storage
 bun run test:cpp -- --filter=react-native-nitro-storage
 bun run test:cpp:coverage -- --filter=react-native-nitro-storage
+bun run example:doctor
+bun run example:typecheck
+bun run example:prebuild:clean
+bun run example:android:assemble
+bun run example:ios:build
 (cd packages/react-native-nitro-storage && bun run check:pack)
 bun run publish-package:dry -- --yes --with-coverage
 ```
@@ -414,6 +492,11 @@ Release checks:
 ```sh
 bun run build -- --filter=react-native-nitro-storage
 bun run benchmark -- --filter=react-native-nitro-storage
+bun run example:doctor
+bun run example:typecheck
+bun run example:prebuild:clean
+bun run example:android:assemble
+bun run example:ios:build
 (cd packages/react-native-nitro-storage && bun run check:pack)
 bun run publish-package:dry -- --yes
 ```

package/android/build.gradle

@@ -28,10 +28,10 @@ def getExtOrIntegerDefault(name) {
 }
 
 android {
-  namespace "com.nitrostorage"
+  namespace = "com.nitrostorage"
 
   // Use values from root project or defaults
-  ndkVersion getExtOrDefault("ndkVersion")
+  ndkVersion = getExtOrDefault("ndkVersion")
   compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
 
   defaultConfig {
@@ -55,8 +55,8 @@ android {
   }
 
   buildFeatures {
-    buildConfig true
-    prefab true
+    buildConfig = true
+    prefab = true
   }
 
   compileOptions {
@@ -79,7 +79,7 @@ repositories {
 dependencies {
   //noinspection GradleDynamicVersion
   implementation "com.facebook.react:react-native:+"
-  implementation "androidx.security:security-crypto:1.1.0-alpha06"
+  implementation "androidx.security:security-crypto:1.1.0"
   implementation "org.jetbrains.kotlin:kotlin-stdlib:1.9.0"
   implementation project(":react-native-nitro-modules")
 }

package/android/src/main/java/com/nitrostorage/AndroidStorageAdapter.kt

@@ -1,10 +1,11 @@
+@file:Suppress("DEPRECATION")
+
 package com.nitrostorage
 
 import android.content.Context
 import android.security.keystore.KeyPermanentlyInvalidatedException
 import android.security.keystore.UserNotAuthenticatedException
 import android.content.SharedPreferences
-import android.util.Log
 import androidx.security.crypto.EncryptedSharedPreferences
 import androidx.security.crypto.MasterKey
 import java.security.InvalidKeyException
@@ -71,7 +72,6 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
                 .build()
             initializeEncryptedPreferences("NitroStorageBiometric", bioKey)
         } catch (e: Exception) {
-            Log.e("NitroStorage", "Biometric storage unavailable: ${e.message}")
             throw e.wrapStorageException(
                 "NitroStorage: Biometric storage is not available on this device. " +
                     "Ensure biometric hardware is present and credentials are enrolled.",
@@ -96,7 +96,6 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         } catch (e: Exception) {
             when {
                 e.hasCause(AEADBadTagException::class.java) -> {
-                    Log.w("NitroStorage", "Corrupted encryption keys for $name, attempting recovery...")
                     clearCorruptedStorage(name, key)
                     val freshAlias = if (name == "NitroStorageBiometric") biometricMasterKeyAlias else masterKeyAlias
                     val freshKey = MasterKey.Builder(context, freshAlias)
@@ -142,9 +141,7 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
                 else -> masterKeyAlias
             }
             keyStore.deleteEntry(alias)
-            Log.i("NitroStorage", "Cleared corrupted storage: $name")
-        } catch (e: Exception) {
-            Log.e("NitroStorage", "Failed to clear corrupted storage $name: ${e.message}", e)
+        } catch (_: Exception) {
         }
     }
 
@@ -153,7 +150,6 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
             prefs.getString(key, null)
         } catch (e: Exception) {
             if (e.hasCause(AEADBadTagException::class.java)) {
-                Log.w("NitroStorage", "Corrupt entry for key '$key', removing")
                 prefs.edit().remove(key).commit()
                 null
             } else {
@@ -198,8 +194,7 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
             keys.addAll(encryptedPreferences.all.keys.filter { !it.startsWith(INTERNAL_PREFIX) })
             try {
                 keys.addAll(biometricPreferences.all.keys.filter { !it.startsWith(INTERNAL_PREFIX) })
-            } catch (e: Exception) {
-                Log.d("NitroStorage", "Biometric storage unavailable: ${e.message}")
+            } catch (_: Exception) {
             }
             val built = keys.toTypedArray()
             secureKeysCache = built
@@ -369,8 +364,7 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
                 inst.applySecureEditor(inst.encryptedPreferences.edit().remove(key))
                 try {
                     inst.applySecureEditor(inst.biometricPreferences.edit().remove(key))
-                } catch (e: Exception) {
-                    Log.d("NitroStorage", "Biometric storage unavailable: ${e.message}")
+                } catch (_: Exception) {
                 }
                 inst.invalidateSecureKeysCache()
             }
@@ -391,8 +385,7 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
                         biometricEditor.remove(key)
                     }
                     inst.applySecureEditor(biometricEditor)
-                } catch (e: Exception) {
-                    Log.d("NitroStorage", "Biometric storage unavailable: ${e.message}")
+                } catch (_: Exception) {
                 }
                 inst.invalidateSecureKeysCache()
             }
@@ -404,8 +397,7 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
             val hasInEncrypted = inst.encryptedPreferences.contains(key)
             val hasInBiometric = try {
                 inst.biometricPreferences.contains(key)
-            } catch (e: Exception) {
-                Log.d("NitroStorage", "Biometric storage unavailable: ${e.message}")
+            } catch (_: Exception) {
                 false
             }
             return hasInEncrypted || hasInBiometric
@@ -433,8 +425,7 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
             inst.applySecureEditor(inst.encryptedPreferences.edit().clear())
             try {
                 inst.applySecureEditor(inst.biometricPreferences.edit().clear())
-            } catch (e: Exception) {
-                Log.d("NitroStorage", "Biometric storage unavailable: ${e.message}")
+            } catch (_: Exception) {
             }
             inst.invalidateSecureKeysCache()
         }
@@ -466,8 +457,7 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
             val inst = getInstanceOrThrow()
             return try {
                 inst.getSecureSafe(inst.biometricPreferences, key)
-            } catch (e: Exception) {
-                Log.d("NitroStorage", "Biometric storage unavailable: ${e.message}")
+            } catch (_: Exception) {
                 null
             }
         }
@@ -478,8 +468,7 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
             try {
                 inst.applySecureEditor(inst.biometricPreferences.edit().remove(key))
                 inst.invalidateSecureKeysCache()
-            } catch (e: Exception) {
-                Log.d("NitroStorage", "Biometric storage unavailable: ${e.message}")
+            } catch (_: Exception) {
             }
         }
 
@@ -487,8 +476,7 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         fun hasSecureBiometric(key: String): Boolean {
             return try {
                 getInstanceOrThrow().biometricPreferences.contains(key)
-            } catch (e: Exception) {
-                Log.d("NitroStorage", "Biometric storage unavailable: ${e.message}")
+            } catch (_: Exception) {
                 false
             }
         }
@@ -499,8 +487,7 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
             try {
                 inst.applySecureEditor(inst.biometricPreferences.edit().clear())
                 inst.invalidateSecureKeysCache()
-            } catch (e: Exception) {
-                Log.d("NitroStorage", "Biometric storage unavailable: ${e.message}")
+            } catch (_: Exception) {
             }
         }
     }

package/app.plugin.js

@@ -2,16 +2,100 @@ const {
   withInfoPlist,
   withAndroidManifest,
   withMainApplication,
+  withDangerousMod,
   createRunOncePlugin,
 } = require("@expo/config-plugins");
+const fs = require("fs");
+const path = require("path");
+
+const DATA_EXTRACTION_RULES_RESOURCE =
+  "@xml/nitro_storage_data_extraction_rules";
+const FULL_BACKUP_CONTENT_RESOURCE = "@xml/nitro_storage_full_backup_content";
+
+const secureSharedPrefs = [
+  "NitroStorageSecure.xml",
+  "NitroStorageBiometric.xml",
+];
+
+function sharedPrefsExcludes(indent = "    ") {
+  return secureSharedPrefs
+    .map((file) => `${indent}<exclude domain="sharedpref" path="${file}" />`)
+    .join("\n");
+}
+
+function dataExtractionRulesXml() {
+  const excludes = sharedPrefsExcludes("    ");
+  return `<?xml version="1.0" encoding="utf-8"?>
+<data-extraction-rules>
+  <cloud-backup>
+${excludes}
+  </cloud-backup>
+  <device-transfer>
+${excludes}
+  </device-transfer>
+</data-extraction-rules>
+`;
+}
+
+function fullBackupContentXml() {
+  return `<?xml version="1.0" encoding="utf-8"?>
+<full-backup-content>
+${sharedPrefsExcludes("  ")}
+</full-backup-content>
+`;
+}
+
+function ensureBackupAttributes(androidManifest) {
+  const application = androidManifest.manifest.application?.[0];
+  if (!application) {
+    return;
+  }
+
+  application.$ = application.$ || {};
+  if (!application.$["android:dataExtractionRules"]) {
+    application.$["android:dataExtractionRules"] =
+      DATA_EXTRACTION_RULES_RESOURCE;
+  }
+  if (!application.$["android:fullBackupContent"]) {
+    application.$["android:fullBackupContent"] = FULL_BACKUP_CONTENT_RESOURCE;
+  }
+}
+
+function writeAndroidBackupFiles(projectRoot) {
+  const xmlDir = path.join(
+    projectRoot,
+    "android",
+    "app",
+    "src",
+    "main",
+    "res",
+    "xml",
+  );
+  fs.mkdirSync(xmlDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(xmlDir, "nitro_storage_data_extraction_rules.xml"),
+    dataExtractionRulesXml(),
+  );
+  fs.writeFileSync(
+    path.join(xmlDir, "nitro_storage_full_backup_content.xml"),
+    fullBackupContentXml(),
+  );
+}
 
 const withNitroStorage = (config, props = {}) => {
   const defaultFaceIDPermission =
     "Allow $(PRODUCT_NAME) to use Face ID for secure authentication";
-  const { faceIDPermission, addBiometricPermissions = false } = props;
+  const {
+    faceIDPermission,
+    addBiometricPermissions = false,
+    configureAndroidBackup = true,
+  } = props;
 
   config = withInfoPlist(config, (config) => {
-    if (typeof faceIDPermission === "string" && faceIDPermission.trim() !== "") {
+    if (
+      typeof faceIDPermission === "string" &&
+      faceIDPermission.trim() !== ""
+    ) {
       config.modResults.NSFaceIDUsageDescription = faceIDPermission;
     } else if (!config.modResults.NSFaceIDUsageDescription) {
       config.modResults.NSFaceIDUsageDescription = defaultFaceIDPermission;
@@ -20,6 +104,10 @@ const withNitroStorage = (config, props = {}) => {
   });
 
   config = withAndroidManifest(config, (config) => {
+    if (configureAndroidBackup) {
+      ensureBackupAttributes(config.modResults);
+    }
+
     if (!addBiometricPermissions) {
       return config;
     }
@@ -38,10 +126,10 @@ const withNitroStorage = (config, props = {}) => {
     };
 
     const hasBiometric = permissions.some(
-      (p) => p.$?.["android:name"] === "android.permission.USE_BIOMETRIC"
+      (p) => p.$?.["android:name"] === "android.permission.USE_BIOMETRIC",
     );
     const hasFingerprint = permissions.some(
-      (p) => p.$?.["android:name"] === "android.permission.USE_FINGERPRINT"
+      (p) => p.$?.["android:name"] === "android.permission.USE_FINGERPRINT",
     );
 
     if (!hasBiometric) {
@@ -54,6 +142,16 @@ const withNitroStorage = (config, props = {}) => {
     return config;
   });
 
+  if (configureAndroidBackup) {
+    config = withDangerousMod(config, [
+      "android",
+      async (config) => {
+        writeAndroidBackupFiles(config.modRequest.projectRoot);
+        return config;
+      },
+    ]);
+  }
+
   config = withMainApplication(config, (config) => {
     const { modResults } = config;
     const { language, contents } = modResults;
@@ -67,13 +165,13 @@ const withNitroStorage = (config, props = {}) => {
         if (!contents.includes(importStatement)) {
           modResults.contents = contents.replace(
             /(package .*;\n)/,
-            `$1\n${importStatement}\n`
+            `$1\n${importStatement}\n`,
           );
         }
 
         modResults.contents = modResults.contents.replace(
           /(super\.onCreate\(\);)/,
-          `$1\n${initStatement}`
+          `$1\n${initStatement}`,
         );
       }
     } else if (language === "kt") {
@@ -84,13 +182,13 @@ const withNitroStorage = (config, props = {}) => {
         if (!contents.includes(importStatement)) {
           modResults.contents = contents.replace(
             /(package .*\n)/,
-            `$1\n${importStatement}\n`
+            `$1\n${importStatement}\n`,
           );
         }
 
         modResults.contents = modResults.contents.replace(
           /(super\.onCreate\(\))/,
-          `$1\n${initStatement}`
+          `$1\n${initStatement}`,
         );
       }
     }
@@ -104,5 +202,12 @@ const withNitroStorage = (config, props = {}) => {
 module.exports = createRunOncePlugin(
   withNitroStorage,
   "react-native-nitro-storage",
-  "1.0.0"
+  "1.0.0",
 );
+module.exports.withNitroStorage = withNitroStorage;
+module.exports._internal = {
+  dataExtractionRulesXml,
+  fullBackupContentXml,
+  ensureBackupAttributes,
+  writeAndroidBackupFiles,
+};

package/docs/api-reference.md

@@ -72,41 +72,42 @@ See [react-hooks.md](react-hooks.md).
 
 `storage` exposes raw and cross-item utilities:
 
-| Method                                           | Purpose                                                       |
-| ------------------------------------------------ | ------------------------------------------------------------- |
-| `clear(scope)`                                   | Clear one scope.                                              |
-| `clearAll()`                                     | Clear Memory, Disk, and Secure scopes.                        |
-| `clearNamespace(namespace, scope)`               | Remove keys under `namespace:`.                               |
-| `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)`                     | Receive all change events for devtools or logging.            |
-| `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.                                      |
-| `resetMetrics()`                                 | Clear metrics counters.                                       |
-| `getCapabilities()`                              | Read runtime storage capabilities.                            |
-| `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)`                                  | Snapshot raw strings from one scope.                          |
-| `import(data, scope)`                            | Bulk import raw strings.                                      |
+| Method                                           | Purpose                                                                                   |
+| ------------------------------------------------ | ----------------------------------------------------------------------------------------- |
+| `clear(scope)`                                   | Clear one scope.                                                                          |
+| `clearAll()`                                     | Clear Memory, Disk, and Secure scopes.                                                    |
+| `clearNamespace(namespace, scope)`               | Remove keys under `namespace:`.                                                           |
+| `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.                                                                  |
+| `resetMetrics()`                                 | Clear metrics counters.                                                                   |
+| `getCapabilities()`                              | Read runtime storage capabilities.                                                        |
+| `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.
 
@@ -115,7 +116,7 @@ const diskSnapshot = storage.export(StorageScope.Disk);
 storage.import(diskSnapshot, StorageScope.Disk);
 ```
 
-Secure exports contain raw secret values. Do not log `storage.export(StorageScope.Secure)` output or attach it to diagnostics, analytics, crash reports, or support bundles.
+Secure exports contain raw secret values. `storage.export(StorageScope.Secure)` throws unless called with `{ includeSecureValues: true }`; `storage.exportSecureUnsafe()` is the explicit equivalent. Do not log Secure exports or attach them to diagnostics, analytics, crash reports, or support bundles.
 
 ## Event Subscriptions
 
@@ -149,6 +150,8 @@ storage.setEventObserver((event) => {
 });
 ```
 
+`setEventObserver()` redacts Secure `oldValue` and `newValue` fields by default. Pass `{ redactSecureValues: false }` only for in-memory debugging paths that never persist logs. Raw `subscribe*()` APIs preserve values for state integrations.
+
 Local batch APIs emit one `type: "batch"` envelope to scope and prefix/namespace listeners. Key subscribers receive the matching per-key change so direct key integrations do not need to unpack batch envelopes. Secure events can include raw secret values; do not log Secure event payloads in production.
 
 ## Batch Operations

package/docs/batch-transactions-migrations.md

@@ -82,7 +82,7 @@ storage.import(snapshot, StorageScope.Disk);
 
 For Memory scope, import is atomic: all keys are written before listeners fire. For Disk and Secure, import delegates to native or web batch paths.
 
-Secure exports contain raw secret values. Do not log them or include them in diagnostics, analytics, crash reports, or support bundles.
+Secure exports contain raw secret values. `storage.export(StorageScope.Secure)` requires `{ includeSecureValues: true }`; `storage.exportSecureUnsafe()` is the explicit equivalent. Do not log Secure exports or include them in diagnostics, analytics, crash reports, or support bundles.
 
 ## Transactions
 

package/docs/recipes.md

@@ -278,7 +278,7 @@ storage.setEventObserver((event) => {
 });
 ```
 
-Use `subscribePrefix()` or `subscribeNamespace()` for targeted integrations. Use `setEventObserver()` for devtools-style logging. Secure events can include raw secret values, so filter them out of logs.
+Use `subscribePrefix()` or `subscribeNamespace()` for targeted integrations. Use `setEventObserver()` for devtools-style logging; it redacts Secure values by default. Raw Secure subscriptions can include secret values, so filter them out of logs.
 
 ## Capability Checks