react-native-nitro-storage 0.4.4 → 0.5.0

package/SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are shipped for the latest published `0.x` release line.
+
+| Version | Supported |
+| ------- | --------- |
+| `0.5.x` | Yes       |
+| `<0.5`  | No        |
+
+## Reporting a Vulnerability
+
+Report security issues through GitHub Security Advisories with:
+
+- affected package version
+- platform and OS version
+- React Native and `react-native-nitro-modules` versions
+- reproduction steps
+- whether the issue affects Memory, Disk, Secure, biometric storage, web backends, or packaging
+
+Do not publish proof-of-concept exploit details until a fix is available.
+
+## Storage Boundary
+
+Native Secure scope delegates encryption to platform storage APIs: iOS Keychain and Android Jetpack Security `EncryptedSharedPreferences`. Web Secure scope is API-compatible but defaults to namespaced `localStorage`; use a custom web secure backend when browser-side storage must meet a stricter threat model.

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

@@ -1,11 +1,15 @@
 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
 import java.security.KeyStore
+import java.security.KeyStoreException
 import javax.crypto.AEADBadTagException
 
 private fun Throwable.hasCause(type: Class<*>): Boolean {
@@ -17,6 +21,30 @@ private fun Throwable.hasCause(type: Class<*>): Boolean {
     return false
 }
 
+private fun Throwable.storageErrorCode(): String? {
+    return when {
+        hasCause(AEADBadTagException::class.java) -> "storage_corruption"
+        hasCause(UserNotAuthenticatedException::class.java) ||
+            hasCause(KeyStoreException::class.java) -> "authentication_required"
+        hasCause(KeyPermanentlyInvalidatedException::class.java) ||
+            hasCause(InvalidKeyException::class.java) -> "key_invalidated"
+        else -> null
+    }
+}
+
+private fun Throwable.wrapStorageException(
+    defaultMessage: String,
+    defaultCode: String? = null,
+): RuntimeException {
+    val code = storageErrorCode() ?: defaultCode
+    val message = if (code != null) {
+        "[nitro-error:$code] $defaultMessage"
+    } else {
+        defaultMessage
+    }
+    return RuntimeException(message, this)
+}
+
 class AndroidStorageAdapter private constructor(private val context: Context) {
     private val sharedPreferences: SharedPreferences =
         context.getSharedPreferences("NitroStorage", Context.MODE_PRIVATE)
@@ -44,8 +72,11 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
             initializeEncryptedPreferences("NitroStorageBiometric", bioKey)
         } catch (e: Exception) {
             Log.e("NitroStorage", "Biometric storage unavailable: ${e.message}")
-            throw RuntimeException("NitroStorage: Biometric storage is not available on this device. " +
-                "Ensure biometric hardware is present and credentials are enrolled.", e)
+            throw e.wrapStorageException(
+                "NitroStorage: Biometric storage is not available on this device. " +
+                    "Ensure biometric hardware is present and credentials are enrolled.",
+                defaultCode = "biometric_unavailable",
+            )
         }
     }
 
@@ -83,14 +114,17 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
                             EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
                         )
                     } catch (retryEx: Exception) {
-                        throw RuntimeException("NitroStorage: Unrecoverable storage corruption in $name", retryEx)
+                        throw retryEx.wrapStorageException(
+                            "NitroStorage: Unrecoverable storage corruption in $name",
+                            defaultCode = "storage_corruption",
+                        )
                     }
                 }
                 else -> {
                     // Don't wipe on non-corruption failures (e.g., locked keystore)
-                    throw RuntimeException(
+                    throw e.wrapStorageException(
                         "NitroStorage: Failed to initialize $name (${e::class.simpleName}). " +
-                        "This may be a temporary keystore issue. If it persists, clear app data.", e
+                            "This may be a temporary keystore issue. If it persists, clear app data.",
                     )
                 }
             }
@@ -136,7 +170,9 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
                 editor.commit()
             }
         } catch (e: Exception) {
-            throw RuntimeException("NitroStorage: Failed to write to secure storage: ${e.message}", e)
+            throw e.wrapStorageException(
+                "NitroStorage: Failed to write to secure storage: ${e.message}",
+            )
         }
     }
 
