react-native-nitro-storage 0.14.0 → 0.15.0

package/src/storage-core.ts

@@ -62,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 = {
@@ -217,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"
@@ -274,6 +303,7 @@ export type StorageCoreAdapter = {
   backend: StorageCoreBackend;
   changeSource: StorageChangeSource;
   applyAccessControlOnSecureRawWrite: boolean;
+  supportsSecureAccessControlMigration(): boolean;
   ensureScopeSubscription(scope: NonMemoryScope): void;
   maybeCleanupScopeSubscription(scope: NonMemoryScope): void;
   onWillEmitChanges(
@@ -3367,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);
@@ -3951,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;

package/src/testing.ts

@@ -1,6 +1,7 @@
 import { createIndexedDBBackend as createIndexedDBBackendFromSubpath } from "./indexeddb-backend";
 import {
   assertAccessControlLevel,
+  assertProtectedDataListener,
   notifyAllListeners,
   notifyKeyListeners,
 } from "./shared";
@@ -84,6 +85,8 @@ export type {
   WebStorageScope,
 } from "./web-storage-backend";
 export type {
+  SecureAccessControlMigrationOptions,
+  SecureAccessControlMigrationResult,
   SetItemConfig,
   SetStorageItem,
   StorageBatchSetItem,
@@ -224,6 +227,7 @@ function buildTestingModule() {
       backend,
       changeSource: "native",
       applyAccessControlOnSecureRawWrite: true,
+      supportsSecureAccessControlMigration: () => true,
       ensureScopeSubscription: (_scope: NonMemoryScope) => {},
       maybeCleanupScopeSubscription: (_scope: NonMemoryScope) => {},
       onWillEmitChanges: () => {},
@@ -237,6 +241,8 @@ function buildTestingModule() {
 
   const core = createStorageCore(buildAdapter);
   const { internals } = core;
+  let protectedDataAvailable = true;
+  const protectedDataListeners = new Set<() => void>();
 
   const storage = {
     ...core.storage,
@@ -244,6 +250,14 @@ function buildTestingModule() {
       assertAccessControlLevel(level);
       internals.setSecureDefaultAccessControl(level);
     },
+    isProtectedDataAvailable: (): boolean => protectedDataAvailable,
+    onProtectedDataAvailable: (listener: () => void): (() => void) => {
+      assertProtectedDataListener(listener);
+      protectedDataListeners.add(listener);
+      return () => {
+        protectedDataListeners.delete(listener);
+      };
+    },
     setSecureWritesAsync: (_enabled: boolean) => {},
     setKeychainAccessGroup: (_group: string) => {},
     getCapabilities: (): StorageCapabilities => ({
@@ -281,7 +295,24 @@ function buildTestingModule() {
     }),
   };
 
+  const setProtectedDataAvailable = (available: boolean): void => {
+    if (typeof available !== "boolean") {
+      throw new TypeError(
+        "NitroStorage: Protected data availability must be a boolean",
+      );
+    }
+    const wasAvailable = protectedDataAvailable;
+    protectedDataAvailable = available;
+    if (available && !wasAvailable) {
+      Array.from(protectedDataListeners).forEach((listener) => {
+        listener();
+      });
+    }
+  };
+
   const reset = (): void => {
+    protectedDataAvailable = true;
+    protectedDataListeners.clear();
     storage.setEventObserver(undefined);
     storage.setScheduledFlushErrorObserver(undefined);
     storage.setMetricsObserver(undefined);
@@ -303,8 +334,10 @@ function buildTestingModule() {
     removeBatch: core.removeBatch,
     registerMigration: core.registerMigration,
     migrateToLatest: core.migrateToLatest,
+    migrateSecureAccessControl: core.migrateSecureAccessControl,
     runTransaction: core.runTransaction,
     createSecureAuthStorage: core.createSecureAuthStorage,
+    setProtectedDataAvailable,
     reset,
   };
 }
@@ -324,8 +357,12 @@ export const setBatch = defaultModule.setBatch;
 export const removeBatch = defaultModule.removeBatch;
 export const registerMigration = defaultModule.registerMigration;
 export const migrateToLatest = defaultModule.migrateToLatest;
+export const migrateSecureAccessControl =
+  defaultModule.migrateSecureAccessControl;
 export const runTransaction = defaultModule.runTransaction;
 export const createSecureAuthStorage = defaultModule.createSecureAuthStorage;
+export const setMockProtectedDataAvailable =
+  defaultModule.setProtectedDataAvailable;
 
 export function setWebSecureStorageBackend(
   _backend?: WebSecureStorageBackend,