react-native-nitro-storage 0.4.5 → 0.5.0

package/docs/recipes.md

@@ -0,0 +1,281 @@
+# Recipes
+
+These examples cover the public features most apps reach for first.
+
+## Persisted Preferences
+
+```ts
+import { createStorageItem, StorageScope } from "react-native-nitro-storage";
+
+type Preferences = {
+  theme: "system" | "light" | "dark";
+  reduceMotion: boolean;
+};
+
+export const preferencesItem = createStorageItem<Preferences>({
+  key: "preferences",
+  scope: StorageScope.Disk,
+  defaultValue: { theme: "system", reduceMotion: false },
+  validate: (value): value is Preferences =>
+    typeof value === "object" &&
+    value !== null &&
+    "theme" in value &&
+    "reduceMotion" in value,
+});
+```
+
+## Auth Tokens
+
+```ts
+import {
+  AccessControl,
+  createSecureAuthStorage,
+} from "react-native-nitro-storage";
+
+export const auth = createSecureAuthStorage(
+  {
+    accessToken: { ttlMs: 15 * 60 * 1000 },
+    refreshToken: {
+      accessControl: AccessControl.AfterFirstUnlockThisDeviceOnly,
+    },
+  },
+  { namespace: "auth" },
+);
+
+auth.refreshToken.set("opaque-refresh-token");
+```
+
+## Feature Flags with Validation
+
+```ts
+type Flags = {
+  newCheckout: boolean;
+  paywallVariant: "control" | "variant-a" | "variant-b";
+};
+
+export const flagsItem = createStorageItem<Flags>({
+  key: "remoteFlags",
+  scope: StorageScope.Disk,
+  defaultValue: { newCheckout: false, paywallVariant: "control" },
+  validate: (value): value is Flags => {
+    if (typeof value !== "object" || value === null) {
+      return false;
+    }
+
+    const flags = value as Partial<Flags>;
+    return (
+      typeof flags.newCheckout === "boolean" &&
+      (flags.paywallVariant === "control" ||
+        flags.paywallVariant === "variant-a" ||
+        flags.paywallVariant === "variant-b")
+    );
+  },
+  onValidationError: () => ({ newCheckout: false, paywallVariant: "control" }),
+});
+```
+
+## Biometric Secret
+
+```ts
+import {
+  BiometricLevel,
+  createStorageItem,
+  StorageScope,
+} from "react-native-nitro-storage";
+
+export const vaultKeyItem = createStorageItem<string>({
+  key: "vaultKey",
+  scope: StorageScope.Secure,
+  defaultValue: "",
+  biometric: true,
+  biometricLevel: BiometricLevel.BiometryOrPasscode,
+});
+```
+
+## Multi-tenant State
+
+```ts
+function createTenantThemeItem(tenantId: string) {
+  return createStorageItem({
+    key: "theme",
+    namespace: `tenant:${tenantId}`,
+    scope: StorageScope.Disk,
+    defaultValue: "system",
+  });
+}
+
+storage.clearNamespace("tenant:42", StorageScope.Disk);
+```
+
+## Temporary OTP
+
+```ts
+export const otpItem = createStorageItem<string>({
+  key: "otp",
+  scope: StorageScope.Memory,
+  defaultValue: "",
+  expiration: { ttlMs: 2 * 60 * 1000 },
+  onExpired: () => {
+    showOtpExpiredMessage();
+  },
+});
+```
+
+## Bulk Bootstrap
+
+```ts
+const [preferences, flags] = getBatch(
+  [preferencesItem, flagsItem],
+  StorageScope.Disk,
+);
+
+setBatch(
+  [
+    { item: preferencesItem, value: { theme: "dark", reduceMotion: false } },
+    {
+      item: flagsItem,
+      value: { newCheckout: true, paywallVariant: "variant-a" },
+    },
+  ],
+  StorageScope.Disk,
+);
+```
+
+## Transactional Balance Transfer
+
+```ts
+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);
+});
+```
+
+## Custom Codec
+
+```ts
+type CompactFlag = {
+  id: number;
+  active: boolean;
+};
+
+const compactFlagItem = createStorageItem<CompactFlag>({
+  key: "compactFlag",
+  scope: StorageScope.Disk,
+  defaultValue: { id: 0, active: false },
+  serialize: (value) => `${value.id}|${value.active ? "1" : "0"}`,
+  deserialize: (value) => {
+    const [id, active] = value.split("|");
+    return { id: Number(id), active: active === "1" };
+  },
+});
+```
+
+## Coalesced Writes
+
+```ts
+const draftItem = createStorageItem({
+  key: "draft",
+  scope: StorageScope.Disk,
+  defaultValue: "",
+  coalesceDiskWrites: true,
+});
+
+draftItem.set("first edit");
+draftItem.set("second edit");
+storage.flushDiskWrites();
+```
+
+For Secure scope:
+
+```ts
+const tokenItem = createStorageItem({
+  key: "token",
+  scope: StorageScope.Secure,
+  defaultValue: "",
+  coalesceSecureWrites: true,
+});
+
+tokenItem.set("token");
+storage.flushSecureWrites();
+```
+
+## Raw Import
+
+```ts
+storage.import(
+  {
+    "settings:theme": "dark",
+    "settings:locale": "en-US",
+  },
+  StorageScope.Disk,
+);
+```
+
+Raw import writes strings exactly as provided. It does not run item serializers.
+
+## Snapshot and Cleanup
+
+```ts
+const allDiskValues = storage.getAll(StorageScope.Disk);
+const allDiskKeys = storage.getAllKeys(StorageScope.Disk);
+
+storage.clearNamespace("settings", StorageScope.Disk);
+```
+
+## Prefix Inspection
+
+```ts
+const flagKeys = storage.getKeysByPrefix("flags:", StorageScope.Disk);
+const flagValues = storage.getByPrefix("flags:", StorageScope.Disk);
+```
+
+## Optimistic Writes
+
+```ts
+const current = preferencesItem.getWithVersion();
+
+const didWrite = preferencesItem.setIfVersion(current.version, {
+  ...current.value,
+  theme: "dark",
+});
+```
+
+## Metrics
+
+```ts
+storage.setMetricsObserver((event) => {
+  console.log(event.operation, event.scope, event.durationMs);
+});
+
+preferencesItem.get();
+
+const snapshot = storage.getMetricsSnapshot();
+storage.resetMetrics();
+```
+
+## Capability Checks
+
+```ts
+const capabilities = storage.getCapabilities();
+const security = storage.getSecurityCapabilities();
+
+if (security.secureStorage !== "available") {
+  console.warn("Secure storage is not available on this runtime");
+}
+```
+
+## Low-level Raw API
+
+```ts
+storage.setString("raw-key", "raw-value", StorageScope.Disk);
+const rawValue = storage.getString("raw-key", StorageScope.Disk);
+storage.deleteString("raw-key", StorageScope.Disk);
+```
+
+Use raw APIs for migrations and integrations. Use `createStorageItem` for app state.

