@drakkar.software/starfish-client 3.0.0-alpha.21 → 3.0.0-alpha.23

package/dist/sync.js

@@ -1,7 +1,13 @@
-import { deepMerge, stableStringify } from "@drakkar.software/starfish-protocol";
+import { AUTHOR_PUBKEY_FIELD, AUTHOR_SIGNATURE_FIELD, deepMerge, docAuthorCanonicalInput, getBase64, } from "@drakkar.software/starfish-protocol";
 import { ConflictError } from "./types.js";
-import { createEncryptor } from "./crypto.js";
+import { stripPushPrefix } from "./client.js";
 import { ValidationError } from "./validate.js";
+export class AbortError extends Error {
+    constructor() {
+        super("SyncManager was aborted");
+        this.name = "AbortError";
+    }
+}
 export class SyncManager {
     client;
     pullPath;
@@ -9,28 +15,31 @@ export class SyncManager {
     onConflict;
     maxRetries;
     encryptor;
-    signData;
+    signer;
     logger;
     loggerName;
     validate;
     lastHash = null;
     lastCheckpoint = 0;
     localData = {};
+    aborted = false;
     constructor(options) {
         this.client = options.client;
         this.pullPath = options.pullPath;
         this.pushPath = options.pushPath;
         this.onConflict = options.onConflict ?? deepMerge;
         this.maxRetries = options.maxRetries ?? 3;
-        this.signData = options.signData;
+        this.signer = options.signer;
         this.logger = options.logger;
         this.loggerName = options.loggerName ?? options.pullPath.split("/").filter(Boolean).pop() ?? options.pullPath;
         this.validate = options.validate;
-        this.encryptor =
-            options.encryptor ??
-                (options.encryptionSecret && options.encryptionSalt
-                    ? createEncryptor(options.encryptionSecret, options.encryptionSalt, options.encryptionInfo)
-                    : null);
+        this.encryptor = options.encryptor ?? null;
+    }
+    abort() {
+        this.aborted = true;
+    }
+    get isAborted() {
+        return this.aborted;
     }
     getData() {
         return { ...this.localData };
@@ -38,16 +47,31 @@ export class SyncManager {
     getHash() {
         return this.lastHash;
     }
+    /** Set the last-known server hash. Used by persistence layers to restore state across restarts. */
+    setHash(hash) {
+        this.lastHash = hash;
+    }
     getCheckpoint() {
         return this.lastCheckpoint;
     }
     async pull() {
+        if (this.aborted)
+            throw new AbortError();
         this.logger?.pullStart(this.loggerName);
         const start = performance.now();
         try {
+            // NOTE: `SyncManager.pull` does NOT auto-enable `withKeyring`. Clients
+            // that drive the keyring helpers from `recipients.ts` and want to save
+            // the cold-start round-trip should call `client.pull(path, {withKeyring: true})`
+            // directly. We keep `SyncManager` keyring-agnostic so it stays usable
+            // for collections that don't use delegated encryption.
             const result = await this.client.pull(this.pullPath, this.lastCheckpoint);
+            if (this.aborted)
+                throw new AbortError();
             if (this.encryptor) {
                 const decrypted = await this.encryptor.decrypt(result.data);
+                if (this.aborted)
+                    throw new AbortError();
                 this.localData = decrypted;
                 result.data = decrypted;
             }
@@ -69,6 +93,8 @@ export class SyncManager {
         }
     }
     async push(data) {
+        if (this.aborted)
+            throw new AbortError();
         if (this.validate) {
             const result = this.validate(data);
             if (result !== true)
@@ -80,13 +106,33 @@ export class SyncManager {
         let pendingData = data;
         while (attempt <= this.maxRetries) {
             try {
-                const payload = this.encryptor
+                const sealed = this.encryptor
                     ? await this.encryptor.encrypt(pendingData)
                     : pendingData;
-                const sig = this.signData
-                    ? await this.signData(stableStringify(payload))
-                    : undefined;
-                const result = await this.client.push(this.pushPath, payload, this.lastHash, sig);
+                if (this.aborted)
+                    throw new AbortError();
+                // v3.0 signer path: sign the document author proof over the doc-author
+                // canonical input (domain-tagged, bound to documentKey) and pass it as
+                // top-level body siblings of `data` (NOT inside `data`), where the server
+                // verifies it and stores the raw author pubkey.
+                let author;
+                if (this.signer) {
+                    const { devEdPubHex, sign } = await this.signer.getSigner();
+                    if (this.aborted)
+                        throw new AbortError();
+                    const documentKey = stripPushPrefix(this.pushPath);
+                    const canonical = docAuthorCanonicalInput(documentKey, sealed);
+                    const sigBytes = await sign(new TextEncoder().encode(canonical));
+                    if (this.aborted)
+                        throw new AbortError();
+                    author = {
+                        [AUTHOR_PUBKEY_FIELD]: devEdPubHex,
+                        [AUTHOR_SIGNATURE_FIELD]: getBase64().encode(sigBytes),
+                    };
+                }
+                const result = await this.client.push(this.pushPath, sealed, this.lastHash, author);
+                if (this.aborted)
+                    throw new AbortError();
                 this.lastHash = result.hash;
                 this.lastCheckpoint = result.timestamp;
                 this.localData = pendingData;
@@ -94,6 +140,8 @@ export class SyncManager {
                 return result;
             }
             catch (err) {
+                if (err instanceof AbortError)
+                    throw err;
                 if (!(err instanceof ConflictError) || attempt >= this.maxRetries) {
                     this.logger?.pushError(this.loggerName, err instanceof Error ? err.message : String(err));
                     throw err;
@@ -101,14 +149,20 @@ export class SyncManager {
                 this.logger?.conflict(this.loggerName, attempt + 1);
                 try {
                     const remote = await this.client.pull(this.pullPath);
+                    if (this.aborted)
+                        throw new AbortError();
                     const remoteData = this.encryptor
                         ? await this.encryptor.decrypt(remote.data)
                         : remote.data;
+                    if (this.aborted)
+                        throw new AbortError();
                     this.lastHash = remote.hash;
                     this.lastCheckpoint = remote.timestamp;
                     pendingData = this.onConflict(pendingData, remoteData);
                 }
                 catch (resolveErr) {
+                    if (resolveErr instanceof AbortError)
+                        throw resolveErr;
                     const msg = resolveErr instanceof Error ? resolveErr.message : String(resolveErr);
                     this.logger?.pushError(this.loggerName, `Conflict resolution failed (attempt ${attempt + 1}): ${msg}`);
                     throw resolveErr;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakkar.software/starfish-client",
-  "version": "3.0.0-alpha.21",
+  "version": "3.0.0-alpha.23",
   "repository": {
     "type": "git",
     "url": "https://github.com/Drakkar-Software/starfish.git",
@@ -60,7 +60,7 @@
     }
   },
   "dependencies": {
-    "@drakkar.software/starfish-protocol": "3.0.0-alpha.21"
+    "@drakkar.software/starfish-protocol": "3.0.0-alpha.23"
   },
   "devDependencies": {
     "@legendapp/state": "^2.0.0",

package/dist/append.d.ts

@@ -1,50 +0,0 @@
-import type { StarfishClient } from "./client.js";
-import type { PushSuccess } from "@drakkar.software/starfish-protocol";
-/**
- * Appends `item` to an append-only collection.
- *
- * Sends `{ data: item, baseHash: null }` — the server ignores `baseHash` for
- * append-only collections (conflict detection is disabled or delegated to
- * `checkLastItem` on the server side).
- *
- * ```ts
- * await pushAppend(client, "/push/events", { type: "click", ts: Date.now() })
- * ```
- */
-export declare function pushAppend(client: StarfishClient, path: string, item: Record<string, unknown>): Promise<PushSuccess>;
-export interface PullAppendListOptions {
-    /** Array field name. Defaults to `"items"` (server default). */
-    field?: string;
-    /**
-     * Return only items appended after this timestamp (milliseconds since epoch).
-     * Sent as `?checkpoint=<since>`. Omit for a full pull.
-     */
-    since?: number;
-    /**
-     * Return only the last K items. Applied after the `since` filter.
-     * Useful for "latest N entries" queries without a tracked checkpoint.
-     * Sent as `?last=<K>`.
-     */
-    last?: number;
-}
-/**
- * Pulls the stored item array from an append-only collection.
- *
- * Returns `data[field]` filtered to an array; returns `[]` when the document
- * does not exist yet or the field is absent / not an array.
- *
- * Pass `{ since: ts }` for incremental pulls — only items appended after `ts`
- * are returned (requires per-item timestamps on the server, available from 2.0.0).
- *
- * ```ts
- * // Full pull
- * const events = await pullAppendList(client, "/pull/events")
- *
- * // Incremental pull
- * const newEvents = await pullAppendList(client, "/pull/events", { since: lastSyncTs })
- *
- * // Custom field name
- * const logs = await pullAppendList(client, "/pull/audit", { field: "logs" })
- * ```
- */
-export declare function pullAppendList<T = unknown>(client: StarfishClient, path: string, options?: PullAppendListOptions): Promise<T[]>;

package/dist/bindings/broadcast.d.ts

@@ -1,19 +0,0 @@
-import type { StoreApi } from "zustand/vanilla";
-import type { StarfishStore } from "./zustand.js";
-/**
- * Syncs a Zustand Starfish store across browser tabs using BroadcastChannel.
- * Returns a cleanup function that closes the channel.
- */
-export declare function setupBroadcastSync(store: StoreApi<StarfishStore>, name: string): () => void;
-/**
- * Syncs a Zustand Starfish store across browser tabs using storage events.
- * Fallback for environments without BroadcastChannel.
- * Returns a cleanup function.
- */
-export declare function setupStorageFallback(store: StoreApi<StarfishStore>, name: string): () => void;
-/**
- * Auto-detects the best cross-tab sync mechanism and sets it up.
- * Uses BroadcastChannel when available, falls back to storage events.
- * Returns a cleanup function.
- */
-export declare function setupCrossTabSync(store: StoreApi<StarfishStore>, name: string): () => void;

package/dist/bindings/broadcast.js

@@ -1,65 +0,0 @@
-/**
- * Syncs a Zustand Starfish store across browser tabs using BroadcastChannel.
- * Returns a cleanup function that closes the channel.
- */
-export function setupBroadcastSync(store, name) {
-    const channel = new BroadcastChannel(`starfish-${name}`);
-    let lastReceivedData = null;
-    channel.onmessage = (event) => {
-        lastReceivedData = event.data.data;
-        store.setState({ data: event.data.data, dirty: event.data.dirty });
-    };
-    const unsub = store.subscribe((state, prev) => {
-        if (state.data === lastReceivedData)
-            return;
-        if (state.data !== prev.data || state.dirty !== prev.dirty) {
-            channel.postMessage({ data: state.data, dirty: state.dirty });
-        }
-    });
-    return () => {
-        unsub();
-        channel.close();
-    };
-}
-/**
- * Syncs a Zustand Starfish store across browser tabs using storage events.
- * Fallback for environments without BroadcastChannel.
- * Returns a cleanup function.
- */
-export function setupStorageFallback(store, name) {
-    const storageKey = `starfish-broadcast-${name}`;
-    let lastReceivedData = null;
-    const onStorage = (e) => {
-        if (e.key !== storageKey || !e.newValue)
-            return;
-        const payload = JSON.parse(e.newValue);
-        lastReceivedData = payload.data;
-        store.setState({ data: payload.data, dirty: payload.dirty });
-    };
-    globalThis.addEventListener("storage", onStorage);
-    const unsub = store.subscribe((state, prev) => {
-        if (state.data === lastReceivedData)
-            return;
-        if (state.data !== prev.data || state.dirty !== prev.dirty) {
-            localStorage.setItem(storageKey, JSON.stringify({ data: state.data, dirty: state.dirty }));
-        }
-    });
-    return () => {
-        unsub();
-        globalThis.removeEventListener("storage", onStorage);
-    };
-}
-/**
- * Auto-detects the best cross-tab sync mechanism and sets it up.
- * Uses BroadcastChannel when available, falls back to storage events.
- * Returns a cleanup function.
- */
-export function setupCrossTabSync(store, name) {
-    if (typeof BroadcastChannel !== "undefined") {
-        return setupBroadcastSync(store, name);
-    }
-    if (typeof globalThis.addEventListener === "function" && typeof localStorage !== "undefined") {
-        return setupStorageFallback(store, name);
-    }
-    return () => { };
-}

package/dist/bindings/react.d.ts

@@ -1,12 +0,0 @@
-import type { StoreApi } from "zustand/vanilla";
-import type { StarfishStore, StarfishState } from "./zustand.js";
-/** Derived sync status for UI display. */
-export type SyncStatus = "synced" | "syncing" | "pending" | "error" | "offline";
-/** Derive a single sync status from store state. */
-export declare function deriveSyncStatus(state: StarfishState): SyncStatus;
-/** Use the full Starfish store state and actions. */
-export declare function useStarfish(store: StoreApi<StarfishStore>): StarfishStore;
-/** Use only the synced data, with an optional selector for fine-grained subscriptions. */
-export declare function useStarfishData<T = Record<string, unknown>>(store: StoreApi<StarfishStore>, selector?: (data: Record<string, unknown>) => T): T;
-/** Use the derived sync status (synced | syncing | pending | error | offline). */
-export declare function useSyncStatus(store: StoreApi<StarfishStore>): SyncStatus;

package/dist/bindings/react.js

@@ -1,25 +0,0 @@
-import { useStore } from "zustand";
-/** Derive a single sync status from store state. */
-export function deriveSyncStatus(state) {
-    if (!state.online)
-        return "offline";
-    if (state.error)
-        return "error";
-    if (state.syncing)
-        return "syncing";
-    if (state.dirty)
-        return "pending";
-    return "synced";
-}
-/** Use the full Starfish store state and actions. */
-export function useStarfish(store) {
-    return useStore(store);
-}
-/** Use only the synced data, with an optional selector for fine-grained subscriptions. */
-export function useStarfishData(store, selector) {
-    return useStore(store, (state) => selector ? selector(state.data) : state.data);
-}
-/** Use the derived sync status (synced | syncing | pending | error | offline). */
-export function useSyncStatus(store) {
-    return useStore(store, deriveSyncStatus);
-}

package/dist/crypto.js

@@ -1,49 +0,0 @@
-import { getCrypto, getBase64, IV_BYTES, ENCRYPTED_KEY, deriveKey } from "@drakkar.software/starfish-protocol";
-const ALGO = "AES-GCM";
-export { ENCRYPTED_KEY };
-/**
- * Creates an Encryptor that uses AES-256-GCM with HKDF-derived keys.
- */
-export function createEncryptor(secret, salt, info = "starfish-e2e") {
-    if (!secret)
-        throw new Error("encryptionSecret must not be empty");
-    if (!salt)
-        throw new Error("encryptionSalt must not be empty");
-    const keyPromise = deriveKey(secret, salt, info);
-    return {
-        async encrypt(data) {
-            const key = await keyPromise;
-            const c = getCrypto();
-            const b64 = getBase64();
-            const plaintext = new TextEncoder().encode(JSON.stringify(data));
-            const iv = c.getRandomValues(new Uint8Array(IV_BYTES));
-            const ciphertext = await c.subtle.encrypt({ name: ALGO, iv }, key, plaintext);
-            const combined = new Uint8Array(iv.length + ciphertext.byteLength);
-            combined.set(iv);
-            combined.set(new Uint8Array(ciphertext), iv.length);
-            return { [ENCRYPTED_KEY]: b64.encode(combined) };
-        },
-        async decrypt(wrapper) {
-            const encoded = wrapper[ENCRYPTED_KEY];
-            if (typeof encoded !== "string") {
-                throw new Error("Expected encrypted data but received unencrypted document");
-            }
-            const key = await keyPromise;
-            const c = getCrypto();
-            const b64 = getBase64();
-            const combined = b64.decode(encoded);
-            if (combined.length < IV_BYTES) {
-                throw new Error("Encrypted data is too short");
-            }
-            const iv = combined.slice(0, IV_BYTES);
-            const ciphertext = combined.slice(IV_BYTES);
-            try {
-                const plaintext = await c.subtle.decrypt({ name: ALGO, iv }, key, ciphertext);
-                return JSON.parse(new TextDecoder().decode(plaintext));
-            }
-            catch (err) {
-                throw new Error("Decryption failed: data may be tampered or key is incorrect", { cause: err });
-            }
-        },
-    };
-}

package/dist/entitlements.js

@@ -1,41 +0,0 @@
-import { StarfishHttpError } from "./types.js";
-/**
- * Fetches the list of feature slugs from a user's entitlement document.
- *
- * Returns an empty array if the document does not exist yet or the features
- * field is absent — so callers never need to handle a 404.
- *
- * ```ts
- * import { pullEntitlements } from "@drakkar.software/starfish-client"
- *
- * const features = await pullEntitlements(client, userId)
- * // e.g. ["premium-package-1", "paid-cloud-sync"]
- *
- * if (features.includes("paid-cloud-sync")) {
- *   // unlock cloud sync UI
- * }
- * ```
- *
- * The path template must match the server-side collection's `storagePath`.
- * With the recommended default config:
- * ```ts
- * { storagePath: "users/{identity}/entitlements" }
- * // → path: "/pull/users/{userId}/entitlements"  (default)
- * ```
- */
-export async function pullEntitlements(client, userId, opts) {
-    const path = (opts?.path ?? "/pull/users/{userId}/entitlements").replace("{userId}", userId);
-    const field = opts?.field ?? "features";
-    try {
-        const result = await client.pull(path);
-        const list = result.data?.[field];
-        if (!Array.isArray(list))
-            return [];
-        return list.filter((s) => typeof s === "string");
-    }
-    catch (err) {
-        if (err instanceof StarfishHttpError && err.status === 404)
-            return [];
-        throw err;
-    }
-}

package/dist/group-crypto.d.ts

@@ -1,111 +0,0 @@
-/**
- * Group encryption utilities for Starfish.
- *
- * Enables multiple users to share a common encrypted collection without sharing
- * a passphrase. Each member holds their own credentials; a Group Encryption Key
- * (GEK) is distributed per-member using X25519 ECDH key agreement.
- *
- * Typical flow:
- *   1. Each user calls `deriveCredentials(passphrase)` — now includes groupPublicKey / groupPrivateKey.
- *   2. Admin calls `createGroupKeyring(...)` to create a keyring document.
- *   3. Members call `createGroupEncryptor(keyringData, myIdentity, myPrivateKey)` to get an Encryptor.
- *   4. The Encryptor is passed to SyncManager via the `encryptor` option.
- */
-import type { Encryptor } from "./crypto.js";
-/** An ECDH key pair used for group encryption. Hex-encoded for easy serialization. */
-export interface GroupKeyPair {
-    /** Hex-encoded X25519 private key (32 bytes). Keep secret — never store on server. */
-    privateKey: string;
-    /** Hex-encoded X25519 public key (32 bytes). Safe to publish. */
-    publicKey: string;
-}
-/** One epoch's wrapped keys: each member's GEK encrypted to their public key. */
-export interface EpochKeyring {
-    /** The admin's hex-encoded X25519 public key (used for ECDH by members). */
-    adminPublicKey: string;
-    /** Map from member identity (userId) → base64(IV || AES-GCM(GEK)) */
-    wrappedKeys: Record<string, string>;
-}
-/** The full keyring document stored in a Starfish collection. Push this with any SyncManager. */
-export interface GroupKeyring {
-    /** The epoch number currently used for new encryptions. */
-    currentEpoch: number;
-    /** All epochs. Members unwrap the GEK for whichever epoch a document was encrypted with. */
-    epochs: Record<string, EpochKeyring>;
-}
-/**
- * Derives a deterministic X25519 key pair from a passphrase + userId.
- *
- * The derivation uses SHA-256 with a fixed domain separator so it is distinct
- * from the auth token and encryption key derivations. Same passphrase + userId
- * always produces the same key pair on any device (stateless).
- */
-export declare function deriveGroupKeyPair(passphrase: string, userId: string): Promise<GroupKeyPair>;
-/** Generates a random 256-bit Group Encryption Key as a hex string. */
-export declare function generateGroupKey(): string;
-/**
- * Wraps a GEK for a specific member using ECDH key agreement.
- *
- * The wrapper (admin) and member each have an X25519 key pair. ECDH between
- * `wrapperPrivateKey` and `memberPublicKey` produces a shared secret, which is
- * used to derive an AES-256-GCM key that encrypts the GEK.
- *
- * @returns base64(IV || AES-GCM-ciphertext)
- */
-export declare function wrapGroupKey(gek: string, memberPublicKey: string, wrapperPrivateKey: string): Promise<string>;
-/**
- * Unwraps a GEK using the member's own private key and the admin's public key.
- *
- * ECDH between `memberPrivateKey` and `adminPublicKey` yields the same shared
- * secret as the wrapping step, so the same AES key is derived and the GEK is
- * recovered.
- *
- * @returns GEK as a hex string
- */
-export declare function unwrapGroupKey(wrapped: string, memberPrivateKey: string, adminPublicKey: string): Promise<string>;
-/**
- * Creates a new group keyring document with epoch 1.
- *
- * @param adminKeyPair  The admin's key pair (from `deriveGroupKeyPair` or `deriveCredentials`)
- * @param members       Map from member identity (userId) → hex public key
- * @param gek           Optional GEK to use; generated randomly if omitted
- * @returns             The keyring document and the raw GEK (admin keeps the GEK to add future members)
- */
-export declare function createGroupKeyring(adminKeyPair: GroupKeyPair, members: Record<string, string>, gek?: string): Promise<{
-    keyring: GroupKeyring;
-    gek: string;
-}>;
-/**
- * Adds a new member to the current epoch of an existing keyring.
- *
- * The admin supplies the current GEK (returned by `createGroupKeyring` or
- * `rotateGroupKey`) and their key pair to wrap it for the new member.
- * This does NOT rotate the GEK — the new member can read all existing
- * documents encrypted with the current epoch key.
- *
- * Only the admin (whose `publicKey` matches `epochKeyring.adminPublicKey`) can
- * add members, because all wrapped entries must use the same ECDH key pair.
- */
-export declare function addGroupMember(keyring: GroupKeyring, adminKeyPair: GroupKeyPair, currentGek: string, newMemberId: string, newMemberPublicKey: string): Promise<GroupKeyring>;
-/**
- * Rotates the group key, creating a new epoch.
- *
- * Used when removing a member. The removed member retains their old epoch key
- * (and can still read old documents), but cannot read new documents.
- *
- * @param remainingMembers  Map from identity → hex public key for members who keep access
- */
-export declare function rotateGroupKey(keyring: GroupKeyring, adminKeyPair: GroupKeyPair, remainingMembers: Record<string, string>, newGek?: string): Promise<{
-    keyring: GroupKeyring;
-    gek: string;
-}>;
-/**
- * Creates an Encryptor that can decrypt any epoch and encrypts with the current epoch.
- *
- * Wire format: `{ _encrypted: "base64(IV || ciphertext)", _epoch: N }`
- *
- * @param keyring         The keyring document fetched from Starfish
- * @param myIdentity      The caller's userId (to locate their wrapped key in each epoch)
- * @param myPrivateKey    The caller's hex-encoded X25519 private key
- */
-export declare function createGroupEncryptor(keyring: GroupKeyring, myIdentity: string, myPrivateKey: string): Promise<Encryptor>;