@@ -303,14 +339,26 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         @JvmStatic
         fun getSecure(key: String): String? {
             val inst = getInstanceOrThrow()
-            return inst.getSecureSafe(inst.encryptedPreferences, key)
+            return try {
+                inst.getSecureSafe(inst.encryptedPreferences, key)
+            } catch (e: Exception) {
+                throw e.wrapStorageException(
+                    "NitroStorage: Failed to read secure storage: ${e.message}",
+                )
+            }
         }
 
         @JvmStatic
         fun getSecureBatch(keys: Array<String>): Array<String?> {
             val inst = getInstanceOrThrow()
-            return Array(keys.size) { index ->
-                inst.getSecureSafe(inst.encryptedPreferences, keys[index])
+            return try {
+                Array(keys.size) { index ->
+                    inst.getSecureSafe(inst.encryptedPreferences, keys[index])
+                }
+            } catch (e: Exception) {
+                throw e.wrapStorageException(
+                    "NitroStorage: Failed to read secure storage batch: ${e.message}",
+                )
             }
         }
 
@@ -406,7 +454,10 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
                 inst.applySecureEditor(editor)
                 inst.invalidateSecureKeysCache()
             } catch (e: Exception) {
-                throw RuntimeException("NitroStorage: Biometric storage unavailable on this device", e)
+                throw e.wrapStorageException(
+                    "NitroStorage: Biometric storage unavailable on this device",
+                    defaultCode = "biometric_unavailable",
+                )
             }
         }
 

package/docs/api-reference.md

