react-native-nitro-storage 0.4.4 → 0.5.0

package/src/indexeddb-backend.ts

@@ -1,9 +1,17 @@
-import type { WebSecureStorageBackend } from "./index.web";
+import type {
+  WebSecureStorageBackend,
+  WebStorageChangeEvent,
+} from "./web-storage-backend";
 
 const DEFAULT_DB_NAME = "nitro-storage-secure";
 const DEFAULT_STORE_NAME = "keyvalue";
 const DB_VERSION = 1;
 
+export type IndexedDBBackendOptions = {
+  channelName?: string;
+  onError?: (error: Error) => void;
+};
+
 /**
  * Opens (or creates) an IndexedDB database and returns the underlying IDBDatabase.
  * Rejects if IndexedDB is unavailable in the current environment.
@@ -59,9 +67,62 @@ function openDB(dbName: string, storeName: string): Promise<IDBDatabase> {
 export async function createIndexedDBBackend(
   dbName = DEFAULT_DB_NAME,
   storeName = DEFAULT_STORE_NAME,
+  options: IndexedDBBackendOptions = {},
 ): Promise<WebSecureStorageBackend> {
   const db = await openDB(dbName, storeName);
   const cache = new Map<string, string>();
+  const pendingWrites = new Set<Promise<void>>();
+  const subscribers = new Set<(event: WebStorageChangeEvent) => void>();
+  const sourceId = `nitro-storage-${Math.random().toString(36).slice(2)}`;
+  const channelName =
+    options.channelName ?? `nitro-storage:${dbName}:${storeName}`;
+  const channel =
+    typeof BroadcastChannel !== "undefined"
+      ? new BroadcastChannel(channelName)
+      : null;
+
+  function emitExternal(event: WebStorageChangeEvent): void {
+    subscribers.forEach((subscriber) => {
+      subscriber(event);
+    });
+  }
+
+  function handleAsyncError(error: unknown): void {
+    const normalized =
+      error instanceof Error
+        ? error
+        : new Error(String(error ?? "Unknown IndexedDB error"));
+    options.onError?.(normalized);
+  }
+
+  channel?.addEventListener("message", (event: MessageEvent) => {
+    const data = event.data as
+      | (WebStorageChangeEvent & { sourceId?: string })
+      | undefined;
+    if (!data || data.sourceId === sourceId) {
+      return;
+    }
+
+    if (data.key === null) {
+      cache.clear();
+    } else if (data.newValue === null) {
+      cache.delete(data.key);
+    } else {
+      cache.set(data.key, data.newValue);
+    }
+
+    emitExternal({
+      key: data.key,
+      newValue: data.newValue,
+    });
+  });
+
+  function publish(event: WebStorageChangeEvent): void {
+    channel?.postMessage({
+      ...event,
+      sourceId,
+    });
+  }
 
   // Hydrate the in-memory cache from IndexedDB.
   await new Promise<void>((resolve, reject) => {
@@ -85,14 +146,39 @@ export async function createIndexedDBBackend(
       reject(tx.error ?? new Error("Failed to load IndexedDB entries."));
   });
 
-  /** Fire-and-forget IndexedDB write. Errors are silently ignored to avoid
-   *  breaking the synchronous caller — the in-memory cache is always authoritative. */
+  function trackWrite(tx: IDBTransaction): void {
+    const pending = new Promise<void>((resolve) => {
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => {
+        handleAsyncError(
+          tx.error ?? new Error("Failed to persist IndexedDB transaction."),
+        );
+        resolve();
+      };
+      tx.onabort = () => {
+        handleAsyncError(
+          tx.error ?? new Error("IndexedDB transaction was aborted."),
+        );
+        resolve();
+      };
+    });
+    pendingWrites.add(pending);
+    void pending.finally(() => {
+      pendingWrites.delete(pending);
+    });
+  }
+
+  /** Fire-and-forget IndexedDB write. The in-memory cache remains authoritative,
+   *  but async persistence failures are surfaced through `onError` and `flush()`. */
   function persistSet(key: string, value: string): void {
     try {
       const tx = db.transaction(storeName, "readwrite");
       tx.objectStore(storeName).put(value, key);
+      trackWrite(tx);
     } catch {
-      // Best-effort; cache is the source of truth.
+      handleAsyncError(
+        new Error(`Failed to queue IndexedDB write for "${key}".`),
+      );
     }
   }
 
@@ -100,8 +186,11 @@ export async function createIndexedDBBackend(
     try {
       const tx = db.transaction(storeName, "readwrite");
       tx.objectStore(storeName).delete(key);
+      trackWrite(tx);
     } catch {
-      // Best-effort.
+      handleAsyncError(
+        new Error(`Failed to queue IndexedDB delete for "${key}".`),
+      );
     }
   }
 
