@buoy-gg/storage 7.0.16 → 7.0.18

package/lib/commonjs/storage/utils/snapshotProvider.js

@@ -0,0 +1,447 @@
+"use strict";
+
+var _asyncStorage = _interopRequireDefault(require("@react-native-async-storage/async-storage"));
+var _sharedUi = require("@buoy-gg/shared-ui");
+var _asyncStorageCompat = require("./asyncStorageCompat");
+var _clearAllStorage = require("./clearAllStorage");
+var _MMKVInstanceRegistry = require("./MMKVInstanceRegistry");
+var _mmkvTypeDetection = require("./mmkvTypeDetection");
+var _SecureStoreRegistry = require("./SecureStoreRegistry");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Time Machine snapshot provider for device storage (AsyncStorage + MMKV +
+ * SecureStore).
+ *
+ * Registered into @buoy-gg/shared-ui's stateSnapshotRegistry at module init;
+ * consumed by @buoy-gg/time-machine.
+ *
+ * Buoy's own keys (isDevToolsStorageKey — @react_buoy*, @buoy*, buoy-*,
+ * legacy patterns) are excluded on BOTH capture and restore, so a snapshot
+ * can never clobber dev-tool settings. Restore is a diff: app keys missing
+ * from the snapshot are deleted, snapshot entries are written back.
+ *
+ * Known-lossy by design (each surfaces a warning/skip):
+ * - MMKV ArrayBuffer values are never transported.
+ * - SecureStore biometric keys are never read or written (auth prompt).
+ * - SecureStore keys outside the registered descriptor list are invisible.
+ */
+
+function deleteMMKVKey(instance, key) {
+  // v4 renamed delete() to remove() — support both
+  if (instance.remove) instance.remove(key);else instance.delete?.(key);
+}
+function status() {
+  return {
+    canCapture: true,
+    canRestore: true
+  };
+}
+
+/** Shared by capture() and the live side of previewItems(). */
+async function captureStorageData() {
+  const warnings = [];
+  const appKeys = (await _asyncStorage.default.getAllKeys()).filter(k => !(0, _sharedUi.isDevToolsStorageKey)(k));
+  const asyncPairs = (await (0, _asyncStorageCompat.readMany)(appKeys)).filter(pair => pair[1] !== null);
+  const mmkv = {};
+  for (const {
+    id,
+    instance
+  } of _MMKVInstanceRegistry.mmkvInstanceRegistry.getAll()) {
+    try {
+      mmkv[id] = instance.getAllKeys().filter(key => !(0, _sharedUi.isDevToolsStorageKey)(key)).map(key => {
+        const {
+          value,
+          type: valueType
+        } = (0, _mmkvTypeDetection.detectMMKVType)(instance, key);
+        if (valueType === "buffer") {
+          warnings.push(`mmkv "${id}"/"${key}": ArrayBuffer value not capturable`);
+        }
+        return {
+          key,
+          value,
+          valueType
+        };
+      });
+    } catch {
+      warnings.push(`mmkv "${id}": unreadable, captured without entries`);
+      mmkv[id] = [];
+    }
+  }
+  const secure = {};
+  const secureModule = _SecureStoreRegistry.secureStoreRegistry.getModule();
+  for (const {
+    key,
+    options
+  } of _SecureStoreRegistry.secureStoreRegistry.getAll()) {
+    if (options.requireAuthentication) {
+      warnings.push(`secure "${key}": biometric-protected, not capturable`);
+      continue;
+    }
+    let value = null;
+    if (secureModule) {
+      try {
+        value = await secureModule.getItemAsync(key, options);
+      } catch {
+        warnings.push(`secure "${key}": unreadable, captured as unset`);
+      }
+    }
+    secure[key] = value;
+  }
+  return {
+    data: {
+      async: asyncPairs,
+      mmkv,
+      secure
+    },
+    warnings
+  };
+}
+async function capture() {
+  const {
+    data,
+    warnings
+  } = await captureStorageData();
+  return {
+    data,
+    warnings
+  };
+}
+async function restore(data, options) {
+  const snapshot = data;
+  const excludedSet = new Set(options?.excludeKeys ?? []);
+  const includedSet = options?.includeKeys ? new Set(options.includeKeys) : null;
+  /** True when this item may be touched (scope + exclusions agree). */
+  const touch = key => !excludedSet.has(key) && (!includedSet || includedSet.has(key));
+  let excludedHits = 0;
+  const result = {
+    ok: true,
+    applied: 0,
+    skipped: [],
+    warnings: []
+  };
+  if (!snapshot) {
+    return {
+      ok: false,
+      applied: 0,
+      skipped: [],
+      warnings: ["empty storage snapshot"]
+    };
+  }
+
+  // ── AsyncStorage: delete app keys missing from the snapshot, write the rest ──
+  try {
+    const snapPairs = (snapshot.async ?? []).filter(([k]) => !(0, _sharedUi.isDevToolsStorageKey)(k) && touch(`async:${k}`));
+    const snapKeys = new Set(snapPairs.map(([k]) => k));
+    const liveKeys = (await _asyncStorage.default.getAllKeys()).filter(k => !(0, _sharedUi.isDevToolsStorageKey)(k));
+    const toRemove = liveKeys.filter(k => !snapKeys.has(k) && touch(`async:${k}`));
+    excludedHits += (snapshot.async ?? []).length - snapPairs.length;
+    if (toRemove.length > 0) await (0, _asyncStorageCompat.removeMany)(toRemove);
+    if (snapPairs.length > 0) await (0, _asyncStorageCompat.writeMany)(snapPairs);
+    result.applied += snapPairs.length + toRemove.length;
+  } catch (e) {
+    result.ok = false;
+    result.warnings.push(`asyncstorage restore failed: ${String(e)}`);
+  }
+
+  // ── MMKV: per registered writable instance, diff against the snapshot ──
+  for (const [id, entries] of Object.entries(snapshot.mmkv ?? {})) {
+    const registered = _MMKVInstanceRegistry.mmkvInstanceRegistry.get(id);
+    if (!registered) {
+      result.skipped.push({
+        id: `mmkv:${id}`,
+        reason: "instance not registered"
+      });
+      continue;
+    }
+    if (registered.instance.isReadOnly) {
+      result.skipped.push({
+        id: `mmkv:${id}`,
+        reason: "instance registered read-only"
+      });
+      continue;
+    }
+    const {
+      instance
+    } = registered;
+    try {
+      const snapKeys = new Set(entries.map(e => e.key));
+      const liveKeys = instance.getAllKeys().filter(key => !(0, _sharedUi.isDevToolsStorageKey)(key));
+      for (const key of liveKeys) {
+        if (!touch(`mmkv:${id}/${key}`)) {
+          excludedHits += 1;
+          continue;
+        }
+        if (!snapKeys.has(key)) {
+          deleteMMKVKey(instance, key);
+          result.applied += 1;
+        }
+      }
+      for (const entry of entries) {
+        if ((0, _sharedUi.isDevToolsStorageKey)(entry.key)) continue;
+        if (!touch(`mmkv:${id}/${entry.key}`)) continue;
+        if (entry.valueType === "buffer") {
+          result.skipped.push({
+            id: `mmkv:${id}/${entry.key}`,
+            reason: "ArrayBuffer values cannot be restored"
+          });
+          continue;
+        }
+        instance.set(entry.key, entry.value);
+        result.applied += 1;
+      }
+    } catch (e) {
+      result.ok = false;
+      result.warnings.push(`mmkv "${id}" restore failed: ${String(e)}`);
+    }
+  }
+
+  // ── SecureStore: diff over the registered, non-biometric descriptor list ──
+  const secureSnap = snapshot.secure ?? {};
+  for (const {
+    key,
+    options
+  } of _SecureStoreRegistry.secureStoreRegistry.getAll()) {
+    if (!touch(`secure:${key}`)) {
+      excludedHits += 1;
+      continue;
+    }
+    if (options.requireAuthentication) {
+      if (key in secureSnap) {
+        result.skipped.push({
+          id: `secure:${key}`,
+          reason: "biometric-protected keys are never written"
+        });
+      }
+      continue;
+    }
+    try {
+      if (key in secureSnap) {
+        const value = secureSnap[key];
+        if (value === null) await _SecureStoreRegistry.secureStoreRegistry.deleteValue(key);else await _SecureStoreRegistry.secureStoreRegistry.setValue(key, value);
+      } else {
+        // Registered key with no snapshot entry — snapshot predates it; unset.
+        await _SecureStoreRegistry.secureStoreRegistry.deleteValue(key);
+      }
+      result.applied += 1;
+    } catch (e) {
+      result.ok = false;
+      result.warnings.push(`secure "${key}" restore failed: ${String(e)}`);
+    }
+  }
+  for (const key of Object.keys(secureSnap)) {
+    if (!touch(`secure:${key}`)) continue;
+    if (!_SecureStoreRegistry.secureStoreRegistry.getAll().some(e => e.key === key)) {
+      result.skipped.push({
+        id: `secure:${key}`,
+        reason: "key no longer registered with registerSecureStoreKeys"
+      });
+    }
+  }
+  if (excludedHits > 0) {
+    result.warnings.push(`${excludedHits} item(s) excluded by you`);
+  }
+  return result;
+}
+
+/** Wipe to fresh-install state (Buoy keys preserved). Used by baseline restore. */
+async function clear() {
+  const result = {
+    ok: true,
+    applied: 0,
+    skipped: [],
+    warnings: []
+  };
+  try {
+    await (0, _clearAllStorage.clearAllAppStorage)();
+    result.applied += 1;
+  } catch (e) {
+    result.ok = false;
+    result.warnings.push(`asyncstorage clear failed: ${String(e)}`);
+  }
+  for (const {
+    id,
+    instance
+  } of _MMKVInstanceRegistry.mmkvInstanceRegistry.getAll()) {
+    if (instance.isReadOnly) {
+      result.skipped.push({
+        id: `mmkv:${id}`,
+        reason: "instance registered read-only"
+      });
+      continue;
+    }
+    try {
+      for (const key of instance.getAllKeys().filter(k => !(0, _sharedUi.isDevToolsStorageKey)(k))) {
+        deleteMMKVKey(instance, key);
+        result.applied += 1;
+      }
+    } catch (e) {
+      result.ok = false;
+      result.warnings.push(`mmkv "${id}" clear failed: ${String(e)}`);
+    }
+  }
+  for (const {
+    key,
+    options
+  } of _SecureStoreRegistry.secureStoreRegistry.getAll()) {
+    if (options.requireAuthentication) {
+      result.skipped.push({
+        id: `secure:${key}`,
+        reason: "biometric-protected keys are never written"
+      });
+      continue;
+    }
+    try {
+      await _SecureStoreRegistry.secureStoreRegistry.deleteValue(key);
+      result.applied += 1;
+    } catch (e) {
+      result.ok = false;
+      result.warnings.push(`secure "${key}" clear failed: ${String(e)}`);
+    }
+  }
+  return result;
+}
+const ITEM_RENDER_CHAR_LIMIT = 256 * 1024;
+function classifyValue(key, label, oldValue, newValue, inOld, inNew) {
+  if (!inNew) return {
+    key,
+    label,
+    verdict: "removed",
+    oldValue
+  };
+  if (!inOld) return {
+    key,
+    label,
+    verdict: "added",
+    newValue
+  };
+  if (Object.is(oldValue, newValue)) return {
+    key,
+    label,
+    verdict: "unchanged"
+  };
+  const tooLarge = typeof oldValue === "string" && oldValue.length > ITEM_RENDER_CHAR_LIMIT || typeof newValue === "string" && newValue.length > ITEM_RENDER_CHAR_LIMIT;
+  if (tooLarge) {
+    return {
+      key,
+      label,
+      verdict: "too-large",
+      reason: "value too large to render a diff — restore still applies it"
+    };
+  }
+  return {
+    key,
+    label,
+    verdict: "changed",
+    oldValue,
+    newValue
+  };
+}
+
+/** Per-key restore preview across all three backends. */
+async function previewItems(target, base) {
+  const targetData = target ?? {
+    async: [],
+    mmkv: {},
+    secure: {}
+  };
+  const liveMode = base === undefined;
+  const baseData = liveMode ? (await captureStorageData()).data : base ?? {
+    async: [],
+    mmkv: {},
+    secure: {}
+  };
+  const items = [];
+  const notes = [];
+
+  // ── AsyncStorage ──
+  const oldAsync = new Map(baseData.async ?? []);
+  const newAsync = new Map(targetData.async ?? []);
+  for (const key of new Set([...oldAsync.keys(), ...newAsync.keys()])) {
+    if ((0, _sharedUi.isDevToolsStorageKey)(key)) continue;
+    items.push(classifyValue(`async:${key}`, key, oldAsync.get(key), newAsync.get(key), oldAsync.has(key), newAsync.has(key)));
+  }
+
+  // ── MMKV ──
+  const instanceIds = new Set([...Object.keys(baseData.mmkv ?? {}), ...Object.keys(targetData.mmkv ?? {})]);
+  for (const id of instanceIds) {
+    const registered = liveMode ? _MMKVInstanceRegistry.mmkvInstanceRegistry.get(id) : null;
+    const instanceUnavailable = liveMode && !registered;
+    const readOnly = liveMode && registered?.instance.isReadOnly === true;
+    const oldEntries = new Map((baseData.mmkv?.[id] ?? []).map(e => [e.key, e]));
+    const newEntries = new Map((targetData.mmkv?.[id] ?? []).map(e => [e.key, e]));
+    for (const key of new Set([...oldEntries.keys(), ...newEntries.keys()])) {
+      if ((0, _sharedUi.isDevToolsStorageKey)(key)) continue;
+      const itemKey = `mmkv:${id}/${key}`;
+      const label = `${id} · ${key}`;
+      const oldE = oldEntries.get(key);
+      const newE = newEntries.get(key);
+      let item = classifyValue(itemKey, label, oldE?.value, newE?.value, oldEntries.has(key), newEntries.has(key));
+      if (item.verdict !== "unchanged") {
+        if (instanceUnavailable) {
+          item = {
+            ...item,
+            verdict: "wont-apply",
+            reason: "MMKV instance not registered"
+          };
+        } else if (readOnly) {
+          item = {
+            ...item,
+            verdict: "wont-apply",
+            reason: "MMKV instance registered read-only"
+          };
+        } else if (newE?.valueType === "buffer" || oldE?.valueType === "buffer") {
+          item = {
+            ...item,
+            verdict: "wont-apply",
+            reason: "ArrayBuffer values cannot be restored"
+          };
+        }
+      }
+      items.push(item);
+    }
+  }
+
+  // ── SecureStore ──
+  const oldSecure = baseData.secure ?? {};
+  const newSecure = targetData.secure ?? {};
+  const registeredSecure = liveMode ? new Map(_SecureStoreRegistry.secureStoreRegistry.getAll().map(e => [e.key, e])) : null;
+  for (const key of new Set([...Object.keys(oldSecure), ...Object.keys(newSecure)])) {
+    let item = classifyValue(`secure:${key}`, key, oldSecure[key], newSecure[key], key in oldSecure, key in newSecure);
+    if (liveMode && item.verdict !== "unchanged") {
+      const entry = registeredSecure?.get(key);
+      if (!entry) {
+        item = {
+          ...item,
+          verdict: "wont-apply",
+          reason: "key no longer registered with registerSecureStoreKeys"
+        };
+      } else if (entry.options.requireAuthentication) {
+        item = {
+          ...item,
+          verdict: "wont-apply",
+          reason: "biometric-protected keys are never written"
+        };
+      }
+    }
+    items.push(item);
+  }
+  if (liveMode) {
+    const biometric = _SecureStoreRegistry.secureStoreRegistry.getAll().filter(e => e.options.requireAuthentication).length;
+    if (biometric > 0) {
+      notes.push(`${biometric} biometric-protected secure key(s) are never read or written`);
+    }
+  }
+  return {
+    items,
+    notes
+  };
+}
+(0, _sharedUi.registerStateSnapshotProvider)({
+  id: "storage",
+  label: "Storage",
+  status,
+  capture,
+  restore,
+  clear,
+  previewItems
+});

