react-native-nitro-storage 0.5.3 → 0.5.5

package/src/index.web.ts

@@ -54,6 +54,8 @@ export type {
   StorageKeyChangeEvent,
 } from "./storage-events";
 export type {
+  WebDiskStorageBackend,
+  WebSecureStorageBackend,
   WebStorageBackend,
   WebStorageChangeEvent,
   WebStorageScope,
@@ -75,6 +77,12 @@ export type StorageMetricsEvent = {
   keysCount: number;
 };
 export type StorageMetricsObserver = (event: StorageMetricsEvent) => void;
+export type StorageEventObserverOptions = {
+  redactSecureValues?: boolean;
+};
+export type StorageExportOptions = {
+  includeSecureValues?: boolean;
+};
 export type StorageMetricSummary = {
   count: number;
   totalDurationMs: number;
@@ -118,8 +126,24 @@ type RawBatchPathItem = {
   _hasValidation?: boolean;
   _hasExpiration?: boolean;
   _isBiometric?: boolean;
+  _biometricLevel?: BiometricLevel;
   _secureAccessControl?: AccessControl;
 };
+type RollbackRecord =
+  | {
+      kind: "memory";
+      value: unknown;
+    }
+  | {
+      kind: "raw";
+      value: string | undefined;
+      accessControl?: AccessControl;
+    }
+  | {
+      kind: "biometric";
+      value: string | undefined;
+      level: BiometricLevel;
+    };
 
 function asInternal<T>(item: StorageItem<T>): StorageItemInternal<T> {
   return item as StorageItemInternal<T>;
@@ -134,6 +158,27 @@ function isUpdater<T>(
 function typedKeys<K extends string, V>(record: Record<K, V>): K[] {
   return Object.keys(record) as K[];
 }
+function assertEnumInteger(
+  value: number,
+  min: number,
+  max: number,
+  label: string,
+): void {
+  if (!Number.isFinite(value) || value < min || value > max) {
+    throw new Error(`NitroStorage: Invalid ${label}`);
+  }
+  if (value !== Math.trunc(value)) {
+    throw new Error(`NitroStorage: Invalid ${label}`);
+  }
+}
+
+function assertAccessControlLevel(level: number): void {
+  assertEnumInteger(level, 0, 4, "access control level");
+}
+
+function assertBiometricLevel(level: number): void {
+  assertEnumInteger(level, 0, 2, "biometric level");
+}
 type NonMemoryScope = StorageScope.Disk | StorageScope.Secure;
 type PendingDiskWrite = {
   key: string;
@@ -217,6 +262,7 @@ let hasWarnedAboutWebBiometricFallback = false;
 let hasWindowStorageEventSubscription = false;
 let metricsObserver: StorageMetricsObserver | undefined;
 let eventObserver: StorageEventListener | undefined;
+let eventObserverRedactSecureValues = true;
 const metricsCounters = new Map<
   string,
   { count: number; totalDurationMs: number; maxDurationMs: number }
@@ -515,6 +561,21 @@ function resetBackendChangeSubscription(scope: NonMemoryScope): void {
   externalSyncUnsubscribers.delete(scope);
 }
 
+function closeWebBackend(
+  scope: NonMemoryScope,
+  backend: WebStorageBackend | undefined,
+): void {
+  if (!backend?.close) {
+    return;
+  }
+
+  try {
+    backend.close();
+  } catch (error) {
+    throw createWebStorageError(scope, "close", error, backend);
+  }
+}
+
 function ensureExternalSyncSubscriptions(): void {
   if (
     !hasWindowStorageEventSubscription &&
@@ -638,6 +699,49 @@ function hasStorageChangeObservers(scope: StorageScope): boolean {
   return storageEvents.hasListeners(scope) || eventObserver !== undefined;
 }
 
+function shouldReadPreviousEventValues(scope: StorageScope): boolean {
+  if (storageEvents.hasListeners(scope)) {
+    return true;
+  }
+  if (!eventObserver) {
+    return false;
+  }
+  return scope !== StorageScope.Secure || !eventObserverRedactSecureValues;
+}
+
+const SECURE_EVENT_REDACTED_VALUE = "[secure]";
+
+function redactSecureKeyChange(
+  event: StorageKeyChangeEvent,
+): StorageKeyChangeEvent {
+  if (event.scope !== StorageScope.Secure) {
+    return event;
+  }
+
+  return {
+    ...event,
+    oldValue:
+      event.oldValue === undefined ? undefined : SECURE_EVENT_REDACTED_VALUE,
+    newValue:
+      event.newValue === undefined ? undefined : SECURE_EVENT_REDACTED_VALUE,
+  };
+}
+
+function eventForGlobalObserver(event: StorageChangeEvent): StorageChangeEvent {
+  if (!eventObserverRedactSecureValues || event.scope !== StorageScope.Secure) {
+    return event;
+  }
+
+  if (event.type === "key") {
+    return redactSecureKeyChange(event);
+  }
+
+  return {
+    ...event,
+    changes: event.changes.map(redactSecureKeyChange),
+  };
+}
+
 function emitKeyChange(
   scope: StorageScope,
   key: string,
@@ -655,7 +759,7 @@ function emitKeyChange(
     source,
   );
   storageEvents.emitKey(event);
-  eventObserver?.(event);
+  eventObserver?.(eventForGlobalObserver(event));
 }
 
 function emitBatchChange(
@@ -676,7 +780,7 @@ function emitBatchChange(
     changes,
   };
   storageEvents.emitBatch(event);
-  eventObserver?.(event);
+  eventObserver?.(eventForGlobalObserver(event));
 }
 
 function readPendingSecureWrite(key: string): string | undefined {
@@ -866,6 +970,11 @@ const WebStorage: Storage = {
     if (scope !== StorageScope.Disk && scope !== StorageScope.Secure) {
       return;
     }
+    if (keys.length !== values.length) {
+      throw new Error(
+        "NitroStorage: Keys and values size mismatch in setBatch",
+      );
+    }
 
     const entries: (readonly [string, string])[] = [];
     keys.forEach((key, index) => {
@@ -888,7 +997,13 @@ const WebStorage: Storage = {
       });
     });
     const keyIndex = ensureWebScopeKeyIndex(scope);
-    keys.forEach((key) => keyIndex.add(key));
+    entries.forEach(([storageKey]) =>
+      keyIndex.add(
+        scope === StorageScope.Secure
+          ? storageKey.slice(SECURE_WEB_PREFIX.length)
+          : storageKey,
+      ),
+    );
     const listeners = getScopedListeners(scope);
     keys.forEach((key) => notifyKeyListeners(listeners, key));
   },
@@ -988,7 +1103,9 @@ const WebStorage: Storage = {
     }
     return 0;
   },
-  setSecureAccessControl: () => {},
+  setSecureAccessControl: (level: number) => {
+    assertAccessControlLevel(level);
+  },
   setSecureWritesAsync: (_enabled: boolean) => {},
   setKeychainAccessGroup: () => {},
   setSecureBiometric: (key: string, value: string) => {
@@ -998,7 +1115,17 @@ const WebStorage: Storage = {
       BiometricLevel.BiometryOnly,
     );
   },
-  setSecureBiometricWithLevel: (key: string, value: string, _level: number) => {
+  setSecureBiometricWithLevel: (key: string, value: string, level: number) => {
+    assertBiometricLevel(level);
+    if (level === BiometricLevel.None) {
+      withWebBackendOperation(StorageScope.Secure, "setSecure", (backend) => {
+        backend.removeItem(toBiometricStorageKey(key));
+        backend.setItem(toSecureStorageKey(key), value);
+      });
+      ensureWebScopeKeyIndex(StorageScope.Secure).add(key);
+      notifyKeyListeners(getScopedListeners(StorageScope.Secure), key);
+      return;
+    }
     if (
       typeof __DEV__ !== "undefined" &&
       __DEV__ &&
@@ -1233,15 +1360,19 @@ export const storage = {
   ): (() => void) => {
     return storage.subscribePrefix(scope, prefixKey(namespace, ""), listener);
   },
-  setEventObserver: (observer?: StorageEventListener) => {
+  setEventObserver: (
+    observer?: StorageEventListener,
+    options: StorageEventObserverOptions = {},
+  ) => {
     eventObserver = observer;
+    eventObserverRedactSecureValues = options.redactSecureValues !== false;
     if (observer) {
       ensureExternalSyncSubscriptions();
     }
   },
   clear: (scope: StorageScope) => {
     measureOperation("storage:clear", scope, () => {
-      const previousValues = hasStorageChangeObservers(scope)
+      const previousValues = shouldReadPreviousEventValues(scope)
         ? storage.getAll(scope)
         : {};
       if (scope === StorageScope.Memory) {
@@ -1345,7 +1476,7 @@ export const storage = {
       }
 
       const keyPrefix = prefixKey(namespace, "");
-      const previousValues = hasStorageChangeObservers(scope)
+      const previousValues = shouldReadPreviousEventValues(scope)
         ? storage.getByPrefix(keyPrefix, scope)
         : {};
       if (scope === StorageScope.Disk) {
@@ -1491,11 +1622,26 @@ export const storage = {
       return result;
     });
   },
-  export: (scope: StorageScope): Record<string, string> => {
+  export: (
+    scope: StorageScope,
+    options: StorageExportOptions = {},
+  ): Record<string, string> => {
+    if (scope === StorageScope.Secure && options.includeSecureValues !== true) {
+      throw new Error(
+        "NitroStorage: exporting Secure scope exposes raw secret values. Pass { includeSecureValues: true } or use exportSecureUnsafe().",
+      );
+    }
     return measureOperation("storage:export", scope, () =>
       storage.getAll(scope),
     );
   },
+  exportSecureUnsafe: (): Record<string, string> => {
+    return measureOperation(
+      "storage:exportSecureUnsafe",
+      StorageScope.Secure,
+      () => storage.getAll(StorageScope.Secure),
+    );
+  },
   size: (scope: StorageScope): number => {
     return measureOperation("storage:size", scope, () => {
       assertValidScope(scope);
@@ -1510,6 +1656,7 @@ export const storage = {
     });
   },
   setAccessControl: (level: AccessControl) => {
+    assertAccessControlLevel(level);
     secureDefaultAccessControl = level;
     recordMetric("storage:setAccessControl", StorageScope.Secure, 0);
   },
@@ -1698,12 +1845,17 @@ export const storage = {
 export function setWebSecureStorageBackend(
   backend?: WebSecureStorageBackend,
 ): void {
+  const previousBackend = webSecureStorageBackend;
+  const nextBackend = backend ?? createDefaultSecureBackend();
   pendingSecureWrites.clear();
-  webSecureStorageBackend = backend ?? createDefaultSecureBackend();
   resetBackendChangeSubscription(StorageScope.Secure);
+  webSecureStorageBackend = nextBackend;
   hydratedWebScopeKeyIndex.delete(StorageScope.Secure);
   clearScopeRawCache(StorageScope.Secure);
   ensureExternalSyncSubscriptions();
+  if (previousBackend !== nextBackend) {
+    closeWebBackend(StorageScope.Secure, previousBackend);
+  }
 }
 
 export function getWebSecureStorageBackend():
@@ -1715,12 +1867,17 @@ export function getWebSecureStorageBackend():
 export function setWebDiskStorageBackend(
   backend?: WebDiskStorageBackend,
 ): void {
+  const previousBackend = webDiskStorageBackend;
+  const nextBackend = backend ?? createDefaultDiskBackend();
   pendingDiskWrites.clear();
-  webDiskStorageBackend = backend ?? createDefaultDiskBackend();
   resetBackendChangeSubscription(StorageScope.Disk);
+  webDiskStorageBackend = nextBackend;
   hydratedWebScopeKeyIndex.delete(StorageScope.Disk);
   clearScopeRawCache(StorageScope.Disk);
   ensureExternalSyncSubscriptions();
+  if (previousBackend !== nextBackend) {
+    closeWebBackend(StorageScope.Disk, previousBackend);
+  }
 }
 
 export function getWebDiskStorageBackend(): WebDiskStorageBackend | undefined {
@@ -1793,6 +1950,7 @@ type StorageItemInternal<T> = StorageItem<T> & {
   _hasExpiration: boolean;
   _readCacheEnabled: boolean;
   _isBiometric: boolean;
+  _biometricLevel: BiometricLevel;
   _defaultValue: T;
   _secureAccessControl?: AccessControl;
 };
@@ -1863,6 +2021,12 @@ export function createStorageItem<T = undefined>(
   if (expiration && expiration.ttlMs <= 0) {
     throw new Error("expiration.ttlMs must be greater than 0.");
   }
+  if (config.scope === StorageScope.Secure) {
+    assertBiometricLevel(resolvedBiometricLevel);
+    if (secureAccessControl !== undefined) {
+      assertAccessControlLevel(secureAccessControl);
+    }
+  }
 
   const listeners = new Set<() => void>();
   let unsubscribe: (() => void) | null = null;
@@ -2350,6 +2514,7 @@ export function createStorageItem<T = undefined>(
     _hasExpiration: expiration !== undefined,
     _readCacheEnabled: readCache,
     _isBiometric: isBiometric,
+    _biometricLevel: resolvedBiometricLevel,
     _defaultValue: defaultValue,
     ...(secureAccessControl !== undefined
       ? { _secureAccessControl: secureAccessControl }
@@ -2528,7 +2693,7 @@ export function setBatch<T>(
 
         flushSecureWrites();
         const keys = secureEntries.map(({ item }) => item.key);
-        const oldValues = hasStorageChangeObservers(scope)
+        const oldValues = shouldReadPreviousEventValues(scope)
           ? WebStorage.getBatch(keys, scope)
           : [];
         const groupedByAccessControl = new Map<
@@ -2585,7 +2750,7 @@ export function setBatch<T>(
 
       const keys = items.map((entry) => entry.item.key);
       const values = items.map((entry) => entry.item.serialize(entry.value));
-      const oldValues = hasStorageChangeObservers(scope)
+      const oldValues = shouldReadPreviousEventValues(scope)
         ? WebStorage.getBatch(keys, scope)
         : [];
       WebStorage.setBatch(keys, values, scope);
@@ -2643,7 +2808,7 @@ export function removeBatch(
       if (scope === StorageScope.Secure) {
         flushSecureWrites();
       }
-      const oldValues = hasStorageChangeObservers(scope)
+      const oldValues = shouldReadPreviousEventValues(scope)
         ? WebStorage.getBatch(keys, scope)
         : [];
       WebStorage.removeBatch(keys, scope);
@@ -2729,19 +2894,40 @@ export function runTransaction<T>(
     }
 
     const NOT_SET = Symbol();
-    const rollback = new Map<string, unknown>();
+    const rollback = new Map<string, RollbackRecord>();
 
-    const rememberRollback = (key: string) => {
+    const rememberRollback = (
+      key: string,
+      item?: Pick<StorageItem<unknown>, "key" | "scope">,
+    ) => {
       if (rollback.has(key)) {
         return;
       }
       if (scope === StorageScope.Memory) {
-        rollback.set(
-          key,
-          memoryStore.has(key) ? memoryStore.get(key) : NOT_SET,
-        );
+        rollback.set(key, {
+          kind: "memory",
+          value: memoryStore.has(key) ? memoryStore.get(key) : NOT_SET,
+        });
       } else {
-        rollback.set(key, getRawValue(key, scope));
+        const internal = item
+          ? (item as StorageItemInternal<unknown>)
+          : undefined;
+        if (scope === StorageScope.Secure && internal?._isBiometric === true) {
+          rollback.set(key, {
+            kind: "biometric",
+            value: WebStorage.getSecureBiometric(key),
+            level: internal._biometricLevel,
+          });
+          return;
+        }
+        rollback.set(key, {
+          kind: "raw",
+          value: getRawValue(key, scope),
+          ...(scope === StorageScope.Secure &&
+          internal?._secureAccessControl !== undefined
+            ? { accessControl: internal._secureAccessControl }
+            : {}),
+        });
       }
     };
 
@@ -2762,12 +2948,12 @@ export function runTransaction<T>(
       },
       setItem: (item, value) => {
         assertBatchScope([item], scope);
-        rememberRollback(item.key);
+        rememberRollback(item.key, item);
         item.set(value);
       },
       removeItem: (item) => {
         assertBatchScope([item], scope);
-        rememberRollback(item.key);
+        rememberRollback(item.key, item);
         item.delete();
       },
     };
@@ -2777,25 +2963,49 @@ export function runTransaction<T>(
     } catch (error) {
       const rollbackEntries = Array.from(rollback.entries()).reverse();
       if (scope === StorageScope.Memory) {
-        rollbackEntries.forEach(([key, previousValue]) => {
-          if (previousValue === NOT_SET) {
+        rollbackEntries.forEach(([key, record]) => {
+          if (record.value === NOT_SET) {
             memoryStore.delete(key);
           } else {
-            memoryStore.set(key, previousValue);
+            memoryStore.set(key, record.value);
           }
           notifyKeyListeners(memoryListeners, key);
         });
       } else {
-        const keysToSet: string[] = [];
-        const valuesToSet: string[] = [];
+        const groupedKeysToSet = new Map<
+          AccessControl,
+          { keys: string[]; values: string[] }
+        >();
         const keysToRemove: string[] = [];
 
-        rollbackEntries.forEach(([key, previousValue]) => {
-          if (previousValue === undefined) {
+        rollbackEntries.forEach(([key, record]) => {
+          if (record.kind === "biometric") {
+            if (record.value === undefined) {
+              WebStorage.deleteSecureBiometric(key);
+            } else {
+              WebStorage.setSecureBiometricWithLevel(
+                key,
+                record.value,
+                record.level,
+              );
+            }
+            return;
+          }
+          if (record.kind !== "raw") {
+            return;
+          }
+          if (record.value === undefined) {
             keysToRemove.push(key);
           } else {
-            keysToSet.push(key);
-            valuesToSet.push(previousValue as string);
+            const accessControl =
+              record.accessControl ?? secureDefaultAccessControl;
+            const existingGroup = groupedKeysToSet.get(accessControl);
+            const group = existingGroup ?? { keys: [], values: [] };
+            group.keys.push(key);
+            group.values.push(record.value);
+            if (!existingGroup) {
+              groupedKeysToSet.set(accessControl, group);
+            }
           }
         });
 
@@ -2805,12 +3015,15 @@ export function runTransaction<T>(
         if (scope === StorageScope.Secure) {
           flushSecureWrites();
         }
-        if (keysToSet.length > 0) {
-          WebStorage.setBatch(keysToSet, valuesToSet, scope);
-          keysToSet.forEach((key, index) =>
-            cacheRawValue(scope, key, valuesToSet[index]),
+        groupedKeysToSet.forEach((group, accessControl) => {
+          if (scope === StorageScope.Secure) {
+            WebStorage.setSecureAccessControl(accessControl);
+          }
+          WebStorage.setBatch(group.keys, group.values, scope);
+          group.keys.forEach((key, index) =>
+            cacheRawValue(scope, key, group.values[index]),
           );
-        }
+        });
         if (keysToRemove.length > 0) {
           WebStorage.removeBatch(keysToRemove, scope);
           keysToRemove.forEach((key) => cacheRawValue(scope, key, undefined));

package/src/indexeddb-backend.ts

@@ -74,6 +74,7 @@ export async function createIndexedDBBackend(
   const pendingWrites = new Set<Promise<void>>();
   const pendingErrors: Error[] = [];
   const subscribers = new Set<(event: WebStorageChangeEvent) => void>();
+  let closed = false;
   const sourceId = `nitro-storage-${Math.random().toString(36).slice(2)}`;
   const channelName =
     options.channelName ?? `nitro-storage:${dbName}:${storeName}`;
@@ -82,6 +83,12 @@ export async function createIndexedDBBackend(
       ? new BroadcastChannel(channelName)
       : null;
 
+  function assertOpen(): void {
+    if (closed) {
+      throw new Error(`IndexedDB backend "${dbName}/${storeName}" is closed.`);
+    }
+  }
+
   function emitExternal(event: WebStorageChangeEvent): void {
     subscribers.forEach((subscriber) => {
       subscriber(event);
@@ -98,6 +105,10 @@ export async function createIndexedDBBackend(
   }
 
   channel?.addEventListener("message", (event: MessageEvent) => {
+    if (closed) {
+      return;
+    }
+
     const data = event.data as
       | (WebStorageChangeEvent & { sourceId?: string })
       | undefined;
@@ -209,34 +220,41 @@ export async function createIndexedDBBackend(
   const backend: WebSecureStorageBackend = {
     name: `indexeddb:${dbName}/${storeName}`,
     getItem(key: string): string | null {
+      assertOpen();
       return cache.get(key) ?? null;
     },
 
     setItem(key: string, value: string): void {
+      assertOpen();
       cache.set(key, value);
       persistSet(key, value);
       publish({ key, newValue: value });
     },
 
     removeItem(key: string): void {
+      assertOpen();
       cache.delete(key);
       persistDelete(key);
       publish({ key, newValue: null });
     },
 
     clear(): void {
+      assertOpen();
       cache.clear();
       persistClear();
       publish({ key: null, newValue: null });
     },
 
     getAllKeys(): string[] {
+      assertOpen();
       return Array.from(cache.keys());
     },
     getMany(keys: string[]): (string | null)[] {
+      assertOpen();
       return keys.map((key) => cache.get(key) ?? null);
     },
     setMany(entries): void {
+      assertOpen();
       entries.forEach(([key, value]) => {
         cache.set(key, value);
       });
@@ -253,6 +271,7 @@ export async function createIndexedDBBackend(
       }
     },
     removeMany(keys: string[]): void {
+      assertOpen();
       keys.forEach((key) => {
         cache.delete(key);
       });
@@ -269,9 +288,11 @@ export async function createIndexedDBBackend(
       }
     },
     size(): number {
+      assertOpen();
       return cache.size;
     },
     subscribe(listener): () => void {
+      assertOpen();
       subscribers.add(listener);
       return () => {
         subscribers.delete(listener);
@@ -286,6 +307,15 @@ export async function createIndexedDBBackend(
       const [error] = pendingErrors.splice(0);
       throw error;
     },
+    close(): void {
+      if (closed) {
+        return;
+      }
+      closed = true;
+      subscribers.clear();
+      channel?.close();
+      db.close();
+    },
   };
 
   return backend;

package/src/web-storage-backend.ts

@@ -21,6 +21,7 @@ export type WebStorageBackend = {
   size?: () => number;
   subscribe?: (listener: (event: WebStorageChangeEvent) => void) => () => void;
   flush?: () => Promise<void>;
+  close?: () => void;
   name?: string;
 };