@@ -109,12 +198,14 @@ export async function createIndexedDBBackend(
     try {
       const tx = db.transaction(storeName, "readwrite");
       tx.objectStore(storeName).clear();
+      trackWrite(tx);
     } catch {
-      // Best-effort.
+      handleAsyncError(new Error("Failed to queue IndexedDB clear."));
     }
   }
 
   const backend: WebSecureStorageBackend = {
+    name: `indexeddb:${dbName}/${storeName}`,
     getItem(key: string): string | null {
       return cache.get(key) ?? null;
     },
@@ -122,21 +213,71 @@ export async function createIndexedDBBackend(
     setItem(key: string, value: string): void {
       cache.set(key, value);
       persistSet(key, value);
+      publish({ key, newValue: value });
     },
 
     removeItem(key: string): void {
       cache.delete(key);
       persistDelete(key);
+      publish({ key, newValue: null });
     },
 
     clear(): void {
       cache.clear();
       persistClear();
+      publish({ key: null, newValue: null });
     },
 
     getAllKeys(): string[] {
       return Array.from(cache.keys());
     },
+    getMany(keys: string[]): (string | null)[] {
+      return keys.map((key) => cache.get(key) ?? null);
+    },
+    setMany(entries): void {
+      entries.forEach(([key, value]) => {
+        cache.set(key, value);
+      });
+      try {
+        const tx = db.transaction(storeName, "readwrite");
+        const store = tx.objectStore(storeName);
+        entries.forEach(([key, value]) => {
+          store.put(value, key);
+          publish({ key, newValue: value });
+        });
+        trackWrite(tx);
+      } catch {
+        handleAsyncError(new Error("Failed to queue IndexedDB batch write."));
+      }
+    },
+    removeMany(keys: string[]): void {
+      keys.forEach((key) => {
+        cache.delete(key);
+      });
+      try {
+        const tx = db.transaction(storeName, "readwrite");
+        const store = tx.objectStore(storeName);
+        keys.forEach((key) => {
+          store.delete(key);
+          publish({ key, newValue: null });
+        });
+        trackWrite(tx);
+      } catch {
+        handleAsyncError(new Error("Failed to queue IndexedDB batch delete."));
+      }
+    },
+    size(): number {
+      return cache.size;
+    },
+    subscribe(listener): () => void {
+      subscribers.add(listener);
+      return () => {
+        subscribers.delete(listener);
+      };
+    },
+    async flush(): Promise<void> {
+      await Promise.all(Array.from(pendingWrites));
+    },
   };
 
   return backend;

package/src/storage-runtime.ts

@@ -0,0 +1,129 @@
+export type StorageErrorCode =
+  | "keychain_locked"
+  | "authentication_required"
+  | "key_invalidated"
+  | "storage_corruption"
+  | "biometric_unavailable"
+  | "unsupported";
+
+export type StorageCapabilities = {
+  platform: "native" | "web";
+  backend: {
+    disk: string;
+    secure: string;
+  };
+  writeBuffering: {
+    disk: boolean;
+    secure: boolean;
+  };
+  errorClassification: boolean;
+};
+
+export type SecurityCapabilityStatus = "available" | "unavailable" | "unknown";
+
+export type SecurityCapabilities = {
+  platform: "native" | "web";
+  secureStorage: {
+    backend: string;
+    encrypted: SecurityCapabilityStatus;
+    accessControl: SecurityCapabilityStatus;
+    keychainAccessGroup: SecurityCapabilityStatus;
+    hardwareBacked: SecurityCapabilityStatus;
+  };
+  biometric: {
+    storage: SecurityCapabilityStatus;
+    prompt: SecurityCapabilityStatus;
+    biometryOnly: SecurityCapabilityStatus;
+    biometryOrPasscode: SecurityCapabilityStatus;
+  };
+  metadata: {
+    perKey: boolean;
+    listsWithoutValues: boolean;
+    persistsTimestamps: boolean;
+  };
+};
+
+export type SecureStorageMetadata = {
+  key: string;
+  exists: boolean;
+  kind: "secure" | "biometric" | "missing";
+  backend: string;
+  encrypted: SecurityCapabilityStatus;
+  hardwareBacked: SecurityCapabilityStatus;
+  biometricProtected: boolean;
+  valueExposed: false;
+};
+
+const STORAGE_ERROR_TAG_PATTERN = /\[nitro-error:([a-z_]+)\]/;
+
+export function getStorageErrorCode(
+  err: unknown,
+): StorageErrorCode | undefined {
+  if (!(err instanceof Error)) {
+    return undefined;
+  }
+
+  const message = err.message;
+  const taggedCode = message.match(STORAGE_ERROR_TAG_PATTERN)?.[1];
+
+  if (
+    taggedCode === "keychain_locked" ||
+    taggedCode === "authentication_required" ||
+    taggedCode === "key_invalidated" ||
+    taggedCode === "storage_corruption" ||
+    taggedCode === "biometric_unavailable" ||
+    taggedCode === "unsupported"
+  ) {
+    return taggedCode;
+  }
+
+  if (message.includes("errSecInteractionNotAllowed")) {
+    return "keychain_locked";
+  }
+
+  if (
+    message.includes("UserNotAuthenticatedException") ||
+    message.includes("KeyStoreException") ||
+    message.includes("android.security.keystore")
+  ) {
+    return "authentication_required";
+  }
+
+  if (
+    message.includes("KeyPermanentlyInvalidatedException") ||
+    message.includes("InvalidKeyException")
+  ) {
+    return "key_invalidated";
+  }
+
+  if (
+    message.includes("AEADBadTagException") ||
+    message.toLowerCase().includes("storage corruption") ||
+    message.toLowerCase().includes("corrupted storage")
+  ) {
+    return "storage_corruption";
+  }
+
+  if (
+    message.toLowerCase().includes("biometric storage unavailable") ||
+    message.toLowerCase().includes("biometric storage is not available")
+  ) {
+    return "biometric_unavailable";
+  }
+
+  if (message.toLowerCase().includes("unsupported")) {
+    return "unsupported";
+  }
+
+  return undefined;
+}
+
+export function isLockedStorageErrorCode(
+  code: StorageErrorCode | undefined,
+): boolean {
+  return (
+    code === "keychain_locked" ||
+    code === "authentication_required" ||
+    code === "key_invalidated"
+  );
+}

package/src/web-storage-backend.ts

@@ -0,0 +1,129 @@
+import { StorageScope } from "./Storage.types";
+
+export type WebStorageChangeEvent = {
+  key: string | null;
+  newValue: string | null;
+};
+
+export type WebStorageScope = StorageScope.Disk | StorageScope.Secure;
+
+export type WebStorageBackend = {
+  getItem: (key: string) => string | null;
+  setItem: (key: string, value: string) => void;
+  removeItem: (key: string) => void;
+  clear: () => void;
+  getAllKeys: () => string[];
+  getMany?: (keys: string[]) => (string | null)[];
+  setMany?: (
+    entries: readonly (readonly [key: string, value: string])[],
+  ) => void;
+  removeMany?: (keys: string[]) => void;
+  size?: () => number;
+  subscribe?: (listener: (event: WebStorageChangeEvent) => void) => () => void;
+  flush?: () => Promise<void>;
+  name?: string;
+};
+
+export type WebDiskStorageBackend = WebStorageBackend;
+export type WebSecureStorageBackend = WebStorageBackend;
+
+type LocalStorageBackendOptions = {
+  includeKey?: (key: string) => boolean;
+  name?: string;
+  resolveStorage?: () => Storage | undefined;
+};
+
+function getResolvedStorage(
+  resolveStorage: (() => Storage | undefined) | undefined,
+): Storage | undefined {
+  if (resolveStorage) {
+    return resolveStorage();
+  }
+
+  if (typeof globalThis.localStorage === "undefined") {
+    return undefined;
+  }
+
+  return globalThis.localStorage;
+}
+
+export function createLocalStorageWebBackend(
+  options: LocalStorageBackendOptions = {},
+): WebStorageBackend {
+  const includeKey = options.includeKey;
+  const resolveStorage = options.resolveStorage;
+
+  const listKeys = (): string[] => {
+    const storage = getResolvedStorage(resolveStorage);
+    if (!storage) {
+      return [];
+    }
+
+    const keys: string[] = [];
+    for (let index = 0; index < storage.length; index += 1) {
+      const key = storage.key(index);
+      if (!key) {
+        continue;
+      }
+      if (includeKey && !includeKey(key)) {
+        continue;
+      }
+      keys.push(key);
+    }
+    return keys;
+  };
+
+  return {
+    name: options.name ?? "localStorage",
+    getItem(key: string): string | null {
+      return getResolvedStorage(resolveStorage)?.getItem(key) ?? null;
+    },
+    setItem(key: string, value: string): void {
+      getResolvedStorage(resolveStorage)?.setItem(key, value);
+    },
+    removeItem(key: string): void {
+      getResolvedStorage(resolveStorage)?.removeItem(key);
+    },
+    clear(): void {
+      const storage = getResolvedStorage(resolveStorage);
+      if (!storage) {
+        return;
+      }
+
+      listKeys().forEach((key) => {
+        storage.removeItem(key);
+      });
+    },
+    getAllKeys(): string[] {
+      return listKeys();
+    },
+    getMany(keys: string[]): (string | null)[] {
+      const storage = getResolvedStorage(resolveStorage);
+      if (!storage) {
+        return keys.map(() => null);
+      }
+      return keys.map((key) => storage.getItem(key));
+    },
+    setMany(entries): void {
+      const storage = getResolvedStorage(resolveStorage);
+      if (!storage) {
+        return;
+      }
+      entries.forEach(([key, value]) => {
+        storage.setItem(key, value);
+      });
+    },
+    removeMany(keys: string[]): void {
+      const storage = getResolvedStorage(resolveStorage);
+      if (!storage) {
+        return;
+      }
+      keys.forEach((key) => {
+        storage.removeItem(key);
+      });
+    },
+    size(): number {
+      return listKeys().length;
+    },
+  };
+}