@@ -0,0 +1,217 @@
+# API Reference
+
+This page lists the public API surface. For copy-ready workflows, see [recipes.md](recipes.md).
+
+## createStorageItem
+
+```ts
+const item = createStorageItem<T>({
+  key: "theme",
+  scope: StorageScope.Disk,
+  defaultValue: "system",
+});
+```
+
+`StorageItemConfig<T>`:
+
+| Field                  | Type                             | Purpose                                                          |
+| ---------------------- | -------------------------------- | ---------------------------------------------------------------- |
+| `key`                  | `string`                         | Storage key. Combined with `namespace` when provided.            |
+| `scope`                | `StorageScope`                   | Memory, Disk, or Secure.                                         |
+| `defaultValue`         | `T`                              | Value returned when no stored value exists.                      |
+| `serialize`            | `(value: T) => string`           | Custom string encoder. Defaults to primitive/JSON serialization. |
+| `deserialize`          | `(value: string) => T`           | Custom string decoder.                                           |
+| `validate`             | `(value: unknown) => value is T` | Runtime guard for stored data.                                   |
+| `onValidationError`    | `(invalidValue: unknown) => T`   | Replacement value when validation fails.                         |
+| `expiration`           | `{ ttlMs: number }`              | Time-to-live for the value.                                      |
+| `onExpired`            | `(key: string) => void`          | Called when a read detects TTL expiry.                           |
+| `readCache`            | `boolean`                        | Cache parsed values in memory.                                   |
+| `coalesceDiskWrites`   | `boolean`                        | Buffer Disk writes until the next flush.                         |
+| `coalesceSecureWrites` | `boolean`                        | Buffer Secure writes until the next flush.                       |
+| `namespace`            | `string`                         | Prefix keys as `namespace:key`.                                  |
+| `biometric`            | `boolean`                        | Store through biometric secure storage.                          |
+| `biometricLevel`       | `BiometricLevel`                 | Require biometric/passcode or biometric-only access.             |
+| `accessControl`        | `AccessControl`                  | Platform secure accessibility setting.                           |
+
+`StorageItem<T>`:
+
+| Method                         | Purpose                                                     |
+| ------------------------------ | ----------------------------------------------------------- |
+| `get()`                        | Return the typed value or the default value.                |
+| `getWithVersion()`             | Return `{ value, version }` for optimistic writes.          |
+| `set(value)`                   | Store a value. Accepts direct values or updater functions.  |
+| `setIfVersion(version, value)` | Store only when the current version still matches.          |
+| `delete()`                     | Remove the key.                                             |
+| `has()`                        | Check whether the key exists.                               |
+| `subscribe(callback)`          | Subscribe to item changes. Returns an unsubscribe function. |
+| `serialize(value)`             | Serialize a value with the item encoder.                    |
+| `deserialize(value)`           | Deserialize a raw string with the item decoder.             |
+
+## React Hooks
+
+```ts
+const [value, setValue] = useStorage(item);
+const [selected, setItem] = useStorageSelector(item, selector, isEqual);
+const setOnly = useSetStorage(item);
+```
+
+See [react-hooks.md](react-hooks.md).
+
+## storage
+
+`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:`.                               |
+| `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.                                             |
+| `import(data, scope)`              | Bulk import raw strings.                                      |
+
+Raw string APIs bypass item serialization and validation. Prefer `StorageItem<T>` unless you are migrating, importing, or writing a custom integration.
+
+## Batch Operations
+
+```ts
+const values = getBatch([themeItem, localeItem], StorageScope.Disk);
+
+setBatch(
+  [
+    { item: themeItem, value: "dark" },
+    { item: localeItem, value: "en-US" },
+  ],
+  StorageScope.Disk,
+);
+
+removeBatch([themeItem, localeItem], StorageScope.Disk);
+```
+
+See [batch-transactions-migrations.md](batch-transactions-migrations.md).
+
+## Transactions
+
+```ts
+runTransaction(StorageScope.Disk, (tx) => {
+  const current = tx.getItem(balanceItem);
+  tx.setItem(balanceItem, current + 10);
+});
+```
+
+If the callback throws, previously changed keys in that transaction are rolled back synchronously.
+
+## Migrations
+
+```ts
+registerMigration(2, (ctx) => {
+  const oldTheme = ctx.getRaw("theme");
+  if (oldTheme === "black") {
+    ctx.setRaw("theme", "dark");
+  }
+});
+
+migrateToLatest(StorageScope.Disk);
+```
+
+Migration versions are tracked per scope.
+
+## Secure Auth Storage
+
+```ts
+const auth = createSecureAuthStorage({
+  accessToken: { ttlMs: 15 * 60 * 1000 },
+  refreshToken: { accessControl: AccessControl.AfterFirstUnlockThisDeviceOnly },
+});
+
+auth.accessToken.set("token");
+```
+
+The returned object is a typed record of secure string `StorageItem`s.
+
+## Web Backend APIs
+
+```ts
+setWebDiskStorageBackend(backend);
+getWebDiskStorageBackend();
+setWebSecureStorageBackend(backend);
+getWebSecureStorageBackend();
+await flushWebStorageBackends();
+```
+
+See [web-backends.md](web-backends.md).
+
+## Enums
+
+```ts
+enum StorageScope {
+  Memory = 0,
+  Disk = 1,
+  Secure = 2,
+}
+
+enum BiometricLevel {
+  None = 0,
+  BiometryOrPasscode = 1,
+  BiometryOnly = 2,
+}
+```
+
+`AccessControl` values:
+
+- `WhenUnlocked`
+- `AfterFirstUnlock`
+- `WhenPasscodeSetThisDeviceOnly`
+- `WhenUnlockedThisDeviceOnly`
+- `AfterFirstUnlockThisDeviceOnly`
+
+## Exported Types
+
+Common public types:
+
+- `Storage`
+- `Validator<T>`
+- `ExpirationConfig`
+- `StorageItem<T>`
+- `StorageItemConfig<T>`
+- `StorageBatchSetItem<T>`
+- `StorageVersion`
+- `VersionedValue<T>`
+- `StorageMetricsEvent`
+- `StorageMetricsObserver`
+- `StorageMetricSummary`
+- `MigrationContext`
+- `Migration`
+- `TransactionContext`
+- `SecureAuthStorageConfig<K>`
+- `SecurityCapabilities`
+- `SecureStorageMetadata`
+- `StorageErrorCode`
+- `WebStorageBackend`
+- `WebDiskStorageBackend`
+- `WebSecureStorageBackend`
+- `WebStorageChangeEvent`
+- `WebStorageScope`
+
+The IndexedDB subpath exports `createIndexedDBBackend()` and `IndexedDBBackendOptions`.

package/docs/batch-transactions-migrations.md

@@ -0,0 +1,186 @@
+# Batch, Transactions, and Migrations
+
+Use these APIs when a workflow touches several keys or needs a controlled upgrade path.
+
+## Batch Reads
+
+```ts
+import {
+  createStorageItem,
+  getBatch,
+  StorageScope,
+} from "react-native-nitro-storage";
+
+const themeItem = createStorageItem({
+  key: "theme",
+  scope: StorageScope.Disk,
+  defaultValue: "system",
+});
+
+const localeItem = createStorageItem({
+  key: "locale",
+  scope: StorageScope.Disk,
+  defaultValue: "en-US",
+});
+
+const [theme, locale] = getBatch([themeItem, localeItem], StorageScope.Disk);
+```
+
+All items in a batch must use the same scope.
+
+## Batch Writes
+
+```ts
+import { setBatch, StorageScope } from "react-native-nitro-storage";
+
+setBatch(
+  [
+    { item: themeItem, value: "dark" },
+    { item: localeItem, value: "pt-BR" },
+  ],
+  StorageScope.Disk,
+);
+```
+
+Memory-scope batch writes are two-phase: all values are written first, then listeners are notified. Items with validation or TTL fall back to per-item writes so those rules still run.
+
+## Batch Removes
+
+```ts
+import { removeBatch, StorageScope } from "react-native-nitro-storage";
+
+removeBatch([themeItem, localeItem], StorageScope.Disk);
+```
+
+## Raw Import
+
+`storage.import(data, scope)` writes raw strings. It does not serialize values.
+
+```ts
+import { storage, StorageScope } from "react-native-nitro-storage";
+
+storage.import(
+  {
+    "flags:newOnboarding": "true",
+    "flags:paywall": "control",
+  },
+  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.
+
+## Transactions
+
+Use `runTransaction(scope, callback)` when several raw or item writes should roll back together if the callback throws.
+
+```ts
+import { runTransaction, StorageScope } from "react-native-nitro-storage";
+
+const fromBalanceItem = createStorageItem({
+  key: "account:from",
+  scope: StorageScope.Disk,
+  defaultValue: 100,
+});
+
+const toBalanceItem = createStorageItem({
+  key: "account:to",
+  scope: StorageScope.Disk,
+  defaultValue: 0,
+});
+
+runTransaction(StorageScope.Disk, (tx) => {
+  const from = tx.getItem(fromBalanceItem);
+
+  if (from < 25) {
+    throw new Error("Insufficient balance");
+  }
+
+  tx.setItem(fromBalanceItem, from - 25);
+  tx.setItem(toBalanceItem, tx.getItem(toBalanceItem) + 25);
+});
+```
+
+Transaction context methods:
+
+- `getRaw(key)`
+- `setRaw(key, value)`
+- `removeRaw(key)`
+- `getItem(item)`
+- `setItem(item, value)`
+- `removeItem(item)`
+
+If the callback throws, Nitro Storage restores the keys it changed during that transaction.
+
+## Migrations
+
+Register migrations with monotonically increasing versions, then migrate a scope to the latest known version.
+
+```ts
+import {
+  migrateToLatest,
+  registerMigration,
+  StorageScope,
+} from "react-native-nitro-storage";
+
+registerMigration(1, (ctx) => {
+  const oldValue = ctx.getRaw("theme");
+  if (oldValue === "black") {
+    ctx.setRaw("theme", "dark");
+  }
+});
+
+registerMigration(2, (ctx) => {
+  const token = ctx.getRaw("token");
+  if (token) {
+    ctx.setRaw("auth:accessToken", token);
+    ctx.removeRaw("token");
+  }
+});
+
+migrateToLatest(StorageScope.Disk);
+```
+
+Migration context methods work with raw strings. Use item serializers manually when migrating structured data.
+
+```ts
+registerMigration(3, (ctx) => {
+  const raw = ctx.getRaw("settings");
+  if (!raw) {
+    return;
+  }
+
+  const settings = JSON.parse(raw) as { mode?: string };
+  ctx.setRaw(
+    "settings",
+    JSON.stringify({
+      ...settings,
+      theme: settings.mode ?? "system",
+    }),
+  );
+});
+```
+
+## Prefix Queries and Cleanup
+
+```ts
+const keys = storage.getKeysByPrefix("tenant:42:", StorageScope.Disk);
+const values = storage.getByPrefix("tenant:42:", StorageScope.Disk);
+
+storage.clearNamespace("tenant:42", StorageScope.Disk);
+```
+
+Use namespaces for multi-account or tenant-specific state so cleanup is predictable.
+
+## Optimistic Versioned Writes
+
+```ts
+const current = themeItem.getWithVersion();
+
+const didWrite = themeItem.setIfVersion(
+  current.version,
+  current.value === "dark" ? "light" : "dark",
+);
+```
+
+`setIfVersion()` returns `false` if another write changed the item after `getWithVersion()`.

package/docs/benchmarks.md

@@ -0,0 +1,37 @@
+# Benchmarks
+
+Benchmarks are release checks, not product promises. Use them to catch regressions on the local machine and CI image used by this repo.
+
+Run:
+
+```sh
+bun run benchmark -- --filter=react-native-nitro-storage
+```
+
+The benchmark script checks representative synchronous read/write paths and fails when results drift beyond the configured threshold.
+
+## Interpreting Results
+
+- Compare results on the same machine and Node/Bun version.
+- Treat large deltas as a prompt to inspect recent storage-runtime, serialization, native bridge, or cache changes.
+- Do not compare web backend numbers against native secure storage numbers; they measure different systems.
+- Secure storage performance depends on platform state, device lock state, biometric prompts, and Keystore/Keychain behavior.
+
+## Release Checklist
+
+Before publishing:
+
+```sh
+bun run lint -- --filter=react-native-nitro-storage
+bun run format:check -- --filter=react-native-nitro-storage
+bun run typecheck -- --filter=react-native-nitro-storage
+bun run test:types -- --filter=react-native-nitro-storage
+bun run test -- --filter=react-native-nitro-storage
+bun run test:cpp -- --filter=react-native-nitro-storage
+bun run build -- --filter=react-native-nitro-storage
+bun run benchmark -- --filter=react-native-nitro-storage
+bun run --cwd packages/react-native-nitro-storage check:pack
+npm publish --dry-run
+```
+
+Keep the dry-publish output in the release notes when validating a version locally.

package/docs/mmkv-migration.md

@@ -0,0 +1,80 @@
+# MMKV Migration
+
+Use `migrateFromMMKV(mmkv, item, deleteAfterMigration?)` when an app already stores values with `react-native-mmkv` and you want to move one key at a time into Nitro Storage.
+
+The helper reads in this order:
+
+1. `mmkv.getString(key)`
+2. `mmkv.getNumber(key)`
+3. `mmkv.getBoolean(key)`
+
+It writes through `item.set()`, so custom serialization, validation, TTL behavior, and listeners remain active.
+
+## Basic Migration
+
+```ts
+import {
+  createStorageItem,
+  migrateFromMMKV,
+  StorageScope,
+} from "react-native-nitro-storage";
+import { MMKV } from "react-native-mmkv";
+
+const mmkv = new MMKV();
+
+const usernameItem = createStorageItem({
+  key: "username",
+  scope: StorageScope.Disk,
+  defaultValue: "",
+});
+
+const migrated = migrateFromMMKV(mmkv, usernameItem, true);
+```
+
+`migrated` is `true` when a value was found and written. The third argument deletes the MMKV key after a successful write.
+
+## Type Conversion
+
+MMKV numbers and booleans are converted through the target item's serializer.
+
+```ts
+const launchCountItem = createStorageItem({
+  key: "launchCount",
+  scope: StorageScope.Disk,
+  defaultValue: 0,
+});
+
+migrateFromMMKV(mmkv, launchCountItem, true);
+```
+
+## Custom Serialized Values
+
+```ts
+type Settings = {
+  compactMode: boolean;
+};
+
+const settingsItem = createStorageItem<Settings>({
+  key: "settings",
+  scope: StorageScope.Disk,
+  defaultValue: { compactMode: false },
+  serialize: JSON.stringify,
+  deserialize: JSON.parse,
+  validate: (value): value is Settings =>
+    typeof value === "object" &&
+    value !== null &&
+    "compactMode" in value &&
+    typeof value.compactMode === "boolean",
+});
+
+migrateFromMMKV(mmkv, settingsItem, true);
+```
+
+## Migration Strategy
+
+- Migrate stable keys first: preferences, feature flags, and local settings.
+- Keep secure credentials in Secure scope instead of moving them to Disk scope.
+- Run migration once during startup, before components read the target item.
+- Delete the MMKV key only after you have shipped and observed the migration path.
+
+For larger data-shape upgrades, use the versioned migration APIs in [batch-transactions-migrations.md](batch-transactions-migrations.md).