react-native-nitro-storage 0.13.0 → 0.15.0

package/src/Storage.nitro.ts

@@ -26,4 +26,6 @@ export interface Storage extends HybridObject<{ ios: "c++"; android: "c++" }> {
   deleteSecureBiometric(key: string): void;
   hasSecureBiometric(key: string): boolean;
   clearSecureBiometric(): void;
+  isProtectedDataAvailable(): boolean;
+  onProtectedDataAvailable(listener: () => void): () => void;
 }

package/src/Storage.types.ts

@@ -20,8 +20,10 @@ export enum AccessControl {
 export enum BiometricLevel {
   /** No biometric requirement (default). */
   None = 0,
-  /** Require biometric or passcode for each access. */
+  /** iOS: Keychain user presence. Android: recent authentication when opening
+   * the protected store; later access uses its cached keyset. Web: no biometric enforcement. */
   BiometryOrPasscode = 1,
-  /** Require biometric only (no passcode fallback). */
+  /** Biometric-only Keychain/Keystore policy, without passcode fallback.
+   * Android authenticates when opening the store, not each access. Web: no biometric enforcement. */
   BiometryOnly = 2,
 }

package/src/core/durability.ts

@@ -2,6 +2,15 @@ import { runMicrotask } from "../shared";
 import { StorageScope, type AccessControl } from "../Storage.types";
 import type { PendingDiskWrite, PendingSecureWrite } from "../shared";
 
+export type StorageScheduledFlushError = {
+  readonly scope: StorageScope.Disk | StorageScope.Secure;
+  readonly error: unknown;
+};
+
+export type StorageScheduledFlushErrorObserver = (
+  error: StorageScheduledFlushError,
+) => void;
+
 export type DurabilityBackend = {
   setBatch(keys: string[], values: string[], scope: number): void;
   removeBatch(keys: string[], scope: number): void;
@@ -9,6 +18,9 @@ export type DurabilityBackend = {
 };
 
 export type DurabilityCoordinator = {
+  setScheduledFlushErrorObserver(
+    observer: StorageScheduledFlushErrorObserver | undefined,
+  ): void;
   setDiskWritesAsync(enabled: boolean): void;
   isDiskWritesAsync(): boolean;
   hasPendingDiskWrite(key: string): boolean;
@@ -42,6 +54,8 @@ export function createDurabilityCoordinator(options: {
   let nextGeneration = 0;
   let diskFlushScheduled = false;
   let diskWritesAsync = false;
+  let scheduledFlushErrorObserver:
+    StorageScheduledFlushErrorObserver | undefined;
   const pendingSecureWrites = new Map<string, PendingSecureWrite>();
   let secureFlushScheduled = false;
   const securePromotionsInProgress = new Set<string>();
@@ -168,6 +182,33 @@ export function createDurabilityCoordinator(options: {
     }
   }
 
+  function reportScheduledFlushError(
+    scope: StorageScheduledFlushError["scope"],
+    error: unknown,
+  ): void {
+    const observer = scheduledFlushErrorObserver;
+    if (observer === undefined) {
+      throw error;
+    }
+    observer({ scope, error });
+  }
+
+  function flushScheduledDiskWrites(): void {
+    try {
+      flushDiskWrites();
+    } catch (error) {
+      reportScheduledFlushError(StorageScope.Disk, error);
+    }
+  }
+
+  function flushScheduledSecureWrites(): void {
+    try {
+      flushSecureWrites();
+    } catch (error) {
+      reportScheduledFlushError(StorageScope.Secure, error);
+    }
+  }
+
   function scheduleDiskWrite(
     key: string,
     value: string | undefined,
@@ -182,7 +223,7 @@ export function createDurabilityCoordinator(options: {
       return pendingWrite;
     }
     diskFlushScheduled = true;
-    runMicrotask(flushDiskWrites);
+    runMicrotask(flushScheduledDiskWrites);
     return pendingWrite;
   }
 
@@ -204,7 +245,7 @@ export function createDurabilityCoordinator(options: {
       return pendingWrite;
     }
     secureFlushScheduled = true;
-    runMicrotask(flushSecureWrites);
+    runMicrotask(flushScheduledSecureWrites);
     return pendingWrite;
   }
 
@@ -225,6 +266,9 @@ export function createDurabilityCoordinator(options: {
   }
 
   return {
+    setScheduledFlushErrorObserver(observer) {
+      scheduledFlushErrorObserver = observer;
+    },
     setDiskWritesAsync(enabled) {
       diskWritesAsync = enabled;
       if (!enabled) {

package/src/index.ts

@@ -8,6 +8,7 @@ import { createIndexedDBBackend as createIndexedDBBackendFromSubpath } from "./i
 import { unescapeCollidingRawValue } from "./internal";
 import {
   assertAccessControlLevel,
+  assertProtectedDataListener,
   notifyAllListeners,
   notifyKeyListeners,
   type NonMemoryScope,
@@ -49,6 +50,10 @@ export type {
   VersionedValue,
 } from "./shared";
 export { isKeychainLockedError } from "./shared";
+export type {
+  StorageScheduledFlushError,
+  StorageScheduledFlushErrorObserver,
+} from "./core/durability";
 
 export { StorageScope, AccessControl, BiometricLevel } from "./Storage.types";
 export type { Storage } from "./Storage.nitro";
@@ -78,6 +83,8 @@ export type {
   WebStorageScope,
 } from "./web-storage-backend";
 export type {
+  SecureAccessControlMigrationOptions,
+  SecureAccessControlMigrationResult,
   SetItemConfig,
   SetStorageItem,
   StorageBatchSetItem,
@@ -260,6 +267,7 @@ function buildNativeAdapter(
     backend: nativeBackend,
     changeSource: "native",
     applyAccessControlOnSecureRawWrite: true,
+    supportsSecureAccessControlMigration: () => Platform.OS === "ios",
     ensureScopeSubscription: ensureNativeScopeSubscription,
     maybeCleanupScopeSubscription: maybeCleanupNativeScopeSubscription,
     onWillEmitChanges: (scope, keys, operation, source) => {
@@ -300,6 +308,21 @@ export const storage = {
       },
     );
   },
+  isProtectedDataAvailable: (): boolean => {
+    const module = getStorageModule();
+    return typeof module.isProtectedDataAvailable === "function"
+      ? module.isProtectedDataAvailable()
+      : true;
+  },
+  onProtectedDataAvailable: (listener: () => void): (() => void) => {
+    assertProtectedDataListener(listener);
+    const module = getStorageModule();
+    if (typeof module.onProtectedDataAvailable !== "function") {
+      return () => {};
+    }
+    const unsubscribe = module.onProtectedDataAvailable(listener);
+    return typeof unsubscribe === "function" ? unsubscribe : () => {};
+  },
   setSecureWritesAsync: (enabled: boolean) => {
     internals.measureOperation(
       "storage:setSecureWritesAsync",
@@ -364,6 +387,7 @@ export const setBatch = core.setBatch;
 export const removeBatch = core.removeBatch;
 export const registerMigration = core.registerMigration;
 export const migrateToLatest = core.migrateToLatest;
+export const migrateSecureAccessControl = core.migrateSecureAccessControl;
 export const runTransaction = core.runTransaction;
 export const createSecureAuthStorage = core.createSecureAuthStorage;
 

package/src/index.web.ts

@@ -3,6 +3,7 @@ import { createIndexedDBBackend as createIndexedDBBackendFromSubpath } from "./i
 import { unescapeCollidingRawValue } from "./internal";
 import {
   assertAccessControlLevel,
+  assertProtectedDataListener,
   createStorageCompositeError,
   assertBiometricLevel,
   notifyAllListeners,
@@ -48,6 +49,10 @@ export type {
   VersionedValue,
 } from "./shared";
 export { isKeychainLockedError } from "./shared";
+export type {
+  StorageScheduledFlushError,
+  StorageScheduledFlushErrorObserver,
+} from "./core/durability";
 
 export { StorageScope, AccessControl, BiometricLevel } from "./Storage.types";
 export type { Storage } from "./Storage.nitro";
@@ -82,6 +87,8 @@ export {
   type WebBackendCapabilities,
 } from "./web-backend-contract";
 export type {
+  SecureAccessControlMigrationOptions,
+  SecureAccessControlMigrationResult,
   SetItemConfig,
   SetStorageItem,
   StorageBatchSetItem,
@@ -807,6 +814,11 @@ const WebStorage: Storage = {
   },
   setSecureWritesAsync: (_enabled: boolean) => {},
   setKeychainAccessGroup: () => {},
+  isProtectedDataAvailable: () => true,
+  onProtectedDataAvailable: (listener: () => void) => {
+    assertProtectedDataListener(listener);
+    return () => {};
+  },
   setSecureBiometric: (key: string, value: string) => {
     WebStorage.setSecureBiometricWithLevel(
       key,
@@ -1019,6 +1031,7 @@ function buildWebAdapter(
     backend: WebStorage,
     changeSource: "web",
     applyAccessControlOnSecureRawWrite: false,
+    supportsSecureAccessControlMigration: () => false,
     ensureScopeSubscription: () => {
       ensureExternalSyncSubscriptions();
     },
@@ -1045,6 +1058,10 @@ export const storage = {
       0,
     );
   },
+  isProtectedDataAvailable: (): boolean =>
+    WebStorage.isProtectedDataAvailable(),
+  onProtectedDataAvailable: (listener: () => void): (() => void) =>
+    WebStorage.onProtectedDataAvailable(listener),
   setSecureWritesAsync: (_enabled: boolean) => {
     getInternals().recordMetric(
       "storage:setSecureWritesAsync",
@@ -1110,6 +1127,7 @@ export const setBatch = core.setBatch;
 export const removeBatch = core.removeBatch;
 export const registerMigration = core.registerMigration;
 export const migrateToLatest = core.migrateToLatest;
+export const migrateSecureAccessControl = core.migrateSecureAccessControl;
 export const runTransaction = core.runTransaction;
 export const createSecureAuthStorage = core.createSecureAuthStorage;
 

package/src/shared.ts

@@ -75,7 +75,23 @@ export type MigrationContext = {
   removeRaw: (key: string) => void;
 };
 
-export type Migration = (context: MigrationContext) => void;
+type CallableThenableResult<TResult> = TResult extends {
+  then?: infer Then;
+}
+  ? Extract<Then, (...args: never[]) => unknown> extends never
+    ? never
+    : TResult
+  : never;
+
+export type SynchronousCallbackResult<TResult> = [
+  CallableThenableResult<TResult>,
+] extends [never]
+  ? TResult
+  : never;
+
+export type Migration<TResult = unknown> = (
+  context: MigrationContext,
+) => SynchronousCallbackResult<TResult>;
 
 export type KeyListenerRegistry = Map<string, Set<() => void>>;
 
@@ -212,6 +228,16 @@ export function assertBiometricLevel(level: number): void {
   assertEnumInteger(level, 0, 2, "biometric level");
 }
 
+export function assertProtectedDataListener(
+  listener: unknown,
+): asserts listener is () => void {
+  if (typeof listener !== "function") {
+    throw new TypeError(
+      "NitroStorage: Protected data listener must be a function",
+    );
+  }
+}
+
 export type NonMemoryScope = StorageScope.Disk | StorageScope.Secure;
 
 export type PendingDiskWrite = {

package/src/storage-core.ts

@@ -1,4 +1,7 @@
-import { createDurabilityCoordinator } from "./core/durability";
+import {
+  createDurabilityCoordinator,
+  type StorageScheduledFlushErrorObserver,
+} from "./core/durability";
 import { createMetricsRegistry } from "./core/metrics";
 import {
   MIGRATION_VERSION_KEY,
@@ -44,6 +47,7 @@ import {
   type StorageMetricsObserver,
   type StorageSelectorListener,
   type StorageSelectorSubscribeOptions,
+  type SynchronousCallbackResult,
   type StorageVersion,
   type Validator,
   type VersionedValue,
@@ -58,7 +62,12 @@ import {
   type StorageKeyChangeEvent,
 } from "./storage-events";
 import type { StorageSetter } from "./storage-hooks";
-import { isStorageError, type SecureStorageMetadata } from "./storage-runtime";
+import {
+  getStorageErrorCode,
+  isStorageError,
+  type SecureStorageMetadata,
+  type StorageErrorCode,
+} from "./storage-runtime";
 import { StorageScope, AccessControl, BiometricLevel } from "./Storage.types";
 
 export type TransactionContext = {
@@ -76,6 +85,28 @@ export type TransactionContext = {
   ) => void;
 };
 
+function assertSynchronousCallbackResult(
+  value: unknown,
+  callbackKind: "Transaction" | "Migration",
+): void {
+  if (
+    value === null ||
+    (typeof value !== "object" && typeof value !== "function")
+  ) {
+    return;
+  }
+
+  const then = (value as { then?: unknown }).then;
+  if (typeof then !== "function") {
+    return;
+  }
+
+  void Promise.resolve(value).catch(() => undefined);
+  throw new TypeError(
+    `${callbackKind} callbacks must be synchronous and cannot return a Promise or thenable.`,
+  );
+}
+
 export type StorageItemConfig<T> = {
   key: string;
   scope: StorageScope;
@@ -191,6 +222,30 @@ export type StorageClearOptions = {
   except?: readonly StorageKeyRef[];
 };
 
+export type SecureAccessControlMigrationOptions = {
+  /** Secure keys to rewrite. Defaults to every Secure key. */
+  keys?: readonly string[];
+};
+
+export type SecureAccessControlMigrationResult = {
+  /** Keys rewritten so the Keychain item carries the new access level. */
+  migrated: string[];
+  /** Keys left unchanged because the Keychain was locked (`keychain_locked`). */
+  locked: string[];
+  /** Keys that no longer exist when the migration reached them. */
+  missing: string[];
+  /** Biometric-protected keys, and every key on platforms without access classes. */
+  skipped: string[];
+  /** Keys left unchanged because of another error. */
+  failed: { key: string; code?: StorageErrorCode }[];
+  /**
+   * `true` when flushing queued Secure writes or listing the Secure keys
+   * failed with `keychain_locked`. The default level and every item are
+   * unchanged; retry once protected data is available.
+   */
+  enumerationLocked: boolean;
+};
+
 export type SetItemConfig<TMember extends string = string> = Omit<
   StorageItemConfig<Record<string, true>>,
   "defaultValue" | "serialize" | "deserialize"
@@ -248,6 +303,7 @@ export type StorageCoreAdapter = {
   backend: StorageCoreBackend;
   changeSource: StorageChangeSource;
   applyAccessControlOnSecureRawWrite: boolean;
+  supportsSecureAccessControlMigration(): boolean;
   ensureScopeSubscription(scope: NonMemoryScope): void;
   maybeCleanupScopeSubscription(scope: NonMemoryScope): void;
   onWillEmitChanges(
@@ -318,7 +374,7 @@ function asInternal<T>(item: StorageItem<T>): StorageItemInternal<T> {
 export function createStorageCore(
   buildAdapter: (internals: StorageCoreInternals) => StorageCoreAdapter,
 ) {
-  const registeredMigrations = new Map<number, Migration>();
+  const registeredMigrations = new Map<number, Migration<unknown>>();
   const itemGroups = new Map<string, Set<StorageItemInternal<unknown>>>();
   const registeredKeyCounts = new Map<string, number>();
   const memoryStore = new Map<string, unknown>();
@@ -1485,6 +1541,12 @@ export function createStorageCore(
         flushSecureWrites();
       });
     },
+    /** Observes scheduled flush failures; explicit flush calls still throw. */
+    setScheduledFlushErrorObserver: (
+      observer?: StorageScheduledFlushErrorObserver,
+    ): void => {
+      durability.setScheduledFlushErrorObserver(observer);
+    },
     setMetricsObserver: (observer?: StorageMetricsObserver) => {
       metrics.setObserver(observer);
     },
@@ -3320,7 +3382,10 @@ export function createStorageCore(
     );
   }
 
-  function registerMigration(version: number, migration: Migration): void {
+  function registerMigration<TResult>(
+    version: number,
+    migration: Migration<TResult>,
+  ): void {
     if (!Number.isInteger(version) || version <= 0) {
       throw new Error("Migration version must be a positive integer.");
     }
@@ -3332,6 +3397,95 @@ export function createStorageCore(
     registeredMigrations.set(version, migration);
   }
 
+  function migrateSecureAccessControl(
+    level: AccessControl,
+    options?: SecureAccessControlMigrationOptions,
+  ): SecureAccessControlMigrationResult {
+    return measureOperation(
+      "storage:migrateSecureAccessControl",
+      StorageScope.Secure,
+      () => {
+        assertAccessControlLevel(level);
+        const requestedKeys = options?.keys;
+        requestedKeys?.forEach((key) => {
+          assertValidStorageKey(key);
+        });
+
+        let keys: string[];
+        try {
+          flushSecureWrites();
+          keys = Array.from(
+            new Set(
+              requestedKeys ?? adapter.backend.getAllKeys(StorageScope.Secure),
+            ),
+          );
+        } catch (error) {
+          if (getStorageErrorCode(error) !== "keychain_locked") {
+            throw error;
+          }
+          return {
+            migrated: [],
+            locked: [],
+            missing: [],
+            skipped: [],
+            failed: [],
+            enumerationLocked: true,
+          };
+        }
+        secureDefaultAccessControl = level;
+        adapter.backend.setSecureAccessControl(level);
+
+        const result: SecureAccessControlMigrationResult = {
+          migrated: [],
+          locked: [],
+          missing: [],
+          skipped: [],
+          failed: [],
+          enumerationLocked: false,
+        };
+        if (!adapter.supportsSecureAccessControlMigration()) {
+          result.skipped = keys;
+          return result;
+        }
+
+        keys.forEach((key) => {
+          try {
+            let hasBiometric: boolean;
+            try {
+              hasBiometric = adapter.backend.hasSecureBiometric(key);
+            } catch (error) {
+              if (getStorageErrorCode(error) !== "keychain_locked") {
+                throw error;
+              }
+              result.skipped.push(key);
+              return;
+            }
+            if (hasBiometric) {
+              result.skipped.push(key);
+              return;
+            }
+            const raw = adapter.backend.get(key, StorageScope.Secure);
+            if (raw === undefined) {
+              result.missing.push(key);
+              return;
+            }
+            adapter.backend.set(key, raw, StorageScope.Secure);
+            result.migrated.push(key);
+          } catch (error) {
+            const code = getStorageErrorCode(error);
+            if (code === "keychain_locked") {
+              result.locked.push(key);
+            } else {
+              result.failed.push(code === undefined ? { key } : { key, code });
+            }
+          }
+        });
+        return result;
+      },
+      options?.keys?.length ?? 1,
+    );
+  }
+
   function migrateToLatest(scope: StorageScope = StorageScope.Disk): number {
     return measureOperation("migration:run", scope, () => {
       assertValidScope(scope);
@@ -3348,7 +3502,8 @@ export function createStorageCore(
           return;
         }
         runTransaction(scope, (tx) => {
-          migration(tx);
+          const migrationResult: unknown = migration(tx);
+          assertSynchronousCallbackResult(migrationResult, "Migration");
           tx.setRaw(MIGRATION_VERSION_KEY, String(version));
         });
         appliedVersion = version;
@@ -3360,7 +3515,7 @@ export function createStorageCore(
 
   function runTransaction<T>(
     scope: StorageScope,
-    transaction: (context: TransactionContext) => T,
+    transaction: (context: TransactionContext) => SynchronousCallbackResult<T>,
   ): T {
     return measureOperation("transaction:run", scope, () => {
       assertValidScope(scope);
@@ -3379,6 +3534,12 @@ export function createStorageCore(
       };
       const rollback = new Map<string, TransactionRollbackEntry>();
       const itemRenameStates = new Map<StorageItemInternal<unknown>, boolean>();
+      let transactionOpen = true;
+      const assertTransactionOpen = (): void => {
+        if (!transactionOpen) {
+          throw new TypeError("Transaction context is closed.");
+        }
+      };
 
       const rememberRollback = (
         key: string,
@@ -3486,26 +3647,34 @@ export function createStorageCore(
 
       const tx: TransactionContext = {
         scope,
-        getRaw: (key) => getRawValue(key, scope),
+        getRaw: (key) => {
+          assertTransactionOpen();
+          return getRawValue(key, scope);
+        },
         setRaw: (key, value) => {
+          assertTransactionOpen();
           rememberRollback(key);
           setRawValue(key, value, scope);
         },
         removeRaw: (key) => {
+          assertTransactionOpen();
           rememberRollback(key, undefined, scope === StorageScope.Secure);
           removeRawValue(key, scope);
         },
         getItem: (item) => {
+          assertTransactionOpen();
           assertBatchScope([item], scope);
           rememberItemRollback(item);
           return item.get();
         },
         setItem: (item, value) => {
+          assertTransactionOpen();
           assertBatchScope([item], scope);
           rememberItemRollback(item);
           item.set(value);
         },
         removeItem: (item) => {
+          assertTransactionOpen();
           assertBatchScope([item], scope);
           rememberItemRollback(item);
           item.delete();
@@ -3513,8 +3682,12 @@ export function createStorageCore(
       };
 
       try {
-        return transaction(tx);
+        const result = transaction(tx);
+        assertSynchronousCallbackResult(result, "Transaction");
+        transactionOpen = false;
+        return result;
       } catch (error) {
+        transactionOpen = false;
         itemRenameStates.forEach((migrated, item) => {
           item._setRenameMigrationState(migrated);
         });
@@ -3897,6 +4070,7 @@ export function createStorageCore(
     removeBatch,
     registerMigration,
     migrateToLatest,
+    migrateSecureAccessControl,
     runTransaction,
     createSecureAuthStorage,
     internals,

package/src/storage-platform.ts

@@ -7,6 +7,8 @@ import type { AccessControl, StorageScope } from "./Storage.types";
 
 export type PlatformStorage = StorageCore["storage"] & {
   setAccessControl(level: AccessControl): void;
+  isProtectedDataAvailable(): boolean;
+  onProtectedDataAvailable(listener: () => void): () => void;
   setSecureWritesAsync(enabled: boolean): void;
   setKeychainAccessGroup(group: string): void;
   getCapabilities(): StorageCapabilities;