@ursalock/zustand 0.2.8 → 0.3.1

package/dist/index.d.ts

@@ -142,6 +142,21 @@ interface SyncOptions {
     onStatusChange?: (status: SyncStatus) => void;
     /** HTTP client for making requests (default: FetchHttpClient) */
     httpClient?: IHttpClient;
+    /** Storage provider for offline queue (default: localStorage) */
+    storageProvider?: {
+        getItem(key: string): string | null;
+        setItem(key: string, value: string): void;
+    };
+    /**
+     * HMAC key for sync integrity verification (Encrypt-then-MAC).
+     * When provided, every push includes an HMAC-SHA256 tag over the
+     * ciphertext; every pull verifies it before passing data to the
+     * decryption layer. This detects server-side tampering.
+     *
+     * Should be derived from the user's master key via a separate
+     * derivation path (key separation principle).
+     */
+    hmacKey?: Uint8Array;
 }
 /**
  * Create a sync engine instance
@@ -254,6 +269,8 @@ type StoreVault<S, Ps> = S extends {
         hasPendingChanges: () => boolean;
         /** Clear all stored data (local + server) */
         clearStorage: () => Promise<void>;
+        /** Clean up sync interval and timers */
+        destroy: () => void;
         /** Subscribe to hydration start */
         onHydrate: (fn: VaultListener<T>) => () => void;
         /** Subscribe to hydration complete */
@@ -349,5 +366,33 @@ declare function useSyncStatus<T extends {
         getSyncStatus?: () => SyncStatus;
     };
 }>(useStore: () => T): SyncStatus;
+/**
+ * Hook to check if store has been hydrated
+ *
+ * @example
+ * ```tsx
+ * const hydrated = useHydrated(useStore)
+ * if (!hydrated) return <Loading />
+ * ```
+ */
+declare function useHydrated<T extends {
+    vault?: {
+        hasHydrated?: () => boolean;
+    };
+}>(useStore: () => T): boolean;
+/**
+ * Hook to check if there are pending offline changes
+ *
+ * @example
+ * ```tsx
+ * const hasPending = usePendingChanges(useStore)
+ * if (hasPending) return <PendingBadge />
+ * ```
+ */
+declare function usePendingChanges<T extends {
+    vault?: {
+        hasPendingChanges?: () => boolean;
+    };
+}>(useStore: () => T): boolean;
 
-export { type EncryptedStorageOptions, FetchHttpClient, type IHttpClient, type IHttpRequest, type IHttpResponse, type IStorageProvider, type IVaultStorage, type JwkEncryptedStorageOptions, type LegacyEncryptedStorageOptions, LocalStorageProvider, type SyncEngine, type SyncState, type SyncStatus, type VaultOptions, type VaultOptionsJwk, type VaultOptionsLegacy, type VaultStorage, createSyncEngine, createVaultStorage, useSyncStatus, vault };
+export { type EncryptedStorageOptions, FetchHttpClient, type IHttpClient, type IHttpRequest, type IHttpResponse, type IStorageProvider, type IVaultStorage, type JwkEncryptedStorageOptions, type LegacyEncryptedStorageOptions, LocalStorageProvider, type SyncEngine, type SyncState, type SyncStatus, type VaultOptions, type VaultOptionsJwk, type VaultOptionsLegacy, type VaultStorage, createSyncEngine, createVaultStorage, useHydrated, usePendingChanges, useSyncStatus, vault };

package/dist/index.js

@@ -4,8 +4,10 @@ import {
   decrypt,
   deriveKey,
   recoveryKeyToBytes,
+  validateRecoveryKey,
   encryptWithJwk,
-  decryptWithJwk
+  decryptWithJwk,
+  constantTimeEqual
 } from "@ursalock/crypto";
 
 // src/providers/local-storage.ts
