@buoy-gg/storage 7.0.40 → 7.0.42

package/lib/module/storage/hooks/useSecureStoreKeys.js

@@ -1,156 +1 @@
-"use strict";
-
-import { useState, useEffect, useCallback, useRef } from "react";
-import { secureStoreRegistry } from "../utils/SecureStoreRegistry";
-
-/**
- * Placeholder value shown for `requireAuthentication` keys. Reading those
- * triggers a biometric (Face ID / fingerprint) prompt, so the tool never
- * auto-reads them — it just shows they exist.
- */
-const BIOMETRIC_PLACEHOLDER = "•••••• (biometric protected)";
-
-/**
- * How often to re-read registered SecureStore values.
- *
- * SecureStore is the one backend with no change feed at all: AsyncStorage and
- * MMKV writes are intercepted (and MMKV has a native value-changed listener),
- * but the keychain gives no notification, so a value written by the app while
- * the tool is open would otherwise stay stale until the browser remounts.
- * Polling is the only option — kept cheap by re-reading a handful of registered
- * keys and only committing state when a value actually changed.
- */
-const DEFAULT_POLL_MS = 3000;
-/** Identity signature used to skip no-op state updates. */
-function signature(keys) {
-  return JSON.stringify(keys);
-}
-
-/**
- * Read all registered SecureStore keys into StorageKeyInfo[] for the browser.
- *
- * SecureStore has no enumeration API, so this only surfaces keys declared via
- * `registerSecureStoreKeys()` (see SecureStoreRegistry). Values are read with
- * the options each key was registered with (keychainService must match), and
- * biometric-protected keys are listed without being read.
- *
- * Values are re-read on a poll and whenever the registry changes, so the
- * browser tracks writes the app makes while the tool is open.
- */
-export function useSecureStoreKeys(options = {}) {
-  const {
-    pollMs = DEFAULT_POLL_MS
-  } = options;
-  const [storageKeys, setStorageKeys] = useState([]);
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState(null);
-
-  // Last committed content, so a poll that finds nothing new costs zero
-  // renders (this hook feeds a non-virtualized list of every storage key).
-  const signatureRef = useRef(signature([]));
-  const hasLoadedRef = useRef(false);
-  const inFlightRef = useRef(false);
-  const commit = useCallback(keys => {
-    const next = signature(keys);
-    if (next === signatureRef.current) return;
-    signatureRef.current = next;
-    setStorageKeys(keys);
-  }, []);
-  const fetchSecureStoreData = useCallback(async () => {
-    // Reads are async and the poll is unconditional — never stack them.
-    if (inFlightRef.current) return;
-    inFlightRef.current = true;
-    try {
-      const module = secureStoreRegistry.getModule();
-      const entries = secureStoreRegistry.getAll();
-      if (!module || entries.length === 0) {
-        commit([]);
-        hasLoadedRef.current = true;
-        setIsLoading(false);
-        return;
-      }
-
-      // Only the first read is a "loading" state; polls refresh in place so the
-      // browser never flashes its spinner over data it already has.
-      if (!hasLoadedRef.current) setIsLoading(true);
-      setError(null);
-      const keys = [];
-      for (const entry of entries) {
-        if (entry.options.requireAuthentication) {
-          // Never auto-read: reading would fire a biometric prompt.
-          keys.push({
-            key: entry.key,
-            value: BIOMETRIC_PLACEHOLDER,
-            storageType: "secure",
-            status: "optional_present",
-            category: "optional",
-            description: entry.description ?? "Protected by biometric authentication — value not read by DevTools",
-            ...(entry.options.keychainService && {
-              instanceId: entry.options.keychainService
-            })
-          });
-          continue;
-        }
-        let rawValue = null;
-        try {
-          rawValue = await module.getItemAsync(entry.key, entry.options);
-        } catch {
-          // Key unreadable (e.g. keychain state changed) — treat as missing.
-        }
-
-        // Parse JSON values for the DataViewer, same as the AsyncStorage hook.
-        let parsedValue = rawValue;
-        if (rawValue) {
-          try {
-            parsedValue = JSON.parse(rawValue);
-          } catch {
-            parsedValue = rawValue;
-          }
-        }
-        keys.push({
-          key: entry.key,
-          value: rawValue === null ? undefined : parsedValue,
-          storageType: "secure",
-          status: rawValue === null ? "required_missing" : "optional_present",
-          category: rawValue === null ? "required" : "optional",
-          ...(entry.description && {
-            description: entry.description
-          }),
-          ...(entry.options.keychainService && {
-            instanceId: entry.options.keychainService
-          })
-        });
-      }
-      commit(keys);
-    } catch (err) {
-      setError(err instanceof Error ? err : new Error("Failed to read SecureStore"));
-      commit([]);
-    } finally {
-      hasLoadedRef.current = true;
-      inFlightRef.current = false;
-      setIsLoading(false);
-    }
-  }, [commit]);
-
-  // Initial fetch + poll. Registration usually happens at app startup, but the
-  // registry is also refilled on the dashboard every time a device syncs, so
-  // subscribe as well rather than assuming the key list is final at mount.
-  useEffect(() => {
-    fetchSecureStoreData();
-    const unsubscribe = secureStoreRegistry.subscribe(() => {
-      fetchSecureStoreData();
-    });
-    if (pollMs <= 0) return unsubscribe;
-    const interval = setInterval(fetchSecureStoreData, pollMs);
-    return () => {
-      unsubscribe();
-      clearInterval(interval);
-    };
-  }, [fetchSecureStoreData, pollMs]);
-  return {
-    storageKeys,
-    isLoading,
-    error,
-    refresh: fetchSecureStoreData
-  };
-}
+"use strict";import{useState as k,useEffect as M,useCallback as L,useRef as p}from"react";import{requiredKeyAppliesTo as J}from"../utils/requiredStorageKeyScope";import{secureStoreRegistry as _}from"../utils/SecureStoreRegistry";const N="\u2022\u2022\u2022\u2022\u2022\u2022 (biometric protected)";const P=3e3;function R(c){return JSON.stringify(c)}export function useSecureStoreKeys(c=[],A={}){const{pollMs:d=P}=A;const x=p(c);x.current=c;const E=JSON.stringify(c);const[I,w]=k([]);const[O,f]=k(true);const[V,v]=k(null);const T=p(R([]));const y=p(false);const g=p(false);const l=L(r=>{const o=R(r);if(o===T.current)return;T.current=o;w(r)},[]);const u=L(async()=>{if(g.current)return;g.current=true;try{const r=_.getModule();const o=_.getAll();const S=x.current.filter(e=>J(e,"secure"));const C=e=>S.find(t=>(typeof t==="string"?t:t.key)===e);if(!r||o.length===0&&S.length===0){l([]);y.current=true;f(false);return}if(!y.current)f(true);v(null);const h=[];const D=[...o,...S.map(e=>typeof e==="string"?e:e.key).filter(e=>!o.some(t=>t.key===e)).map(e=>({key:e,options:{},description:void 0}))];for(const e of D){const t=C(e.key);const n=typeof t==="object"?t:void 0;const b={...n?.expectedValue!==void 0&&{expectedValue:n.expectedValue},...n?.expectedType!==void 0&&{expectedType:n.expectedType}};const m=n?.description??e.description;if(e.options.requireAuthentication){h.push({key:e.key,value:N,storageType:"secure",status:t?"required_present":"optional_present",category:t?"required":"optional",description:m??"Protected by biometric authentication \u2014 value not read by DevTools",...b,...e.options.keychainService&&{instanceId:e.options.keychainService}});continue}let i=null;try{i=await r.getItemAsync(e.key,e.options)}catch{}if(i===null&&!t)continue;let s=i;if(i){try{s=JSON.parse(i)}catch{s=i}}let a="optional_present";if(t){if(i===null)a="required_missing";else if(n?.expectedValue!==void 0)a=String(s)===String(n.expectedValue)?"required_present":"required_wrong_value";else if(n?.expectedType!==void 0){const F=s===null?"null":Array.isArray(s)?"array":typeof s;const q=n.expectedType.toLowerCase();a=F===q||q==="string"&&typeof i==="string"?"required_present":"required_wrong_type"}else a="required_present"}h.push({key:e.key,value:i===null?void 0:s,storageType:"secure",status:a,category:t?"required":"optional",...m&&{description:m},...b,...e.options.keychainService&&{instanceId:e.options.keychainService}})}l(h)}catch(r){v(r instanceof Error?r:new Error("Failed to read SecureStore"));l([])}finally{y.current=true;g.current=false;f(false)}},[l,E]);M(()=>{u();const r=_.subscribe(()=>{u()});if(d<=0)return r;const o=setInterval(u,d);return()=>{r();clearInterval(o)}},[u,d]);return{storageKeys:I,isLoading:O,error:V,refresh:u}}