package/docs/secure-storage.md

@@ -0,0 +1,171 @@
+# Secure Storage
+
+Secure scope is for secrets: refresh tokens, credentials, API tokens, and device-bound keys. It uses iOS Keychain on iOS and Android Keystore-backed EncryptedSharedPreferences on Android.
+
+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.
+
+## Store a Secure Token
+
+```ts
+import {
+  AccessControl,
+  createStorageItem,
+  StorageScope,
+} from "react-native-nitro-storage";
+
+export const refreshTokenItem = createStorageItem<string>({
+  key: "refreshToken",
+  namespace: "auth",
+  scope: StorageScope.Secure,
+  defaultValue: "",
+  accessControl: AccessControl.AfterFirstUnlockThisDeviceOnly,
+});
+
+refreshTokenItem.set("opaque-refresh-token");
+```
+
+## Biometric Secrets
+
+```ts
+import {
+  BiometricLevel,
+  createStorageItem,
+  StorageScope,
+} from "react-native-nitro-storage";
+
+export const recoveryCodeItem = createStorageItem<string>({
+  key: "recoveryCode",
+  namespace: "vault",
+  scope: StorageScope.Secure,
+  defaultValue: "",
+  biometric: true,
+  biometricLevel: BiometricLevel.BiometryOnly,
+});
+```
+
+`BiometricLevel.BiometryOnly` does not allow passcode fallback. Use `BiometricLevel.BiometryOrPasscode` when passcode fallback is acceptable.
+
+## Access Control
+
+`accessControl` maps to platform accessibility rules where available.
+
+| Value                                          | Use when                                                          |
+| ---------------------------------------------- | ----------------------------------------------------------------- |
+| `AccessControl.WhenUnlocked`                   | The secret should be readable only after the device is unlocked.  |
+| `AccessControl.AfterFirstUnlock`               | Background refresh needs access after first unlock until restart. |
+| `AccessControl.WhenPasscodeSetThisDeviceOnly`  | The secret must stay on this device and require a passcode.       |
+| `AccessControl.WhenUnlockedThisDeviceOnly`     | The secret should not migrate through backup/restore.             |
+| `AccessControl.AfterFirstUnlockThisDeviceOnly` | Background refresh is needed, but migration is not allowed.       |
+
+## Secure Auth Item Map
+
+`createSecureAuthStorage()` creates a namespaced map of secure string items.
+
+```ts
+import {
+  AccessControl,
+  BiometricLevel,
+  createSecureAuthStorage,
+} from "react-native-nitro-storage";
+
+export const authStorage = createSecureAuthStorage(
+  {
+    accessToken: { ttlMs: 15 * 60 * 1000 },
+    refreshToken: {
+      accessControl: AccessControl.AfterFirstUnlockThisDeviceOnly,
+    },
+    recoveryCode: {
+      biometric: true,
+      biometricLevel: BiometricLevel.BiometryOrPasscode,
+    },
+  },
+  { namespace: "auth" },
+);
+
+authStorage.refreshToken.set("opaque-refresh-token");
+```
+
+## Runtime Capabilities
+
+Use capability APIs to decide which support messages or diagnostics to show.
+
+```ts
+import { storage } from "react-native-nitro-storage";
+
+const capabilities = storage.getSecurityCapabilities();
+
+if (capabilities.secureStorage === "available") {
+  // Secure scope is backed by the configured native or web secure backend.
+}
+```
+
+Capability fields are status values, not guarantees beyond the active backend. Hardware-backed storage is reported as `unknown` unless the platform can prove it.
+
+## Metadata Without Values
+
+Use metadata APIs when rendering diagnostics or support dumps where secret values must stay out of memory.
+
+```ts
+import { storage } from "react-native-nitro-storage";
+
+const oneKey = storage.getSecureMetadata("auth:refreshToken");
+const allKeys = storage.getAllSecureMetadata();
+```
+
+`getSecureMetadata()` and `getAllSecureMetadata()` never return stored secret values. They report key existence, storage kind, backend name, access-control metadata, and whether a metadata path accidentally exposed a value.
+
+## Locked Keychain Errors
+
+```ts
+import { isKeychainLockedError } from "react-native-nitro-storage";
+
+try {
+  refreshTokenItem.get();
+} catch (error) {
+  if (isKeychainLockedError(error)) {
+    // Defer token refresh until the device is unlocked.
+  }
+}
+```
+
+The helper recognizes iOS locked Keychain cases and Android invalidated/locked key cases surfaced by the native bridge.
+
+## Android Secure Write Mode
+
+Android secure writes default to synchronous persistence. Enable async writes when write throughput is more important than immediate durability:
+
+```ts
+import { storage } from "react-native-nitro-storage";
+
+storage.setSecureWritesAsync(true);
+refreshTokenItem.set("opaque-refresh-token");
+storage.flushSecureWrites();
+```
+
+Call `flushSecureWrites()` before assertions, namespace clears, or any boundary that requires deterministic persistence.
+
+## Web Secure Backend
+
+Browsers cannot provide iOS Keychain or Android Keystore guarantees. On web, Secure scope is only as strong as the backend you configure.
+
+```ts
+import { setWebSecureStorageBackend } from "react-native-nitro-storage";
+import { createIndexedDBBackend } from "react-native-nitro-storage/indexeddb-backend";
+
+const backend = await createIndexedDBBackend();
+setWebSecureStorageBackend(backend);
+```
+
+See [web-backends.md](web-backends.md) for backend contracts and IndexedDB setup.
+
+## Release Checks
+
+Before releasing secure-storage changes, run:
+
+```sh
+bun run test -- --filter=react-native-nitro-storage
+bun run test:cpp -- --filter=react-native-nitro-storage
+bun run --cwd packages/react-native-nitro-storage check:pack
+```
+
+Also run an end-to-end auth flow on a locked/unlocked real device when changing biometric or Keychain behavior.