package/lib/commonjs/storage/utils/storageTimeTravelUtils.js

@@ -16,6 +16,10 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
  * Provides jump and undo functionality for AsyncStorage operations.
  */
 
+function isOmittedStorageValue(value) {
+  return !!value && typeof value === "object" && value.__buoyValueOnDevice === true;
+}
+
 /**
  * Undo a single storage operation
  *
@@ -35,6 +39,9 @@ async function undoOperation(event) {
     action,
     data
   } = event;
+  if (isOmittedStorageValue(data?.prevValue) || isOmittedStorageValue(data?.prevPairs)) {
+    throw new Error("Cannot undo: previous value is still on the device — fetch getEventDetail first");
+  }
   {
     switch (action) {
       case "setItem":
@@ -113,6 +120,12 @@ async function jumpToState(events, targetEventIndex) {
   if (targetEventIndex < 0 || targetEventIndex >= events.length) {
     throw new Error(`Invalid event index: ${targetEventIndex}`);
   }
+  for (const event of events) {
+    const data = event.data;
+    if (isOmittedStorageValue(data?.value) || isOmittedStorageValue(data?.prevValue) || isOmittedStorageValue(data?.pairs) || isOmittedStorageValue(data?.prevPairs)) {
+      throw new Error("Cannot jump: some event values are still on the device — fetch getEventDetail first");
+    }
+  }
 
   // Build up the state by applying each event up to and including the target.
   // We use the final values from each event, not the operations themselves.
@@ -260,14 +273,15 @@ function canUndo(event) {
     case "setItem":
     case "mergeItem":
     case "removeItem":
-      // Can undo if we have the key
-      return !!data?.key;
+      // Can undo if we have the key — but not while prevValue is still a
+      // wire-form on-device marker (restoring that would write garbage).
+      return !!data?.key && !isOmittedStorageValue(data.prevValue);
     case "multiSet":
     case "multiRemove":
     case "multiMerge":
     case "clear":
       // Can undo if we have previous pairs
-      return !!data?.prevPairs && data.prevPairs.length > 0;
+      return !!data?.prevPairs && data.prevPairs.length > 0 && !isOmittedStorageValue(data.prevPairs);
     default:
       return false;
   }

package/lib/module/index.js

@@ -11,6 +11,9 @@
  * bypassing the tool's intended usage patterns.
  */
 
+// Side-effect: registers the Time Machine snapshot provider
+import "./storage/utils/snapshotProvider";
+
 // =============================================================================
 // PRESET (Primary entry point for users)
 // =============================================================================
@@ -79,7 +82,12 @@ export { storageSyncAdapter } from "./storage/sync/storageSyncAdapter";
 // INTERNAL EXPORTS (For @buoy-gg/* packages only - not part of public API)
 // =============================================================================
 /** @internal */
-export { storageEventStore } from "./storage/stores/storageEventStore";
+export { storageEventStore,
+// Exported so remote mirrors (Buoy Desktop) can ask "did the device withhold
+// this value?" without re-deriving the wire contract — and, in the case of
+// `batchPairsOf`, without re-introducing the union-narrowing bug that reading
+// `pairs`/`prevPairs` off a StorageEvent invites.
+isValueOnDevice, batchPairsOf } from "./storage/stores/storageEventStore";
 /**
  * Tell a mounted storage browser to re-read every backend. Used by the desktop
  * dashboard, where local storage listeners are suppressed and device data