@drakkar.software/starfish-client 3.0.0-alpha.2 → 3.0.0-alpha.4

package/dist/group-crypto.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../src/group-crypto.ts", "../src/crypto.ts"],
-  "sourcesContent": ["/**\n * Group encryption utilities for Starfish.\n *\n * Enables multiple users to share a common encrypted collection without sharing\n * a passphrase. Each member holds their own credentials; a Group Encryption Key\n * (GEK) is distributed per-member using X25519 ECDH key agreement.\n *\n * Typical flow:\n *   1. Each user calls `deriveCredentials(passphrase)` \u2014 now includes groupPublicKey / groupPrivateKey.\n *   2. Admin calls `createGroupKeyring(...)` to create a keyring document.\n *   3. Members call `createGroupEncryptor(keyringData, myIdentity, myPrivateKey)` to get an Encryptor.\n *   4. The Encryptor is passed to SyncManager via the `encryptor` option.\n */\n\nimport { x25519 } from \"@noble/curves/ed25519.js\"\nimport { getCrypto, getBase64, IV_BYTES, deriveKey } from \"@drakkar.software/starfish-protocol\"\nimport type { Encryptor } from \"./crypto.js\"\nimport { createEncryptor } from \"./crypto.js\"\n\n// \u2500\u2500 Internal helpers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nfunction bytesToHex(bytes: Uint8Array): string {\n  return Array.from(bytes, (b) => b.toString(16).padStart(2, \"0\")).join(\"\")\n}\n\nfunction hexToBytes(hex: string): Uint8Array {\n  const bytes = new Uint8Array(hex.length / 2)\n  for (let i = 0; i < bytes.length; i++) {\n    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16)\n  }\n  return bytes\n}\n\nconst ALGO = \"AES-GCM\"\nconst GROUP_WRAP_SALT = \"starfish-group-wrap\"\nconst GROUP_WRAP_INFO = \"starfish-group-wrap\"\nconst GROUP_ECDH_DOMAIN = \"starfish-group-ecdh\"\nconst GROUP_DATA_INFO = \"starfish-group\"\nconst GEK_BYTES = 32\n\n// \u2500\u2500 Types \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/** An ECDH key pair used for group encryption. Hex-encoded for easy serialization. */\nexport interface GroupKeyPair {\n  /** Hex-encoded X25519 private key (32 bytes). Keep secret \u2014 never store on server. */\n  privateKey: string\n  /** Hex-encoded X25519 public key (32 bytes). Safe to publish. */\n  publicKey: string\n}\n\n/** One epoch's wrapped keys: each member's GEK encrypted to their public key. */\nexport interface EpochKeyring {\n  /** The admin's hex-encoded X25519 public key (used for ECDH by members). */\n  adminPublicKey: string\n  /** Map from member identity (userId) \u2192 base64(IV || AES-GCM(GEK)) */\n  wrappedKeys: Record<string, string>\n}\n\n/** The full keyring document stored in a Starfish collection. Push this with any SyncManager. */\nexport interface GroupKeyring {\n  /** The epoch number currently used for new encryptions. */\n  currentEpoch: number\n  /** All epochs. Members unwrap the GEK for whichever epoch a document was encrypted with. */\n  epochs: Record<string, EpochKeyring>\n}\n\n// \u2500\u2500 Key derivation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Derives a deterministic X25519 key pair from a passphrase + userId.\n *\n * The derivation uses SHA-256 with a fixed domain separator so it is distinct\n * from the auth token and encryption key derivations. Same passphrase + userId\n * always produces the same key pair on any device (stateless).\n */\nexport async function deriveGroupKeyPair(passphrase: string, userId: string): Promise<GroupKeyPair> {\n  const c = getCrypto()\n  const enc = new TextEncoder()\n  const input = enc.encode(`${passphrase}:${userId}:${GROUP_ECDH_DOMAIN}`)\n  const hash = await c.subtle.digest(\"SHA-256\", input)\n  const privateKeyBytes = new Uint8Array(hash)\n  const publicKeyBytes = x25519.getPublicKey(privateKeyBytes)\n  return { privateKey: bytesToHex(privateKeyBytes), publicKey: bytesToHex(publicKeyBytes) }\n}\n\n// \u2500\u2500 GEK generation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/** Generates a random 256-bit Group Encryption Key as a hex string. */\nexport function generateGroupKey(): string {\n  const c = getCrypto()\n  return bytesToHex(c.getRandomValues(new Uint8Array(GEK_BYTES)))\n}\n\n// \u2500\u2500 Key wrapping / unwrapping \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Wraps a GEK for a specific member using ECDH key agreement.\n *\n * The wrapper (admin) and member each have an X25519 key pair. ECDH between\n * `wrapperPrivateKey` and `memberPublicKey` produces a shared secret, which is\n * used to derive an AES-256-GCM key that encrypts the GEK.\n *\n * @returns base64(IV || AES-GCM-ciphertext)\n */\nexport async function wrapGroupKey(\n  gek: string,\n  memberPublicKey: string,\n  wrapperPrivateKey: string,\n): Promise<string> {\n  const sharedSecret = x25519.getSharedSecret(hexToBytes(wrapperPrivateKey), hexToBytes(memberPublicKey))\n  const wrappingKey = await deriveKey(bytesToHex(sharedSecret), GROUP_WRAP_SALT, GROUP_WRAP_INFO)\n\n  const c = getCrypto()\n  const b64 = getBase64()\n  const iv = c.getRandomValues(new Uint8Array(IV_BYTES))\n  const encrypted = await c.subtle.encrypt({ name: ALGO, iv }, wrappingKey, hexToBytes(gek).buffer as ArrayBuffer)\n\n  const combined = new Uint8Array(IV_BYTES + encrypted.byteLength)\n  combined.set(iv)\n  combined.set(new Uint8Array(encrypted), IV_BYTES)\n  return b64.encode(combined)\n}\n\n/**\n * Unwraps a GEK using the member's own private key and the admin's public key.\n *\n * ECDH between `memberPrivateKey` and `adminPublicKey` yields the same shared\n * secret as the wrapping step, so the same AES key is derived and the GEK is\n * recovered.\n *\n * @returns GEK as a hex string\n */\nexport async function unwrapGroupKey(\n  wrapped: string,\n  memberPrivateKey: string,\n  adminPublicKey: string,\n): Promise<string> {\n  const sharedSecret = x25519.getSharedSecret(hexToBytes(memberPrivateKey), hexToBytes(adminPublicKey))\n  const wrappingKey = await deriveKey(bytesToHex(sharedSecret), GROUP_WRAP_SALT, GROUP_WRAP_INFO)\n\n  const b64 = getBase64()\n  const c = getCrypto()\n  const combined = b64.decode(wrapped)\n  const iv = combined.slice(0, IV_BYTES)\n  const ciphertext = combined.slice(IV_BYTES)\n  try {\n    const decrypted = await c.subtle.decrypt({ name: ALGO, iv }, wrappingKey, ciphertext)\n    return bytesToHex(new Uint8Array(decrypted))\n  } catch {\n    throw new Error(\"Failed to unwrap group key: decryption failed (wrong keys or corrupted data)\")\n  }\n}\n\n// \u2500\u2500 Keyring management \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Creates a new group keyring document with epoch 1.\n *\n * @param adminKeyPair  The admin's key pair (from `deriveGroupKeyPair` or `deriveCredentials`)\n * @param members       Map from member identity (userId) \u2192 hex public key\n * @param gek           Optional GEK to use; generated randomly if omitted\n * @returns             The keyring document and the raw GEK (admin keeps the GEK to add future members)\n */\nexport async function createGroupKeyring(\n  adminKeyPair: GroupKeyPair,\n  members: Record<string, string>,\n  gek?: string,\n): Promise<{ keyring: GroupKeyring; gek: string }> {\n  const resolvedGek = gek ?? generateGroupKey()\n  const wrappedKeys: Record<string, string> = {}\n  for (const [memberId, memberPublicKey] of Object.entries(members)) {\n    wrappedKeys[memberId] = await wrapGroupKey(resolvedGek, memberPublicKey, adminKeyPair.privateKey)\n  }\n  const keyring: GroupKeyring = {\n    currentEpoch: 1,\n    epochs: {\n      \"1\": { adminPublicKey: adminKeyPair.publicKey, wrappedKeys },\n    },\n  }\n  return { keyring, gek: resolvedGek }\n}\n\n/**\n * Adds a new member to the current epoch of an existing keyring.\n *\n * The admin supplies the current GEK (returned by `createGroupKeyring` or\n * `rotateGroupKey`) and their key pair to wrap it for the new member.\n * This does NOT rotate the GEK \u2014 the new member can read all existing\n * documents encrypted with the current epoch key.\n *\n * Only the admin (whose `publicKey` matches `epochKeyring.adminPublicKey`) can\n * add members, because all wrapped entries must use the same ECDH key pair.\n */\nexport async function addGroupMember(\n  keyring: GroupKeyring,\n  adminKeyPair: GroupKeyPair,\n  currentGek: string,\n  newMemberId: string,\n  newMemberPublicKey: string,\n): Promise<GroupKeyring> {\n  const epochKey = String(keyring.currentEpoch)\n  const epochKeyring = keyring.epochs[epochKey]\n  if (!epochKeyring) throw new Error(`Epoch ${keyring.currentEpoch} not found in keyring`)\n  if (epochKeyring.adminPublicKey !== adminKeyPair.publicKey) {\n    throw new Error(`Provided key pair does not match the admin public key stored in epoch ${keyring.currentEpoch}`)\n  }\n\n  const wrapped = await wrapGroupKey(currentGek, newMemberPublicKey, adminKeyPair.privateKey)\n\n  return {\n    ...keyring,\n    epochs: {\n      ...keyring.epochs,\n      [epochKey]: {\n        ...epochKeyring,\n        wrappedKeys: { ...epochKeyring.wrappedKeys, [newMemberId]: wrapped },\n      },\n    },\n  }\n}\n\n/**\n * Rotates the group key, creating a new epoch.\n *\n * Used when removing a member. The removed member retains their old epoch key\n * (and can still read old documents), but cannot read new documents.\n *\n * @param remainingMembers  Map from identity \u2192 hex public key for members who keep access\n */\nexport async function rotateGroupKey(\n  keyring: GroupKeyring,\n  adminKeyPair: GroupKeyPair,\n  remainingMembers: Record<string, string>,\n  newGek?: string,\n): Promise<{ keyring: GroupKeyring; gek: string }> {\n  const epochKey = String(keyring.currentEpoch)\n  const epochKeyring = keyring.epochs[epochKey]\n  if (epochKeyring && epochKeyring.adminPublicKey !== adminKeyPair.publicKey) {\n    throw new Error(\n      `Provided key pair does not match the admin public key stored in epoch ${keyring.currentEpoch}`,\n    )\n  }\n  const resolvedGek = newGek ?? generateGroupKey()\n  const newEpoch = keyring.currentEpoch + 1\n  const wrappedKeys: Record<string, string> = {}\n  for (const [memberId, memberPublicKey] of Object.entries(remainingMembers)) {\n    wrappedKeys[memberId] = await wrapGroupKey(resolvedGek, memberPublicKey, adminKeyPair.privateKey)\n  }\n  const newKeyring: GroupKeyring = {\n    currentEpoch: newEpoch,\n    epochs: {\n      ...keyring.epochs,\n      [String(newEpoch)]: { adminPublicKey: adminKeyPair.publicKey, wrappedKeys },\n    },\n  }\n  return { keyring: newKeyring, gek: resolvedGek }\n}\n\n// \u2500\u2500 Encryptor factory \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Creates an Encryptor that can decrypt any epoch and encrypts with the current epoch.\n *\n * Wire format: `{ _encrypted: \"base64(IV || ciphertext)\", _epoch: N }`\n *\n * @param keyring         The keyring document fetched from Starfish\n * @param myIdentity      The caller's userId (to locate their wrapped key in each epoch)\n * @param myPrivateKey    The caller's hex-encoded X25519 private key\n */\nexport async function createGroupEncryptor(\n  keyring: GroupKeyring,\n  myIdentity: string,\n  myPrivateKey: string,\n): Promise<Encryptor> {\n  // Unwrap GEK for each epoch we have a key for\n  const epochEncryptors = new Map<number, Encryptor>()\n  for (const [epochStr, epochKeyring] of Object.entries(keyring.epochs)) {\n    const epoch = parseInt(epochStr, 10)\n    const wrapped = epochKeyring.wrappedKeys[myIdentity]\n    if (!wrapped) continue\n    const gek = await unwrapGroupKey(wrapped, myPrivateKey, epochKeyring.adminPublicKey)\n    epochEncryptors.set(epoch, createEncryptor(gek, `epoch-${epoch}`, GROUP_DATA_INFO))\n  }\n\n  const currentEpoch = keyring.currentEpoch\n  const currentEncryptor = epochEncryptors.get(currentEpoch)\n  if (!currentEncryptor) {\n    throw new Error(\n      `No wrapped key found for identity \"${myIdentity}\" in epoch ${currentEpoch}. ` +\n        `Ensure the admin has added this member to the keyring.`,\n    )\n  }\n\n  return {\n    async encrypt(data: Record<string, unknown>): Promise<Record<string, unknown>> {\n      const encrypted = await currentEncryptor.encrypt(data)\n      return { ...encrypted, _epoch: currentEpoch }\n    },\n\n    async decrypt(wrapper: Record<string, unknown>): Promise<Record<string, unknown>> {\n      const epoch = typeof wrapper._epoch === \"number\" ? wrapper._epoch : currentEpoch\n      const encryptor = epochEncryptors.get(epoch)\n      if (!encryptor) {\n        throw new Error(\n          `No key available for epoch ${epoch}. ` +\n            `This document was encrypted in a different epoch. ` +\n            `Ensure your keyring is up to date.`,\n        )\n      }\n      return encryptor.decrypt(wrapper)\n    },\n  }\n}\n", "import { getCrypto, getBase64, IV_BYTES, ENCRYPTED_KEY, deriveKey } from \"@drakkar.software/starfish-protocol\"\n\nconst ALGO = \"AES-GCM\"\n\nexport { ENCRYPTED_KEY }\n\n/** Encrypt/decrypt interface for client-side E2E encryption. */\nexport interface Encryptor {\n  encrypt(data: Record<string, unknown>): Promise<Record<string, unknown>>\n  decrypt(wrapper: Record<string, unknown>): Promise<Record<string, unknown>>\n}\n\n/**\n * Creates an Encryptor that uses AES-256-GCM with HKDF-derived keys.\n */\nexport function createEncryptor(secret: string, salt: string, info: string = \"starfish-e2e\"): Encryptor {\n  if (!secret) throw new Error(\"encryptionSecret must not be empty\")\n  if (!salt) throw new Error(\"encryptionSalt must not be empty\")\n  const keyPromise = deriveKey(secret, salt, info)\n\n  return {\n    async encrypt(data: Record<string, unknown>): Promise<Record<string, unknown>> {\n      const key = await keyPromise\n      const c = getCrypto()\n      const b64 = getBase64()\n      const plaintext = new TextEncoder().encode(JSON.stringify(data))\n      const iv = c.getRandomValues(new Uint8Array(IV_BYTES))\n      const ciphertext = await c.subtle.encrypt({ name: ALGO, iv }, key, plaintext)\n\n      const combined = new Uint8Array(iv.length + ciphertext.byteLength)\n      combined.set(iv)\n      combined.set(new Uint8Array(ciphertext), iv.length)\n\n      return { [ENCRYPTED_KEY]: b64.encode(combined) }\n    },\n\n    async decrypt(wrapper: Record<string, unknown>): Promise<Record<string, unknown>> {\n      const encoded = wrapper[ENCRYPTED_KEY]\n      if (typeof encoded !== \"string\") {\n        throw new Error(\"Expected encrypted data but received unencrypted document\")\n      }\n\n      const key = await keyPromise\n      const c = getCrypto()\n      const b64 = getBase64()\n      const combined = b64.decode(encoded)\n      if (combined.length < IV_BYTES) {\n        throw new Error(\"Encrypted data is too short\")\n      }\n      const iv = combined.slice(0, IV_BYTES)\n      const ciphertext = combined.slice(IV_BYTES)\n      try {\n        const plaintext = await c.subtle.decrypt({ name: ALGO, iv }, key, ciphertext)\n        return JSON.parse(new TextDecoder().decode(plaintext))\n      } catch (err) {\n        throw new Error(\"Decryption failed: data may be tampered or key is incorrect\", { cause: err })\n      }\n    },\n  }\n}\n"],
-  "mappings": "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",
-  "names": ["getCrypto", "getBase64", "IV_BYTES", "deriveKey", "ALGO", "getCrypto", "deriveKey", "getBase64", "IV_BYTES"]
-}

