@ursalock/zustand 0.2.8

package/dist/index.d.ts

@@ -0,0 +1,353 @@
+import { StoreMutatorIdentifier, StateCreator } from 'zustand';
+import { CipherJWK } from '@ursalock/crypto';
+
+/**
+ * Storage interfaces for vault middleware
+ * Follows Dependency Inversion Principle - depend on abstractions not concretions
+ */
+/**
+ * Base storage provider interface
+ * Abstracts away the underlying storage mechanism (localStorage, AsyncStorage, etc.)
+ */
+interface IStorageProvider {
+    /** Get item from storage */
+    getItem(key: string): Promise<string | null>;
+    /** Set item in storage */
+    setItem(key: string, value: string): Promise<void>;
+    /** Remove item from storage */
+    removeItem(key: string): Promise<void>;
+}
+/**
+ * Encrypted vault storage interface
+ * Higher-level abstraction that handles encryption/decryption
+ */
+interface IVaultStorage {
+    /** Get decrypted state from storage */
+    getItem(name: string): Promise<string | null>;
+    /** Set encrypted state in storage */
+    setItem(name: string, value: string): Promise<void>;
+    /** Remove state from storage */
+    removeItem(name: string): Promise<void>;
+}
+
+/**
+ * Encrypted storage layer for vault middleware
+ * Supports both legacy recovery key and new CipherJWK encryption
+ *
+ * Refactored to follow SOLID principles:
+ * - Uses IStorageProvider interface (Dependency Inversion)
+ * - Separates encryption concerns from storage access (Single Responsibility)
+ * - Injectable storage provider for testing
+ */
+
+interface VaultStorage extends IVaultStorage {
+}
+
+/** Legacy options using recovery key string */
+interface LegacyEncryptedStorageOptions {
+    /** Recovery key for encryption (legacy mode) */
+    recoveryKey: string;
+    /** Underlying storage provider (default: LocalStorageProvider) */
+    storageProvider?: IStorageProvider;
+    /** Key prefix in storage */
+    prefix?: string;
+    /** @deprecated Use storageProvider instead. For backward compatibility with VaultStorage */
+    storage?: VaultStorage;
+}
+/** New options using CipherJWK directly */
+interface JwkEncryptedStorageOptions {
+    /** CipherJWK for encryption (from ZKCredentials) */
+    cipherJwk: CipherJWK;
+    /** Underlying storage provider (default: LocalStorageProvider) */
+    storageProvider?: IStorageProvider;
+    /** Key prefix in storage */
+    prefix?: string;
+    /** @deprecated Use storageProvider instead. For backward compatibility with VaultStorage */
+    storage?: VaultStorage;
+}
+type EncryptedStorageOptions = LegacyEncryptedStorageOptions | JwkEncryptedStorageOptions;
+/**
+ * Create an encrypted storage wrapper
+ * Supports both legacy recovery key and new CipherJWK modes
+ *
+ * Uses dependency injection for storage provider (Dependency Inversion Principle)
+ */
+declare function createVaultStorage(options: EncryptedStorageOptions): VaultStorage;
+
+/**
+ * HTTP client interface for sync engine
+ * Follows Dependency Inversion Principle - allows mocking and alternative implementations
+ */
+/** HTTP request options */
+interface IHttpRequest {
+    url: string;
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    headers?: Record<string, string>;
+    body?: string;
+}
+/** HTTP response */
+interface IHttpResponse {
+    ok: boolean;
+    status: number;
+    json<T = unknown>(): Promise<T>;
+    text(): Promise<string>;
+}
+/** HTTP client interface */
+interface IHttpClient {
+    /**
+     * Make an HTTP request
+     * @param request Request options
+     * @returns Response
+     */
+    request(request: IHttpRequest): Promise<IHttpResponse>;
+}
+
+/**
+ * Sync engine for vault middleware
+ * Handles bidirectional sync with server + offline queue
+ *
+ * Refactored to follow SOLID principles:
+ * - IHttpClient interface (Dependency Inversion)
+ * - Separated offline queue logic (Single Responsibility)
+ * - Injectable HTTP client for testing
+ */
+
+type SyncStatus = "idle" | "syncing" | "synced" | "error" | "offline";
+interface SyncState {
+    /** Last successful sync timestamp */
+    lastSyncAt: number | null;
+    /** Current sync status */
+    status: SyncStatus;
+    /** Pending changes waiting to be synced */
+    pendingChanges: boolean;
+    /** Last error message */
+    error: string | null;
+}
+interface SyncOptions {
+    /** Server base URL */
+    serverUrl: string;
+    /** Vault name */
+    name: string;
+    /** Auth token getter */
+    getToken: () => string | null;
+    /** Called when server has newer data */
+    onServerData: (data: string, salt: string, updatedAt: number) => void;
+    /** Get current local data */
+    getLocalData: () => {
+        data: string;
+        salt: string;
+        updatedAt: number;
+    };
+    /** Called on sync status change */
+    onStatusChange?: (status: SyncStatus) => void;
+    /** HTTP client for making requests (default: FetchHttpClient) */
+    httpClient?: IHttpClient;
+}
+/**
+ * Create a sync engine instance
+ * Uses dependency injection for HTTP client (Dependency Inversion Principle)
+ */
+declare function createSyncEngine(options: SyncOptions): {
+    sync: () => Promise<void>;
+    push: () => Promise<void>;
+    pull: () => Promise<boolean>;
+    getState: () => SyncState;
+    clearQueue: () => void;
+};
+type SyncEngine = ReturnType<typeof createSyncEngine>;
+
+/**
+ * vault() middleware - Drop-in replacement for persist()
+ * Adds E2EE encryption and cloud sync to Zustand stores
+ *
+ * Supports two encryption modes:
+ * - Legacy: recoveryKey string (Argon2id key derivation)
+ * - New: cipherJwk from ZKCredentials (PRF-derived)
+ *
+ * Type pattern follows zustand's persist middleware:
+ * - Simple internal implementation type (VaultImpl)
+ * - Complex public API type (Vault)
+ * - Cast at export: `vaultImpl as unknown as Vault`
+ */
+
+/** Base vault middleware options */
+interface VaultOptionsBase<S, PersistedState = S> {
+    /** Unique name for this vault (used as storage key) */
+    name: string;
+    /**
+     * Server URL for sync (optional)
+     * If not provided, only local encrypted storage is used
+     */
+    server?: string;
+    /**
+     * Auth token getter for server sync
+     * Required if server is provided
+     */
+    getToken?: () => string | null;
+    /** Custom storage implementation */
+    storage?: VaultStorage;
+    /** Storage key prefix (default: 'ursalock:') */
+    prefix?: string;
+    /**
+     * Partial state to persist
+     * @default (state) => state (persist everything)
+     */
+    partialize?: (state: S) => PersistedState;
+    /**
+     * Merge function for rehydration
+     * @default Object.assign
+     */
+    merge?: (persistedState: unknown, currentState: S) => S;
+    /**
+     * Called when state is loaded from storage
+     */
+    onRehydrateStorage?: (state: S) => ((state?: S, error?: unknown) => void) | void;
+    /**
+     * Skip hydration on init (useful for SSR)
+     * Call rehydrate() manually when ready
+     */
+    skipHydration?: boolean;
+    /**
+     * Sync interval in ms (default: 30000 = 30s)
+     * Set to 0 to disable auto-sync
+     */
+    syncInterval?: number;
+}
+/** Legacy options using recovery key string */
+interface VaultOptionsLegacy<S, PersistedState = S> extends VaultOptionsBase<S, PersistedState> {
+    /** Recovery key for E2EE encryption (legacy mode) */
+    recoveryKey: string;
+}
+/** New options using CipherJWK from ZKCredentials */
+interface VaultOptionsJwk<S, PersistedState = S> extends VaultOptionsBase<S, PersistedState> {
+    /** CipherJWK for E2EE encryption (from ZKCredentials) */
+    cipherJwk: CipherJWK;
+}
+type VaultOptions<S, PersistedState = S> = VaultOptionsLegacy<S, PersistedState> | VaultOptionsJwk<S, PersistedState>;
+
+type VaultListener<S> = (state: S) => void;
+
+/** Store shape extended with vault API */
+type StoreVault<S, Ps> = S extends {
+    getState: () => infer T;
+    setState: {
+        (...args: infer Sa1): infer Sr1;
+        (...args: infer Sa2): infer Sr2;
+    };
+} ? {
+    setState(...args: Sa1): Sr1 | Promise<void>;
+    setState(...args: Sa2): Sr2 | Promise<void>;
+    vault: {
+        /** Full bidirectional sync with server */
+        sync: () => Promise<void>;
+        /** Push local changes to server */
+        push: () => Promise<void>;
+        /** Pull latest from server */
+        pull: () => Promise<boolean>;
+        /** Rehydrate from local storage */
+        rehydrate: () => Promise<void>;
+        /** Check if store has been hydrated */
+        hasHydrated: () => boolean;
+        /** Get current sync status */
+        getSyncStatus: () => SyncStatus;
+        /** Check if there are pending offline changes */
+        hasPendingChanges: () => boolean;
+        /** Clear all stored data (local + server) */
+        clearStorage: () => Promise<void>;
+        /** Subscribe to hydration start */
+        onHydrate: (fn: VaultListener<T>) => () => void;
+        /** Subscribe to hydration complete */
+        onFinishHydration: (fn: VaultListener<T>) => () => void;
+    };
+} : never;
+type Write<T, U> = Omit<T, keyof U> & U;
+type WithVault<S, A> = Write<S, StoreVault<S, A>>;
+/** Public API type with complex mutator support */
+type Vault = <T, Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = [], U = T>(initializer: StateCreator<T, [...Mps, ["vault", unknown]], Mcs>, options: VaultOptions<T, U>) => StateCreator<T, Mps, [["vault", U], ...Mcs]>;
+declare module "zustand" {
+    interface StoreMutators<S, A> {
+        vault: WithVault<S, A>;
+    }
+}
+/**
+ * vault() middleware - Add E2EE encrypted persistence to Zustand
+ *
+ * @example Using CipherJWK from ZKCredentials (recommended)
+ * ```ts
+ * const useStore = create(
+ *   vault(
+ *     (set) => ({
+ *       count: 0,
+ *       increment: () => set((s) => ({ count: s.count + 1 })),
+ *     }),
+ *     {
+ *       name: 'my-store',
+ *       cipherJwk: credential.cipherJwk, // From ZKCredentials
+ *       server: 'https://vault.example.com', // optional
+ *     }
+ *   )
+ * )
+ * ```
+ *
+ * @example Using recovery key (legacy)
+ * ```ts
+ * const useStore = create(
+ *   vault(
+ *     (set) => ({ ... }),
+ *     {
+ *       name: 'my-store',
+ *       recoveryKey: 'ABCD-EFGH-...',
+ *     }
+ *   )
+ * )
+ * ```
+ */
+declare const vault: Vault;
+
+/**
+ * LocalStorage implementation of IStorageProvider
+ * Concrete implementation following Dependency Inversion Principle
+ */
+
+/**
+ * LocalStorage provider with async interface
+ * Wraps synchronous localStorage with async API for consistency
+ */
+declare class LocalStorageProvider implements IStorageProvider {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+
+/**
+ * Fetch-based HTTP client implementation
+ * Concrete implementation of IHttpClient using browser fetch API
+ */
+
+/**
+ * HTTP client using native fetch API
+ */
+declare class FetchHttpClient implements IHttpClient {
+    request(request: IHttpRequest): Promise<IHttpResponse>;
+}
+
+/**
+ * React hooks for vault status
+ */
+
+/**
+ * Hook to get sync status from a vault store
+ *
+ * @example
+ * ```tsx
+ * const status = useSyncStatus(useStore)
+ * // 'idle' | 'syncing' | 'synced' | 'error' | 'offline'
+ * ```
+ */
+declare function useSyncStatus<T extends {
+    vault?: {
+        getSyncStatus?: () => SyncStatus;
+    };
+}>(useStore: () => T): SyncStatus;
+
+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 };