package/lib/module/storage/hooks/useStorageEvents.js

@@ -1,58 +1 @@
-"use strict";
-
-/**
- * useStorageEvents Hook
- *
- * React hook for subscribing to storage events from the centralized store.
- * Uses self-managing Subscribable pattern - the storage listener automatically
- * starts when this hook mounts and stops when all subscribers unmount.
- *
- * @example
- * ```typescript
- * function MyComponent() {
- *   const { events, clearEvents, isCapturing } = useStorageEvents();
- *
- *   return (
- *     <View>
- *       {events.map((event) => (
- *         <Text key={event.timestamp.toString()}>
- *           {event.action}: {event.data?.key}
- *         </Text>
- *       ))}
- *     </View>
- *   );
- * }
- * ```
- */
-
-import { useMemo } from "react";
-import { useEventStoreEvents } from "@buoy-gg/shared-ui";
-import { storageEventStore } from "../stores/storageEventStore";
-
-// Re-export StorageEvent for convenience
-
-export function useStorageEvents(options = {}) {
-  const {
-    storageType = "all",
-    maxEvents = 500,
-    enabled = true
-  } = options;
-  // Stable per storageType so the shared hook doesn't resubscribe every render.
-  const select = useMemo(() => storageType === "all" ? undefined : events => events.filter(e => e.storageType === storageType), [storageType]);
-  // Subscribing auto-starts the storage listener (Subscribable pattern), and
-  // the shared hook frame-coalesces write bursts into one commit.
-  const {
-    events,
-    clearEvents,
-    isActive
-  } = useEventStoreEvents(storageEventStore, {
-    maxEvents,
-    enabled,
-    select
-  });
-  return {
-    events,
-    clearEvents,
-    isCapturing: isActive
-  };
-}
+"use strict";import{useMemo as l}from"react";import{useEventStoreEvents as m}from"@buoy-gg/shared-ui";import{storageEventStore as v}from"../stores/storageEventStore";export function useStorageEvents(t={}){const{storageType:e="all",maxEvents:r=500,enabled:s=true}=t;const o=l(()=>e==="all"?void 0:u=>u.filter(c=>c.storageType===e),[e]);const{events:n,clearEvents:i,isActive:a}=m(v,{maxEvents:r,enabled:s,select:o});return{events:n,clearEvents:i,isCapturing:a}}

