react-native-nitro-storage 0.3.0 → 0.3.2

package/src/index.ts

@@ -1,7 +1,6 @@
-import { useRef, useSyncExternalStore } from "react";
 import { NitroModules } from "react-native-nitro-modules";
 import type { Storage } from "./Storage.nitro";
-import { StorageScope } from "./Storage.types";
+import { StorageScope, AccessControl, BiometricLevel } from "./Storage.types";
 import {
   MIGRATION_VERSION_KEY,
   type StoredEnvelope,
@@ -11,9 +10,11 @@ import {
   decodeNativeBatchValue,
   serializeWithPrimitiveFastPath,
   deserializeWithPrimitiveFastPath,
+  prefixKey,
+  isNamespaced,
 } from "./internal";
 
-export { StorageScope } from "./Storage.types";
+export { StorageScope, AccessControl, BiometricLevel } from "./Storage.types";
 export type { Storage } from "./Storage.nitro";
 export { migrateFromMMKV } from "./migration";
 
@@ -37,15 +38,36 @@ export type TransactionContext = {
   setRaw: (key: string, value: string) => void;
   removeRaw: (key: string) => void;
   getItem: <T>(item: Pick<StorageItem<T>, "scope" | "key" | "get">) => T;
-  setItem: <T>(item: Pick<StorageItem<T>, "scope" | "key" | "set">, value: T) => void;
-  removeItem: (item: Pick<StorageItem<unknown>, "scope" | "key" | "delete">) => void;
+  setItem: <T>(
+    item: Pick<StorageItem<T>, "scope" | "key" | "set">,
+    value: T,
+  ) => void;
+  removeItem: (
+    item: Pick<StorageItem<unknown>, "scope" | "key" | "delete">,
+  ) => void;
 };
 
 type KeyListenerRegistry = Map<string, Set<() => void>>;
 type RawBatchPathItem = {
   _hasValidation?: boolean;
   _hasExpiration?: boolean;
+  _isBiometric?: boolean;
+  _secureAccessControl?: AccessControl;
 };
+
+function asInternal<T>(item: StorageItem<T>): StorageItemInternal<T> {
+  return item as StorageItemInternal<T>;
+}
+
+function isUpdater<T>(
+  valueOrFn: T | ((prev: T) => T),
+): valueOrFn is (prev: T) => T {
+  return typeof valueOrFn === "function";
+}
+
+function typedKeys<K extends string, V>(record: Record<K, V>): K[] {
+  return Object.keys(record) as K[];
+}
 type NonMemoryScope = StorageScope.Disk | StorageScope.Secure;
 type PendingSecureWrite = { key: string; value: string | undefined };
 
@@ -73,28 +95,37 @@ const scopedListeners = new Map<NonMemoryScope, KeyListenerRegistry>([
   [StorageScope.Secure, new Map()],
 ]);
 const scopedUnsubscribers = new Map<NonMemoryScope, () => void>();
-const scopedRawCache = new Map<NonMemoryScope, Map<string, string | undefined>>([
-  [StorageScope.Disk, new Map()],
-  [StorageScope.Secure, new Map()],
-]);
+const scopedRawCache = new Map<NonMemoryScope, Map<string, string | undefined>>(
+  [
+    [StorageScope.Disk, new Map()],
+    [StorageScope.Secure, new Map()],
+  ],
+);
 const pendingSecureWrites = new Map<string, PendingSecureWrite>();
 let secureFlushScheduled = false;
+let secureDefaultAccessControl: AccessControl = AccessControl.WhenUnlocked;
 
 function getScopedListeners(scope: NonMemoryScope): KeyListenerRegistry {
   return scopedListeners.get(scope)!;
 }
 
-function getScopeRawCache(scope: NonMemoryScope): Map<string, string | undefined> {
+function getScopeRawCache(
+  scope: NonMemoryScope,
+): Map<string, string | undefined> {
   return scopedRawCache.get(scope)!;
 }
 
-function cacheRawValue(scope: NonMemoryScope, key: string, value: string | undefined): void {
+function cacheRawValue(
+  scope: NonMemoryScope,
+  key: string,
+  value: string | undefined,
+): void {
   getScopeRawCache(scope).set(key, value);
 }
 
 function readCachedRawValue(
   scope: NonMemoryScope,
-  key: string
+  key: string,
 ): string | undefined {
   return getScopeRawCache(scope).get(key);
 }
@@ -120,7 +151,7 @@ function notifyAllListeners(registry: KeyListenerRegistry): void {
 function addKeyListener(
   registry: KeyListenerRegistry,
   key: string,
-  listener: () => void
+  listener: () => void,
 ): () => void {
   let listeners = registry.get(key);
   if (!listeners) {
@@ -177,6 +208,7 @@ function flushSecureWrites(): void {
   });
 
   const storageModule = getStorageModule();
+  storageModule.setSecureAccessControl(secureDefaultAccessControl);
   if (keysToSet.length > 0) {
     storageModule.setBatch(keysToSet, valuesToSet, StorageScope.Secure);
   }
@@ -260,6 +292,7 @@ function setRawValue(key: string, value: string, scope: StorageScope): void {
   if (scope === StorageScope.Secure) {
     flushSecureWrites();
     clearPendingSecureWrite(key);
+    getStorageModule().setSecureAccessControl(secureDefaultAccessControl);
   }
 
   getStorageModule().set(key, value, scope);
@@ -318,6 +351,81 @@ export const storage = {
     storage.clear(StorageScope.Disk);
     storage.clear(StorageScope.Secure);
   },
+  clearNamespace: (namespace: string, scope: StorageScope) => {
+    assertValidScope(scope);
+    if (scope === StorageScope.Memory) {
+      for (const key of memoryStore.keys()) {
+        if (isNamespaced(key, namespace)) {
+          memoryStore.delete(key);
+        }
+      }
+      notifyAllListeners(memoryListeners);
+      return;
+    }
+
+    const keyPrefix = prefixKey(namespace, "");
+    if (scope === StorageScope.Secure) {
+      flushSecureWrites();
+    }
+
+    clearScopeRawCache(scope);
+    getStorageModule().removeByPrefix(keyPrefix, scope);
+  },
+  clearBiometric: () => {
+    getStorageModule().clearSecureBiometric();
+  },
+  has: (key: string, scope: StorageScope): boolean => {
+    assertValidScope(scope);
+    if (scope === StorageScope.Memory) {
+      return memoryStore.has(key);
+    }
+    return getStorageModule().has(key, scope);
+  },
+  getAllKeys: (scope: StorageScope): string[] => {
+    assertValidScope(scope);
+    if (scope === StorageScope.Memory) {
+      return Array.from(memoryStore.keys());
+    }
+    return getStorageModule().getAllKeys(scope);
+  },
+  getAll: (scope: StorageScope): Record<string, string> => {
+    assertValidScope(scope);
+    const result: Record<string, string> = {};
+    if (scope === StorageScope.Memory) {
+      memoryStore.forEach((value, key) => {
+        if (typeof value === "string") result[key] = value;
+      });
+      return result;
+    }
+    const keys = getStorageModule().getAllKeys(scope);
+    if (keys.length === 0) return result;
+    const values = getStorageModule().getBatch(keys, scope);
+    keys.forEach((key, idx) => {
+      const val = decodeNativeBatchValue(values[idx]);
+      if (val !== undefined) result[key] = val;
+    });
+    return result;
+  },
+  size: (scope: StorageScope): number => {
+    assertValidScope(scope);
+    if (scope === StorageScope.Memory) {
+      return memoryStore.size;
+    }
+    return getStorageModule().size(scope);
+  },
+  setAccessControl: (level: AccessControl) => {
+    secureDefaultAccessControl = level;
+    getStorageModule().setSecureAccessControl(level);
+  },
+  setSecureWritesAsync: (enabled: boolean) => {
+    getStorageModule().setSecureWritesAsync(enabled);
+  },
+  flushSecureWrites: () => {
+    flushSecureWrites();
+  },
+  setKeychainAccessGroup: (group: string) => {
+    getStorageModule().setKeychainAccessGroup(group);
+  },
 };
 
 export interface StorageItemConfig<T> {
@@ -329,27 +437,50 @@ export interface StorageItemConfig<T> {
   validate?: Validator<T>;
   onValidationError?: (invalidValue: unknown) => T;
   expiration?: ExpirationConfig;
+  onExpired?: (key: string) => void;
   readCache?: boolean;
   coalesceSecureWrites?: boolean;
+  namespace?: string;
+  biometric?: boolean;
+  accessControl?: AccessControl;
 }
 
 export interface StorageItem<T> {
   get: () => T;
   set: (value: T | ((prev: T) => T)) => void;
   delete: () => void;
+  has: () => boolean;
   subscribe: (callback: () => void) => () => void;
   serialize: (value: T) => string;
   deserialize: (value: string) => T;
-  _triggerListeners: () => void;
-  _hasValidation?: boolean;
-  _hasExpiration?: boolean;
-  _readCacheEnabled?: boolean;
   scope: StorageScope;
   key: string;
 }
 
+type StorageItemInternal<T> = StorageItem<T> & {
+  _triggerListeners: () => void;
+  _hasValidation: boolean;
+  _hasExpiration: boolean;
+  _readCacheEnabled: boolean;
+  _isBiometric: boolean;
+  _secureAccessControl?: AccessControl;
+};
+
 function canUseRawBatchPath(item: RawBatchPathItem): boolean {
-  return item._hasExpiration === false && item._hasValidation === false;
+  return (
+    item._hasExpiration === false &&
+    item._hasValidation === false &&
+    item._isBiometric !== true &&
+    item._secureAccessControl === undefined
+  );
+}
+
+function canUseSecureRawBatchPath(item: RawBatchPathItem): boolean {
+  return (
+    item._hasExpiration === false &&
+    item._hasValidation === false &&
+    item._isBiometric !== true
+  );
 }
 
 function defaultSerialize<T>(value: T): string {
@@ -361,19 +492,29 @@ function defaultDeserialize<T>(value: string): T {
 }
 
 export function createStorageItem<T = undefined>(
-  config: StorageItemConfig<T>
+  config: StorageItemConfig<T>,
 ): StorageItem<T> {
+  const storageKey = prefixKey(config.namespace, config.key);
   const serialize = config.serialize ?? defaultSerialize;
   const deserialize = config.deserialize ?? defaultDeserialize;
   const isMemory = config.scope === StorageScope.Memory;
+  const isBiometric =
+    config.biometric === true && config.scope === StorageScope.Secure;
+  const secureAccessControl = config.accessControl;
   const validate = config.validate;
   const onValidationError = config.onValidationError;
   const expiration = config.expiration;
+  const onExpired = config.onExpired;
   const expirationTtlMs = expiration?.ttlMs;
-  const memoryExpiration = expiration && isMemory ? new Map<string, number>() : null;
+  const memoryExpiration =
+    expiration && isMemory ? new Map<string, number>() : null;
   const readCache = !isMemory && config.readCache === true;
   const coalesceSecureWrites =
-    config.scope === StorageScope.Secure && config.coalesceSecureWrites === true;
+    config.scope === StorageScope.Secure &&
+    config.coalesceSecureWrites === true &&
+    !isBiometric &&
+    secureAccessControl === undefined;
+  const defaultValue = config.defaultValue as T;
   const nonMemoryScope: NonMemoryScope | null =
     config.scope === StorageScope.Disk
       ? StorageScope.Disk
@@ -390,11 +531,13 @@ export function createStorageItem<T = undefined>(
   let lastRaw: unknown = undefined;
   let lastValue: T | undefined;
   let hasLastValue = false;
+  let lastExpiresAt: number | null | undefined = undefined;
 
   const invalidateParsedCache = () => {
     lastRaw = undefined;
     lastValue = undefined;
     hasLastValue = false;
+    lastExpiresAt = undefined;
   };
 
   const ensureSubscription = () => {
@@ -408,80 +551,106 @@ export function createStorageItem<T = undefined>(
     };
 
     if (isMemory) {
-      unsubscribe = addKeyListener(memoryListeners, config.key, listener);
+      unsubscribe = addKeyListener(memoryListeners, storageKey, listener);
       return;
     }
 
     ensureNativeScopeSubscription(nonMemoryScope!);
-    unsubscribe = addKeyListener(getScopedListeners(nonMemoryScope!), config.key, listener);
+    unsubscribe = addKeyListener(
+      getScopedListeners(nonMemoryScope!),
+      storageKey,
+      listener,
+    );
   };
 
   const readStoredRaw = (): unknown => {
     if (isMemory) {
       if (memoryExpiration) {
-        const expiresAt = memoryExpiration.get(config.key);
+        const expiresAt = memoryExpiration.get(storageKey);
         if (expiresAt !== undefined && expiresAt <= Date.now()) {
-          memoryExpiration.delete(config.key);
-          memoryStore.delete(config.key);
-          notifyKeyListeners(memoryListeners, config.key);
+          memoryExpiration.delete(storageKey);
+          memoryStore.delete(storageKey);
+          notifyKeyListeners(memoryListeners, storageKey);
+          onExpired?.(storageKey);
           return undefined;
         }
       }
-      return memoryStore.get(config.key) as T | undefined;
+      return memoryStore.get(storageKey);
     }
 
-    if (nonMemoryScope === StorageScope.Secure && hasPendingSecureWrite(config.key)) {
-      return readPendingSecureWrite(config.key);
+    if (
+      nonMemoryScope === StorageScope.Secure &&
+      !isBiometric &&
+      hasPendingSecureWrite(storageKey)
+    ) {
+      return readPendingSecureWrite(storageKey);
     }
 
     if (readCache) {
-      if (hasCachedRawValue(nonMemoryScope!, config.key)) {
-        return readCachedRawValue(nonMemoryScope!, config.key);
+      if (hasCachedRawValue(nonMemoryScope!, storageKey)) {
+        return readCachedRawValue(nonMemoryScope!, storageKey);
       }
     }
 
-    const raw = getStorageModule().get(config.key, config.scope);
-    cacheRawValue(nonMemoryScope!, config.key, raw);
+    if (isBiometric) {
+      return getStorageModule().getSecureBiometric(storageKey);
+    }
+
+    const raw = getStorageModule().get(storageKey, config.scope);
+    cacheRawValue(nonMemoryScope!, storageKey, raw);
     return raw;
   };
 
   const writeStoredRaw = (rawValue: string): void => {
-    cacheRawValue(nonMemoryScope!, config.key, rawValue);
+    if (isBiometric) {
+      getStorageModule().setSecureBiometric(storageKey, rawValue);
+      return;
+    }
+
+    cacheRawValue(nonMemoryScope!, storageKey, rawValue);
 
     if (coalesceSecureWrites) {
-      scheduleSecureWrite(config.key, rawValue);
+      scheduleSecureWrite(storageKey, rawValue);
       return;
     }
 
     if (nonMemoryScope === StorageScope.Secure) {
-      clearPendingSecureWrite(config.key);
+      clearPendingSecureWrite(storageKey);
+      getStorageModule().setSecureAccessControl(
+        secureAccessControl ?? secureDefaultAccessControl,
+      );
     }
 
-    getStorageModule().set(config.key, rawValue, config.scope);
+    getStorageModule().set(storageKey, rawValue, config.scope);
   };
 
   const removeStoredRaw = (): void => {
-    cacheRawValue(nonMemoryScope!, config.key, undefined);
+    if (isBiometric) {
+      getStorageModule().deleteSecureBiometric(storageKey);
+      return;
+    }
+
+    cacheRawValue(nonMemoryScope!, storageKey, undefined);
 
     if (coalesceSecureWrites) {
-      scheduleSecureWrite(config.key, undefined);
+      scheduleSecureWrite(storageKey, undefined);
       return;
     }
 
     if (nonMemoryScope === StorageScope.Secure) {
-      clearPendingSecureWrite(config.key);
+      clearPendingSecureWrite(storageKey);
     }
 
-    getStorageModule().remove(config.key, config.scope);
+    getStorageModule().remove(storageKey, config.scope);
   };
 
   const writeValueWithoutValidation = (value: T): void => {
     if (isMemory) {
       if (memoryExpiration) {
-        memoryExpiration.set(config.key, Date.now() + (expirationTtlMs ?? 0));
+        memoryExpiration.set(storageKey, Date.now() + (expirationTtlMs ?? 0));
       }
-      memoryStore.set(config.key, value);
-      notifyKeyListeners(memoryListeners, config.key);
+      memoryStore.set(storageKey, value);
+      notifyKeyListeners(memoryListeners, storageKey);
       return;
     }
 
@@ -504,12 +673,12 @@ export function createStorageItem<T = undefined>(
       return onValidationError(invalidValue);
     }
 
-    return config.defaultValue as T;
+    return defaultValue;
   };
 
   const ensureValidatedValue = (
     candidate: unknown,
-    hadStoredValue: boolean
+    hadStoredValue: boolean,
   ): T => {
     if (!validate || validate(candidate)) {
       return candidate as T;
@@ -517,7 +686,7 @@ export function createStorageItem<T = undefined>(
 
     const resolved = resolveInvalidValue(candidate);
     if (validate && !validate(resolved)) {
-      return config.defaultValue as T;
+      return defaultValue;
     }
     if (hadStoredValue) {
       writeValueWithoutValidation(resolved);
@@ -528,35 +697,61 @@ export function createStorageItem<T = undefined>(
   const get = (): T => {
     const raw = readStoredRaw();
 
-    const canUseCachedValue = !expiration && !memoryExpiration;
-    if (canUseCachedValue && raw === lastRaw && hasLastValue) {
-      return lastValue as T;
+    if (!memoryExpiration && raw === lastRaw && hasLastValue) {
+      if (!expiration || lastExpiresAt === null) {
+        return lastValue as T;
+      }
+
+      if (typeof lastExpiresAt === "number") {
+        if (lastExpiresAt > Date.now()) {
+          return lastValue as T;
+        }
+
+        removeStoredRaw();
+        invalidateParsedCache();
+        onExpired?.(storageKey);
+        lastValue = ensureValidatedValue(defaultValue, false);
+        hasLastValue = true;
+        return lastValue;
+      }
     }
 
     lastRaw = raw;
 
     if (raw === undefined) {
-      lastValue = ensureValidatedValue(config.defaultValue, false);
+      lastExpiresAt = undefined;
+      lastValue = ensureValidatedValue(defaultValue, false);
       hasLastValue = true;
       return lastValue;
     }
 
     if (isMemory) {
+      lastExpiresAt = undefined;
       lastValue = ensureValidatedValue(raw, true);
       hasLastValue = true;
       return lastValue;
     }
 
-    let deserializableRaw = raw as string;
+    if (typeof raw !== "string") {
+      lastExpiresAt = undefined;
+      lastValue = ensureValidatedValue(defaultValue, false);
+      hasLastValue = true;
+      return lastValue;
+    }
+
+    let deserializableRaw = raw;
 
     if (expiration) {
+      let envelopeExpiresAt: number | null = null;
       try {
-        const parsed = JSON.parse(raw as string) as unknown;
+        const parsed = JSON.parse(raw) as unknown;
         if (isStoredEnvelope(parsed)) {
+          envelopeExpiresAt = parsed.expiresAt;
           if (parsed.expiresAt <= Date.now()) {
             removeStoredRaw();
             invalidateParsedCache();
-            lastValue = ensureValidatedValue(config.defaultValue, false);
+            onExpired?.(storageKey);
+            lastValue = ensureValidatedValue(defaultValue, false);
             hasLastValue = true;
             return lastValue;
           }
@@ -566,6 +761,9 @@ export function createStorageItem<T = undefined>(
       } catch {
         // Keep backward compatibility with legacy raw values.
       }
+      lastExpiresAt = envelopeExpiresAt;
+    } else {
+      lastExpiresAt = undefined;
     }
 
     lastValue = ensureValidatedValue(deserialize(deserializableRaw), true);
@@ -574,17 +772,13 @@ export function createStorageItem<T = undefined>(
   };
 
   const set = (valueOrFn: T | ((prev: T) => T)): void => {
-    const currentValue = get();
-    const newValue =
-      typeof valueOrFn === "function"
-        ? (valueOrFn as (prev: T) => T)(currentValue)
-        : valueOrFn;
+    const newValue = isUpdater(valueOrFn) ? valueOrFn(get()) : valueOrFn;
 
     invalidateParsedCache();
 
     if (validate && !validate(newValue)) {
       throw new Error(
-        `Validation failed for key "${config.key}" in scope "${StorageScope[config.scope]}".`
+        `Validation failed for key "${storageKey}" in scope "${StorageScope[config.scope]}".`,
       );
     }
 
@@ -596,16 +790,22 @@ export function createStorageItem<T = undefined>(
 
     if (isMemory) {
       if (memoryExpiration) {
-        memoryExpiration.delete(config.key);
+        memoryExpiration.delete(storageKey);
       }
-      memoryStore.delete(config.key);
-      notifyKeyListeners(memoryListeners, config.key);
+      memoryStore.delete(storageKey);
+      notifyKeyListeners(memoryListeners, storageKey);
       return;
     }
 
     removeStoredRaw();
   };
 
+  const hasItem = (): boolean => {
+    if (isMemory) return memoryStore.has(storageKey);
+    if (isBiometric) return getStorageModule().hasSecureBiometric(storageKey);
+    return getStorageModule().has(storageKey, config.scope);
+  };
+
   const subscribe = (callback: () => void): (() => void) => {
     ensureSubscription();
     listeners.add(callback);
@@ -621,10 +821,11 @@ export function createStorageItem<T = undefined>(
     };
   };
 
-  const storageItem: StorageItem<T> = {
+  const storageItem: StorageItemInternal<T> = {
     get,
     set,
     delete: deleteItem,
+    has: hasItem,
     subscribe,
     serialize,
     deserialize,
@@ -635,62 +836,29 @@ export function createStorageItem<T = undefined>(
     _hasValidation: validate !== undefined,
     _hasExpiration: expiration !== undefined,
     _readCacheEnabled: readCache,
+    _isBiometric: isBiometric,
+    ...(secureAccessControl !== undefined
+      ? { _secureAccessControl: secureAccessControl }
+      : {}),
     scope: config.scope,
-    key: config.key,
+    key: storageKey,
   };
 
   return storageItem;
 }
 
-export function useStorage<T>(
-  item: StorageItem<T>
-): [T, (value: T | ((prev: T) => T)) => void] {
-  const value = useSyncExternalStore(item.subscribe, item.get, item.get);
-  return [value, item.set];
-}
-
-export function useStorageSelector<T, TSelected>(
-  item: StorageItem<T>,
-  selector: (value: T) => TSelected,
-  isEqual: (prev: TSelected, next: TSelected) => boolean = Object.is
-): [TSelected, (value: T | ((prev: T) => T)) => void] {
-  const selectedRef = useRef<{ hasValue: false } | { hasValue: true; value: TSelected }>({
-    hasValue: false,
-  });
-
-  const getSelectedSnapshot = () => {
-    const nextSelected = selector(item.get());
-    const current = selectedRef.current;
-    if (current.hasValue && isEqual(current.value, nextSelected)) {
-      return current.value;
-    }
-
-    selectedRef.current = { hasValue: true, value: nextSelected };
-    return nextSelected;
-  };
-
-  const selectedValue = useSyncExternalStore(
-    item.subscribe,
-    getSelectedSnapshot,
-    getSelectedSnapshot
-  );
-  return [selectedValue, item.set];
-}
-
-export function useSetStorage<T>(item: StorageItem<T>) {
-  return item.set;
-}
+export { useStorage, useStorageSelector, useSetStorage } from "./storage-hooks";
 
 type BatchReadItem<T> = Pick<
   StorageItem<T>,
-  | "key"
-  | "scope"
-  | "get"
-  | "deserialize"
-  | "_hasValidation"
-  | "_hasExpiration"
-  | "_readCacheEnabled"
->;
+  "key" | "scope" | "get" | "deserialize"
+> & {
+  _hasValidation?: boolean;
+  _hasExpiration?: boolean;
+  _readCacheEnabled?: boolean;
+  _isBiometric?: boolean;
+  _secureAccessControl?: AccessControl;
+};
 type BatchRemoveItem = Pick<StorageItem<unknown>, "key" | "scope" | "delete">;
 
 export type StorageBatchSetItem<T> = {
@@ -700,7 +868,7 @@ export type StorageBatchSetItem<T> = {
 
 export function getBatch(
   items: readonly BatchReadItem<unknown>[],
-  scope: StorageScope
+  scope: StorageScope,
 ): unknown[] {
   assertBatchScope(items, scope);
 
@@ -708,7 +876,11 @@ export function getBatch(
     return items.map((item) => item.get());
   }
 
-  const useRawBatchPath = items.every((item) => canUseRawBatchPath(item));
+  const useRawBatchPath = items.every((item) =>
+    scope === StorageScope.Secure
+      ? canUseSecureRawBatchPath(item)
+      : canUseRawBatchPath(item),
+  );
   if (!useRawBatchPath) {
     return items.map((item) => item.get());
   }
@@ -745,6 +917,9 @@ export function getBatch(
     fetchedValues.forEach((value, index) => {
       const key = keysToFetch[index];
       const targetIndex = keyIndexes[index];
+      if (key === undefined || targetIndex === undefined) {
+        return;
+      }
       rawValues[targetIndex] = value;
       cacheRawValue(scope, key, value);
     });
@@ -761,11 +936,11 @@ export function getBatch(
 
 export function setBatch<T>(
   items: readonly StorageBatchSetItem<T>[],
-  scope: StorageScope
+  scope: StorageScope,
 ): void {
   assertBatchScope(
     items.map((batchEntry) => batchEntry.item),
-    scope
+    scope,
   );
 
   if (scope === StorageScope.Memory) {
@@ -773,7 +948,52 @@ export function setBatch<T>(
     return;
   }
 
-  const useRawBatchPath = items.every(({ item }) => canUseRawBatchPath(item));
+  if (scope === StorageScope.Secure) {
+    const secureEntries = items.map(({ item, value }) => ({
+      item,
+      value,
+      internal: asInternal(item),
+    }));
+    const canUseSecureBatchPath = secureEntries.every(({ internal }) =>
+      canUseSecureRawBatchPath(internal),
+    );
+    if (!canUseSecureBatchPath) {
+      items.forEach(({ item, value }) => item.set(value));
+      return;
+    }
+
+    flushSecureWrites();
+    const storageModule = getStorageModule();
+    const groupedByAccessControl = new Map<
+      number,
+      { keys: string[]; values: string[] }
+    >();
+
+    secureEntries.forEach(({ item, value, internal }) => {
+      const accessControl =
+        internal._secureAccessControl ?? secureDefaultAccessControl;
+      const existingGroup = groupedByAccessControl.get(accessControl);
+      const group = existingGroup ?? { keys: [], values: [] };
+      group.keys.push(item.key);
+      group.values.push(item.serialize(value));
+      if (!existingGroup) {
+        groupedByAccessControl.set(accessControl, group);
+      }
+    });
+
+    groupedByAccessControl.forEach((group, accessControl) => {
+      storageModule.setSecureAccessControl(accessControl);
+      storageModule.setBatch(group.keys, group.values, scope);
+      group.keys.forEach((key, index) =>
+        cacheRawValue(scope, key, group.values[index]),
+      );
+    });
+    return;
+  }
+
+  const useRawBatchPath = items.every(({ item }) =>
+    canUseRawBatchPath(asInternal(item)),
+  );
   if (!useRawBatchPath) {
     items.forEach(({ item, value }) => item.set(value));
     return;
@@ -782,16 +1002,13 @@ export function setBatch<T>(
   const keys = items.map((entry) => entry.item.key);
   const values = items.map((entry) => entry.item.serialize(entry.value));
 
-  if (scope === StorageScope.Secure) {
-    flushSecureWrites();
-  }
   getStorageModule().setBatch(keys, values, scope);
   keys.forEach((key, index) => cacheRawValue(scope, key, values[index]));
 }
 
 export function removeBatch(
   items: readonly BatchRemoveItem[],
-  scope: StorageScope
+  scope: StorageScope,
 ): void {
   assertBatchScope(items, scope);
 
@@ -820,7 +1037,9 @@ export function registerMigration(version: number, migration: Migration): void {
   registeredMigrations.set(version, migration);
 }
 
-export function migrateToLatest(scope: StorageScope = StorageScope.Disk): number {
+export function migrateToLatest(
+  scope: StorageScope = StorageScope.Disk,
+): number {
   assertValidScope(scope);
   const currentVersion = readMigrationVersion(scope);
   const versions = Array.from(registeredMigrations.keys())
@@ -850,7 +1069,7 @@ export function migrateToLatest(scope: StorageScope = StorageScope.Disk): number
 
 export function runTransaction<T>(
   scope: StorageScope,
-  transaction: (context: TransactionContext) => T
+  transaction: (context: TransactionContext) => T,
 ): T {
   assertValidScope(scope);
   if (scope === StorageScope.Secure) {
@@ -908,3 +1127,43 @@ export function runTransaction<T>(
     throw error;
   }
 }
+
+export type SecureAuthStorageConfig<K extends string = string> = Record<
+  K,
+  {
+    ttlMs?: number;
+    biometric?: boolean;
+    accessControl?: AccessControl;
+  }
+>;
+
+export function createSecureAuthStorage<K extends string>(
+  config: SecureAuthStorageConfig<K>,
+  options?: { namespace?: string },
+): Record<K, StorageItem<string>> {
+  const ns = options?.namespace ?? "auth";
+  const result: Partial<Record<K, StorageItem<string>>> = {};
+
+  for (const key of typedKeys(config)) {
+    const itemConfig = config[key];
+    const expirationConfig =
+      itemConfig.ttlMs !== undefined ? { ttlMs: itemConfig.ttlMs } : undefined;
+    result[key] = createStorageItem<string>({
+      key,
+      scope: StorageScope.Secure,
+      defaultValue: "",
+      namespace: ns,
+      ...(itemConfig.biometric !== undefined
+        ? { biometric: itemConfig.biometric }
+        : {}),
+      ...(itemConfig.accessControl !== undefined
+        ? { accessControl: itemConfig.accessControl }
+        : {}),
+      ...(expirationConfig !== undefined
+        ? { expiration: expirationConfig }
+        : {}),
+    });
+  }
+
+  return result as Record<K, StorageItem<string>>;
+}