package/dist/history.js

@@ -1,61 +0,0 @@
-export class SnapshotHistory {
-    snapshots = [];
-    maxSnapshots;
-    storageKey;
-    constructor(options) {
-        this.maxSnapshots = options?.maxSnapshots ?? 20;
-        this.storageKey = options?.storageKey;
-        if (this.storageKey) {
-            try {
-                const raw = localStorage.getItem(this.storageKey);
-                if (raw) {
-                    const parsed = JSON.parse(raw);
-                    if (Array.isArray(parsed))
-                        this.snapshots = parsed;
-                }
-            }
-            catch { /* corrupted or unavailable — start fresh */ }
-        }
-    }
-    /** Take a labeled snapshot of the given data. */
-    take(label, data) {
-        this.snapshots.push({
-            timestamp: Date.now(),
-            label,
-            data: JSON.stringify(data),
-        });
-        if (this.snapshots.length > this.maxSnapshots) {
-            this.snapshots = this.snapshots.slice(-this.maxSnapshots);
-        }
-        this.persist();
-    }
-    /** Restore data from a snapshot at the given index. Returns undefined if index is invalid or data is corrupt. */
-    restore(index) {
-        const snapshot = this.snapshots[index];
-        if (!snapshot)
-            return undefined;
-        try {
-            return JSON.parse(snapshot.data);
-        }
-        catch {
-            return undefined;
-        }
-    }
-    /** List available snapshots (metadata only, no data payload). */
-    list() {
-        return this.snapshots.map(({ timestamp, label }) => ({ timestamp, label }));
-    }
-    /** Clear all snapshots. */
-    clear() {
-        this.snapshots = [];
-        this.persist();
-    }
-    persist() {
-        if (!this.storageKey)
-            return;
-        try {
-            localStorage.setItem(this.storageKey, JSON.stringify(this.snapshots));
-        }
-        catch { /* quota exceeded — skip silently */ }
-    }
-}