package/docs/web-backends.md

@@ -0,0 +1,141 @@
+# Web Backends
+
+Nitro Storage runs on web through synchronous backend contracts. Disk and Secure scopes can use different backends.
+
+The default web backend is localStorage-style. Configure custom backends when you need IndexedDB persistence, tests with isolated storage, cross-tab sync, or a platform-specific secret wrapper.
+
+## Backend Contract
+
+```ts
+import type { WebStorageBackend } from "react-native-nitro-storage";
+
+const backend: WebStorageBackend = {
+  name: "memory-test-backend",
+  getItem: (key) => map.get(key) ?? null,
+  setItem: (key, value) => {
+    map.set(key, value);
+  },
+  removeItem: (key) => {
+    map.delete(key);
+  },
+  clear: () => {
+    map.clear();
+  },
+  getAllKeys: () => Array.from(map.keys()),
+};
+```
+
+Optional methods improve performance and observability:
+
+- `getMany(keys)`
+- `setMany(entries)`
+- `removeMany(keys)`
+- `size()`
+- `subscribe(listener)`
+- `flush()`
+- `name`
+
+`subscribe(listener)` should report `{ key, newValue }` changes. Use `key: null` when the whole backend is cleared.
+
+## Disk Backend
+
+```ts
+import {
+  setWebDiskStorageBackend,
+  storage,
+  StorageScope,
+} from "react-native-nitro-storage";
+
+setWebDiskStorageBackend(backend);
+storage.setString("theme", "dark", StorageScope.Disk);
+```
+
+## Secure Backend
+
+```ts
+import {
+  setWebSecureStorageBackend,
+  storage,
+  StorageScope,
+} from "react-native-nitro-storage";
+
+setWebSecureStorageBackend(backend);
+storage.setString("auth:refreshToken", "opaque-token", StorageScope.Secure);
+```
+
+Web Secure storage is only as strong as the configured backend. Browser storage does not provide iOS Keychain or Android Keystore guarantees.
+
+## Flush Pending Web Writes
+
+Backends may persist asynchronously while serving reads synchronously from memory. Use `flushWebStorageBackends()` before assertions or page lifecycle boundaries.
+
+```ts
+import { flushWebStorageBackends } from "react-native-nitro-storage";
+
+await flushWebStorageBackends();
+```
+
+## IndexedDB Secure Backend
+
+`createIndexedDBBackend()` returns a `WebSecureStorageBackend` with a synchronous in-memory cache and asynchronous IndexedDB persistence.
+
+```ts
+import { setWebSecureStorageBackend } from "react-native-nitro-storage";
+import { createIndexedDBBackend } from "react-native-nitro-storage/indexeddb-backend";
+
+const backend = await createIndexedDBBackend("app-secure", "keyvalue", {
+  channelName: "app-secure-sync",
+  onError: (error) => {
+    console.error("IndexedDB secure storage failed", error);
+  },
+});
+
+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.
+
+## Cross-tab Updates
+
+The IndexedDB backend uses `BroadcastChannel` when available. Other tabs receive cache invalidation events and update their in-memory copy.
+
+If you provide your own backend, implement `subscribe(listener)` to keep Nitro Storage caches aligned with external writes.
+
+## Testing Backend
+
+```ts
+import type { WebStorageBackend } from "react-native-nitro-storage";
+
+export function createMemoryBackend(): WebStorageBackend {
+  const values = new Map<string, string>();
+  const listeners = new Set<
+    (event: { key: string | null; newValue: string | null }) => void
+  >();
+
+  function emit(key: string | null, newValue: string | null) {
+    listeners.forEach((listener) => listener({ key, newValue }));
+  }
+
+  return {
+    name: "memory",
+    getItem: (key) => values.get(key) ?? null,
+    setItem: (key, value) => {
+      values.set(key, value);
+      emit(key, value);
+    },
+    removeItem: (key) => {
+      values.delete(key);
+      emit(key, null);
+    },
+    clear: () => {
+      values.clear();
+      emit(null, null);
+    },
+    getAllKeys: () => Array.from(values.keys()),
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+```

package/lib/commonjs/index.js

@@ -113,6 +113,7 @@ let secureFlushScheduled = false;
 let secureDefaultAccessControl = _Storage.AccessControl.WhenUnlocked;
 let metricsObserver;
 const metricsCounters = new Map();
+const nativeSecureBackend = "platform-secure-storage";
 function recordMetric(operation, scope, durationMs, keysCount = 1) {
   const existing = metricsCounters.get(operation);
   if (!existing) {
@@ -654,7 +655,7 @@ const storage = exports.storage = {
     platform: "native",
     backend: {
       disk: "platform-preferences",
-      secure: "platform-secure-storage"
+      secure: nativeSecureBackend
     },
     writeBuffering: {
       disk: true,
@@ -662,6 +663,55 @@ const storage = exports.storage = {
     },
     errorClassification: true
   }),
+  getSecurityCapabilities: () => ({
+    platform: "native",
+    secureStorage: {
+      backend: nativeSecureBackend,
+      encrypted: "available",
+      accessControl: "unknown",
+      keychainAccessGroup: "unknown",
+      hardwareBacked: "unknown"
+    },
+    biometric: {
+      storage: "unknown",
+      prompt: "unknown",
+      biometryOnly: "unknown",
+      biometryOrPasscode: "unknown"
+    },
+    metadata: {
+      perKey: true,
+      listsWithoutValues: true,
+      persistsTimestamps: false
+    }
+  }),
+  getSecureMetadata: key => {
+    return measureOperation("storage:getSecureMetadata", _Storage.StorageScope.Secure, () => {
+      flushSecureWrites();
+      const storageModule = getStorageModule();
+      const biometricProtected = storageModule.hasSecureBiometric(key);
+      const exists = biometricProtected || storageModule.has(key, _Storage.StorageScope.Secure);
+      let kind = "missing";
+      if (exists) {
+        kind = biometricProtected ? "biometric" : "secure";
+      }
+      return {
+        key,
+        exists,
+        kind,
+        backend: nativeSecureBackend,
+        encrypted: "available",
+        hardwareBacked: "unknown",
+        biometricProtected,
+        valueExposed: false
+      };
+    });
+  },
+  getAllSecureMetadata: () => {
+    return measureOperation("storage:getAllSecureMetadata", _Storage.StorageScope.Secure, () => {
+      flushSecureWrites();
+      return getStorageModule().getAllKeys(_Storage.StorageScope.Secure).map(key => storage.getSecureMetadata(key));
+    });
+  },
   getString: (key, scope) => {
     return measureOperation("storage:getString", scope, () => {
       return getRawValue(key, scope);