package/dist/index.js

@@ -0,0 +1,593 @@
+// src/storage.ts
+import {
+  encrypt,
+  decrypt,
+  deriveKey,
+  recoveryKeyToBytes,
+  encryptWithJwk,
+  decryptWithJwk
+} from "@ursalock/crypto";
+
+// src/providers/local-storage.ts
+var LocalStorageProvider = class {
+  async getItem(key) {
+    if (typeof window === "undefined") return null;
+    return localStorage.getItem(key);
+  }
+  async setItem(key, value) {
+    if (typeof window === "undefined") return;
+    localStorage.setItem(key, value);
+  }
+  async removeItem(key) {
+    if (typeof window === "undefined") return;
+    localStorage.removeItem(key);
+  }
+};
+
+// src/storage.ts
+function isJwkMode(options) {
+  return "cipherJwk" in options;
+}
+function isJwkStoredData(data) {
+  return "mode" in data && data.mode === "jwk";
+}
+function createVaultStorage(options) {
+  const prefix = options.prefix ?? "ursalock:";
+  const storageProvider = options.storageProvider ?? options.storage ?? new LocalStorageProvider();
+  if (isJwkMode(options)) {
+    return createJwkStorage(options.cipherJwk, storageProvider, prefix);
+  } else {
+    return createLegacyStorage(options.recoveryKey, storageProvider, prefix);
+  }
+}
+function createJwkStorage(cipherJwk, storage, prefix) {
+  return {
+    async getItem(name) {
+      const raw = await storage.getItem(prefix + name);
+      if (!raw) return null;
+      try {
+        const stored = JSON.parse(raw);
+        const encrypted = base64ToBytes(stored.data);
+        const decrypted = await decryptWithJwk(encrypted, cipherJwk);
+        return new TextDecoder().decode(decrypted);
+      } catch (error) {
+        console.error("[ursalock] Failed to decrypt stored data:", error);
+        return null;
+      }
+    },
+    async setItem(name, value) {
+      try {
+        const plaintext = new TextEncoder().encode(value);
+        const encrypted = await encryptWithJwk(plaintext, cipherJwk);
+        const stored = {
+          data: bytesToBase64(encrypted.combined),
+          version: 2,
+          updatedAt: Date.now(),
+          mode: "jwk"
+        };
+        await storage.setItem(prefix + name, JSON.stringify(stored));
+      } catch (error) {
+        console.error("[ursalock] Failed to encrypt data:", error);
+        throw error;
+      }
+    },
+    async removeItem(name) {
+      await storage.removeItem(prefix + name);
+    }
+  };
+}
+function createLegacyStorage(recoveryKey, storage, prefix) {
+  let cachedKey = null;
+  let cachedSalt = null;
+  async function getOrDeriveKey(salt) {
+    if (cachedKey && cachedSalt && (!salt || arrayEqual(salt, cachedSalt))) {
+      return { key: cachedKey, salt: cachedSalt };
+    }
+    const keyBytes = recoveryKeyToBytes(recoveryKey);
+    const result = await deriveKey({
+      password: keyBytes,
+      salt
+    });
+    cachedKey = result.key;
+    cachedSalt = result.salt;
+    return result;
+  }
+  return {
+    async getItem(name) {
+      const raw = await storage.getItem(prefix + name);
+      if (!raw) return null;
+      try {
+        const stored = JSON.parse(raw);
+        if (isJwkStoredData(stored)) {
+          console.error("[ursalock] Cannot decrypt JWK data with recovery key");
+          return null;
+        }
+        const salt = base64ToBytes(stored.salt);
+        const { key } = await getOrDeriveKey(salt);
+        const encrypted = base64ToBytes(stored.data);
+        const decrypted = await decrypt(encrypted, key);
+        return new TextDecoder().decode(decrypted);
+      } catch (error) {
+        console.error("[ursalock] Failed to decrypt stored data:", error);
+        return null;
+      }
+    },
+    async setItem(name, value) {
+      try {
+        const { key, salt } = await getOrDeriveKey();
+        const plaintext = new TextEncoder().encode(value);
+        const encrypted = await encrypt(plaintext, key);
+        const stored = {
+          data: bytesToBase64(encrypted.combined),
+          salt: bytesToBase64(salt),
+          version: 1,
+          updatedAt: Date.now()
+        };
+        await storage.setItem(prefix + name, JSON.stringify(stored));
+      } catch (error) {
+        console.error("[ursalock] Failed to encrypt data:", error);
+        throw error;
+      }
+    },
+    async removeItem(name) {
+      await storage.removeItem(prefix + name);
+    }
+  };
+}
+function bytesToBase64(bytes) {
+  const CHUNK_SIZE = 32768;
+  let result = "";
+  for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {
+    const chunk = bytes.subarray(i, i + CHUNK_SIZE);
+    result += String.fromCharCode.apply(null, chunk);
+  }
+  return btoa(result);
+}
+function base64ToBytes(base64) {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  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;
+}
+
+// src/providers/fetch-http.ts
+var FetchHttpClient = class {
+  async request(request) {
+    const response = await fetch(request.url, {
+      method: request.method,
+      headers: request.headers,
+      body: request.body
+    });
+    return {
+      ok: response.ok,
+      status: response.status,
+      json: () => response.json(),
+      text: () => response.text()
+    };
+  }
+};
+
+// src/sync.ts
+var QUEUE_KEY = "ursalock:offline-queue";
+function createSyncEngine(options) {
+  const {
+    serverUrl,
+    name,
+    getToken,
+    onServerData,
+    getLocalData,
+    onStatusChange,
+    httpClient = new FetchHttpClient()
+  } = options;
+  let status = "idle";
+  let lastSyncAt = null;
+  let error = null;
+  const setStatus = (newStatus, newError) => {
+    status = newStatus;
+    error = newError ?? null;
+    onStatusChange?.(newStatus);
+  };
+  const loadQueue = () => {
+    if (typeof localStorage === "undefined") return { pending: [] };
+    try {
+      const stored = localStorage.getItem(`${QUEUE_KEY}:${name}`);
+      return stored ? JSON.parse(stored) : { pending: [] };
+    } catch {
+      return { pending: [] };
+    }
+  };
+  const saveQueue = (queue) => {
+    if (typeof localStorage === "undefined") return;
+    try {
+      localStorage.setItem(`${QUEUE_KEY}:${name}`, JSON.stringify(queue));
+    } catch {
+    }
+  };
+  const enqueue = (data, salt) => {
+    const queue = loadQueue();
+    queue.pending.push({ data, salt, timestamp: Date.now() });
+    if (queue.pending.length > 10) {
+      queue.pending = queue.pending.slice(-10);
+    }
+    saveQueue(queue);
+  };
+  const clearQueue = () => {
+    saveQueue({ pending: [] });
+  };
+  const isOnline = () => {
+    return typeof navigator === "undefined" || navigator.onLine;
+  };
+  const fetchServer = async () => {
+    const token = getToken();
+    if (!token) return null;
+    const res = await httpClient.request({
+      url: `${serverUrl}/vault/by-name/${encodeURIComponent(name)}`,
+      method: "GET",
+      headers: {
+        "Authorization": `Bearer ${token}`,
+        "Content-Type": "application/json"
+      }
+    });
+    if (res.status === 404) return null;
+    if (!res.ok) throw new Error(`Server error: ${res.status}`);
+    return res.json();
+  };
+  const pushServer = async (data, salt) => {
+    const token = getToken();
+    if (!token) throw new Error("Not authenticated");
+    let existing = null;
+    try {
+      existing = await fetchServer();
+    } catch {
+    }
+    if (existing) {
+      const res = await httpClient.request({
+        url: `${serverUrl}/vault/${existing.uid}`,
+        method: "PUT",
+        headers: {
+          "Authorization": `Bearer ${token}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ data, salt })
+      });
+      if (!res.ok) {
+        const errorText = await res.text().catch(() => "");
+        throw new Error(`Server error: ${res.status} ${errorText}`);
+      }
+      return res.json();
+    }
+    const createRes = await httpClient.request({
+      url: `${serverUrl}/vault`,
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${token}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ name, data, salt })
+    });
+    if (createRes.status === 409) {
+      const nowExisting = await fetchServer();
+      if (!nowExisting) {
+        throw new Error("Vault conflict but not found on retry");
+      }
+      const retryRes = await httpClient.request({
+        url: `${serverUrl}/vault/${nowExisting.uid}`,
+        method: "PUT",
+        headers: {
+          "Authorization": `Bearer ${token}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ data, salt })
+      });
+      if (!retryRes.ok) {
+        const errorText = await retryRes.text().catch(() => "");
+        throw new Error(`Server error: ${retryRes.status} ${errorText}`);
+      }
+      return retryRes.json();
+    }
+    if (!createRes.ok) {
+      const errorText = await createRes.text().catch(() => "");
+      throw new Error(`Server error: ${createRes.status} ${errorText}`);
+    }
+    return createRes.json();
+  };
+  const sync = async () => {
+    if (!isOnline()) {
+      setStatus("offline");
+      return;
+    }
+    setStatus("syncing");
+    try {
+      const queue = loadQueue();
+      if (queue.pending.length > 0) {
+        const latest = queue.pending[queue.pending.length - 1];
+        if (latest) {
+          await pushServer(latest.data, latest.salt);
+          clearQueue();
+        }
+      }
+      const local = getLocalData();
+      const server = await fetchServer();
+      if (!server) {
+        if (local.data) {
+          await pushServer(local.data, local.salt);
+        }
+      } else if (server.updatedAt > local.updatedAt) {
+        onServerData(server.data, server.salt, server.updatedAt);
+      } else if (local.updatedAt > server.updatedAt) {
+        await pushServer(local.data, local.salt);
+      }
+      lastSyncAt = Date.now();
+      setStatus("synced");
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Sync failed";
+      console.error("[ursalock] Sync error:", message);
+      setStatus("error", message);
+      if (message.includes("Server error")) {
+        const local = getLocalData();
+        enqueue(local.data, local.salt);
+      }
+    }
+  };
+  const push = async () => {
+    if (!isOnline()) {
+      const local = getLocalData();
+      enqueue(local.data, local.salt);
+      setStatus("offline");
+      return;
+    }
+    setStatus("syncing");
+    try {
+      const local = getLocalData();
+      await pushServer(local.data, local.salt);
+      lastSyncAt = Date.now();
+      setStatus("synced");
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Push failed";
+      console.error("[ursalock] Push error:", message);
+      const local = getLocalData();
+      enqueue(local.data, local.salt);
+      setStatus("error", message);
+    }
+  };
+  const pull = async () => {
+    if (!isOnline()) {
+      setStatus("offline");
+      return false;
+    }
+    setStatus("syncing");
+    try {
+      const server = await fetchServer();
+      if (server) {
+        const local = getLocalData();
+        if (server.updatedAt > local.updatedAt) {
+          onServerData(server.data, server.salt, server.updatedAt);
+          lastSyncAt = Date.now();
+          setStatus("synced");
+          return true;
+        }
+      }
+      setStatus("synced");
+      return false;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Pull failed";
+      console.error("[ursalock] Pull error:", message);
+      setStatus("error", message);
+      return false;
+    }
+  };
+  const getState = () => ({
+    lastSyncAt,
+    status,
+    pendingChanges: loadQueue().pending.length > 0,
+    error
+  });
+  return {
+    sync,
+    push,
+    pull,
+    getState,
+    clearQueue
+  };
+}
+
+// src/vault.ts
+function isJwkMode2(options) {
+  return "cipherJwk" in options;
+}
+var vaultImpl = (config, baseOptions) => (set, get, api) => {
+  const options = {
+    partialize: (state) => state,
+    merge: (persistedState, currentState) => ({
+      ...currentState,
+      ...persistedState
+    }),
+    syncInterval: 3e4,
+    ...baseOptions
+  };
+  const {
+    name,
+    server,
+    getToken,
+    partialize,
+    merge,
+    onRehydrateStorage,
+    skipHydration = false,
+    syncInterval
+  } = options;
+  const storage = options.storage ?? createVaultStorage(
+    isJwkMode2(options) ? { cipherJwk: options.cipherJwk, prefix: options.prefix } : { recoveryKey: options.recoveryKey, prefix: options.prefix }
+  );
+  let hasHydrated = false;
+  let localUpdatedAt = 0;
+  let hasLocalData = false;
+  let syncDebounceTimer = null;
+  const hydrationListeners = /* @__PURE__ */ new Set();
+  const finishHydrationListeners = /* @__PURE__ */ new Set();
+  let syncEngine = null;
+  if (server && getToken) {
+    syncEngine = createSyncEngine({
+      serverUrl: server,
+      name,
+      getToken,
+      onServerData: (data, _salt, updatedAt) => {
+        if (localUpdatedAt > updatedAt) {
+          void syncEngine?.push();
+          return;
+        }
+        try {
+          const parsed = JSON.parse(data);
+          const merged = merge(parsed, get());
+          set(merged, true);
+          localUpdatedAt = updatedAt;
+          void storage.setItem(name, JSON.stringify(partialize({ ...get() })));
+        } catch (err) {
+          console.error("[ursalock] Failed to parse server data:", err);
+        }
+      },
+      getLocalData: () => {
+        const state = partialize({ ...get() });
+        return {
+          data: JSON.stringify(state),
+          salt: "",
+          // Salt is handled by storage layer
+          updatedAt: localUpdatedAt
+        };
+      }
+    });
+  }
+  const persistState = async () => {
+    const state = partialize({ ...get() });
+    await storage.setItem(name, JSON.stringify(state));
+    localUpdatedAt = Date.now();
+    if (syncEngine) {
+      if (syncDebounceTimer) {
+        clearTimeout(syncDebounceTimer);
+      }
+      syncDebounceTimer = setTimeout(() => {
+        syncDebounceTimer = null;
+        void syncEngine?.sync();
+      }, 3e3);
+    }
+  };
+  const rehydrate = async () => {
+    hasHydrated = false;
+    hydrationListeners.forEach((cb) => cb(get()));
+    const postRehydrationCallback = onRehydrateStorage?.(get()) || void 0;
+    try {
+      const stored = await storage.getItem(name);
+      if (stored) {
+        const parsed = JSON.parse(stored);
+        const merged = merge(parsed, get());
+        set(merged, true);
+        hasLocalData = true;
+      }
+      hasHydrated = true;
+      postRehydrationCallback?.(get(), void 0);
+      finishHydrationListeners.forEach((cb) => cb(get()));
+    } catch (error) {
+      postRehydrationCallback?.(void 0, error);
+    }
+  };
+  const sync = async () => {
+    if (!syncEngine) return;
+    await syncEngine.sync();
+  };
+  const push = async () => {
+    if (!syncEngine) return;
+    await syncEngine.push();
+  };
+  const pull = async () => {
+    if (!syncEngine) return false;
+    return syncEngine.pull();
+  };
+  const getSyncStatus = () => {
+    if (!syncEngine) return "idle";
+    return syncEngine.getState().status;
+  };
+  const hasPendingChanges = () => {
+    if (!syncEngine) return false;
+    return syncEngine.getState().pendingChanges;
+  };
+  const clearStorage = async () => {
+    await storage.removeItem(name);
+    syncEngine?.clearQueue();
+  };
+  const savedSetState = api.setState;
+  api.setState = ((state, replace) => {
+    if (replace) {
+      savedSetState(state, true);
+    } else {
+      savedSetState(state);
+    }
+    void persistState();
+  });
+  const configResult = config(
+    ((partial, replace) => {
+      if (replace) {
+        set(partial, true);
+      } else {
+        set(partial);
+      }
+      void persistState();
+    }),
+    get,
+    api
+  );
+  const storeWithVault = api;
+  storeWithVault.vault = {
+    sync,
+    push,
+    pull,
+    rehydrate,
+    hasHydrated: () => hasHydrated,
+    getSyncStatus,
+    hasPendingChanges,
+    clearStorage,
+    onHydrate: (cb) => {
+      hydrationListeners.add(cb);
+      return () => hydrationListeners.delete(cb);
+    },
+    onFinishHydration: (cb) => {
+      finishHydrationListeners.add(cb);
+      return () => finishHydrationListeners.delete(cb);
+    }
+  };
+  if (!skipHydration) {
+    void rehydrate().then(() => {
+      if (syncEngine) {
+        void syncEngine.sync();
+      }
+    });
+  } else {
+    hasHydrated = true;
+  }
+  if (server && syncInterval > 0) {
+    setInterval(() => void sync(), syncInterval);
+  }
+  return configResult;
+};
+var vault = vaultImpl;
+
+// src/hooks.ts
+function useSyncStatus(useStore) {
+  const store = useStore();
+  return store.vault?.getSyncStatus?.() ?? "idle";
+}
+export {
+  FetchHttpClient,
+  LocalStorageProvider,
+  createSyncEngine,
+  createVaultStorage,
+  useSyncStatus,
+  vault
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@ursalock/zustand",
+  "version": "0.2.8",
+  "description": "Encrypted persistence middleware for Zustand with passkey E2EE",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ursalock/crypto": "^0.2.0"
+  },
+  "peerDependencies": {
+    "zustand": ">=4.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0",
+    "zustand": "^5.0.0"
+  },
+  "keywords": [
+    "zustand",
+    "middleware",
+    "encryption",
+    "e2ee",
+    "passkey",
+    "prf",
+    "sync",
+    "persist"
+  ],
+  "license": "MIT",
+  "author": "Nicolas de Luz <ndlz@pm.me>",
+  "homepage": "https://github.com/nicodlz/ursalock#readme",
+  "bugs": {
+    "url": "https://github.com/nicodlz/ursalock/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nicodlz/ursalock.git",
+    "directory": "packages/zustand"
+  }
+}