package/dist/logger.js

@@ -1,80 +0,0 @@
-/** Console-based sync logger with structured output. */
-export const consoleSyncLogger = {
-    pullStart: (s) => console.log(`[starfish:${s}] pull started`),
-    pullSuccess: (s, ms, m) => {
-        let msg = `[starfish:${s}] pull OK (${ms}ms)`;
-        if (m?.bytesTransferred)
-            msg += ` ${m.bytesTransferred}B`;
-        if (m?.cacheHit)
-            msg += ` (cache hit)`;
-        console.log(msg);
-    },
-    pullError: (s, err) => console.error(`[starfish:${s}] pull failed: ${err}`),
-    pushStart: (s) => console.log(`[starfish:${s}] push started`),
-    pushSuccess: (s, ms, m) => {
-        let msg = `[starfish:${s}] push OK (${ms}ms)`;
-        if (m?.bytesTransferred)
-            msg += ` ${m.bytesTransferred}B`;
-        console.log(msg);
-    },
-    pushError: (s, err) => console.error(`[starfish:${s}] push failed: ${err}`),
-    conflict: (s, n) => console.warn(`[starfish:${s}] conflict (attempt ${n})`),
-};
-/** Silent sync logger (no output). */
-export const noopSyncLogger = {
-    pullStart: () => { },
-    pullSuccess: () => { },
-    pullError: () => { },
-    pushStart: () => { },
-    pushSuccess: () => { },
-    pushError: () => { },
-    conflict: () => { },
-};
-/** Create a metrics collector that accumulates sync statistics. */
-export function createMetricsCollector() {
-    const stores = new Map();
-    function ensureStore(name) {
-        let s = stores.get(name);
-        if (!s) {
-            s = { totalPulls: 0, totalPushes: 0, totalDurationMs: 0, totalBytes: 0, totalConflicts: 0 };
-            stores.set(name, s);
-        }
-        return s;
-    }
-    return {
-        recordPull(name, durationMs, metrics) {
-            const s = ensureStore(name);
-            s.totalPulls++;
-            s.totalDurationMs += durationMs;
-            if (metrics?.bytesTransferred)
-                s.totalBytes += metrics.bytesTransferred;
-        },
-        recordPush(name, durationMs, metrics) {
-            const s = ensureStore(name);
-            s.totalPushes++;
-            s.totalDurationMs += durationMs;
-            if (metrics?.bytesTransferred)
-                s.totalBytes += metrics.bytesTransferred;
-        },
-        recordConflict(name) {
-            ensureStore(name).totalConflicts++;
-        },
-        getSummary() {
-            const result = {};
-            for (const [name, s] of stores) {
-                const totalOps = s.totalPulls + s.totalPushes;
-                result[name] = {
-                    totalPulls: s.totalPulls,
-                    totalPushes: s.totalPushes,
-                    avgDurationMs: totalOps > 0 ? Math.round(s.totalDurationMs / totalOps) : 0,
-                    totalBytes: s.totalBytes,
-                    totalConflicts: s.totalConflicts,
-                };
-            }
-            return result;
-        },
-        reset() {
-            stores.clear();
-        },
-    };
-}