package/lib/module/storage/stores/storageEventStore.js

@@ -1,301 +1 @@
-"use strict";
-
-/**
- * Storage Event Store
- *
- * Centralized store that aggregates storage events from AsyncStorage and MMKV
- * into a single event stream. Uses BaseEventStore pattern - the storage listener
- * automatically starts when the first subscriber joins and stops when the last
- * subscriber leaves.
- *
- * @example
- * ```typescript
- * import { storageEventStore } from '@buoy-gg/storage';
- *
- * // Subscribe to storage events - automatically starts capturing!
- * const unsubscribe = storageEventStore.subscribeToEvents((events) => {
- *   console.log('Storage events:', events);
- * });
- *
- * // Later, clean up - automatically stops if no other subscribers
- * unsubscribe();
- * ```
- */
-
-import { BaseEventStore } from "@buoy-gg/shared-ui";
-import { startListening as startAsyncStorageListening, addListener as addAsyncStorageListener, isListening as isAsyncStorageListening } from "../utils/AsyncStorageListener";
-import { addMMKVListener } from "../utils/MMKVListener";
-import { mmkvInstanceRegistry } from "../utils/MMKVInstanceRegistry";
-import { detectMMKVType } from "../utils/mmkvTypeDetection";
-
-/**
- * Unified storage event type combining AsyncStorage and MMKV events.
- * `id` is assigned by the store when the event enters — needed because raw
- * events have no unique identifier (rapid same-key writes can share a
- * millisecond timestamp), and React keys must be unique per render.
- */
-
-/** True when a field is the wire-form VALUE_ON_DEVICE marker. */
-export function isValueOnDevice(value) {
-  return !!value && typeof value === "object" && value.__buoyValueOnDevice === true;
-}
-
-/**
- * `pairs` / `prevPairs` are AsyncStorage-only — they carry the batch
- * operations (multiSet / multiRemove / multiMerge / clear), and MMKV has no
- * batch API, so its `data` has no such fields. Reading them off the
- * `StorageEvent` union needs narrowing, and this is the one place that does
- * it; writing them unconditionally would also graft meaningless keys onto
- * every MMKV event on the wire.
- */
-export function batchPairsOf(event) {
-  if (event.storageType !== "async" || !event.data) return {};
-  return {
-    pairs: event.data.pairs,
-    prevPairs: event.data.prevPairs
-  };
-}
-function eventHasOnDeviceValues(event) {
-  const data = event.data;
-  if (!data) return false;
-  const {
-    pairs,
-    prevPairs
-  } = batchPairsOf(event);
-  return isValueOnDevice(data.value) || isValueOnDevice(data.prevValue) || isValueOnDevice(pairs) || isValueOnDevice(prevPairs);
-}
-let storageEventIdCounter = 0;
-function nextStorageEventId() {
-  return `se-${Date.now()}-${++storageEventIdCounter}`;
-}
-
-/**
- * Listener callback type for storage events array
- */
-
-/**
- * Listener callback for individual new events
- */
-
-class StorageEventStore extends BaseEventStore {
-  // Unsubscribe functions for raw listeners
-  asyncStorageUnsubscribe = null;
-  mmkvUnsubscribe = null;
-  hasScannedInitialState = false;
-  constructor() {
-    super({
-      storeName: "storage",
-      maxEvents: 500
-    });
-  }
-
-  /**
-   * Scan all registered MMKV instances and AsyncStorage for existing keys,
-   * creating synthetic events so that getEvents() includes the current state
-   * (not just changes made after capture started). Only runs once per store
-   * lifetime to avoid duplicates.
-   */
-  async scanExistingState() {
-    if (this.hasScannedInitialState) return;
-    this.hasScannedInitialState = true;
-    const now = new Date();
-
-    // ── MMKV: synchronous scan ──
-    const instances = mmkvInstanceRegistry.getAll();
-    for (const {
-      id: instanceId,
-      instance
-    } of instances) {
-      try {
-        const keys = instance.getAllKeys();
-        for (const key of keys) {
-          const {
-            value,
-            type: valueType
-          } = detectMMKVType(instance, key);
-          const actionMap = {
-            string: "set.string",
-            number: "set.number",
-            boolean: "set.boolean",
-            buffer: "set.buffer"
-          };
-          const action = actionMap[valueType] ?? "set.string";
-          this.addEvent({
-            action,
-            timestamp: now,
-            instanceId,
-            data: {
-              key,
-              value,
-              valueType,
-              initialScan: true
-            },
-            storageType: "mmkv",
-            id: nextStorageEventId()
-          });
-        }
-      } catch {
-        // Instance may not be accessible — skip silently
-      }
-    }
-
-    // ── AsyncStorage: async scan ──
-    try {
-      const {
-        asyncStorage,
-        readMany
-      } = require("../utils/asyncStorageCompat");
-      if (asyncStorage) {
-        const allKeys = await asyncStorage.getAllKeys();
-        if (allKeys.length > 0) {
-          const pairs = await readMany(allKeys);
-          for (const [key, rawValue] of pairs) {
-            this.addEvent({
-              action: "setItem",
-              timestamp: now,
-              data: {
-                key,
-                value: rawValue ?? undefined,
-                initialScan: true
-              },
-              storageType: "async",
-              id: nextStorageEventId()
-            });
-          }
-        }
-      }
-    } catch {
-      // AsyncStorage not available — skip silently
-    }
-  }
-
-  /**
-   * Start capturing storage events from both AsyncStorage and MMKV
-   */
-  async startCapturing() {
-    // Start AsyncStorage listening if not already active
-    if (!isAsyncStorageListening()) {
-      await startAsyncStorageListening();
-    }
-
-    // Subscribe to AsyncStorage events
-    if (!this.asyncStorageUnsubscribe) {
-      this.asyncStorageUnsubscribe = addAsyncStorageListener(event => {
-        const storageEvent = {
-          ...event,
-          storageType: "async",
-          id: nextStorageEventId()
-        };
-        this.addEvent(storageEvent);
-      });
-    }
-
-    // Subscribe to MMKV events
-    if (!this.mmkvUnsubscribe) {
-      this.mmkvUnsubscribe = addMMKVListener(event => {
-        const storageEvent = {
-          ...event,
-          storageType: "mmkv",
-          id: nextStorageEventId()
-        };
-        this.addEvent(storageEvent);
-      });
-    }
-
-    // Scan existing keys so getEvents() includes pre-existing state
-    await this.scanExistingState();
-  }
-
-  /**
-   * Stop capturing storage events
-   */
-  stopCapturing() {
-    // Unsubscribe from AsyncStorage
-    if (this.asyncStorageUnsubscribe) {
-      this.asyncStorageUnsubscribe();
-      this.asyncStorageUnsubscribe = null;
-    }
-
-    // Unsubscribe from MMKV
-    if (this.mmkvUnsubscribe) {
-      this.mmkvUnsubscribe();
-      this.mmkvUnsubscribe = null;
-    }
-  }
-
-  /**
-   * Check if currently capturing events (has subscribers)
-   */
-  isCapturing() {
-    return this.asyncStorageUnsubscribe !== null || this.mmkvUnsubscribe !== null;
-  }
-
-  /**
-   * Get events filtered by storage type
-   */
-  getEventsByType(storageType) {
-    return this.events.filter(event => event.storageType === storageType);
-  }
-
-  /**
-   * Replace the event list, keeping values a remote mirror already hydrated.
-   * Wire-form snapshots always carry VALUE_ON_DEVICE markers for oversized
-   * payloads; a later snapshot must not blank the detail pane (or wipe
-   * `prevValue` that time-travel undo needs).
-   */
-  replaceEvents(events) {
-    const hydrated = new Map();
-    for (const existing of this.events) {
-      if (!eventHasOnDeviceValues(existing)) {
-        hydrated.set(existing.id, existing);
-      }
-    }
-    const merged = events.map(incoming => {
-      const kept = hydrated.get(incoming.id);
-      if (!kept || !eventHasOnDeviceValues(incoming)) return incoming;
-      // Restore only the fields this event's storage type actually has, so an
-      // MMKV event never grows `pairs`/`prevPairs` it has no meaning for.
-      return {
-        ...incoming,
-        data: {
-          ...incoming.data,
-          value: kept.data?.value,
-          prevValue: kept.data?.prevValue,
-          ...batchPairsOf(kept)
-        }
-      };
-    });
-    super.replaceEvents(merged);
-  }
-
-  /**
-   * Hydrate one mirrored event with real values fetched on demand from the
-   * device via the adapter's `getEventDetail`. Remote-mirror (desktop) only.
-   */
-  hydrateEvent(event) {
-    const index = this.events.findIndex(e => e.id === event.id);
-    if (index === -1) return;
-    const current = this.events[index];
-    const next = this.events.slice();
-    next[index] = {
-      ...current,
-      ...event,
-      timestamp: current.timestamp,
-      data: {
-        ...current.data,
-        ...event.data
-      }
-    };
-    super.replaceEvents(next);
-  }
-}
-
-// Singleton instance
-export const storageEventStore = new StorageEventStore();
-
-// Convenience exports
-export const subscribeToStorageEvents = listener => storageEventStore.subscribeToEvents(listener);
-export const onStorageEvent = callback => storageEventStore.onEvent(callback);
-export const getStorageEvents = () => storageEventStore.getEvents();
-export const clearStorageEvents = () => storageEventStore.clearEvents();
-export const isStorageCapturing = () => storageEventStore.isCapturing();
+"use strict";import{BaseEventStore as l}from"@buoy-gg/shared-ui";import{startListening as v,addListener as m,isListening as y}from"../utils/AsyncStorageListener";import{addMMKVListener as b}from"../utils/MMKVListener";import{mmkvInstanceRegistry as f}from"../utils/MMKVInstanceRegistry";import{detectMMKVType as h}from"../utils/mmkvTypeDetection";export function isValueOnDevice(s){return!!s&&typeof s==="object"&&s.__buoyValueOnDevice===true}export function batchPairsOf(s){if(s.storageType!=="async"||!s.data)return{};return{pairs:s.data.pairs,prevPairs:s.data.prevPairs}}function d(s){const t=s.data;if(!t)return false;const{pairs:n,prevPairs:a}=batchPairsOf(s);return isValueOnDevice(t.value)||isValueOnDevice(t.prevValue)||isValueOnDevice(n)||isValueOnDevice(a)}let S=0;function c(){return`se-${Date.now()}-${++S}`}class E extends l{asyncStorageUnsubscribe=null;mmkvUnsubscribe=null;hasScannedInitialState=false;constructor(){super({storeName:"storage",maxEvents:500})}async scanExistingState(){if(this.hasScannedInitialState)return;this.hasScannedInitialState=true;const t=new Date;const n=f.getAll();for(const{id:a,instance:e}of n){try{const r=e.getAllKeys();for(const i of r){const{value:u,type:o}=h(e,i);const p={string:"set.string",number:"set.number",boolean:"set.boolean",buffer:"set.buffer"};const g=p[o]??"set.string";this.addEvent({action:g,timestamp:t,instanceId:a,data:{key:i,value:u,valueType:o,initialScan:true},storageType:"mmkv",id:c()})}}catch{}}try{const{asyncStorage:a,readMany:e}=require("../utils/asyncStorageCompat");if(a){const r=await a.getAllKeys();if(r.length>0){const i=await e(r);for(const[u,o]of i){this.addEvent({action:"setItem",timestamp:t,data:{key:u,value:o??void 0,initialScan:true},storageType:"async",id:c()})}}}}catch{}}async startCapturing(){if(!y()){await v()}if(!this.asyncStorageUnsubscribe){this.asyncStorageUnsubscribe=m(t=>{const n={...t,storageType:"async",id:c()};this.addEvent(n)})}if(!this.mmkvUnsubscribe){this.mmkvUnsubscribe=b(t=>{const n={...t,storageType:"mmkv",id:c()};this.addEvent(n)})}await this.scanExistingState()}stopCapturing(){if(this.asyncStorageUnsubscribe){this.asyncStorageUnsubscribe();this.asyncStorageUnsubscribe=null}if(this.mmkvUnsubscribe){this.mmkvUnsubscribe();this.mmkvUnsubscribe=null}}isCapturing(){return this.asyncStorageUnsubscribe!==null||this.mmkvUnsubscribe!==null}getEventsByType(t){return this.events.filter(n=>n.storageType===t)}replaceEvents(t){const n=new Map;for(const e of this.events){if(!d(e)){n.set(e.id,e)}}const a=t.map(e=>{const r=n.get(e.id);if(!r||!d(e))return e;return{...e,data:{...e.data,value:r.data?.value,prevValue:r.data?.prevValue,...batchPairsOf(r)}}});super.replaceEvents(a)}hydrateEvent(t){const n=this.events.findIndex(r=>r.id===t.id);if(n===-1)return;const a=this.events[n];const e=this.events.slice();e[n]={...a,...t,timestamp:a.timestamp,data:{...a.data,...t.data}};super.replaceEvents(e)}}export const storageEventStore=new E;export const subscribeToStorageEvents=s=>storageEventStore.subscribeToEvents(s);export const onStorageEvent=s=>storageEventStore.onEvent(s);export const getStorageEvents=()=>storageEventStore.getEvents();export const clearStorageEvents=()=>storageEventStore.clearEvents();export const isStorageCapturing=()=>storageEventStore.isCapturing();