@@ -77,6 +79,9 @@ function createJwkStorage(cipherJwk, storage, prefix) {
   };
 }
 function createLegacyStorage(recoveryKey, storage, prefix) {
+  if (!validateRecoveryKey(recoveryKey)) {
+    throw new Error("[ursalock] Invalid recovery key format");
+  }
   let cachedKey = null;
   let cachedSalt = null;
   async function getOrDeriveKey(salt) {
@@ -151,13 +156,7 @@ function base64ToBytes(base64) {
   }
   return bytes;
 }
-function arrayEqual(a, b) {
-  if (a.length !== b.length) return false;
-  for (let i = 0; i < a.length; i++) {
-    if (a[i] !== b[i]) return false;
-  }
-  return true;
-}
+var arrayEqual = constantTimeEqual;
 
 // src/providers/fetch-http.ts
 var FetchHttpClient = class {
@@ -177,6 +176,7 @@ var FetchHttpClient = class {
 };
 
 // src/sync.ts
+import { computeHmac, verifyHmac } from "@ursalock/crypto";
 var QUEUE_KEY = "ursalock:offline-queue";
 function createSyncEngine(options) {
   const {
@@ -186,29 +186,34 @@ function createSyncEngine(options) {
     onServerData,
     getLocalData,
     onStatusChange,
-    httpClient = new FetchHttpClient()
+    httpClient = new FetchHttpClient(),
+    storageProvider,
+    hmacKey
   } = options;
+  const textEncoder = new TextEncoder();
+  const queueStorage = storageProvider ?? (typeof localStorage !== "undefined" ? localStorage : null);
   let status = "idle";
   let lastSyncAt = null;
   let error = null;
+  let knownServerVersion = null;
   const setStatus = (newStatus, newError) => {
     status = newStatus;
     error = newError ?? null;
     onStatusChange?.(newStatus);
   };
   const loadQueue = () => {
-    if (typeof localStorage === "undefined") return { pending: [] };
+    if (!queueStorage) return { pending: [] };
     try {
-      const stored = localStorage.getItem(`${QUEUE_KEY}:${name}`);
+      const stored = queueStorage.getItem(`${QUEUE_KEY}:${name}`);
       return stored ? JSON.parse(stored) : { pending: [] };
     } catch {
       return { pending: [] };
     }
   };
   const saveQueue = (queue) => {
-    if (typeof localStorage === "undefined") return;
+    if (!queueStorage) return;
     try {
-      localStorage.setItem(`${QUEUE_KEY}:${name}`, JSON.stringify(queue));
+      queueStorage.setItem(`${QUEUE_KEY}:${name}`, JSON.stringify(queue));
     } catch {
     }
   };
@@ -228,7 +233,10 @@ function createSyncEngine(options) {
   };
   const fetchServer = async () => {
     const token = getToken();
-    if (!token) return null;
+    if (!token) {
+      console.warn("[ursalock] fetchServer: no auth token available, skipping");
+      return null;
+    }
     const res = await httpClient.request({
       url: `${serverUrl}/vault/by-name/${encodeURIComponent(name)}`,
       method: "GET",
@@ -239,17 +247,47 @@ function createSyncEngine(options) {
     });
     if (res.status === 404) return null;
     if (!res.ok) throw new Error(`Server error: ${res.status}`);
-    return res.json();
+    const vault2 = await res.json();
+    knownServerVersion = vault2.version;
+    return vault2;
+  };
+  const computeTag = async (data) => {
+    if (!hmacKey) return void 0;
+    return computeHmac(textEncoder.encode(data), hmacKey);
+  };
+  const verifyTag = async (vault2) => {
+    if (!hmacKey) return;
+    if (!vault2.hmac) {
+      console.warn(
+        "[ursalock] Server vault has no HMAC tag. This is expected for vaults created before integrity verification was enabled. The vault will be re-signed on next push."
+      );
+      return;
+    }
+    const valid = await verifyHmac(
+      textEncoder.encode(vault2.data),
+      hmacKey,
+      vault2.hmac
+    );
+    if (!valid) {
+      throw new Error(
+        "[ursalock] HMAC verification failed: server data has been tampered with or the integrity key is wrong"
+      );
+    }
   };
   const pushServer = async (data, salt) => {
     const token = getToken();
     if (!token) throw new Error("Not authenticated");
+    const hmac = await computeTag(data);
     let existing = null;
     try {
       existing = await fetchServer();
     } catch {
     }
     if (existing) {
+      const body = { data, salt, ...hmac != null && { hmac } };
+      if (knownServerVersion != null) {
+        body.version = knownServerVersion;
+      }
       const res = await httpClient.request({
         url: `${serverUrl}/vault/${existing.uid}`,
         method: "PUT",
@@ -257,13 +295,48 @@ function createSyncEngine(options) {
           "Authorization": `Bearer ${token}`,
           "Content-Type": "application/json"
         },
-        body: JSON.stringify({ data, salt })
+        body: JSON.stringify(body)
       });
+      if (res.status === 409) {
+        const latest = await fetchServer();
+        if (latest) {
+          await verifyTag(latest);
+          onServerData(latest.data, latest.salt, latest.updatedAt);
+          const retryLocal = getLocalData();
+          const retryHmac = await computeTag(retryLocal.data);
+          const retryBody = {
+            data: retryLocal.data,
+            salt: retryLocal.salt,
+            ...retryHmac != null && { hmac: retryHmac }
+          };
+          if (knownServerVersion != null) {
+            retryBody.version = knownServerVersion;
+          }
+          const retryRes = await httpClient.request({
+            url: `${serverUrl}/vault/${existing.uid}`,
+            method: "PUT",
+            headers: {
+              "Authorization": `Bearer ${token}`,
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify(retryBody)
+          });
+          if (!retryRes.ok) {
+            const errorText = await retryRes.text().catch(() => "");
+            throw new Error(`Server error: ${retryRes.status} ${errorText}`);
+          }
+          const result3 = await retryRes.json();
+          knownServerVersion = result3.version;
+          return result3;
+        }
+      }
       if (!res.ok) {
         const errorText = await res.text().catch(() => "");
         throw new Error(`Server error: ${res.status} ${errorText}`);
       }
-      return res.json();
+      const result2 = await res.json();
+      knownServerVersion = result2.version;
+      return result2;
     }
     const createRes = await httpClient.request({
       url: `${serverUrl}/vault`,
@@ -272,13 +345,17 @@ function createSyncEngine(options) {
         "Authorization": `Bearer ${token}`,
         "Content-Type": "application/json"
       },
-      body: JSON.stringify({ name, data, salt })
+      body: JSON.stringify({ name, data, salt, ...hmac != null && { hmac } })
     });
     if (createRes.status === 409) {
       const nowExisting = await fetchServer();
       if (!nowExisting) {
         throw new Error("Vault conflict but not found on retry");
       }
+      const retryBody = { data, salt, ...hmac != null && { hmac } };
+      if (knownServerVersion != null) {
+        retryBody.version = knownServerVersion;
+      }
       const retryRes = await httpClient.request({
         url: `${serverUrl}/vault/${nowExisting.uid}`,
         method: "PUT",
@@ -286,19 +363,23 @@ function createSyncEngine(options) {
           "Authorization": `Bearer ${token}`,
           "Content-Type": "application/json"
         },
-        body: JSON.stringify({ data, salt })
+        body: JSON.stringify(retryBody)
       });
       if (!retryRes.ok) {
         const errorText = await retryRes.text().catch(() => "");
         throw new Error(`Server error: ${retryRes.status} ${errorText}`);
       }
-      return retryRes.json();
+      const result2 = await retryRes.json();
+      knownServerVersion = result2.version;
+      return result2;
     }
     if (!createRes.ok) {
       const errorText = await createRes.text().catch(() => "");
       throw new Error(`Server error: ${createRes.status} ${errorText}`);
     }
-    return createRes.json();
+    const result = await createRes.json();
+    knownServerVersion = result.version;
+    return result;
   };
   const sync = async () => {
     if (!isOnline()) {
@@ -322,6 +403,7 @@ function createSyncEngine(options) {
           await pushServer(local.data, local.salt);
         }
       } else if (server.updatedAt > local.updatedAt) {
+        await verifyTag(server);
         onServerData(server.data, server.salt, server.updatedAt);
       } else if (local.updatedAt > server.updatedAt) {
         await pushServer(local.data, local.salt);
@@ -370,6 +452,7 @@ function createSyncEngine(options) {
       if (server) {
         const local = getLocalData();
         if (server.updatedAt > local.updatedAt) {
+          await verifyTag(server);
           onServerData(server.data, server.salt, server.updatedAt);
           lastSyncAt = Date.now();
           setStatus("synced");
@@ -401,6 +484,7 @@ function createSyncEngine(options) {
 }
 
 // src/vault.ts
+var logCatch = (context) => (err) => console.error(`[ursalock] ${context}:`, err);
 function isJwkMode2(options) {
   return "cipherJwk" in options;
 }
@@ -441,7 +525,7 @@ var vaultImpl = (config, baseOptions) => (set, get, api) => {
       getToken,
       onServerData: (data, _salt, updatedAt) => {
         if (localUpdatedAt > updatedAt) {
-          void syncEngine?.push();
+          void syncEngine?.push().catch(logCatch("Push after local-newer conflict"));
           return;
         }
         try {
@@ -449,7 +533,7 @@ var vaultImpl = (config, baseOptions) => (set, get, api) => {
           const merged = merge(parsed, get());
           set(merged, true);
           localUpdatedAt = updatedAt;
-          void storage.setItem(name, JSON.stringify(partialize({ ...get() })));
+          void storage.setItem(name, JSON.stringify(partialize({ ...get() }))).catch(logCatch("Persist server data to local storage"));
         } catch (err) {
           console.error("[ursalock] Failed to parse server data:", err);
         }
@@ -475,7 +559,7 @@ var vaultImpl = (config, baseOptions) => (set, get, api) => {
       }
       syncDebounceTimer = setTimeout(() => {
         syncDebounceTimer = null;
-        void syncEngine?.sync();
+        void syncEngine?.sync().catch(logCatch("Debounced sync"));
       }, 3e3);
     }
   };
@@ -529,7 +613,7 @@ var vaultImpl = (config, baseOptions) => (set, get, api) => {
     } else {
       savedSetState(state);
     }
-    void persistState();
+    void persistState().catch(logCatch("Persist state"));
   });
   const configResult = config(
     ((partial, replace) => {
@@ -538,7 +622,7 @@ var vaultImpl = (config, baseOptions) => (set, get, api) => {
       } else {
         set(partial);
       }
-      void persistState();
+      void persistState().catch(logCatch("Persist state"));
     }),
     get,
     api
@@ -565,15 +649,27 @@ var vaultImpl = (config, baseOptions) => (set, get, api) => {
   if (!skipHydration) {
     void rehydrate().then(() => {
       if (syncEngine) {
-        void syncEngine.sync();
+        void syncEngine.sync().catch(logCatch("Initial sync after hydration"));
       }
-    });
+    }).catch(logCatch("Auto-rehydration"));
   } else {
     hasHydrated = true;
   }
+  let syncIntervalId = null;
   if (server && syncInterval > 0) {
-    setInterval(() => void sync(), syncInterval);
+    syncIntervalId = setInterval(() => void sync().catch(logCatch("Periodic sync")), syncInterval);
   }
+  const vaultApi = storeWithVault.vault;
+  vaultApi.destroy = () => {
+    if (syncIntervalId) {
+      clearInterval(syncIntervalId);
+      syncIntervalId = null;
+    }
+    if (syncDebounceTimer) {
+      clearTimeout(syncDebounceTimer);
+      syncDebounceTimer = null;
+    }
+  };
   return configResult;
 };
 var vault = vaultImpl;
@@ -583,11 +679,21 @@ function useSyncStatus(useStore) {
   const store = useStore();
   return store.vault?.getSyncStatus?.() ?? "idle";
 }
+function useHydrated(useStore) {
+  const store = useStore();
+  return store.vault?.hasHydrated?.() ?? false;
+}
+function usePendingChanges(useStore) {
+  const store = useStore();
+  return store.vault?.hasPendingChanges?.() ?? false;
+}
 export {
   FetchHttpClient,
   LocalStorageProvider,
   createSyncEngine,
   createVaultStorage,
+  useHydrated,
+  usePendingChanges,
   useSyncStatus,
   vault
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ursalock/zustand",
-  "version": "0.2.8",
+  "version": "0.3.1",
   "description": "Encrypted persistence middleware for Zustand with passkey E2EE",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,7 +22,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@ursalock/crypto": "^0.2.0"
+    "@ursalock/crypto": "^0.3.1"
   },
   "peerDependencies": {
     "zustand": ">=4.0.0"