package/dist/migrate.js

@@ -1,38 +0,0 @@
-/**
- * Creates a migration runner that upgrades documents to the current schema version.
- *
- * Given a document with `_schemaVersion`, applies each migration in sequence
- * until the document reaches `currentVersion`. Throws if the document version
- * is ahead of the app (forward compatibility guard).
- */
-export function createMigrator(config) {
-    // Eagerly validate the migration chain
-    for (let v = 1; v < config.currentVersion; v++) {
-        if (!config.migrations[v]) {
-            throw new Error(`Missing migration for version ${v} -> ${v + 1}`);
-        }
-    }
-    return (data) => {
-        const version = typeof data._schemaVersion === "number" ? data._schemaVersion : 1;
-        if (version > config.currentVersion) {
-            throw new Error(`Document schema version ${version} is newer than app version ${config.currentVersion}. Update the app.`);
-        }
-        if (version === config.currentVersion)
-            return data;
-        let result = { ...data };
-        for (let v = version; v < config.currentVersion; v++) {
-            const fn = config.migrations[v];
-            if (!fn) {
-                throw new Error(`Missing migration for version ${v} -> ${v + 1}`);
-            }
-            try {
-                result = fn(result);
-            }
-            catch (err) {
-                throw new Error(`Migration from version ${v} to ${v + 1} failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
-            }
-        }
-        result._schemaVersion = config.currentVersion;
-        return result;
-    };
-}

package/dist/mobile-lifecycle.js

@@ -1,55 +0,0 @@
-// ── Implementation ────────────────────────────────────────────────────────────
-/**
- * Wires React Native app lifecycle events to a Starfish store.
- *
- * - **Background**: flushes pending changes before the OS suspends the app.
- * - **Foreground**: pulls remote changes when the user returns to the app.
- * - **NetInfo**: forwards connectivity changes to `store.getState().setOnline()`.
- *
- * Uses dependency injection so no `react-native` or `netinfo` imports are needed
- * in this package. Pass the modules directly:
- *
- * ```ts
- * import { AppState } from "react-native"
- * import NetInfo from "@react-native-community/netinfo"
- * import { createMobileLifecycle } from "@drakkar.software/starfish-client"
- *
- * // Call once, after the store is created:
- * const cleanup = createMobileLifecycle(
- *   store,
- *   { appState: AppState, netInfo: NetInfo },
- * )
- *
- * // In a React component (e.g. root layout):
- * useEffect(() => cleanup, [])
- * ```
- *
- * @returns A cleanup function that removes all event listeners.
- */
-export function createMobileLifecycle(store, deps, options = {}) {
-    const { pullOnForeground = true, flushOnBackground = true } = options;
-    const appSub = deps.appState.addEventListener("change", (appState) => {
-        if (appState === "background" && flushOnBackground) {
-            if (store.getState().dirty) {
-                store.getState().flush().catch(() => { });
-            }
-        }
-        else if (appState === "active" && pullOnForeground) {
-            const { online, syncing } = store.getState();
-            if (online && !syncing) {
-                store.getState().pull().catch(() => { });
-            }
-        }
-        // "inactive" (iOS transition) and other states are intentionally ignored
-    });
-    let netUnsub = null;
-    if (deps.netInfo) {
-        netUnsub = deps.netInfo.addEventListener(({ isConnected }) => {
-            store.getState().setOnline(!!isConnected);
-        });
-    }
-    return () => {
-        appSub.remove();
-        netUnsub?.();
-    };
-}

package/dist/multi-store.js

@@ -1,92 +0,0 @@
-// ── Types ─────────────────────────────────────────────────────────────────────
-// ── Implementation ────────────────────────────────────────────────────────────
-/**
- * Creates a multi-store sync coordinator.
- *
- * Collects multiple application stores into a single Starfish sync document,
- * with versioned schema migrations for backward compatibility.
- *
- * ```ts
- * const multiSync = createMultiStoreSync({
- *   slices: {
- *     tasks: {
- *       serialize: () => taskStore.getState().tasks,
- *       restore: (tasks) => taskStore.setState({ tasks }),
- *     },
- *     settings: {
- *       serialize: () => settingsStore.getState().settings,
- *       restore: (settings) => settingsStore.setState({ settings }),
- *     },
- *   },
- *   version: 2,
- *   migrations: {
- *     // data from version 1 → upgrade to version 2
- *     1: (data) => ({ ...data, settings: { ...(data.settings as object), darkMode: false } }),
- *   },
- * })
- *
- * // Push:
- * starfishStore.getState().set(() => multiSync.serialize())
- *
- * // Restore on pull (pass as onRemoteUpdate to createStarfishStore):
- * createStarfishStore({
- *   name: "app",
- *   syncManager,
- *   onRemoteUpdate: (doc) => multiSync.restore(doc as BackupDocument),
- * })
- * ```
- */
-export function createMultiStoreSync(options) {
-    const { slices, version, migrations = {} } = options;
-    // Validate migration chain at construction time (fail fast)
-    for (const fromVersion of Object.keys(migrations)) {
-        const v = Number(fromVersion);
-        if (isNaN(v) || v < 1) {
-            throw new Error(`Migration key must be a positive integer, got: "${fromVersion}"`);
-        }
-    }
-    function serialize() {
-        const data = {};
-        for (const key of Object.keys(slices)) {
-            data[key] = slices[key].serialize();
-        }
-        return { version, timestamp: Date.now(), data };
-    }
-    function restore(doc) {
-        if (typeof doc !== "object" || doc === null) {
-            throw new Error("restore: expected a BackupDocument object");
-        }
-        const docVersion = doc.version ?? 1;
-        if (typeof docVersion !== "number" || !Number.isInteger(docVersion) || docVersion < 1) {
-            throw new Error(`restore: invalid document version: ${String(doc.version)}`);
-        }
-        if (docVersion > version) {
-            throw new Error(`restore: document version ${docVersion} is newer than current version ${version}. ` +
-                `Update the app to restore this backup.`);
-        }
-        // Run migrations sequentially from docVersion up to current version
-        let data = typeof doc.data === "object" && doc.data !== null
-            ? { ...doc.data }
-            : {};
-        for (let v = docVersion; v < version; v++) {
-            const migration = migrations[v];
-            if (!migration)
-                continue;
-            try {
-                data = migration(data);
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                throw new Error(`restore: migration from version ${v} to ${v + 1} failed: ${msg}`);
-            }
-        }
-        // Restore each slice
-        for (const key of Object.keys(slices)) {
-            const sliceData = data[key];
-            if (sliceData !== undefined) {
-                slices[key].restore(sliceData);
-            }
-        }
-    }
-    return { serialize, restore, version };
-}

package/dist/polling.js

@@ -1,52 +0,0 @@
-const DEFAULT_INTERVALS = {
-    "slow-2g": 120_000,
-    "2g": 60_000,
-    "3g": 30_000,
-    "4g": 10_000,
-};
-const DEFAULT_FALLBACK_MS = 15_000;
-/**
- * Start periodic pulling at a fixed interval.
- * Skips pulls when offline or already syncing.
- * Returns a cleanup function that stops polling.
- */
-export function startPolling(pullFn, getState, intervalMs = 30_000) {
-    const timer = setInterval(() => {
-        const { online, syncing } = getState();
-        if (online && !syncing)
-            pullFn().catch(() => { });
-    }, intervalMs);
-    return () => clearInterval(timer);
-}
-/**
- * Start polling with adaptive intervals based on network quality.
- * Uses the Network Information API (`navigator.connection.effectiveType`) when available.
- * Returns controls to pause, resume, or stop polling.
- */
-export function startAdaptivePolling(pullFn, getState, options) {
-    let intervalMs;
-    if (options?.intervalMs != null) {
-        intervalMs = options.intervalMs;
-    }
-    else {
-        const intervals = options?.intervals ?? DEFAULT_INTERVALS;
-        let effectiveType;
-        if (typeof navigator !== "undefined" && "connection" in navigator) {
-            effectiveType = navigator.connection.effectiveType;
-        }
-        intervalMs = (effectiveType != null ? intervals[effectiveType] : undefined) ?? DEFAULT_FALLBACK_MS;
-    }
-    let paused = false;
-    const timer = setInterval(() => {
-        if (paused)
-            return;
-        const { online, syncing } = getState();
-        if (online && !syncing)
-            pullFn().catch(() => { });
-    }, intervalMs);
-    return {
-        pause: () => { paused = true; },
-        resume: () => { paused = false; },
-        stop: () => clearInterval(timer),
-    };
-}

package/dist/resolvers.js

@@ -1,223 +0,0 @@
-/** Shallow structural comparison of two values. Handles objects, arrays, and primitives. */
-function shallowEqual(a, b) {
-    if (a === b)
-        return true;
-    if (a == null || b == null)
-        return a === b;
-    if (typeof a !== typeof b)
-        return false;
-    if (typeof a !== "object")
-        return false;
-    if (Array.isArray(a) !== Array.isArray(b))
-        return false;
-    if (Array.isArray(a) && Array.isArray(b)) {
-        if (a.length !== b.length)
-            return false;
-        return a.every((v, i) => shallowEqual(v, b[i]));
-    }
-    const aObj = a;
-    const bObj = b;
-    const aKeys = Object.keys(aObj);
-    const bKeys = Object.keys(bObj);
-    if (aKeys.length !== bKeys.length)
-        return false;
-    return aKeys.every((k) => shallowEqual(aObj[k], bObj[k]));
-}
-/**
- * Wrap a standard ConflictResolver to also return metadata about which fields conflicted.
- * Compares local and remote keys to detect differing fields.
- */
-export function withConflictMeta(resolver) {
-    return (local, remote) => {
-        const conflictedFields = [];
-        const allKeys = new Set([...Object.keys(local), ...Object.keys(remote)]);
-        for (const key of allKeys) {
-            const lv = local[key];
-            const rv = remote[key];
-            if (!shallowEqual(lv, rv)) {
-                conflictedFields.push(key);
-            }
-        }
-        const data = resolver(local, remote);
-        // Determine how it was resolved using structural comparison
-        let resolvedBy = "merged";
-        if (shallowEqual(data, local))
-            resolvedBy = "local";
-        else if (shallowEqual(data, remote))
-            resolvedBy = "remote";
-        return {
-            data,
-            meta: {
-                conflictedFields,
-                resolvedBy,
-                timestamp: Date.now(),
-            },
-        };
-    };
-}
-/** Compare two timestamp values. Handles both numeric (epoch) and string (ISO-8601) timestamps. */
-function compareTimestamps(a, b) {
-    if (typeof a === "number" && typeof b === "number")
-        return a >= b;
-    return String(a ?? "") >= String(b ?? "");
-}
-/**
- * Creates a conflict resolver that merges arrays by ID with per-item
- * timestamp comparison, and uses document-level timestamp for scalars.
- *
- * For arrays: builds a union of both sets keyed by `idKey`. When both
- * sides have the same item, the one with the newer `timestampKey` wins.
- * For scalars: the document with the newer `documentTimestampKey` wins.
- *
- * @example
- * ```ts
- * const merge = createUnionMerge()
- * const sync = new SyncManager({ ..., onConflict: merge })
- * ```
- */
-export function createUnionMerge(options) {
-    const idKey = options?.idKey ?? "id";
-    const tsKey = options?.timestampKey ?? "updatedAt";
-    const docTsKey = options?.documentTimestampKey ?? "timestamp";
-    return (local, remote) => {
-        const result = {};
-        const localNewer = compareTimestamps(local[docTsKey], remote[docTsKey]);
-        const allKeys = new Set([...Object.keys(local), ...Object.keys(remote)]);
-        for (const key of allKeys) {
-            const lv = local[key];
-            const rv = remote[key];
-            // Both sides have arrays — attempt ID-based union
-            if (Array.isArray(lv) && Array.isArray(rv)) {
-                const map = new Map();
-                // Seed with remote items
-                for (const item of rv) {
-                    if (item && typeof item === "object" && idKey in item) {
-                        map.set(item[idKey], item);
-                    }
-                    else {
-                        map.set(Symbol(), item);
-                    }
-                }
-                // Overlay local items (per-item timestamp wins)
-                for (const item of lv) {
-                    if (item && typeof item === "object" && idKey in item) {
-                        const localItem = item;
-                        const id = localItem[idKey];
-                        const remoteItem = map.get(id);
-                        if (!remoteItem) {
-                            map.set(id, localItem);
-                        }
-                        else {
-                            if (compareTimestamps(localItem[tsKey], remoteItem[tsKey])) {
-                                map.set(id, localItem);
-                            }
-                        }
-                    }
-                    else {
-                        map.set(Symbol(), item);
-                    }
-                }
-                result[key] = [...map.values()];
-            }
-            else if (lv !== undefined && rv !== undefined) {
-                // Scalar: document-level timestamp wins
-                result[key] = localNewer ? lv : rv;
-            }
-            else {
-                // Only one side has the key
-                result[key] = lv ?? rv;
-            }
-        }
-        return result;
-    };
-}
-/**
- * Creates a conflict resolver that handles soft-deleted items (tombstones).
- * Extends union merge with tombstone awareness: if an item exists on one side
- * with a `deletedAtKey` set, that deletion is respected even if the other side
- * still has the item alive — as long as the deletion timestamp is newer.
- */
-export function createSoftDeleteResolver(options) {
-    const idKey = options?.idKey ?? "id";
-    const tsKey = options?.timestampKey ?? "updatedAt";
-    const deletedAtKey = options?.deletedAtKey ?? "_deletedAt";
-    const baseMerge = createUnionMerge(options);
-    return (local, remote) => {
-        const merged = baseMerge(local, remote);
-        // Build a tombstone map from both sides: id → deletedAt timestamp
-        const tombstones = new Map();
-        for (const source of [local, remote]) {
-            for (const key of Object.keys(source)) {
-                const arr = source[key];
-                if (!Array.isArray(arr))
-                    continue;
-                for (const item of arr) {
-                    if (item && typeof item === "object" && idKey in item && deletedAtKey in item) {
-                        const rec = item;
-                        const id = rec[idKey];
-                        const deletedAt = rec[deletedAtKey];
-                        if (typeof deletedAt === "number" || typeof deletedAt === "string") {
-                            const existing = tombstones.get(id);
-                            if (existing == null || compareTimestamps(deletedAt, existing))
-                                tombstones.set(id, deletedAt);
-                        }
-                    }
-                }
-            }
-        }
-        // For merged arrays, ensure tombstoned items stay deleted
-        // (don't resurrect an item if its tombstone is newer than its updatedAt)
-        for (const key of Object.keys(merged)) {
-            const value = merged[key];
-            if (!Array.isArray(value))
-                continue;
-            merged[key] = value.filter((item) => {
-                if (!item || typeof item !== "object" || !(idKey in item))
-                    return true;
-                const rec = item;
-                const id = rec[idKey];
-                const deletedAt = tombstones.get(id);
-                if (deletedAt == null)
-                    return true;
-                // Keep the item if it has a deletedAt (it's the tombstone itself)
-                if (rec[deletedAtKey] != null)
-                    return true;
-                // Filter out alive items that have a newer tombstone
-                return compareTimestamps(rec[tsKey], deletedAt) && rec[tsKey] !== deletedAt;
-            });
-        }
-        return merged;
-    };
-}
-/**
- * Simple resolver: the document with the newer timestamp wins entirely.
- * No per-field or per-item merging.
- */
-export function timestampWinner(timestampKey = "timestamp") {
-    return (local, remote) => {
-        return compareTimestamps(local[timestampKey], remote[timestampKey])
-            ? local
-            : remote;
-    };
-}
-/**
- * Remove expired tombstones from an array of items.
- * Items with a `deletedAtKey` older than `ttlMs` are pruned.
- *
- * @param items - Array of items, some with a deletedAt timestamp
- * @param ttlMs - Time-to-live in ms for tombstones (default: 30 days)
- * @param deletedAtKey - Key marking deletion timestamp (default: "_deletedAt")
- */
-export function pruneTombstones(items, ttlMs = 30 * 24 * 60 * 60 * 1000, deletedAtKey = "_deletedAt") {
-    const cutoff = Date.now() - ttlMs;
-    return items.filter((item) => {
-        const deletedAt = item[deletedAtKey];
-        if (deletedAt == null)
-            return true;
-        if (typeof deletedAt === "number")
-            return deletedAt > cutoff;
-        if (typeof deletedAt === "string")
-            return new Date(deletedAt).getTime() > cutoff;
-        return false;
-    });
-}