react-native-nitro-storage 0.5.4 → 0.5.5

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.6-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,7 @@ 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 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:
 
@@ -199,7 +201,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 +286,44 @@ 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
+type Preferences = {
+  theme: "system" | "light" | "dark";
+  compactMode: boolean;
+};
+
+const preferencesItem = createStorageItem<Preferences>({
+  key: "preferences",
+  scope: StorageScope.Disk,
+  defaultValue: { theme: "system", compactMode: false },
+  validate: (value): value is Preferences =>
+    typeof value === "object" &&
+    value !== null &&
+    ["system", "light", "dark"].includes(
+      (value as Partial<Preferences>).theme ?? "",
+    ) &&
+    typeof (value as Partial<Preferences>).compactMode === "boolean",
+});
+
+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                                                                                                  |
@@ -297,7 +337,7 @@ Peer dependencies:
 
 - `react >=18.2.0`
 - `react-native >=0.75.0`
-- `react-native-nitro-modules >=0.35.5`
+- `react-native-nitro-modules >=0.35.6`
 
 ## Security Model
 

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
 

package/docs/secure-storage.md

@@ -4,6 +4,8 @@ Secure scope is for secrets: refresh tokens, credentials, API tokens, and device
 
 Use Disk scope for non-secret persisted state. Secure storage has stronger boundaries but more platform rules, especially around biometric prompts, device lock state, and backup/restore behavior.
 
+Keep Secure values small. Platform secure stores are optimized for credentials and keys, not large payloads or support bundles.
+
 ## Store a Secure Token
 
 ```ts
@@ -116,12 +118,12 @@ const allKeys = storage.getAllSecureMetadata();
 
 ## Secure Export Warning
 
-`storage.export(StorageScope.Secure)` returns raw secret values so it can round-trip with `storage.import(data, StorageScope.Secure)`.
+`storage.export(StorageScope.Secure)` throws unless you explicitly opt into exposing raw secret values. Use `storage.exportSecureUnsafe()` or `storage.export(StorageScope.Secure, { includeSecureValues: true })` only when you need to round-trip with `storage.import(data, StorageScope.Secure)`.
 
 ```ts
 import { storage, StorageScope } from "react-native-nitro-storage";
 
-const secureSnapshot = storage.export(StorageScope.Secure);
+const secureSnapshot = storage.exportSecureUnsafe();
 storage.import(secureSnapshot, StorageScope.Secure);
 ```
 
@@ -129,9 +131,18 @@ Only keep Secure exports in memory for the shortest possible workflow. Do not lo
 
 ## Secure Event Warning
 
-Secure scope event subscriptions and `storage.setEventObserver()` can receive raw secret values in `oldValue`, `newValue`, or batch `changes`.
+Secure scope event subscriptions can receive raw secret values in `oldValue`, `newValue`, or batch `changes`. `storage.setEventObserver()` redacts Secure values by default because observer callbacks are commonly used for logging and devtools.
+
+Use Secure events for in-memory coordination only. Do not log Secure event payloads or send them to analytics, crash reporting, support bundles, or devtools sessions that persist outside the device. Pass `{ redactSecureValues: false }` to `setEventObserver()` only for local, non-persistent debugging.
+
+## Android Backup Rules
+
+Android secure storage uses encrypted SharedPreferences. Restored encrypted preference files can become unreadable when the app's Keystore keys are not restored with them. The Expo plugin configures backup exclusions for Nitro Storage secure files by default:
+
+- `NitroStorageSecure.xml`
+- `NitroStorageBiometric.xml`
 
-Use Secure events for in-memory coordination only. Do not log Secure event payloads or send them to analytics, crash reporting, support bundles, or devtools sessions that persist outside the device.
+If you disable `configureAndroidBackup` or maintain custom Android backup XML, add equivalent exclusions for both cloud backup and device transfer.
 
 ## Locked Keychain Errors
 

package/docs/web-backends.md

@@ -33,10 +33,13 @@ Optional methods improve performance and observability:
 - `size()`
 - `subscribe(listener)`
 - `flush()`
+- `close()`
 - `name`
 
 `subscribe(listener)` should report `{ key, newValue }` changes. Use `key: null` when the whole backend is cleared.
 
+`close()` should release backend-owned resources such as database handles or broadcast channels. Nitro Storage calls it when a configured Disk or Secure backend is replaced.
+
 ## Disk Backend
 
 ```ts
@@ -95,6 +98,8 @@ setWebSecureStorageBackend(backend);
 
 Reads are synchronous because they are served from memory after initial load. Writes update memory first and persist to IndexedDB in the background.
 
+The IndexedDB backend exposes `close()` and rejects later synchronous operations after it is closed.
+
 ## Cross-tab Updates
 
 The IndexedDB backend uses `BroadcastChannel` when available. Other tabs receive cache invalidation events and update their in-memory copy.