react-native-nitro-storage 0.4.5 → 0.5.1

package/docs/react-hooks.md

@@ -0,0 +1,113 @@
+# React Hooks
+
+Nitro Storage hooks connect a `StorageItem<T>` to React with `useSyncExternalStore`. No provider is needed, and the same item can also be used outside React.
+
+Keep storage items at module scope. Creating items during render creates new subscriptions and breaks cache reuse.
+
+## useStorage
+
+Use `useStorage(item)` when a component both reads and writes the full value.
+
+```tsx
+import {
+  createStorageItem,
+  StorageScope,
+  useStorage,
+} from "react-native-nitro-storage";
+
+const themeItem = createStorageItem({
+  key: "theme",
+  scope: StorageScope.Disk,
+  defaultValue: "system",
+});
+
+export function ThemeToggle() {
+  const [theme, setTheme] = useStorage(themeItem);
+
+  return (
+    <Button
+      title={theme}
+      onPress={() => setTheme(theme === "dark" ? "light" : "dark")}
+    />
+  );
+}
+```
+
+Updater functions read the current stored value first:
+
+```ts
+const countItem = createStorageItem({
+  key: "count",
+  scope: StorageScope.Memory,
+  defaultValue: 0,
+});
+
+const [, setCount] = useStorage(countItem);
+setCount((current) => current + 1);
+```
+
+Direct `set(value)` writes do not read the current value first.
+
+## useStorageSelector
+
+Use `useStorageSelector(item, selector, isEqual?)` when the stored value is larger than what the component renders.
+
+```tsx
+type Profile = {
+  name: string;
+  email: string;
+  plan: "free" | "pro";
+};
+
+const profileItem = createStorageItem<Profile>({
+  key: "profile",
+  scope: StorageScope.Disk,
+  defaultValue: { name: "", email: "", plan: "free" },
+});
+
+export function PlanBadge() {
+  const [plan] = useStorageSelector(profileItem, (profile) => profile.plan);
+  return <Text>{plan}</Text>;
+}
+```
+
+Pass a custom equality function when the selector returns an object:
+
+```ts
+const [contact] = useStorageSelector(
+  profileItem,
+  (profile) => ({ name: profile.name, email: profile.email }),
+  (prev, next) => prev.name === next.name && prev.email === next.email,
+);
+```
+
+## useSetStorage
+
+Use `useSetStorage(item)` for controls that write without rendering from the value.
+
+```tsx
+const dismissItem = createStorageItem({
+  key: "welcomeDismissed",
+  scope: StorageScope.Disk,
+  defaultValue: false,
+});
+
+export function DismissWelcomeButton() {
+  const setDismissed = useSetStorage(dismissItem);
+  return <Button title="Dismiss" onPress={() => setDismissed(true)} />;
+}
+```
+
+## Subscribe Outside React
+
+Every item has a low-level subscription API:
+
+```ts
+const unsubscribe = themeItem.subscribe(() => {
+  analytics.track("theme_changed", { theme: themeItem.get() });
+});
+
+unsubscribe();
+```
+
+Subscriptions fire after item writes and after TTL expiry is detected during a read.

package/docs/recipes.md

@@ -0,0 +1,302 @@
+# 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 and Export
+
+```ts
+const snapshot = storage.export(StorageScope.Disk);
+
+storage.import(snapshot, StorageScope.Disk);
+```
+
+Raw export/import reads and writes strings exactly as stored. It does not run item serializers. Secure exports contain raw secret values, so do not log them or attach them to diagnostics.
+
+## 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();
+```
+
+## Event Logging
+
+```ts
+const unsubscribe = storage.subscribePrefix(
+  StorageScope.Disk,
+  "settings:",
+  (event) => {
+    if (event.type === "batch") {
+      console.log("settings changed", event.changes.length);
+      return;
+    }
+
+    console.log(event.key, event.operation);
+  },
+);
+
+storage.setEventObserver((event) => {
+  if (event.scope !== StorageScope.Secure) {
+    console.log(event.type, event.operation);
+  }
+});
+```
+
+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.
+
+## 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,190 @@
+# 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.
+
+## Secure Export Warning
+
+`storage.export(StorageScope.Secure)` returns raw secret values so it can round-trip with `storage.import(data, StorageScope.Secure)`.
+
+```ts
+import { storage, StorageScope } from "react-native-nitro-storage";
+
+const secureSnapshot = storage.export(StorageScope.Secure);
+storage.import(secureSnapshot, StorageScope.Secure);
+```
+
+Only keep Secure exports in memory for the shortest possible workflow. Do not log them or include them in diagnostics, analytics, crash reports, or support bundles.
+
+## Secure Event Warning
+
+Secure scope event subscriptions and `storage.setEventObserver()` can receive raw secret values in `oldValue`, `newValue`, or batch `changes`.
+
+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.
+
+## 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.